Recovery and emergency stops
This page covers what to do when something is lost or may be compromised. Each section starts with the steps, then explains what they do and don't cover.
A lost or stolen device
A paired device can approve, and may also have displayed or copied values where policy allows it. Treat a lost device as able to approve until you revoke it, and rotate values that may have been exposed.
-
If you need to cut client access at once, stop your HTTPS front end or block client access to it. For a deployment using
tailscale serve, the command issudo tailscale serve --https=443 off. Use your proxy's own stop procedure otherwise. This needs neither Bouncer nor OpenBao, andbouncer-adminstill works. It does not revoke existing OpenBao tokens or copied values. -
Find and revoke the device:
docker compose exec bouncer bouncer-admin device list docker compose exec bouncer bouncer-admin device revoke <device-id>From then on the device can't sign in, approve, deny or see anything. Every standing grant it approved is ended, with its tokens. Time-limited grants it approved stay active until they end; the command lists them with their end times.
-
Decide about those time-limited grants. If you can't tell which approvals were genuine, run the kill switch, which ends every existing grant for everyone. Also suspend personal Always approved uses as described below:
docker compose exec bouncer bouncer-admin revoke --allRevoke the device before the kill switch. The kill switch alone leaves the device paired, so it could approve the next request.
-
Restore your HTTPS front end or access rule, if you stopped it in step 1. For
tailscale serve:sudo tailscale serve --bg --https=443 http://127.0.0.1:8080Then pair the replacement. The person's other devices get a "New device paired" alert.
-
Check the record from the time the device was lost:
docker compose exec -T bouncer bouncer-admin log export --since 2026-11-14T18:00:00Z > lost-device.jsonl
None of these steps can take back a secret a requester already read. If an approval on the lost device may not have been genuine, rotate the secrets it released (Copied secrets).
Lost admin access
In Bouncer, "admin" means whoever can run bouncer-admin on the server's machine. There's no separate admin account or password to lose.
| What's lost | What to do |
|---|---|
| The person who ran the server has left | Anyone with root on the server, or in its docker group, is the admin. Remove the person's shell and group access, then follow When someone leaves for their devices and requesters |
| Your shell access to the server | Regain it the way you would for any machine you own (console, hypervisor, cloud provider). Bouncer has no back door |
| The server itself | Build a new one from the install steps with a new secret_id, restore the latest database backup, and follow the restore procedure in full |
| The config file | Restore it from your Git repository. Without it you can rebuild it from memory, but instance.id must be exactly the old value, or every paired device stops working |
| The OpenBao admin token | Use the admin login you set up on OpenBao, or make a new root token from the unseal shares. With OpenBao 2.5.3 or later that needs a config change and restarts first: see Make a new root token. Bouncer itself never needs an admin token; only the role kit does |
Cut Bouncer off from OpenBao
Use both Bouncer's kill switch and the role kit's emergency stop if something is wrong with Bouncer itself. If you use SSH host resources, stop the separate SSH signer too, as below.
1. Bouncer's kill switch, on the server:
docker compose exec bouncer bouncer-admin revoke --all
It asks you to type yes (or pass --yes from a script), then ends every grant, cancels every pending request and asks OpenBao to revoke every token Bouncer issued. Check its report for any revoke it couldn't confirm. Expected result (from our test run):
Kill switch done. The cutoff committed at 2026-11-15T06:29:05Z: no token can be issued from before it.
Grants revoked: 0
Pending requests cancelled: 0
Tokens confirmed revoked: 0
Tokens OpenBao refused: 0
Tokens with no clear answer: 0
A secret value that was already read can't be recalled. Rotate any that may have been.
It exits 0 when OpenBao confirmed every revoke, and 10 when it didn't. Running it again is safe.
The kill switch ends grants that exist when you run it. It does not switch off Always approved on personal credentials: where allowed, a person's command-line key can get a new grant straight afterwards without a device. Suspend it for every storage area that allows it:
docker compose exec bouncer bouncer-admin personal suspend --namespace <namespace-id>
Then docker compose stop bouncer if you want the server off. To cut access off independently of Bouncer, use both applicable role-kit stops below.
2. The role kit's emergency stop, from the machine with your OpenBao admin token. The role kit (deploy/openbao-role-kit) is the set of scripts that created Bouncer's role on OpenBao. Its emergency stop doesn't need Bouncer at all, so it works even if the server is compromised or gone:
cd ~/bouncer/deploy/openbao-role-kit
export BAO_ADDR=https://openbao.example.com:8443
bao login # your OpenBao admin token
./emergency-stop.sh # asks for confirmation; --dry-run only prints
It destroys Bouncer's secret_ids, revokes Bouncer's logins and every token it issued, and empties the kit's policies. It needs the kit's resources file next to the scripts. Its exit code says what it found:
| Exit | Meaning |
|---|---|
| 0 | Bouncer is cut off. Nothing had been changed by hand, and everything was revoked |
| 1 | Not confirmed: Bouncer may still have access. Something had been changed by hand or couldn't be read, or a step failed. It has still done every step it could, and lists what it found and what to do |
| 2 | Bouncer is cut off, but some token roles named like the kit's (bouncer-issue-*) weren't the kit's, so it left their tokens alone. It lists them and how to revoke their tokens |
3. The SSH signer's emergency stop. If you use SSH host resources, stop the SSH signer too. Its separate OpenBao login is not touched by emergency-stop.sh. In the same kit folder, with BAO_ADDR set and an OpenBao admin login that has the SSH kit's permissions, run:
./ssh/setup-ssh.sh --emergency-stop
It destroys the signer's secret_ids, revokes its logins and empties its policy. Check its report: anything but exit 0 means the stop isn't confirmed. Exit 1 means it couldn't confirm, including when it found no signer under the current kit settings; exit 3 means it couldn't run with this token or OpenBao. Already signed certificates remain usable until expiry (300 seconds by default), or until a host installs the updated revocation list. To stop them on a host at once, remove the account's principals or the host's CA trust as in Retire a host. The SSH stop and re-enable sequence here is checked against deploy/openbao-role-kit/ssh/setup-ssh.sh; it has not been run for this manual.
Bouncer stays cut off until you set the role kit up again. In this order:
- Deal with what each stop reported: fix any problem that prevented it from running, revoke what it lists, and rotate the secrets those credentials could reach. Rerun any stop that wasn't confirmed.
./setup.sh --accept-unrevocable-tokens, which restores the kit's policies../setup.sh --forget-hand-edits, which clears the kit's record of what it found. After a stop that exited 0, run it straight away. After one that found something, run it only once you've dealt with every item in step 1: after this, nothing in OpenBao shows those findings any more, apart from its audit log.- Give Bouncer a new secret_id (Maintenance).
- If you stopped the SSH signer, run
./ssh/setup-ssh.shagain with the samekit.envandssh/ssh-resources. It restores the policy. Make a new signer secret_id as in step 3 of the kit'sssh/README.md, install it as/etc/bouncer/secrets/bouncer-ssh-secret-id, then recreate the container as in Maintenance, using the SSH signer's file instead. Replacing only Bouncer's token-login secret_id does not re-enable SSH.
The kit's README (deploy/openbao-role-kit/README.md, "Emergency stop") explains each step.
OpenBao recovery basics
| Situation | What to do |
|---|---|
| OpenBao restarted and is sealed | Unseal it with two of its three shares (OpenBao for Bouncer). Restarting it again won't help |
| OpenBao's data is lost | Restore the latest Raft snapshot on a fresh instance and unseal it with the source instance's shares (Backup and restore) |
| Unseal shares are lost (Shamir) | With fewer than the threshold of shares, the data can't be unsealed. Keep encrypted copies in more than one place, and test that you can reach them |
| TPM auto-unseal fails | Use your independently tested recovery plan and escrowed seal key. A complete auto-unseal recovery procedure is not published in this manual |
How this was checked
In our test run, device revoke, requester rotate-key, requester disable and the kill switch were run against the test server, and the outputs above are from that run. Later fake-data tests ran the role kit's emergency stop, its re-arm steps with a new secret_id, and sealing and unsealing a real OpenBao 2.7.2 dev sandbox. The SSH signer's stop, Raft recovery, lost unseal shares and TPM auto-unseal were not run.