Updating Shibboleth

Any healthy authentication system should be updated whenever a serious bug has been found. Bug reports are announced via the Shibboleth-announce mailinglist. Besides bug fixes, the updates usually include some new features that might be useful.
This document intends to describe a simple update procedure for minor updates within the same major version (eg updating to 1.3*b* from a 1.3 version).

Update a running SP

Unix

(insert guidelines for updating an SP on a UNIX system here; this should be easier than updating a Windows system since the binary files are not locked)
Updating a SP on a UNIX system is much simpler than on a Windows OS. When you use rpm's on a RedHat/Fedora system this is even simpler.

Try to download the RPM package (http://wayf.internet2.edu/shibboleth/RPMS\) that is available for your system. When there isn't a RPM package available yet, try to rebuild the SRPM which you can download from http://wayf.internet2.edu/shibboleth/SRPMS/.

Recommended steps to do:

• It couldn't hurt to take a backup of all your configuration files ( /etc/shibboleth , /etc/httpd/conf.d/shibd.conf , =/etc/init.d/shibd=).
• Query the package you are trying to update for more information:
  rpm -qip shibboleth-version.i386.rpm
• You can test if the update will cause any problem's:
  rpm -U --test shibboleth-version.i386.rpm
  If everything is ok, no output will be given.
• Update the package:
  rpm -Uvh shibboleth-version.i386.rpm
• The old configuration files won't be overwritten. The new configuration files will get ".dist" appended. So if there are some major changes in the configuration files you can use them after some modifications.
• Now restart the Shibboleth daemon:
  /etc/init.d/shibd restart
• Restart apache graceful (open connections with apache aren't aborted this way)
  /etc/init.d/httpd graceful

The update is now complete!

Windows

For updating an SP running on the Windows OS there is a special "postinstall" package. To use it, you need to download the archive and copy the files that it contains to the correct files that are in use. You will need to shut down all services that are using the files that you need to overwrite. Unfortunately this probably means you will need to take your webserver offline for a moment to update Shibboleth. So it is wise to be very well prepared before doing this.
Smaller updates do not require any changes to the configuration at first. Though they usually do enable/fix some smaller configuration issues.

Recommended steps to update the Shibboleth software:

• nothing should really prevent you from copying/reading all the current Shibboleth files so here's a good idea: safely back up the current files before you do anything
• download the postinstall package from https://wayf.internet2.edu/shibboleth/win32/ and extract its contents somewhere on the server
• check to which location you need to copy the new files (to overwrite the current ones)
• check the permissions on the current files on that location (write down the owner, group and permissions, you might need them later)
  [your webservice will now go offline]
• stop your webservice (stopping the daemon first will cause all Shibboleth auth requests to cause errors until the webservice goes down, think about what is best in your case)
  • IIS:
    • your ISAPI filter is probably loaded by the main webserver (see properties of the "Web Sites" element in the tree of the IIS manager). In this case you need to stop the entire webserver by (IIS6) right-clicking the webserver in the IIS manager, and the selecting "All tasks...", "Restart IIS...". Select "Stop Internet Services on __" and click ok.
    • if your server is running multiple "Web Sites" and you configured the filter to load for certain web sites only, you might want to choose to stop only those web sites that load the Shibboleth ISAPI filter
  • Apache (1&2): when using Apache httpd on the Windows OS, it files that are in use also get locked. Stop the Apache service completely as you are used to.
• stop the Shibboleth Daemon ("My computer","Manage","Services")
• overwrite the old Shibboleth files with the new ones
• check the permissions of the new files, they should not have been changed (if the webserver can't read the necessary files it will probably fail to start)
• start the Shibboleth daemon again
• start your webserver again
  [your webservice most likely comes back online here]

The update has now been completed.

Update a running !IdP

As of Shibboleth 1.3, the !IdP by default has been installed with the configuration files stored outside the web application itself. This structure makes upgrades of Shibboleth extremely straightforward; however, future versions of Shibboleth may have modified prerequisites which should always be considered when updating(e.g. Java 1.3 will likely be unsupported by Shibboleth 2.0). To update an !IdP:

• Download and unpack the .tar file from http://wayf.internet2.edu/shibboleth/
• Run ./ant install in the root of the unpacked tarball and answer the simple questions.
• The ant installation script will detect the old configuration files and will not overwrite them.
• Reboot Tomcat.

%COMMENT%