Overview

The Jetty Base plugin creates an environment within which you can easily manage one or more Jetty installations to run the Shibboleth IdP and provides a baseline configuration and scripts to help with Jetty service management on both Windows and Linux/etc. systems.

Jetty itself typically runs out of an unmodified distribution folder referred to as JETTY_HOME, while its configuration is stored in a folder tree called JETTY_BASE. This plugin provides scripts to download and manage the former, and files to bootstrap the latter. Notably, this plugin does not include the Jetty software itself; scripts are supplied to help download, verify, and stage Jetty distributions but the plugin will only require updating when the baseline configuration examples change or when new Jetty versions require brand new configuration sets, as happens occasionally.

Unlike most plugins, this one does not modify the IdP configuration or inject any extension code into it; it does however install content to your IdP installation folder, including new scripts into the existing bin folder and various new directories for storing Jetty and its configuration. By design it is self-contained but does provide examples and scripts for help with managing Jetty as a service, particularly on Windows.

Supported Jetty Versions

The plugin currently supports:

• Jetty 12.0.x

• Jetty 12.1.x

Generally speakiing, the plugin will at any given time support all patch releases of one or more Jetty major/minor branches. Officially, it supports only Jetty versions that are under open source maintenance by the Jetty Project, and not any that have reached their public EOL stage (see https://jetty.org/download.html).

Initial Plugin Installation

For a detailed guide on how to install plugins, see https://shibboleth.atlassian.net/wiki/spaces/IDP5/pages/3199500688

Supplied Configuration Details

Some specifics on the configuration we provide:

• The Jetty configuration tree is currently targeted at Jetty 12.1 (though it is so far unchanged from the work done for 12.0). Future plugin versions will support later versions of Jetty as required, while retaining support for Jetty 12.1 for as long as it remains supported, so as to allow migration to future Jetty versions. In other words the plugin supports side-by-side Jetty installations, both within and across Jetty branches.

• The jetty-base configuration as delivered:

  • is designed to run under a constrained user account with limited access to the filesystem, though unavoidably it must be able to read all of the IdP’s configuration.

  • listens on the IPv4 loopback network interface only, as an initial precaution; this is easily changed to expose it to the network when desired

  • listens on Jetty’s default ports, 8080 and 8443; running on privileged ports on anything but Windows will typically require additional steps beyond just adjusting the ports.

  • generates a dummy TLS certificate as a placeholder for you.

  • is directed to log to the IdP’s existing logs directory using the exact logging libraries shipped with the IdP. (These libraries will be updated as the IdP updates them.)

• On Linux, the provided shell scripts:

  • download, signature check, and unpack Jetty (you specify the version to grab and you can download multiple versions as required).

  • TBD: manage symbolic links to Jetty and the configuration to support side by side installation and use.

  • start Jetty, provided the appropriate symbolic links exist or you supply your own environment variables (see below).

• On Windows, the provided batch files:

  • download, signature check, and unpack Jetty (you specify the version to grab and you can download multiple versions as required).

  • download, signature check, and unpack Procrun (used to run Jetty as a Windows system service).

  • start Jetty at the console.

  • setup the (global) environment so as to control the versions of Jetty, Procrun and which Jetty configuration to use.

  • configure procrun to setup the Windows system service.

The result is an “install, download, and go” setup to run the IdP, excluding many value-added features Jetty has that may be required in particular cases. The intention is to allow you to add additional Jetty modules and features as you would if installing Jetty by hand.

For Windows, this is a replacement of the ‘MSI’ Jetty installer which will be retired during the lifetime of V5.2 of the IdP and not provided with IdP V6 in the future.

Directory Structure

The installation and scripts currently create 2 directories below idp.home:

• jetty-base-12

  • This is populated by the plugin installation. One of the files is a reserved one that may be altered by the plugin in the future, but the rest are protected configuration files you may modify to suit your needs in the future. Of course we cannot guarantee Jetty will work after such changes.

• jetty-dist

  • This is where the various versions of Jetty (and Procrun on Windows) are downloaded and unpacked. Nothing here should ever be modified by hand and should be restoreable simply be repeating the download step(s).

  • The Jetty working file location (its “tmp” folder) is also located under here to avoid the need for Jetty’s process to write to its configuration tree.

The rest of the plugin’s installed files are mostly added to bin and almost of those are read-only scripts.

Environment

The shell/batch scripts that the plugin supplies expect 3 (4 on Windows) environment variables to be set, and most of them tend to have suitable defaults if not otherwise set:

On Windows, batch files are supplied to set these values globally (and in the context of the current command shell). Additionally, the setjettybase.bat batch file makes the requisite changes to the Procrun configuration.

Elsewhere, we assume symbolic links are used to point the rest of the scripts at the proper locations without constantly requiring updates to the environment, but you are also free to manage the variables yourself. A stub is added to bin/jettyenv.sh for this purpose and this file will not be altered by upgrades.

The plugin does not yet contain scripts for managing symbolic links but this is planned.

Initial Use

Downloading Jetty

Use the dowloadjetty script with an appropriately current version, for example:

Environment Setup (Windows)

On Windows you can use these batch files to set the variables noted earlier:

Symlink Setup (Non-Windows)

Pending the inclusion of tools to assist, you can establish the assumed symbolic links via:

This isn’t an absolute requirement, but our default paths in various other places assume these paths.

Network Settings

If you need to adjust the default networking for Jetty, you can review and edit the settings in jetty-base-12/shibboleth.ini, which contains a number of commented (and few explicit) Jetty properties used by the standard Jetty modules controlling http and https usage, most notably near the beginning where the ports and hosts (i.e., network interfaces) are controlled.

While we default the ports, the network interfaces are explicitly overridden to 127.0.0.1 only. If you are not proxying from another web server on the same host platform, you will likely want to eventually comment out the jetty.ssl.host property to let it default to 0.0.0.0 and be exposed to external traffic.

Privileged Ports (Non-Windows)

If you need Jetty to listen directly on priviliged ports (80/443 presumably), the simplest way to do this now is with systemd (see below). Our unit file example includes the AmbientCapabilities command needed to allow this at runtime.

If you’re not using systemd, you would need to look into other options that have previously been suggested over the years:

• Jetty comes with a setuid module you can use via --add-module=setuid

• You can forward traffic via the system firewall from those ports.

• Of course, you could run it as root.

• Many others…

Initial Testing

You can run Jetty (and by extension, the IdP) by using the runjetty.sh or runjetty.bat commands depending on OS. This will start Jetty from the command line, and in the non-Windows case will cause Jetty to fork itself into the background as a pair of running processes that you can subsequently stop via the kill command.

With Jetty running, you should immediately be able to run the status command and then set up your IdP.

As noted above, you will need to specify the non privileged port used as default. On Linux:

On Windows you can do the same

But you may chose to set up the default ports (443 and 8443) by editing the`shibboleth.ini` file.

Production Startup Scenarios

Use with systemd (Non-Windows)

Our plugin is designed to facilitate the use of systemd, which has spread to most major Linux distributions these days, particularly the ones we support. We provide a suitable unit example in jetty-base-12/jetty.service that works with our installed run script, bin/runjetty.sh

To install it:

1. Adjust the unit file to meet your needs in a couple of areas:

   1. Set the User and Group appropriately.

   2. Adjust the paths if necessary; the defaults assume our IdP and plugin defaults.

   3. If you are not using Jetty on any privileged ports, you can remove the AmbientCapabilitiesline.

2. Copy the file into your system as root and reload:

   cp jetty-base-12/jetty.service /etc/systemd/system/ systemctl daemon-reload

You should be able to manage the Jetty daemon with standard commands at that point.

Running as a System Service (Windows)

The plugin provides additional support for running Jetty as a Windows system service, but this requires additional steps.

Firstly download a current version of Procrun and establish the environment:

Then use the provided batch file bin/config-jetty.bat to control the Shibboleth Daemon definition. The first parameter describes what to do and must be one of INSTALL, UNINSTALL, or EDIT (must be in upper case).

INSTALL [Username]

This command:

• Declares and configures a Service called “shibd_idp”

  • If you specify Username you will be prompted for a password and the service will run as that user.

  • Otherwise the service runs as the low(ish) privileged “LocalService” account.

• Opens the firewall for this service to receive traffic

• Sets ACLs over the IdP and Jetty directories

• Starts the service

Running this command is a one-off; that is to say, once this is done, you need never do it again. Updating the plugin will not change this configuration, but, again, ensure that the service is stopped (sc.exe stop shibd_idp) before updating the plugin or changing the relevant environment to adjust the versions of anything.)

