Upgrading

Created by Scott Cantor
Last updated: Jan 18, 2017

Before You Begin

It's a good idea to review the Installation material to refamiliarize yourself with the general process. Most importantly, review the ReleaseNotes carefully for any important changes you might need to account for or make. In general, you should not expect upgrades to require changes ahead of time, but security issues or other major bugs might occasionally require special care.

The upgrade process is designed to be very safe, and will never overwrite any configuration files, views/templates, properties, etc. that you have modified, except that any files in idp.home/system or idp.home/webapp are fair game and may be modified by any upgrade, so you should bear this in mind.

By design, the idp.home/edit-webapp directory can be used to preserve changes across upgrades, but if you modify an existing file (as opposed to adding files), you should always compare your changed versions to the upgraded files to understand if any changes are important, though we will make every effort to highlight any such changes in the ReleaseNotes.

Be aware that rolling upgrades are generally guaranteed to work only for patch upgrades (changes in the final digit). Minor upgrades may sometimes include internal changes to storage formats or other implementation details that could prevent certain features from working interoperably between versions. It is best to either plan for a relatively fast rolling upgrade within a maintenance window, or plan for a short period of downtime.

Windows Upgrade

The installer available for Microsoft Windows handles upgrades from older releases. See the Windows Upgrade  topic for instructions. This also supports upgrading Jetty, if that option was selected.

Non-Windows Upgrade

  1. Download the latest Identity Provider software package (the zip file has Windows line endings, the tarball Unix line endings).
  2. Unpack the archive you downloaded to a convenient location. It will not be needed after installation.
  3. Change into the newly created distribution directory, shibboleth-identityprovider-VERSION
  4. Run either ./bin/install.sh (on non-Windows systems) or .\bin\install.bat (on Windows systems).
    • Make sure to specify the same installation directory you used originally (the idp.home directory). This will cause the installer to perform an upgrade. Using a different installation directory will essentially perform a new installation.
  5. After reviewing any necessary changes, rebuild the warfile with any edits you've applied by running either idp.home/bin/build.sh or idp.home\bin\build.bat.
  6. Re-deploy the new IdP warfile, located in idp.home/war/idp.war.