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

Everyday maintenance

Run these from ~/bouncer/deploy/compose on the server.

Common commands

TaskCommand
Statusdocker compose ps
Logsdocker compose logs -f bouncer
Reload the config after an editdocker 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 everythingdocker compose stop
Start again and wait for healthdocker compose up -d --wait --wait-timeout 120
Revoke a devicedocker compose exec bouncer bouncer-admin device revoke <device-id>
Disable a requesterdocker compose exec bouncer bouncer-admin requester disable <name>
The kill switchdocker compose exec bouncer bouncer-admin revoke --all
Re-confirm a standing grantdocker compose exec bouncer bouncer-admin grant review <grant-id>
Export the approval logdocker 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.

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