Before You Begin
Upgrading from pre-V4 releases
If you are upgrading from a pre-V4 release, you must upgrade to the latest V3 release first and remove all deprecation warnings.
In addition, you must ensure that your versions of Java and servlet container meet the system requirements for V4. If they do not, you should generally upgrade those before attempting to upgrade the IdP software.
For example, Java 11 is now required, and although Jetty 8 was sufficient to run IdP V3, IdP V4 supports only Jetty 9.4+.
Finally, you must install the new version on top of your previous installation. This is not only safe but essential to properly maintain a working system.
One caveat is that you may have customizations in edit-webapp, and those customizations are almost certainly not compatible with V4 without changes. This may require removing them first and making other configuration changes temporarily until the customizations are ported or re-validated on the new version.
In the event that you refuse to adhere to this approach, please be aware that you MUST copy back all previously existing files in the conf directory that were present before, not just the ones you may have changed. Failure to do so is the primary cause of issues after upgrading when the proper approach is not followed. In effect, make sure that you capture all of the files in your configuration management system, not just changed files. Once you install once, you own and effectively have changed all of the files because future upgrades will make that assumption. This will increase the likelihood, but not guarantee, that an improper upgrade "from scratch" will work, but it is still not a supported approach and may lead to outright failure at any time.
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 (barring exigent need and clear documentation) overwrite any configuration files, views/templates, properties, etc. that are already in place, except that any files in idp.home/system are fair game and may be modified or even removed by any upgrade, so you should not modify them or count on them being stable.
By design, the idp.home/edit-webapp directory can be used to preserve changes across upgrades, but if you modify an existing file, principally web.xml, (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 (that result in online servers on different versions) 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.
The installer available for Microsoft Windows handles upgrades from older releases. This also supports upgrading Jetty, if that option was selected.
- Download the latest Identity Provider software package (the zip file has Windows line endings, the tarball Unix line endings).
- Unpack the archive you downloaded to a convenient location. It will not be needed after installation and none of its content should be used outside the scope of the installation process.
- Change into the newly created distribution directory, shibboleth-identityprovider-VERSION
- You should take a backup of the idp.home directory prior to the upgrade in case anything goes wrong. Remember that there are files in this directory tree with highly sensitive information.
- 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 and this is not a supported mechanism for doing upgrades.
- After reviewing any necessary further changes, rebuild the warfile with any edits you've applied by running either idp.home/bin/build.sh or idp.home\bin\build.bat
- Re-deploy the new IdP warfile, located in idp.home/war/idp.war
The rules for upgrades (which in turn drive your upgrade procedure) are derived from the Java Product Version Policy. This means that (except in exceptional circumstances):
- It will be possible to move between patch versions of the same major and minor version (e.g.. from 4.3.2 to 4.3.1 or 4.3.3)
- It will be possible to move to more recent minor versions of the same major version (e.g. from 4.3.2 to 4.4.1, but not from 4.4.1 to 4.3.2)
Exceptions would be:
- Use of reserved ('impl') class names (as per the Java Product Version Policy) in spring configuration
- Use of reserved ('impl') classes by products
- Very rarely if required for security reasons.
In addition, major version releases (V3 to V4, or V5 to V6) will be compatibly upgraded subject to the following constraints:
- The starting installation is the very latest release of the previous major release (at time of writing this is V3.4.6 for a V4.0.0 upgrade).
- The installation starts and operates with no deprecation warnings.