The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

NativeSPLinuxRPMUpgrade

Owned by Scott Cantor
Last updated: Oct 13, 2012Version comment

Ordinarily there would be nothing to say here, but unfortunately there have been unreported bugs and some other mistakes in the Shibboleth package to date, and there are several anomalies that can result from using the rpm -U upgrade option to replace older Shibboleth SP packages with newer ones.

Most of this has started to get cleaned up around the V2.2/2.2.1 timeframe, but the specifics vary and it's less useful to try to explain every last combination than to document the general things to be careful about. If you're starting from an official V2.2.1 package, you can consider anything that doesn't work as intended during an upgrade to be a bug worth reporting.

Init Scripts

Make sure the shibd init script is installed and enabled after an upgrade.

The main area of trouble is related to the handling of the /etc/init.d/shibd script, which until recently was improperly controlled by the SP package. In addition a bug was introduced in the V2.1 SP that results in problems when upgrading from that version.

If you're upgrading from an older package and V2.1 isn't involved, the process is believed to be safe in this respect. On versions of Red Hat with RPM 4.4. or newer, these problems are believed to be worked around, so upgrades should also be safe in that case. That includes Red Hat 5, but does not include Red Hat 4. It also doesn't include cases where unofficial packages on other platforms like SUSE are involved.

If you are affected, the problem is that the script will be improperly removed after upgrading. To avoid these problems, an alternate approach is to uninstall (erase) the original package with rpm -e and then install the new one directly with rpm -i. In between you can safely upgrade all the dependency packages, or address that in whatever fashion you prefer.

If you do upgrade with a faulty package, you can manually clean up the problem by copying the init script into place yourself, as the broken upgrade process improperly removes the old version and prevents the new version from being left in place. You can find the file to copy in /etc/shibboleth/shibd-redhat (another version of the script also exists for SUSE variants now):

# install -m0755 -T /etc/shibboleth/shibd-redhat /etc/rc.d/init.d/shibd

After an upgrade, you also might want to check if the init script is correctly registered with chkconfig --list shibd. Otherwise fix this with

# chkconfig --add shibd
# chkconfig shibd on

Apache Config

Backup your shib.conf Apache config file if you have customized it.

Another confusing area involves the integration with the native Apache by copying the configuration snippet out of /etc/shibboleth and into /etc/httpd/conf.d/shibd.conf (or something similar). Historically the advice has always been to keep your local configuration changes out of this file and do them in your own file, mainly to avoid problems during upgrades if it became necessary in a newer version to add some kind of mandatory command to get the SP to function.

This "advice" was enforced by simply blasting your changes by re-copying the original over top of your version during an upgrade. This has now been corrected (in V2.5) by marking the file as a configuration file to protect, which ensures your version will be left in place.

Unfortunately, that only occurs when upgrading from a relatively recent version, because prior package versions may remove the file when they remove themselves during upgrade. So to be safe you should probably back up that file yourself.

Process Restarts

Until recently, the package upgrade process did not properly restart the Apache and shibd processes after an upgrade, which leaves the system in an unstable state and can exhibit runtime problems, particularly if one process was restarted but not the other. This should be corrected in V2.2.1, but it's something to watch for.

Note that the Apache that gets restarted is the OS-supplied version. If you're using a custom version, that's on you to deal with.