sjat/boma

sjat 4ee1b66e23 Source vault password from Vaultwarden via rbw; nest vault structure

Master vault password is fetched from Vaultwarden via the rbw agent
(scripts/vault-pass-client.sh, wired as vault_password_file) instead of a
plaintext .vault_pass. Vault secrets use a nested vault.<service>.<key> map.
Encrypted vault.yml files are excluded from lint. Includes the host rename in
Makefile and STATUS.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-05-30 18:16:35 +02:00

3.2 KiB

Raw Blame History

Runbook — Vault secrets (setup & rotation)

The master vault password lives in Vaultwarden (item boma-ansible-vault) and is fetched on demand by scripts/vault-pass-client.sh through the rbw agent. It is never stored in a plaintext file on disk. See ADR-002.

One-time — `rbw` setup on a new machine

# Install rbw (Debian 13: try apt first, else cargo)
sudo apt install rbw || cargo install rbw

# Point it at the homelab Vaultwarden and log in
rbw config set base_url https://vaultwarden.baobab.band
rbw config set email <your-vaultwarden-email>
rbw login            # prompts for your Vaultwarden master password (+ 2FA if enabled)

# Unlock the agent (do this once per terminal session before vault operations)
rbw unlock

# Sanity check — should print the master vault password:
rbw get boma-ansible-vault

Once unlocked, make encrypt/decrypt/check/deploy and the pre-commit ansible-lint hook all obtain the password automatically. If the agent is locked you'll see a clear "run: rbw unlock" error rather than a hang.

Rotating a single secret value

Ensure the agent is unlocked: rbw unlock

Decrypt the relevant vault file:

make decrypt FILE=inventories/production/group_vars/all/vault.yml

Edit the value (keep the nested vault.<service>.<key> structure).

Re-encrypt:

make encrypt FILE=inventories/production/group_vars/all/vault.yml

Commit and deploy:

git add inventories/production/group_vars/all/vault.yml
git commit -m "Rotate <service> <key>"
make check PLAYBOOK=site   # verify what will change
make deploy PLAYBOOK=site

Rotating the master vault password

This re-keys every encrypted file from the old password to a new one. Order matters — re-key the files before updating Vaultwarden, or the fetch script will hand back the new password while the files are still encrypted with the old one.

Unlock the agent: rbw unlock (so the script can read the current/old password).
Generate a new password and write it to a throwaway file outside the repo:
```
umask 077; rbw generate --length 40 > /tmp/new_vault_pass
```

Re-key all vault files (old via the fetch script, new from the temp file):

find . -path ./.venv -prune -o -name vault.yml -print \
  | xargs ansible-vault rekey \
      --vault-password-file scripts/vault-pass-client.sh \
      --new-vault-password-file /tmp/new_vault_pass

Update the boma-ansible-vault item in Vaultwarden to the new password (paste the contents of /tmp/new_vault_pass), then re-sync: rbw sync.
Shred the temp file: shred -u /tmp/new_vault_pass (or rm -f).
Verify: make decrypt FILE=<a vault.yml> should still work, now via the new password. Commit the re-keyed files.

Rotate the master password when someone with access leaves, or if it is suspected compromised.

Access for additional people / machines

Access is granted in Vaultwarden — share the boma-ansible-vault item (or place it in a shared collection). Each person/machine then runs the one-time rbw setup above. To revoke access, remove the share in Vaultwarden and rotate the master password (above), since anyone who had it could have copied it.

3.2 KiB Raw Blame History