Shibboleth IdP 2.x is becoming End-Of-Life on July 31st, 2016.  This page now exists only as a historical archive.

Please see the instructions on Upgrading a 2.x IdP to 3.x.

Overview and Plan

This guide for upgrading a Shibboleth IdP is based on the assumption the IdP has been built according to the Tuakiri Installing a Shibboleth 2.x IdP manual.

This guide covers updating to the current release in the 2.4.x branch and versions 2.3.x and 2.4.x are considered for the base install. Adjust accordingly for other version combinations.

Overall, this plan assumes to carry over modifications done to the old installation tree (unpacked zip binary) to the new one, rebuilding the war file and reusing the configuration files.

Upgrade plan:

In a nutshell, this plan assumes the configuration files in /opt/shibboleth-idp/conf will be left untouched and only the web application /opt/shibboleth-idp/war/idp.war (and files in /opt/shibboleth-idp/lib/) will get updated. Among the 2.2.x, 2.3.x, and 2.4.x branches, the configuration files are compatible with new releases without modification.

Upgrade Walkthrough

Examine local modifications

Preparing new version

Set the current environment to point to the new version:

IDP_VERSION="2.4.2"
SHIB_INST_HOME=/root/inst/shibboleth-identityprovider-$IDP_VERSION
export IDP_VERSION SHIB_INST_HOME

Download and extract the new version

wget http://www.shibboleth.net/downloads/identity-provider/latest/shibboleth-identityprovider-${IDP_VERSION}-bin.zip
unzip shibboleth-identityprovider-${IDP_VERSION}-bin.zip

Installing local modifications into the new version

Check and backport login page branding.

Update configuration files

Shibboleth IdP is designed to run newer versions with configuration files from an older version - so you can keep your existing configuration files as they are and all already existing features should still work.

However, to benefit from the features added in newer releases, it may be worth adding the relevant sections from the configuration templates (in $SHIB_INST_HOME/src/installer/resources/conf-tmpl) into your configuration files in /opt/shibboleth-idp/conf and the IdP metadata in /opt/shibboleth-idp/metadata/idp-metadata.xml.

Notably:

You can examine the difference by comparing src/installer/resources/conf-tmpl and src/installer/resources/metadata-tmpl in the old and new installation tree - e.g.:

diff -rwu shibboleth-identityprovider-2.3.8-orig/src/installer/resources shibboleth-identityprovider-2.4.2/src/installer/resources | less

and applying the differences (adding new snippets for the new features like ECP or SLO) to your existing configuration files (and IdP metadata) in /opt/shibboleth-idp/conf and /opt/shibboleth-idp/metadata/idp-metadata.xml.

Deploy the new version

Backup the /opt/shibboleth-idp directory before deploying the upgrade