| Table of Contents |
|---|
| Warning |
|---|
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. 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. |
Before You Begin
It is generally safe to upgrade directly to the latest “newer” version as long as that’s only a single major version later than you start from. It is not required to upgrade to, for example, 5.0 before 5.1, etc. However, skipping does of course mean taking into account all of the accumulated ReleaseNotes covering all the intervening versions.
Upgrading from V3 or Earlier
...
If you are upgrading from a pre-V5 release, you must upgrade to the latest V4 release first and remove deprecation warnings. Note that some of these warnings may only be visible in your servlet container’s log. This is due to the order of operations; the IdP’s logging service cannot be started until the global Spring context is running, and some of the configuration triggering warnings may be in that root context.
There is one set of warnings that are an exception to this: the undocumented “SAML2NameID” and “SAML1NameID” attribute encoders produce warnings indicating they were removed from the next major version:
Code Block DEPRECATED xsi:type 'SAML2NameID', (file [/opt/shibboleth-idp/conf/attribute-resolver.xml]): This will be removed in the next major version of this software; replacement is (none)
In fact they were not, and their use (while still unsupported and undocumented) will produce a less aggressive “at risk” warning going forward. There are no explicit plans to remove them, but their use is incompatible with the vast majority of SAML software and should not be used in new deployments.
You must ensure that your versions of Java and servlet container meet the system requirements for V5. This is more complex than usual because there are relatively few servlet containers right now that support both Java and Jakarta Servlet specifications, and V4 requires the former while V5 requires the latter. At a minimum, it’s a good idea to upgrade a V4 system to Java 17 first, likely also installing one of our scripting engine plugins (Nashorn or Rhino).
If using Jetty it should be possible to use essentially the same configuration between Jetty 10 and 11, so if using Jetty 9 you should definitely migrate a V4 system to Jetty 10 before the V5 upgrade, at least in development/testing.
Note that the jetty installed by the V4 windows installer is Jetty 10.x.Finally, remove the system directory before upgrading (the installer will block on this issue). In V4, this directory was used for compatibility with older systems that had overridden the web.xml file, but we are removing this stopgap. In the event your V4 IdP fails to start with the system directory removed, you will need to either remove your overriden copy of web.xml, or at least freshen it by updating the very top of the file and correct the contextConfigLocation context parameter:
Code Block language xml <!-- Spring application context files. Files are loaded in the order they appear with subsequent files overwriting same named beans in previous files. --> <context-param> <param-name>contextConfigLocation</param-name> <param-value>classpath*:/META-INF/net.shibboleth.idp/preconfig.xml,classpath:/net/shibboleth/idp/conf/global-system.xml,classpath*:/META-INF/net.shibboleth.idp/postconfig.xml</param-value> </context-param>
...
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.
...
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. (Having said that, in practice these kinds of breaking changes are rare are most of the time rolling upgrades do in fact work.)
...
The installer available for Microsoft Windows handles upgrades from older releases.
In V5 the installation/update of the IdP is separated from the Installation/update of Jetty-base. A V4 to V5 update involves updating the IdP and then installing jetty-base.
...
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):
...
Use of reserved ('impl') class names (as per the Java Product Version Policy) in configuration.
Use of reserved ('impl') classes by extensions.
Very rarely if required for security reasons.
...