Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

Uninstall

Removing Bouncer means removing its containers and data, its role on OpenBao, and the files on the server. It doesn't touch your secrets in OpenBao.

If you might want the records later, you'll take a final backup and approval log export at the end of step 2, so that they include the kill switch and the sign-outs.

1. End all access

On the server:

cd ~/bouncer/deploy/compose
docker compose exec bouncer bouncer-admin revoke --all

This is the kill switch: it ends every grant and asks OpenBao to revoke every token Bouncer issued. Check its report for any revoke it couldn't confirm.

2. Sign out the apps, and clean up requester machines

Do this while the server still runs, so each sign-out reaches it:

  • In each app, sign out. That revokes the device on the server. If someone can't do it now, they can just uninstall the app later.
  • On each requester machine, delete the key file (shred -u ~/.config/bouncer/key) and uninstall the CLI (Install the CLI).

Then, if you want the records, take the final backup and approval log export on the server, and copy them somewhere safe:

cd ~/bouncer/deploy/compose
BOUNCER_BACKUP_DIR=~/bouncer-backups ./backup.sh final
docker compose exec -T bouncer bouncer-admin log export > ~/bouncer-log-final.jsonl

3. Remove Bouncer's role from OpenBao

You need an OpenBao admin token. If you revoked the root token, get one the way you planned in OpenBao for Bouncer, step 5: your own admin login, or a new root token made from the unseal shares.

Run this from the machine with the role kit (on the Bouncer server itself, that's ~/bouncer/deploy/openbao-role-kit, which step 5 deletes, so do this first):

export BAO_ADDR=https://openbao.example.com:8443
bao login                   # your admin token, unless BAO_TOKEN is already set
cd ~/bouncer/deploy/openbao-role-kit
./teardown.sh --resources resources

It first runs the emergency stop, then deletes the kit's token roles, Bouncer's AppRole and its mount, and the kit's policies, and checks nothing is left. It never touches your KV mounts or secrets. If you used the kit's scoped admin policy, it prints one last command to run with a full admin token (deleting Bouncer's identity entity), and exits 2.

If you used SSH host resources, remove the separate SSH signer too, in this order:

  1. On every host, remove Bouncer's CA trust (Retire a host).

  2. From the same role-kit folder, run:

    ./ssh/setup-ssh.sh --teardown
    

    It needs the matching kit.env, ssh/ssh-resources, the bao CLI and an OpenBao admin login with the SSH kit's permissions. It removes the signer's AppRole mount, policy and CA signing roles. The CA mount stays.

  3. Once no host trusts the CA, remove its mount too:

    ./ssh/setup-ssh.sh --teardown --remove-ca
    

These SSH teardown commands are checked against deploy/openbao-role-kit/ssh/setup-ssh.sh; this sequence has not been run for the manual. Neither command removes trust from destination hosts for you.

4. Stop and remove the containers and data

On the server:

cd ~/bouncer/deploy/compose
docker compose down -v

-v deletes the database volume. Without it, the database stays on the machine.

Then remove the image and, if you set them up, the backup timer and HTTPS front end:

docker image rm localhost/bouncer-server:local   # release download: localhost/bouncer-server:<short commit>
sudo systemctl disable --now bouncer-logical-backup.timer
sudo rm -f /etc/systemd/system/bouncer-logical-backup.service /etc/systemd/system/bouncer-logical-backup.timer \
  /usr/local/libexec/bouncer-backup
sudo systemctl daemon-reload
sudo tailscale serve --https=443 off

5. Remove the files on the server

sudo sh -c 'shred -u /etc/bouncer/secrets/*'
sudo rm -r /etc/bouncer/secrets /etc/bouncer/config
rm -r ~/bouncer

The sh -c matters: your own user can't read the secrets folder (it belongs to the server's user, 10001, with mode 0700), so the * must be expanded by a shell running as root. Written as sudo shred -u /etc/bouncer/secrets/*, your own shell can't expand it, shred fails, and the next line would delete the files without overwriting them first.

For a download installation, remove the release folders under ~/bouncer-releases once you no longer need their kit settings or rollback files.

Keep or delete ~/bouncer-backups and /var/backups/bouncer as you decide.

What stays behind

Personal credentials made in the app stay in OpenBao under their storage area's prefix. Removing the database deletes their ownership records. Delete those values in OpenBao if you no longer need them.

Values that requesters read while Bouncer was running stay valid wherever they were copied. If you are retiring Bouncer because of a suspected compromise, rotate those secrets at their source.

How this was checked

The role kit's teardown.sh was run against our sandbox OpenBao, and docker compose down -v removed our test stack. The shred line was checked in a throwaway container, with a root-only secrets folder and an admin user with sudo: the old form failed with failed to open for writing: No such file or directory and left the files, and the sh -c form removed them. The whole page wasn't run in this order against one server.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).