...
| Note |
|---|
Upgrading from pre-V4 releasesIf 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+ (and Jetty 9 is essentially end of life, so Jetty 10 is strongly recommended). Finally, you 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. Finally, you must always ensure the servlet container is stopped before making any changes to the warfile, including upgrades. |
...
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.
...
Non-Windows Upgrade
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-identityprovideridentity-provider-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
...