Installing the Shibboleth SP from RPM

The Shibboleth project officially provides up-to-date RPMs for the supported Linux platforms (this is currently a tautology, as we define "supported" to mean "we provide RPMs"). These packages are mirrored by a very limited set of distribution sites that we are happy to add to (contact us if you wish to host one).

A special note applies to Red Hat Enterprise Linux (RHEL) 7 and probably all future versions: because of Red Hat's licensing restrictions, it's not as cost effective to target RHEL 7 directly. However, CentOS 7 and Rocky 8+ are identical systems, and the packages for them work on the equivalent RHEL versions, so RHEL 7 deployments should rely on the CentOS 7 package repository and going forward to 8+, the Rocky repositories should be used.

For other RPM-supporting Linux versions, you can usually rebuild the SRPM packages.

Use the Correct RPM or not at all

Under no circumstances should you attempt to install a set of RPM packages built for/with a different OS or version from your own (apart from the CentOS/RHEL exception noted above). This will usually lead to unpredictable problems and support issues. Instead, you can rebuild the SRPM packages.

Incompatibility with RHEL / CentOS 7.0-7.3

Red Hat and CentOS 7.4 included a newer version of OpenSSL than 7.0-7.3, and the official packages don't support versions older than 7.4.

Installing via Yum

The supported approach is to add a yum repository referencing the Shibboleth Project mirror sites alongside your existing OS-supplied repository. This allows you to manage the Shibboleth packages in a standard way and pick up updates using a single command.

For RHEL, the CentOS team provides some material on using yum.

To get a copy of the appropriate repository file for your system, see https://shibboleth.net/downloads/service-provider/RPMS/ for a simple drop down form that will generate a copy for you. Per the note above, RHEL 7 systems must use the CentOS 7 repository.

If you run into problems, the best first step is to repeat that step and see if you need to make any adjustments to the repository definition to deal with whatever transitory issue(s) might be affecting the situation. If that doesn't work, it's very likely that there's nothing wrong the project can fix, and you should expect a response to that effect if you ask. If anything could be done, it already would have been.

Installation varies by OS, but usually you just drop the definition file into a directory such as /etc/yum.repos.d. You can turn the repository on and off by adjusting the "enabled" property in the file, such as to prevent automated updates and maintain manual control. While enabled, the yum command will "see" the Shibboleth packages when you perform standard operations, and installing the SP should require only a single command:

32 bit OS
$ yum install shibboleth
64 bit OS
$ yum install shibboleth.x86_64

Be careful of accidentally installing both the 64-bit and 32-bit version on a 64-bit server. The yum repository contains both versions for some OSs and the OS will think it can install both.

After Installation

The RPM installation process will place various components of Shibboleth in appropriate default directories based on your operating system's file system layout. Typically:

  • Shibboleth configuration files will be placed at /etc/shibboleth and the necessary Apache configuration in /etc/httpd/conf.d/shib.conf

  • shibd will be installed to /usr/sbin and may be managed using service and chkconfig (on System V platforms) or with systemctl (on systemd platforms, some additional information available).

  • An version of mod_shib.so appropriate to the OS-supplied Apache and other pluggable modules will be installed to /usr/lib/shibboleth on a 32-bit OS and /usr/lib64/shibboleth on a 64-bit OS.

Basic Configuration

  1. In httpd.conf:

    • Use of the <RequestMap> feature is not needed for use with Apache, but if you must, its use absolutely requires that the UseCanonicalName Apache directive be set.

    • Ensure that the ServerName directive in each virtual host is properly set, including overriding the scheme or port as required by any load balancing, proxying, or offloading you may be doing.

  2. Restart Apache.

  3. /usr/sbin/shibd must be independently started and run in order to handle requests. The daemon should be loaded and monitored along with all other major services.

  4. By default, the Shibboleth module is configured to log information to the local syslog, with a subset also to the Apache error log.

  5. The shibd service creates its own separate logs in /var/log/shibboleth. This is the most important log used for debugging anything regarding the SP and most problems manifest here rather than on the web server side.