This command has largely the same effect as running the legacy MSI installer.

UNINSTALL

This command deletes the service and its configuration.

It does not remove the firewall changes nor does it change the ACLs.

EDIT

This is a shortcut to start the Procrun Monitor Application. This replaces (and is the same executable as) the shibd_idpw executable installed by the old MSI installer.

Updating From an MSI-Based Jetty Installation (Windows)

As mentioned above the plugin is not forward-compatible with an existing MSI-based install. However the limited configuration available via the MSI install makes moving forward quite simple:

1. Uninstall the existing MSI Jetty installation.

2. Install the plugin as per above.

3. Execute the bin/downloadjetty.bat script to download the desired Jetty version.

4. Review the start.d/shibboleth.ini file against the contents of idp.ini in your old jetty-base tree. Note that logback-related configuration, if any, can be ignored as that is already put into place for you via the plugin.

5. Perform the Windows Service INSTALL step (see the previous section).

6. Test.

7. Finally, remove the old/saved jetty-base configuration.

Ongoing Maintenance

Updating Jetty Patch Versions

This documentation will always address exactly which Jetty major and minor versions are supported and compatible with the plugin. The plugin will be updated when and if the embedded configuration baseline becomes incompatible or unsuited to newer versions. Within those constraints, the plugin is designed to help you download and migrate to new releases as desired and to facilitate side by side testing.

