Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.
On this page
Keep SSH revocations up to date
An SSH host needs Bouncer's revocation list, called a KRL, to reject a certificate before its expiry. This page installs the supplied pull script and systemd timer on a Linux destination host. It assumes the SSH issuer and the host's resource are already set up with the SSH role kit, and that you have the host's CA and account changes ready but not yet turned on. You turn them on in step 4, after the first fetch.
The timer tries every 15 seconds. Delivery depends on a successful fetch and on the host's SSH daemon reading the installed list. Bouncer cannot confirm that each host has received a revoke. A session already open stays open after revocation or certificate expiry.
Before you start
Use a disposable host and fake accounts for the first check. You need:
- the matching server deployment kit, including
deploy/ssh-krl/, from the release you install (Get Bouncer); - root access to the destination host, with Bash, curl,
ssh-keygenand systemd available, and an independent way to administer it; - a working SSH host resource,
its separate OpenBao signer login, and the host's reviewed CA and account
configuration. The kit's
deploy/openbao-role-kit/ssh/README.mdcovers the issuer setup. A principal is an account name, not a host restriction: use a distinct non-root account name for each host; - HTTPS connectivity from the host to Bouncer, with the correct server name
and trusted certificate issuer. Use
BOUNCER_CA_FILEfor a private CA. No particular VPN is required; - access to
bouncer-adminon the Bouncer server to create a requester for this host. It uses the local admin socket, not the host's network login.
The host-trust helper mentioned in the role kit README is
scripts/ops/ssh-host-trust.sh in a matching source checkout. It is not
included in the server deployment kit. The host's CA and account trust need
separate preparation; installing these KRL files alone does not establish it.
Check the host's effective SSH configuration, including its Match blocks.
RevokedKeys must name /etc/ssh/bouncer/revoked.krl for the connections
that use Bouncer certificates. A setting in another matching block can
select a different file or turn this check off. Keep your existing admin
session and recovery route open while changing SSH trust.
Fetch a valid KRL before enabling that trust. If RevokedKeys names a
missing or unreadable file, OpenSSH refuses every public-key login, not only
Bouncer certificates. An empty placeholder with no working delivery does
not provide early revocation.
The names below are examples: resource web1-deploy, host requester
web1-krl, and destination web1.example.com. Use the host and account
recorded in your own inventory.
1. Give the host its own requester key
On the Bouncer server, in the Compose directory, capture just the key in a private file:
(umask 077; docker compose exec -T bouncer bouncer-admin requester add web1-krl --kind host > web1-krl.key)
The explanation goes to standard error; only the key goes to the file. Transfer that file to the destination host over your existing trusted admin route. On the destination host, as root:
install -d -m 700 /etc/bouncer
install -m 600 web1-krl.key /etc/bouncer/krl-host.key
Remove the transfer copies once the installed file is checked. Keep the key out of command arguments, chat and tickets. The pull script accepts key-file modes 600 or 400.
Only an active requester of kind host can fetch the revocation list. Being a host doesn't limit what the key can do: it can also ask for access to any resource whose policy allows it. If this host only fetches revocations, check each resource's requesters list and leave this requester out. A resource with no requesters list, or with "*", lets any requester ask.
2. Install the files and settings
On the destination host as root, from the unpacked kit's root directory:
install -m 755 deploy/ssh-krl/bouncer-krl-pull /usr/local/sbin/
install -m 644 deploy/ssh-krl/bouncer-krl.service deploy/ssh-krl/bouncer-krl.timer /etc/systemd/system/
install -m 600 deploy/ssh-krl/krl.env.example /etc/bouncer/krl.env
install -d -m 755 /etc/ssh/bouncer
Edit /etc/bouncer/krl.env so it has these values. The example file has the
same settings, plus an admin-socket option that applies only on the Bouncer
server's own machine. The requester key itself stays in its separate file:
BOUNCER_URL=https://bouncer.example.com
BOUNCER_KEY_FILE=/etc/bouncer/krl-host.key
BOUNCER_KRL_FILE=/etc/ssh/bouncer/revoked.krl
BOUNCER_KRL_MAX_AGE=120
# BOUNCER_CA_FILE=/etc/bouncer/server-ca.pem
The service loads this file with systemd's EnvironmentFile. Running the
pull script by hand does not load it automatically. Use the service for
the first fetch so it uses the same settings as the timer.
The deploy/ssh-krl/README.md in the 0.5.5 and 0.5.6 kits runs the pull script
directly for the first fetch. That does not load /etc/bouncer/krl.env, so
it stops with set BOUNCER_URL, reports STALE and does not enable the
timer. Follow the steps on this page instead. The README correction in
source is included from 0.5.7.
3. Fetch once, then enable the timer
On the destination host as root:
systemctl daemon-reload
systemctl start bouncer-krl.service
/usr/local/sbin/bouncer-krl-pull --check
Stop if the service fails or the freshness check is stale. Inspect its log before continuing:
journalctl -u bouncer-krl.service --since "10 minutes ago"
A successful fetch installs or retains a valid KRL and records its version
and fetch time. --check fetches nothing: it checks the local last-success
record. With the default paths and 120-second limit above, it must exit 0
and report a fresh fetch. It does not test the running SSH daemon.
Run by hand, --check uses the script's defaults, not krl.env. If you
change BOUNCER_KRL_MAX_AGE or the state folder there, base your monitoring
on the service's failures, which use your settings.
Only after that first fetch succeeds:
systemctl enable --now bouncer-krl.timer
systemctl list-timers bouncer-krl.timer
Verify the timer has a next run, the service keeps succeeding, and the KRL stays readable by the SSH daemon. The service runs once and exits, so between runs it shows as inactive even when it is working. Inspect its result and log, not just whether it is currently active.
4. Turn on the host's CA and account trust
Only after the first fetch succeeds, apply the host's CA and account trust
as the role kit README describes, with ssh-host-trust.sh or by hand, and
reload the SSH daemon. Keep your existing admin session open. Then check
the effective settings again, including Match blocks, as described under
Before you start, and log in once with a Bouncer
certificate before relying on it.
Check a revoke and its limits
From the requester's machine, use a fake host resource and account first:
bouncer ssh web1-deploy --to web1.example.com --reason "Check the SSH evaluation host" -- id -un
bouncer grants --resource web1-deploy --id-only
bouncer revoke <grant-id>
Use the grant ID from your own check. A committed revoke stops Bouncer
issuing another certificate for that grant. For certificates already issued,
the normal output says NOT confirmed. This output was captured with fake
data in the isolated check described below, with example identifiers substituted:
Grant grt_example is revoked as of 2026-11-17T23:38:44Z. No new tokens can be issued for it.
SSH certificate iss_example_1, due to expire 2026-11-17T23:43:43Z: NOT confirmed: it's in Bouncer's revocation list, and each host refuses it once it has fetched that list (normally within 15 seconds)
SSH certificate iss_example_2, due to expire 2026-11-17T23:43:43Z: NOT confirmed: it's in Bouncer's revocation list, and each host refuses it once it has fetched that list (normally within 15 seconds)
2 token(s) weren't confirmed revoked. They still expire on their own by the times shown.
With bouncer --json revoke <grant-id>, each affected entry in credentials
has "outcome": "unknown" and
"pending": "krl_delivery". Neither output confirms host enforcement. With
an unconfirmed certificate, bouncer revoke exits 10 even though the grant
cutoff committed. Inspect the report rather than treating that exit as a
failed cutoff.
Check the host service's log for successful fetches after the revoke and
run /usr/local/sbin/bouncer-krl-pull --check there. This checks delivery
freshness. It does not by itself prove that the running SSH daemon rejects a particular
certificate. Repeating bouncer ssh creates a fresh key and asks Bouncer
again, so that alone does not test a previously issued certificate either.
A full host-enforcement check needs an isolated test with that certificate.
The CLI's "normally within 15 seconds" is how often the host's timer tries to fetch the list when it can reach the server. It isn't a deadline, and it isn't a confirmation.
A host that can't reach Bouncer keeps the last list it installed. In 0.5.6, hosts are also stuck on their last list while OpenBao is sealed, out of reach, or refusing the login of Bouncer or of its SSH signer. In that case, if Bouncer and its database are up, the revoke still takes effect in Bouncer, but hosts can't fetch the new list until OpenBao recovers. Bouncer answers their fetches with HTTP 503, or HTTP 500 if it can't read the CA key. This comes from the source, and wasn't tested in the isolated run. From 0.5.7, Bouncer stores every SSH CA public key it has read, so hosts can fetch newly committed revokes while OpenBao is down, including after Bouncer restarts, as long as Bouncer and its database are up. An installation that has never read the CA, including one just upgraded from 0.5.6 that hasn't read it yet, can't serve a list until OpenBao answers once. In 0.5.5, a server that starts or restarts while OpenBao is unavailable stops instead, so hosts get no answer from it at all.
From 0.5.7, Bouncer records a CA rotation the next time it reads the CA public key successfully. It logs a warning, and the approval log export gets an ssh_ca_changed entry naming the old and new public-key digests. Bouncer keeps every CA public key it has seen, and every revoked grant stays in the list for each of them. The serial numbers of replacement certificates apply only to the CA that issued them. After upgrading, let Bouncer read the CA once before you rotate it: older serial records are tied to the first CA it reads. Bouncer can't rebuild a CA it never saw. Updating which CA a host trusts is always a deliberate step for the host's owner.
The revoke report from that release also includes krl_available while list delivery is pending. false means Bouncer can't build the list at the moment, and the CLI says so instead of estimating when hosts will fetch it. true means a list can be built, not that any host has fetched or enforced it. Older servers leave the field out.
Until a host installs a list that names them, or they expire, certificates that were already issued can still start new logins on that host. Neither the list nor expiry ends a session that's already open.
Monitor and recover delivery
Alert on bouncer-krl.service failures and stale fetches. The default
maximum age is 120 seconds. --check exits 2 if nothing has ever been
fetched or the last successful fetch is too old. A failed fetch keeps the
installed KRL; becoming stale does not automatically close SSH access.
From 0.5.7, BOUNCER_KRL_STALE_POLICY=keep makes this
existing behaviour explicit in krl.env. It is the default and only supported
policy: retain the last good list, report STALE and exit 2 after the freshness
limit. A misspelled policy exits 64. A revoke committed since the last good
fetch waits for the next successful fetch or certificate expiry.
| Symptom | What to check |
|---|---|
| No connection or a TLS error | Bouncer's address, DNS, the chosen network path, and whether the server's certificate name and issuer are trusted. Set BOUNCER_CA_FILE when needed |
| A local key-file error | The configured key path, readability and mode (600 or 400) |
| HTTP 401 or 403 | The key, the requester's enabled state and its host kind. Replace a lost or exposed key through the admin route |
| HTTP 404 | In 0.5.6: no SSH signer is configured. From 0.5.7: no signer is configured and no CA public key has been stored. Check the server's SSH settings |
| HTTP 500 | An error on the server, such as a database problem in 0.5.6 or a failure to read the CA key. Check the server's log with docker compose logs bouncer |
| HTTP 503 | In 0.5.6: Bouncer or OpenBao isn't ready. From 0.5.7: PostgreSQL is unavailable, or Bouncer has never read its SSH CA public key and OpenBao can't supply it. Follow When Bouncer is unavailable. The host keeps its installed list, and certificates missing from it keep working until the next successful fetch or until they expire. To stop Bouncer logins on a host sooner, delete the account's principals file under /etc/ssh/auth_principals/, or remove its trust as in Retire a host |
| An older KRL version is refused | Find out whether the server or its database was restored, and reconcile revokes made since the backup. The script keeps its newer installed list. Only after an intended restore or rollback, follow Reset host version state. Do not clear it just to silence an unexplained error |
| Fresh fetches, but a revoked certificate still logs in | Confirm which RevokedKeys the running SSH daemon uses for that connection, including Match blocks, and test with the same certificate. A fresh fetch alone is not an SSH configuration check |
After fixing the cause, start bouncer-krl.service again and repeat the
freshness and timer checks. If you change its environment file, the next
service run reads it; if you change the unit files, run systemctl daemon-reload
first.
Retire a host
The KRL file goes last, because an SSH daemon that still names a missing
RevokedKeys file refuses every public-key login.
-
Find the SSH daemon that serves logins. Keep your admin session open. Before running the host-trust helper, find the process ID of the daemon serving logins with
ss -ltnp | grep sshd, as root. Ifssh.serviceorsshd.serviceis active, the helper tries those units first. Runsystemctl show -p MainPID ssh.service sshd.serviceand check that one of them shows the same process ID. If neither is active, check the SSH daemon's PID file:sshd -T | grep -i pidfileThe named file must hold the process ID of the daemon serving logins. The helper does not check either identity.
-
Remove the host's Bouncer CA and account trust, then reload the daemon. If you applied the trust with
ssh-host-trust.sh, runssh-host-trust.sh --rollbackas root. It reloads the SSH daemon before it stopsbouncer-krl.timerand removes the CA and KRL. It keeps the KRL and exits 1 if the daemon could still be reading it. If you made the change by hand, first delete the account's principals file under/etc/ssh/auth_principals/, which stops Bouncer certificates at once without a reload. Then remove theTrustedUserCAKeys,RevokedKeysandAuthorizedPrincipalsFilelines you added, and reload the SSH daemon. -
Check CA trust and list references are gone. Check that no SSH configuration file still names Bouncer's CA or list. This should print nothing:
grep -rn 'bouncer/trusted-user-ca.pub\|bouncer/revoked.krl' /etc/ssh/sshd_config /etc/ssh/sshd_config.d/Check the effective settings for both the Bouncer account and your independent recovery account with
sshd -T -C user=<account>,host=<client name>,addr=<client address>. Include every connection detail yourMatchblocks test. Neithertrustedusercakeysnorrevokedkeysmay name a file under/etc/ssh/bouncer/. If you omit a detail aMatchblock tests, sshd skips that block, so the check can look clean when it isn't. Stop here if rollback fails or you cannot verify the listening daemon has stopped using those files. Keep the KRL and delivery working until the cause is fixed. The by-hand retirement commands are checked against the source; this sequence hasn't been run as written. -
Only after step 3 succeeds, stop delivery and remove the host's copy of the list, Bouncer's CA key and the host's requester key. If the helper already did part of this, these commands change nothing:
systemctl disable --now bouncer-krl.timer rm -f /etc/ssh/bouncer/revoked.krl /etc/ssh/bouncer/trusted-user-ca.pub /etc/bouncer/krl-host.keyBefore closing your admin session, open a new SSH session with your independent recovery key. If it is refused, restore an empty list at once from the open admin session:
install -m 644 /dev/null /etc/ssh/bouncer/revoked.krlAn empty list revokes nothing. It is safe here only because step 2 removed the principals files, so no Bouncer certificate can log in even if the running daemon still trusts Bouncer's CA. If a principals file for that CA is still in place, delete it first; otherwise a revoked certificate that hasn't expired could log in again. Other logins still go through the daemon's normal checks. Find which daemon or setting still names the KRL file, correct it, and test a new recovery login before proceeding or closing your admin session.
-
On the Bouncer server, disable the host's KRL requester:
docker compose exec -T bouncer bouncer-admin requester disable web1-krl
How this was checked
This procedure is checked against the source: the kit's pull script, service and timer, release packaging, host-trust checks, CLI and revoke report. 0.5.7 keeps the SSH CA public keys it has read and adds explicit stale-policy configuration and the report field described above; the hardened service and timer are unchanged. The initial 14 KRL pull checks passed with fake keys and a local stub server. The expanded 19 checks also pass, including the stale setting and deliberate restore reset with the installed list kept on fetch failure.
On 18 November 2026, a separate test run with fake data exercised the KRL procedure and its SSH issuer and account-trust prerequisites in a disposable Debian container with systemd as PID 1. It used a real OpenBao 2.7.2 dev sandbox, the built 0.5.6 server and CLI candidate, and the unmodified shipped pull script, hardened service and timer. Fake TLS, local transfers and a software stand-in for an approving device supplied the fixtures.
The same certificate was accepted before delivery and refused after the timer installed its revoke, with 285 seconds of validity left. An existing session stayed open. The default freshness limit detected staleness at 121 seconds; delivery failures, recovery and retirement also passed. The HTTP 503 check used a forwarder fault, not an OpenBao outage. These are observations from that isolated run, not a delivery deadline. This procedure hasn't been run on a real host or with the real apps.
Further isolated checks ran this chapter's commands and the kit README's commands from the source after 0.5.6, where the README is fixed. They created a requester, installed its key and fetched the first list, starting from clean states. The README in the 0.5.5 and 0.5.6 kits was not run. They also tested missing-KRL refusal and recovery. A separate check with an offline fake CA removed the principals file first in the retirement procedure while leaving the old daemon settings loaded. The empty-list undo restored the independent recovery login while the same revoked, unexpired certificate stayed refused. The listener and service PID examples were also run. That focused SSH check did not run Bouncer or OpenBao.
A further source build containing the changes now labelled 0.5.7 passed the existing
end-to-end systemd test with fake data on 18 November. Built before the
version bump, it still reported 0.5.6+33. OpenBao was stopped
and Bouncer restarted into that outage. New issuance was refused without
adding an issuance record. The timer delivered a committed revoke and the
same certificate was refused with 283 seconds left, while a session
that was already open kept working. After OpenBao recovered, an outage in the host's
connection to Bouncer's list endpoint left its installed list, version and
freshness record unchanged. The default 120-second limit
reported STALE at 121 seconds; scheduled recovery installed a newer list and
refused the same certificate with 171 seconds left. A separate recovery
login confirmed that the refusal wasn't sshd penalising the test's source
address. Retirement and
missing-list recovery also passed, and the development host's state was
unchanged after teardown. Automated server checks separately cover a fresh
start with no observed CA, an upgraded installation before its first CA
read, and audited rotations. These were isolated source builds and automated
tests.