Page History

...

• Run the idp application installer from our customized binary distribution, available in /mit/touchstone/builds/NIST/idp2-cams/cams-shibboleth-identityprovider-2.x.y-bin.tgz, and the install script contained therein. For example:

  No Format
  # cd /tmp # rm -rf shibboleth-identityprovider-2.* # tar xzf /path/to/cams-shibboleth-identityprovider-2.1.5-bin.tgz # cd shibboleth-identityprovider-2.1.5 # ./install.sh [There should be no need to override the default responses to the installer's questions.]

  By default (because of one of our customizations to the stock Internet2 distribution) this will install under /usr/local/shibboleth-idp/. The installer will not overwrite the configuration files of an existing installation. For a new installation, the installer will generate a keystore, and prompt for its password; currently we do not use this keystore, so the password does not matter. This distribution contains the standard shibboleth-identityprovider binary distribution, from the Internet2 zip file (http://shibboleth.internet2.edu/downloads/shibboleth/idp/latest/), plus the following customizations:
  • camslogin
    This provides the custom login pages for CAMS users. It is available as a tarball (/mit/touchstone/builds/NIST/idp2-cams/camslogin.tgz) which is unpacked into the top-level directory of the binary distribution.
  • CamsLoginModule (cams-jaas-loginmodule-x.y.jar)
    This is the JAAS login module for CAMS. It is available as a .jar file in /mit/touchstone/builds/NIST/cams-jaas-loginmodule-x.y.jar, where x.y is the version number (currently 1.0). It must be copied into the lib subdirectory of the binary distribution.
  • camsutil-1.0.jar
    This is a helper package used by the login module to validate the username/password. It is available in /mit/touchstone/builds/NIST/camsutil-1.0.jar. It must be copied into the lib subdirectory of the binary distribution along with the login module jar file.
• The installer will create and populate /usr/local/shibboleth-idp; the web application (war) file will be in /usr/local/shibboleth-idp/war/idp.war, but the current version of the idp.war will be available in the locker (/mit/touchstone/builds/NIST/idp2-mit/idp.war).
• The idp application, running under Tomcat, needs full access to the install directory, so make sure it is owned by the tomcat user, e.g.:

  No Format
  # chown -R tomcat:tomcat /usr/local/shibboleth-idp

  To ensure that we run the current version of the web application, download the latest idp.war file from the touchstone locker (/mit/touchstone/builds/NIST/idp2-mit/idp.war) and copy it into /usr/local/tomcat/webapps/:

  No Format
  # cp /path/to/idp.war /usr/local/tomcat/webapps/ # chown tomcat:tomcat /usr/local/tomcat/webapps/idp.war

• Copy the idp's endorsed jar files to tomcat's endorsed dir:

  No Format
  # mkdir -p /usr/local/tomcat/endorsed # cp -p /usr/local/shibboleth-idp/lib/endorsed/*.jar /usr/local/tomcat/endorsed/ # chown -R tomcat:tomcat /usr/local/tomcat/endorsed

• Copy in the idp config files for the server, to the conf subdirectory; these include:
  • attribute-filter.xml
  • attribute-resolver.xml
  • handler.xml
  • internal.xml
  • logging.xml
  • login.config
  • relying-party.xml
  • service.xml
  • tc-config.xml (for terracotta clustering)

Terracotta

(See https://spaces.internet2.edu/display/SHIB2/IdPCluster^{Image Added})

The terracotta software is used to cluster the IdP nodes. Each node must run the terracotta server, as well as the instrumented client (tomcat, in our case). The terracotta server operates in either the active or passive role; only one server should be in the "active/coordinator" state at a time.

Download the terracotta tarball; our current version is in the touchstone locker, in /mit/touchstone/downloads/terracotta-x.y.z.tar.gz. Extract it under /usr/local, create a logs directory for it, make it owned by the tomcat user, and symlink /usr/local/terracotta to it. For example (replace 3.1.1 with the appropriate terracotta version number):

# cd /usr/local
# tar xzf /path/to/terracotta-3.1.1.tar.gz
# mkdir -p terracotta-3.1.1/logs
# chown -R tomcat:tomcat terracotta-3.1.1
# rm -f terracotta
# ln -s terracotta-3.1.1 terracotta

The IdP requires the installation of a couple of Terracotta Integration Modules, and the generation of a boot jar file for Tomcat, which is specific to the Java version:

# setenv TC_HOME /usr/local/terracotta-3.1.1
# setenv TC_INSTALL_DIR $TC_HOME
# setenv JAVA_HOME /usr/java/default
# $TC_HOME/bin/tim-get.sh install tim-vector 2.5.1 org.terracotta.modules
# $TC_HOME/bin/tim-get.sh install tim-tomcat-6.0 2.0.1
# $TC_HOME/bin/make-boot-jar.sh -f /usr/local/shibboleth-idp/conf/tc-config.xml

Be sure to regenerate this jar after installing a new JDK.

Install the init script from /mit/touchstone/maint/shibboleth-idp/terracotta/terracotta.init in /etc/init.d, and make sure it is configured to start at boot time. Note that terracotta must be started before tomcat.

# cp /path/to/terracotta.init /etc/init.d/terracotta
# chmod 755 /etc/init.d/terracotta
# chkconfig --add terracotta

To avoid performance impact during business hours, we disable automatic garbage collection of terracotta objects. Instead, we run a nightly cron job to do the garbage collection manually. Since this should only be done on the active/coordinator node, the script, run-dgc-if-active.sh, checks the server mode, then runs the garbage collector if and only if the server is the active node. Both the script and cron file can be obtained in /mit/touchstone/maint/shibboleth-idp/terracotta/; install as follows:

# cp /path/to/run-dgc-if-active.sh /usr/local/shibboleth-idp/bin/
# cp /path/to/run-dgc.cron /etc/cron.d/run-dgc