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.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 16 Next »

For upgrading a pre-2.x SP version, see the NativeSPUpgradeOlder topic.

There are two main approaches to upgrading the SP on Windows from an earlier 2.x release:

  • Uninstall, and then reinstall using the latest Windows Installer package.
  • Unpack the latest "postinstall" ZIP archive on top of an existing installation.

Both approaches will maintain your existing configuration and are fairly risk free. The primary difference involves the potential manual effort involved in re-applying IIS configuration changes if the installer fails to properly create the necessary settings.

In general, if using anything other than IIS, it is suggested that the installer be used. With IIS, the postinstall package may be a better choice if your initial integration with IIS required manual changes to permissions, or filter or script mapping settings.

The only real downside to the postinstall approach, apart from the assumption it makes about your install path, is that it will tend to leave stale/unused libraries on your system, but this should have no particular negative effect on the software.

Installer-based Upgrades

While the reinstallation process should preserve your configuration and log files, it's a good idea to save these files just in case, by copying your etc and var/log folders to a safe location.

To use the installer to perform an upgrade, the previous installer has to be removed first. In most cases, the new installer will detect this if you forget, and warn you about it.

1. To remove the older software, you should begin by stopping your web server, and then access the Add/Remove Programs feature in Windows and perform a "Change" operation. The "Change" option should give you the option to "Remove" the software at that point.

Do NOT attempt to directly "Uninstall" the package, or it will hang. Instead, follow the directions above. "Change" followed by removal should complete successfully. Newer installed versions explicitly disable the Uninstall option, but the older releases did not.

At this point, the software files will have been removed, but your configuration and log files will be intact.

2. You generally don't need to reboot at this point, and can proceed directly to reinstall the software using the newer installer. Be sure to select the same installation directory and other options that you used originally. If you fail to do so, your old configuration will not be adopted by the new installation without manually copying and/or modifying files.

3. Assuming you follow these directions, when reinstallation completes you should be able to immediately restart the upgraded Shibboleth Daemon Service using the Services administration tool. It should be using the same configuration as before (check the log file to ensure it appears to be running).

4. For a non-IIS installation, you can then proceed to restart your web server at this point, and service should be restored using the new software. An IIS server MAY require manual intervention to recreate non-standard filter and script mapping rules in some cases. You may want to examine the IIS configuration and check for the Shibboleth filter and ".sso" script mapping in the places you expect to find it before attempting to restart the IIS service.

5. Once you've verified your system is working properly, you'll want to remove the backup of your configuration files (since it probably contains your private key).

6. Finally, when time permits, you'll want to check the NativeSPConfigurationChanges topic to see if there are any configuration changes required to bring your system fully up to date. All compatible upgrades are guaranteed to maintain the integrity and "correctness" of your existing configuration, but you may be left with deprecated settings that could eventually cause problems or prevent new features from working.

Postinstall ZIP Upgrades

A somewhat simplified upgrade option that may work better for IIS installations is to simply unpack a new set of binaries, schemas, and other default files on top of your existing software tree. This approach has the advantage of being very fast to perform, and won't affect any of your IIS settings.

You can only rely on this method if your existing software is installed to the C:\opt\shibboleth-sp folder. The ZIP file contains a matching directory structure and will NOT result in a correctly updated installation if the target structure doesn't match.

You can certainly move files around or unpack the files to a different drive, but there's one thing that won't work: the share/xml directories contain "catalog.xml" files that contain paths to XML schemas. Those paths start with C:\opt\shibboleth-sp. You would need to edit all of the catalogs to reflect your own install path, which is not hard, but is not fun either.

1. The first step is to verify that the required Microsoft C/C++ runtime libraries are installed for the version of the compiler used to build the release you're upgrading to. You can find the installers needed for the current release at http://shibboleth.net/downloads/service-provider/msredist/

2. Proceed by stopping both your web server and the Shibboleth Daemon Service to allow the files to be overwritten. To make sure nothing breaks, simply backup the entire C:\opt\shibboleth-sp software tree for safekeeping.

3. Perform the update by unpacking the ZIP archive on top of the existing C:\opt\shibboleth-sp directory by extracting it directly above the opt folder. You should be prompted to overwrite the existing files and should indicate that it can do so. If you aren't prompted, you selected the wrong location to extract to in this step.

4. Upon completion, you should be able to immediately restart the Shibboleth Daemon Service. If this succeeds (check the log file), you can restart your web server and service should be restored using the new software.

5. Once you've verified your system is working properly, you'll want to remove the backup of your original files (since it probably contains your private key).

6. Finally, when time permits, you'll want to check the NativeSPConfigurationChanges topic to see if there are any configuration changes required to bring your system fully up to date. All compatible upgrades are guaranteed to maintain the integrity and "correctness" of your existing configuration, but you may be left with deprecated settings that could eventually cause problems or prevent new features from working.

  • No labels