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
Everyday maintenance
Run these from ~/bouncer/deploy/compose on the server.
Common commands
| Task | Command |
|---|---|
| Status | docker compose ps |
| Logs | docker compose logs -f bouncer |
| Reload the config after an edit | docker compose exec bouncer bouncer-admin config reload |
Recreate and wait for health (needed for a new resource or an openbao change) | docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer |
| Stop everything | docker compose stop |
| Start again and wait for health | docker compose up -d --wait --wait-timeout 120 |
| Revoke a device | docker compose exec bouncer bouncer-admin device revoke <device-id> |
| Disable a requester | docker compose exec bouncer bouncer-admin requester disable <name> |
| The kill switch | docker compose exec bouncer bouncer-admin revoke --all |
| Re-confirm a standing grant | docker compose exec bouncer bouncer-admin grant review <grant-id> |
| Export the approval log | docker compose exec -T bouncer bouncer-admin log export --since 7d > log.jsonl |
docker compose down removes the containers but keeps the database. docker compose down -v also deletes the database, with every device, requester and the approval log. Don't use -v unless you mean it, and take a backup first.
Replace the OpenBao secret_id
Bouncer's secret_id expires. The role kit asks for 90 days, but OpenBao caps it at the AppRole mount's maximum lease time, which is 32 days unless you raised it (Install, step 2d). Replace it well before it expires, or at once if it may have leaked. Check the new secret_id's actual lifetime as in step 2d, and schedule the next rotation from that.
On the machine with your OpenBao admin token, note the secret_ids that exist now (by their accessors, which aren't secret), then make a new one into a file:
OLD=$(bao list -format=json auth/bouncer-approle/role/bouncer-server/secret-id | jq -r '.[]')
HANDOVER=$(mktemp -d)
(umask 077; bao write -f -field=secret_id auth/bouncer-approle/role/bouncer-server/secret-id > "$HANDOVER/bouncer-secret-id")
scp "$HANDOVER/bouncer-secret-id" admin@bouncer.example.com:
shred -u "$HANDOVER"/* && rmdir "$HANDOVER"
Bouncer reads the role_id and secret_id files only when it logs in to OpenBao again, not on every request, and a running login can stay valid after its secret_id is replaced. Compose also mounts each secret as a file, so a replaced host file can leave the running container reading the old one. So install the new file and recreate the container: that remounts the file and forces a fresh login.
In our test run, skipping the recreate left the old login working until its token was revoked or expired. After that, the server answered 503 backend_auth_failed (0.5.6 and later) until the container was recreated with the new file.
sudo install -m 0400 -o 10001 -g 10001 ~/bouncer-secret-id /etc/bouncer/secrets/bouncer-secret-id
shred -u ~/bouncer-secret-id
docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer
docker compose logs bouncer # look for "bouncer-server is up"
curl --fail --silent --show-error http://127.0.0.1:8080/v1/health
Check the result before you destroy anything. The log must show bouncer-server is up and no AppRole login error, and the curl must succeed. If the wait fails or times out, stop and read the log. If the new login fails, fix the secret_id file, its permissions or the AppRole settings, and recreate the container again. Keep the old secret_ids, and the $OLD list in your admin shell, until the new login works.
If you use SSH host resources, repeat these steps for the SSH signer's own secret_id. With the kit's default prefix, its AppRole path is auth/bouncer-ssh-approle/role/bouncer-ssh-signer and its configured secret file is /run/secrets/bouncer-ssh-secret-id inside the container. Replace the host file you mounted there, rather than bouncer-secret-id, and use the signer's AppRole path for both listing and destroying its old secret_ids. Keep its accessor list separate from $OLD.
Then, on the admin machine:
for a in $OLD; do
bao write auth/bouncer-approle/role/bouncer-server/secret-id-accessor/destroy secret_id_accessor="$a"
done
Change the database password
PostgreSQL reads the password file only when it first creates the database, so changing the file alone locks the server out. Change it inside PostgreSQL first, from a file, so the value never appears on screen, on a command line or in PostgreSQL's log:
NEW=$(mktemp -d)
(umask 077; head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' > "$NEW/bouncer-db-password")
{ echo "SET log_statement = 'none'; SET log_min_error_statement = 'panic';"
printf "ALTER ROLE bouncer PASSWORD '%s';\n" "$(cat "$NEW/bouncer-db-password")"
} | docker compose exec -T -u postgres postgres psql --quiet --set=ON_ERROR_STOP=1
sudo install -m 0400 -o 10001 -g 10001 "$NEW/bouncer-db-password" /etc/bouncer/secrets/bouncer-db-password
shred -u "$NEW/bouncer-db-password" && rmdir "$NEW"
docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer
docker compose logs bouncer # look for "bouncer-server is up"
Between the ALTER ROLE and the recreate, the server can't open new database connections, so do the steps together. Recreating remounts the password file; wait for health before continuing. If it fails, inspect both container logs. The kit's own test checked that the old password was refused and the new one stayed out of PostgreSQL's log; it passed in our run.
Standing grants and their reviews
If you allow standing grants (grants with no end time), each one is suspended when its review is due (90 days after it starts, by default, durations.always_review). The approvers' devices get a review_due event a week before. To keep it, re-confirm it:
docker compose exec bouncer bouncer-admin grant review grt_01jbx3n4q6s8t0v2w4x6y8z0a2
The Bouncer project hasn't decided the policy for standing grants yet. Keep them off. Re-confirming is an admin action, not a fresh approval from a device; it is logged as review_confirmed.
Updating the pinned base images
The PostgreSQL image (in compose.yaml) and the Rust and Debian images (in the Dockerfile) are pinned by digest, so they never change by themselves, and so they don't pick up security fixes by themselves either. Someone has to update the digests from time to time and rebuild. Nothing does this automatically yet.