URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/refresh-metadata-sp.html
Author: Patrik Schnellmann - SWITCH
Author: Valery Tschopp - SWITCH
Author: Lukas Haemmerle- SWITCH
$Date: 2008/02/11 12:25:59 $
$Revision: 1.9 $

Automatically Refresh SWITCHaai Federation Metadata for Shibboleth Service Provider 1.3

Introduction
SWITCHaai Metadata Signer Certificate
Installation of the siterefresh Shell Script for Unix-based sytems
Installation of the siterefresh batch script for Windows sytems
Links

Introduction

The SWITCHaai Federation Metadata can be automatically retrieved and checked. An automatic update should be configured to keep the file up-to-date.

We have implemented wrapper scripts for the Shibboleth Service Provider siterefresh tool and the Shibboleth Identity Provider metadatatool. These wrapper scripts can conveniently be installed as a cron job to regularly run once a day.

For Service Providers, the siterefresh tool is installed with Shibboleth SP 1.3. The wrapper script extends it to be used as a cron job/Windows batch job and automate the refreshing of metadata.

The siterefresh script will first download and verify the signature of the XML metadata file. It will then compare the local metadata file currently in use with the downloaded one. If the downloaded metadata file is newer, the script overwrites the metadata file in use with the downloaded version. The Shibboleth Service Provider detects the change of the file and reloads the metadata. The old metadata file will be kept in a backup directory.

SWITCHaai Metadata Signer Certificate

All available SWITCHaai metadata files are digitally signed with the self-signed SWITCHaai Metadata Signer certificate.

Certificate Subject: C=CH, O=SWITCH - Teleinformatikdienste fuer Lehre und Forschung, OU=AAI, CN=SWITCHaai Metadata Signer, emailAddress=aai@switch.ch
MD5 Fingerprint: 1F:E6:A3:83:D8:24:FF:1E:8A:61:7D:73:F6:D7:EF:1A

Installation of the siterefresh Shell Script for Unix-based systems

Download the archive with the metadata signer certificate and the update script from http://www.switch.ch/aai/downloads/siterefresh.tar.gz
and place metadata.crt and siterefresh.sh in /etc/shibboleth/ (or wherever it suits best for your environment).

$ cd /tmp/
$ wget http://www.switch.ch/aai/downloads/siterefresh.tar.gz
$ tar -xzf siterefresh.tar.gz
$ mv metadata.crt siterefresh.sh /etc/shibboleth/
$ chown root:root /etc/shibboleth/siterefresh.sh
$ chmod 754 /etc/shibboleth/siterefresh.sh

Configure the variables highlighted in red in the script according to your own installation:

SHIB_HOME: The home directory of Shibboleth SP 1.3.
Typically: /opt/shibboleth-1.3, /usr/local/shibboleth-1.3 or /usr (if using the Debian package libapache2-mod-shib)
SHIB_ETC: The directory which contains the Shibboleth SP configuration files.
Typically: /etc/shibboleth
SITEREFRESH: The path to the siterefresh binary
Typically: $SHIB_HOME/sbin/siterefresh or $SHIB_HOME/bin/siterefresh (if using the Debian package libapache2-mod-shib)
METADATA_URL: The download URL of the SWITCHaai Federation Metadata file.
METADATA_FILE: Local filename of the SWITCHaai Federation Metadata file.
SIGNER_CRT: Location of the SWITCHaai Metadata Signer X.509 certificate.

#! /bin/sh
#
# Copyright (c) 2007 SWITCH - The Swiss Education & Research Network
#
# siterefresh.sh: automatically download and verify the federation metadata
#
# SWITCHaai Federation Metadata (1.3)
#  http://www.switch.ch/aai/metadata/
# 
# SWITCHaai Metadata Signer certificate:
#  http://www.switch.ch/aai/downloads/metadata.crt
#
# Valery Tschopp - SWITCH - 20050909
# Patrik Schnellmann - SWITCH - 20080211

# Configure directories and path
SHIB_HOME=/usr
SHIB_ETC=/etc/shibboleth
SHIB_SCHEMA=$SHIB_HOME/share/xml/shibboleth
SITEREFRESH=$SHIB_HOME/bin/siterefresh
LOG_FILE=/var/log/shibboleth/siterefresh.log
BACKUPDIR=$SHIB_ETC/backup