To update to a supported patch version:

1. Stop the Jetty instance running the IdP.

2. Download the new Jetty version using the downloadjetty.sh or downloadjetty.bat command script in the bin folder.

   1. Note that you may need to update the truststore if the signature used to sign Jetty artifacts changes and we have not yet updated the plugin to ship the newer keys.

3. Set the environmental variable (bin/setjettyhome.bat on Windows) or adjust the jetty-home symbolic link as applicable.

4. Restart Jetty and test.

Updating the Plugin

Updating the plugin is not required to update Jetty patch versions but may be required at times to update an existing Jetty configuration baseline (in the case of regressions in Jetty) or to accomodate new minor or major Jetty versions. We will communicate these cases via the usual channels.

Assuming the plugin must be updated:

1. Stop the Jetty instance running the IdP.

2. Review any relevant release notes.

3. Update the plugin:

   # Windows bin/plugin.bat -u net.shibboleth.idp.plugin.jetty # Elsewhere bin/plugin.sh -u net.shibboleth.idp.plugin.jetty

In some if not most cases, such an update is likely to add an additional Jetty configuration suitable for use with a previously unsupported (or even unreleased) Jetty version in a new subdirectory named jetty-base-XX where XX will usually be a Jetty major version. This configuration will not be modified based on any existing changes you may have made to the previously supplied configuration examples and is a new baseline on which to apply your changes.

The plugin will not download the newer Jetty release for you either, though the usual download process will apply.

Updating Procrun (Windows only)

1. Stop the shibd_idp service (sc stop shibd_idp).

2. Download the new version of Procrun using the bin/downloadprocrun.bat command.

3. Adjust the environment using the bin/settprocrunversion.bat command.

4. Restart the shibd_idp service (sc start shibd_idp).

Deleting Old Versions

Once you no longer need a version of Jetty or Procrun you can delete them from the jetty-dist folder freely. The software does not track the contents of that folder other than to make use of it when your environment or symbolic links directs it to.

Command Scripts

Troubleshooting

TBD