Skip to end of metadata
Go to start of metadata

Local additions to the official upgrade instructions from the Shibboleth wiki, to be re-visited for each upgrade of the IDP software.

Update/upgrade instructions for IDP version 3.x only!

If you're still running the old Shibboleth IDP version 2.x you can follow another guide to build a completely new IDP, on a current and supported OS and then later migrate settings from IDPv2 over as needed.

Updating from IDP 3.3.0 or older

Seems from version 3.3.0 on the IDP also needs the JSP API 2.3 , which can be found in the libservlet3.1-java package, if you don't have that installed already:

apt install --no-install-recommends libservlet3.1-java

Install new IDP 3.x software over the existing IDP 3.x installation

Download and unpack the latest Shibboleth IDPv3 software, adjusting the value of $VER to the latest/current version. Optional (but recommended, if you understand how PGP and the Web of Trust work) commands for verification of the software using cryptographic signatures from the Shibboleth devlopers are included below.

First we'll stop the running Tomcat because it might otherwise try to reload the Shibboleth application even before we're done with all the required steps provided below:

systemctl stop tomcat9

Next start the upgrade:


export VER=3.4.7
cd /usr/local/src
curl -s https://shibboleth.net/downloads/PGP_KEYS | gpg --import -
curl -O "https://shibboleth.net/downloads/identity-provider/latest/shibboleth-identity-provider-$VER.tar.gz{,.asc}"
gpg --verify shibboleth-identity-provider-$VER.tar.gz.asc
tar xzf shibboleth-identity-provider-$VER.tar.gz
cd shibboleth-identity-provider-$VER
./bin/install.sh < /dev/null

This will use the current directory (/usr/local/src/shibboleth-identity-provider-$VER) as source and the default directory (/opt/shibboleth-idp) as target, and should produce output like this:

Source (Distribution) Directory (press <enter> to accept default: [/usr/local/src/shibboleth-identity-provider-3.x.x]
Installation Directory: [/opt/shibboleth-idp]
Rebuilding /opt/shibboleth-idp/war/idp.war ...
...done
BUILD SUCCESSFUL
Total time: 4 seconds

Adjust permissions

It will be necessary to re-apply file system permission changes done during installation, so just run these again:


chown tomcat /opt/shibboleth-idp/{logs,metadata}
chgrp tomcat -R /opt/shibboleth-idp/{credentials,conf}
chmod g+r -R /opt/shibboleth-idp/conf
chmod 640 /opt/shibboleth-idp/credentials/*
chmod 750 /opt/shibboleth-idp/credentials
chmod g+w /opt/shibboleth-idp/credentials/sealer.*

You'll also want to regenerate the list of the IDP's JARs that shouldn't be scanned during Tomcat startup, see section Slow Startup towards the end of that Shibboleth wiki page. Those will go into /etc/tomcat9/context.xml so we'll make a time-stamped backup copy of that file before replacing its content:


cp -a /etc/tomcat9/context.xml /etc/tomcat9/context.xml.`date -u +%Y%m%dT%H%M%S`

JARS=$(unzip -l /opt/shibboleth-idp/war/idp.war | grep WEB-INF/lib/. | sed -r 's/^.*WEB-INF\/lib\/(.+-)[0-9\.]+-?(RELEASE|GA|Final|[Bb]eta.?|.*avoid-conflict.*)?(-jre)?.jar$/\1*.jar,/' | tr '\n' ' ' | sed 's/, $//')

echo "<Context>
  <WatchedResource>WEB-INF/web.xml</WatchedResource>
  <WatchedResource>\${catalina.base}/conf/web.xml</WatchedResource>
  <Manager pathname=\"\" />
  <JarScanner>
    <JarScanFilter
        pluggabilitySkip=\"\${tomcat.util.scan.StandardJarScanFilter.jarsToSkip}, $JARS\" />
  </JarScanner>
</Context>" > /etc/tomcat9/context.xml

Restart Tomcat, which may take a bit, and check the logs for WARN and ERROR messages: By default the IDP logs to /opt/shibboleth-idp/logs/idp-process.log but if something is seriously wrong and the IDP isn't even able to start up you'll have to look at Tomcat's journal entries:

systemctl restart tomcat9
multitail /opt/shibboleth-idp/logs/idp-process.log -l 'journalctl -u tomcat9.service -f'  # exit with 'q'

Now the IDP should be running the current version and you can test the output of the status command line utility:

/opt/shibboleth-idp/bin/version.sh
/opt/shibboleth-idp/bin/status.sh
  • No labels