# Configure metadata download URL and local filename
METADATA_URL=\
http://www.switch.ch/aai/federation/SWITCHaai/metadata.switchaai_signed.xml
METADATA_FILE=$SHIB_ETC/metadata.switchaai.xml

# Configure signer certificate
SIGNER_CRT=$SHIB_ETC/metadata.crt
if [ ! -r "$SIGNER_CRT" ] ; then
    echo "ERROR: Metadata Signer certificate $SIGNER_CRT not found"
    exit 1
fi

# OS specific support
case "`uname`" in
Linux*) linux=true;;
Darwin*) darwin=true;;
esac

if [ $# -gt 0 ] && [ "$1" != "-v" ]; then
    echo "Usage: $0 [-v]"
    exit 1
fi

if [ "$1" == "-v" ]; then
    VERBOSE=true
fi

# Export environment variables for siterefresh
LD_LIBRARY_PATH=$SHIB_HOME/lib
if $darwin; then
    export DYLD_LIBRARY_PATH=$LD_LIBRARY_PATH
else
    export LD_LIBRARY_PATH
fi

# export path variable
PATH="/bin:/usr/bin"
export PATH

NOW=`date +%Y%m%d%H%M`

# logging (verbose)
if [ $VERBOSE ]; then
    echo "$NOW: $0 starts" >> $LOG_FILE
fi

if [ ! -f "$METADATA_FILE" ] ; then
    touch "$METADATA_FILE"
fi

# Get new metadata file
if [ -f "$METADATA_FILE" ] ; then
    if [ $VERBOSE ] ; then
        echo "$NOW: siterefresh: $METADATA_URL -> $METADATA_FILE" \
            >> $LOG_FILE
    fi
    ${SITEREFRESH} \
        --url $METADATA_URL \
        --out $METADATA_FILE.$NOW \
        --schema $SHIB_SCHEMA \
        --cert $SIGNER_CRT >> $LOG_FILE 2>/dev/null
    ret=$?
    if [ "$ret" -ne "0" ] || [ ! -f "$METADATA_FILE.$NOW" ] ; then
        echo "ERROR: siterefresh of $METADATA_URL failed ($ret)"
        echo "$NOW: ERROR: siterefresh from $METADATA_URL failed ($ret)" \
             >> $LOG_FILE
        exit $ret
    fi
fi

# Make backups
if [ ! -d "$BACKUPDIR" ] ; then
    mkdir $BACKUPDIR
fi

# Compare new to existing. If same, delete new, if not replace existing
# and backup new.
if [ -r $METADATA_FILE.$NOW ] ; then
    if cmp -s $METADATA_FILE.$NOW $METADATA_FILE ; then
        rm -f $METADATA_FILE.$NOW
        echo "$NOW: unmodified $METADATA_FILE" >> $LOG_FILE
    else
        echo "$NOW: new $METADATA_FILE" >> $LOG_FILE
        METADATA_BASENAME=`basename $METADATA_FILE`
        cp -p $METADATA_FILE $BACKUPDIR/$METADATA_BASENAME.$NOW
        mv -f $METADATA_FILE.$NOW $METADATA_FILE
        echo "$NOW: new $METADATA_FILE installed" >> $LOG_FILE
    fi
fi

# logging (verbose)
if [ $VERBOSE ]; then
    echo "$NOW: $0 done." >> $LOG_FILE
fi

Test the script manually:
```
$ /etc/shibboleth/siterefresh.sh
```
Check the output of the script and its logs in /var/log/shibboleth/siterefresh.log.
Let cron periodically call the siterefresh.sh script i.e. install a cron job. Place a symbolic link to the script in /etc/cron.daily and cron will call the siterefresh script each day.
```
$ ln -s /etc/shibboleth/siterefresh.sh /etc/cron.daily/shib-siterefresh
```

Installation of the siterefresh Batch Script for Windows systems

Download the archive with the metadata signer certificate and the update script from http://www.switch.ch/aai/downloads/siterefresh.zip
and place metadata.crt and siterefresh.bat in C:\opt\shibboleth-sp\etc\shibboleth\ (or wherever it suits best for your environment).