6.5.19 EZproxy

EZproxy has no built-in template. It is a PEM Cert+Key+Chain deployment with the three destination paths set to a numbered certificate in the EZproxy ssl directory, plus a post-deploy script that restarts the service. This guide covers the file layout EZproxy expects, the one-time active change, and the restart script for Windows and Linux.

This applies to self-hosted EZproxy. OCLC manages the certificate for hosted EZproxy libraries.

How EZproxy stores certificates

EZproxy keeps every certificate it knows about in the ssl subdirectory of its install directory (C:\Program Files\ezproxy\ssl on Windows, /usr/local/ezproxy/ssl on Linux). Each certificate is a set of files sharing an eight-digit, zero-padded number:

A file named active (no extension) holds the number of the certificate EZproxy serves, without leading zeros. If it contains 99, EZproxy loads 00000099.crt, 00000099.key, and 00000099.ca at service start.

The number must be exactly eight digits. Each certificate created or imported through the admin page takes the next number, so a server that has been through a few renewals may already have twenty or more entries.

Choose a number and point active at it

CertKit overwrites one set of files in place on every renewal rather than adding a new entry each time. Pick a number well above anything the admin page has used (99 is a safe choice) and set the deployment’s three destinations to that number:

The PEM Cert+Key+Chain format writes the server certificate alone to the certificate path and the intermediates to the chain path, which matches how EZproxy separates .crt from .ca. Do not use PEM+KEY or PEM All-in-one, since EZproxy expects the chain in its own file.

After the first deployment, edit active so it contains only the number (for example 99), then restart EZproxy. This is a one-time change. Every later renewal overwrites the same three files and the restart script picks them up.

CertKit does not write a .cnf file, so the entry may show as damaged on the Manage SSL (https) certificates page and cannot be opened or activated from there. EZproxy still serves it. Leave the entry alone in the admin page and manage it from CertKit.

Restart script (Windows)

EZproxy reads certificate files only at startup. Add this PowerShell as the post-deploy script:

# EZproxy: restart the service so it loads the new certificate files
$serviceName = "ezproxy"

$service = Get-Service -Name $serviceName -ErrorAction Stop
Restart-Service -Name $serviceName -Force -ErrorAction Stop
$service.WaitForStatus("Running", [TimeSpan]::FromSeconds(60))

Write-Host "EZproxy restarted. Serving certificate $certThumbprint"

Get-Service fails the deployment with a clear error if the service name is wrong, and WaitForStatus fails it if EZproxy does not return to Running within a minute. In both cases the files are already on disk, so a manual net stop ezproxy and net start ezproxy completes the deployment.

The service is named ezproxy on a default install. Confirm with Get-Service *ezproxy* if the install was customized.

Linux

The same layout applies under the install directory, usually /usr/local/ezproxy/ssl. Set the three destinations to /usr/local/ezproxy/ssl/00000099.crt, .key, and .ca, and use this post-deploy script:

# EZproxy: restart so the new certificate files are loaded
cd /usr/local/ezproxy && ./ezproxy start

./ezproxy start is OCLC’s documented restart command. If EZproxy runs under a systemd unit or init script on this host, use that instead (systemctl restart ezproxy) so process supervision stays intact. If EZproxy runs as a dedicated user, set the deployment’s Owner and Permissions options so that user can read the three files.

Service interruption

The restart drops active proxied connections for a few seconds. Use a deployment window outside library hours so patrons are not interrupted mid-session.

Verify the first deployment

After the first renewal, confirm from outside the server that the login port serves the new certificate:

openssl s_client -connect ezproxy.example.edu:443 -servername ezproxy.example.edu </dev/null 2>/dev/null | openssl x509 -noout -dates -serial

Add the login hostname to monitoring and CertKit repeats this check on its own, alerting when the served certificate stops matching the one it issued.

For a product overview, see certificate automation for EZproxy.