Wikibot: Migrated from services/OPENBAO.md

2026-07-05T18:16:03Z

Migrated from services/OPENBAO.md

New page

''As of: 2026-07-05 — migrated from `services/OPENBAO.md`''

= OpenBao Secret Store =

Self-hosted Vault-API-compatible secret store. The canonical record for credentials used by Claude Code (MCP), shell scripts, and n8n workflows.

'''Vaultwarden remains the human-facing store.''' OpenBao is the machine-facing one. They mirror each other; on rotation, update both.

----

== Container & Files ==

{| class="wikitable"
|-
! Item
! Value
|-
| Container
| <code>openbao</code>
|-
| Compose
| <code>/library/openbao-app/docker-compose.yml</code>
|-
| Config
| <code>/library/openbao-app/config/openbao.hcl</code>
|-
| Storage
| <code>/library/openbao-app/data/</code> (Raft)
|-
| Init output
| <code>/library/openbao-app/.init-output.json</code> (chmod 600 — root token + unseal key)
|-
| Scripts token
| <code>/library/openbao-app/.scripts-token</code> (chmod 600 — used by <code>bao-get.sh</code>)
|-
| Claude token
| <code>/library/openbao-app/.claude-token</code> (chmod 600 — also embedded in <code>~/.claude.json</code>)
|-
| Auto-unseal
| <code>/usr/local/bin/openbao-unseal.sh</code> + <code>openbao-unseal.service</code> (systemd)
|-
| Helper script
| <code>/usr/local/bin/bao-get.sh</code>
|-
| n8n cred sync
| <code>/library/openbao-app/sync-n8n-creds.py</code> (timer: <code>sync-n8n-creds.timer</code>)
|-
| MCP binary
| <code>/usr/local/bin/vault-mcp-server</code> (HashiCorp v0.2.0)
|-
| '''VC sources'''
| <code>scripts/openbao/</code> in this repo — see <code>scripts/openbao/README.md</code> for deploy
|}

<syntaxhighlight lang="bash">
cd /library/openbao-app && docker compose up -d
docker logs --tail=50 openbao 2>&1 | grep -v "^chown\|Could not chown"
</syntaxhighlight>

----

== Ports & Endpoints ==

{| class="wikitable"
|-
! Port
! Purpose
|-
| 8200
| API + UI (HTTP, no TLS — internal only)
|-
| 8201
| Cluster (Raft consensus, single-node here)
|}

{| class="wikitable"
|-
! Endpoint
! URL
|-
| API (host)
| <code>http://localhost:8200</code>
|-
| API (LAN)
| <code>http://192.168.0.109:8200</code>
|-
| API (Tailscale)
| <code>http://100.64.207.155:8200</code>
|-
| API (n8n container)
| <code>http://172.29.0.1:8200</code>
|-
| Web UI
| <code>http://192.168.0.109:8200/ui</code>
|}

'''Not exposed publicly''' — no VPS nginx route, intentionally. UI is LAN/Tailscale only.

----

== Credentials ==

'''All in Vaultwarden → "Stronghold Infrastructure" folder.'''

{| class="wikitable"
|-
! Vaultwarden item
! Contents
|-
| OpenBao Unseal
| root token (<code>s.TqAL...</code>) + unseal key (<code>dHIJ...=</code>) in notes
|-
| OpenBao Tokens
| claude-mcp token (login.password) + scripts-n8n token (custom field)
|}

The init-output.json on stronghold has the same data — that's how <code>openbao-unseal.service</code> reads the unseal key at boot.

----

== Reading Secrets ==

=== From Claude Code (MCP) ===

Just ask: ''"fetch secret/ntfy from vault"'' or ''"what's the mxroute api-key?"'' — the <code>vault</code> MCP server (16 tools) handles it.

=== From shell scripts ===

<syntaxhighlight lang="bash">
bao-get.sh PATH FIELD
# e.g.
bao-get.sh ntfy token
bao-get.sh mxroute api-key
bao-get.sh authentik api-token
</syntaxhighlight>

Reads from <code>/library/openbao-app/.scripts-token</code>. Outputs the field value to stdout, no newline.

=== From curl (any host with LAN access) ===

<syntaxhighlight lang="bash">
TOKEN=$(cat /library/openbao-app/.scripts-token)
curl -sf http://localhost:8200/v1/secret/data/PATH \
-H "X-Vault-Token: $TOKEN" \
| jq -r '.data.data.FIELD'
</syntaxhighlight>

=== From n8n ===

HTTP Request node:
* Method: <code>GET</code>
* URL: <code>http://172.29.0.1:8200/v1/secret/data/PATH</code>
* Headers: <code>X-Vault-Token: <scripts-n8n token></code>
* Response field: <code>data.data.<field></code>

Or in a Code node:
<syntaxhighlight lang="javascript">
const resp = await this.helpers.httpRequest({
method: 'GET',
url: 'http://172.29.0.1:8200/v1/secret/data/mxroute',
headers: { 'X-Vault-Token': '<scripts-n8n token>' },
});
const apiKey = resp.data.data['api-key'];
</syntaxhighlight>

'''Recommended:''' store the scripts-n8n token as an <code>httpHeaderAuth</code> credential in n8n (header name <code>X-Vault-Token</code>) so workflows reference it by credential ID.

----

== Writing Secrets (via root token) ==

<syntaxhighlight lang="bash">
ROOT_TOKEN=$(jq -r .root_token /library/openbao-app/.init-output.json)

# kv put REPLACES the entire record — pass all fields you want kept
docker exec -e BAO_ADDR=http://127.0.0.1:8200 -e BAO_TOKEN="$ROOT_TOKEN" openbao \
bao kv put secret/PATH field1=value1 field2=value2
</syntaxhighlight>

For multiline values (private keys, certs), use the API directly:

<syntaxhighlight lang="bash">
python3 - << 'PY'
import json, urllib.request
payload = {"data": {"private-key": open('/path/to/key').read()}}
req = urllib.request.Request(
"http://localhost:8200/v1/secret/data/PATH",
method="POST", data=json.dumps(payload).encode(),
headers={"X-Vault-Token": "<ROOT_TOKEN>", "Content-Type": "application/json"})
print(urllib.request.urlopen(req).read())
PY
</syntaxhighlight>

----

== Secret Inventory ==

{| class="wikitable"
|-
! Path
! Fields
! Source-of-truth status
|-
| <code>secret/n8n</code>
| <code>api-key</code>
| OpenBao canonical; n8n's own auth is separate
|-
| <code>secret/mxroute</code>
| <code>server</code>, <code>username</code>, <code>api-key</code>
| OpenBao canonical
|-
| <code>secret/homeassistant</code>
| <code>token</code>, <code>host</code>, <code>port</code>
| OpenBao canonical; mirrored in n8n credential <code>R9LGxX...</code> and <code>4RowxM...</code>
|-
| <code>secret/ntfy</code>
| <code>token</code>
| OpenBao canonical; mirrored in n8n credential <code>w0gXpM...</code>
|-
| <code>secret/authentik</code>
| <code>api-token</code>
| OpenBao canonical
|-
| <code>secret/matrix</code>
| <code>zordon-token</code>
| OpenBao canonical; mirrored in n8n credential <code>x5tv5a...</code>
|-
| <code>secret/stalwart</code>
| <code>admin-password</code>
| OpenBao canonical
|-
| <code>secret/immich</code>
| <code>admin-api-key</code>, <code>user-api-key</code>
| OpenBao canonical
|-
| <code>secret/bitwarden</code>
| <code>client-id</code>, <code>client-secret</code>, <code>master-password</code>
| For <code>bw</code> CLI; also in <code>~/.config/claude/vaultwarden.env</code>
|-
| <code>secret/openai</code>
| <code>api-key</code>, <code>bearer-header</code>
| OpenBao canonical; mirrored in n8n credentials <code>NIQrbn...</code>, <code>XB0V2U...</code>
|-
| <code>secret/anthropic</code>
| <code>api-key</code>
| OpenBao canonical; mirrored in n8n credential <code>bEPlqP...</code>
|-
| <code>secret/audiobookshelf</code>
| <code>bearer-header</code>
| OpenBao canonical; mirrored in n8n credential <code>5MCzns...</code>
|-
| <code>secret/ssh-stronghold</code>
| <code>username</code>, <code>host</code>, <code>port</code>, <code>private-key</code>
| OpenBao canonical; mirrored in n8n credential <code>2ugS1i...</code>
|}

To list paths live: <code>bao-get.sh</code> doesn't support list — use the UI or:
<syntaxhighlight lang="bash">
ROOT_TOKEN=$(jq -r .root_token /library/openbao-app/.init-output.json)
docker exec -e BAO_ADDR=http://127.0.0.1:8200 -e BAO_TOKEN="$ROOT_TOKEN" openbao bao kv list secret/
</syntaxhighlight>

----

== Operational ==

=== Restart ===

OpenBao re-seals on every restart. The systemd service handles auto-unseal:

<syntaxhighlight lang="bash">
cd /library/openbao-app && docker compose restart
sudo systemctl start openbao-unseal.service
docker exec -e BAO_ADDR=http://127.0.0.1:8200 openbao bao status | grep Sealed
# Expected: Sealed: false
</syntaxhighlight>

Manual unseal (if the systemd unit fails):
<syntaxhighlight lang="bash">
/usr/local/bin/openbao-unseal.sh
</syntaxhighlight>

=== Backups ===

<code>/library/openbao-app/</code> is mounted into <code>restic-backup</code> as <code>/data/openbao:ro</code> and included in the nightly Hetzner restic backup. Both the Raft data '''and''' <code>.init-output.json</code> are backed up — restoring requires both (the unseal key would be lost otherwise).

=== n8n credential sync ===

n8n credentials are mirrored from OpenBao by <code>/library/openbao-app/sync-n8n-creds.py</code>. The script reads each managed credential's spec (n8n ID + OpenBao path + field mapping) from a <code>MAPPINGS</code> table, diffs against <code>n8n export:credentials --decrypted</code>, and runs <code>n8n import:credentials</code> only on drift. '''Match is by credential ID — never creates new credentials.''' Posts to <code>#notifications:wilsoz.com</code> on change.

<syntaxhighlight lang="bash">
/library/openbao-app/sync-n8n-creds.py --dry-run # preview drift
/library/openbao-app/sync-n8n-creds.py # sync all
/library/openbao-app/sync-n8n-creds.py --only ntfy_auth # one mapping
/library/openbao-app/sync-n8n-creds.py --quiet # cron-friendly
</syntaxhighlight>

Daily timer: <code>sync-n8n-creds.timer</code> (04:30 + 0–5 min jitter). Logs in <code>journalctl -u sync-n8n-creds.service</code>.

'''Rotation flow:''' update OpenBao → next nightly sync (or manual run) propagates to n8n. No workflow edits.

'''Adding a new mapping:''' append to <code>MAPPINGS</code> in the script. Must specify <code>n8n_id</code> (existing credential — create the credential in n8n UI first), <code>n8n_name</code>, <code>n8n_type</code>, <code>bao_path</code>, and a <code>build</code> lambda that returns the n8n <code>data</code> dict from the OpenBao field dict.

=== Token rotation ===

<syntaxhighlight lang="bash">
ROOT_TOKEN=$(jq -r .root_token /library/openbao-app/.init-output.json)
# Revoke old token
docker exec -e BAO_ADDR=http://127.0.0.1:8200 -e BAO_TOKEN="$ROOT_TOKEN" openbao \
bao token revoke <OLD_TOKEN>
# Mint new with same policy
docker exec -e BAO_ADDR=http://127.0.0.1:8200 -e BAO_TOKEN="$ROOT_TOKEN" openbao \
bao token create -policy=readonly-secrets -no-default-policy -ttl=0 -display-name="..."
</syntaxhighlight>

Update <code>~/.claude.json</code> (claude-mcp token) and <code>/library/openbao-app/.scripts-token</code> (scripts-n8n token) to the new values, then update Vaultwarden.

=== Adding a new secret path ===

<syntaxhighlight lang="bash">
ROOT_TOKEN=$(jq -r .root_token /library/openbao-app/.init-output.json)
docker exec -e BAO_ADDR=http://127.0.0.1:8200 -e BAO_TOKEN="$ROOT_TOKEN" openbao \
bao kv put secret/NEWPATH field1=value1
</syntaxhighlight>

The <code>readonly-secrets</code> policy uses <code>path "secret/data/*"</code> so new paths are immediately readable by claude-mcp and scripts-n8n tokens — no policy update needed.

----

== Gotchas (hard-won) ==

# '''Container runs as <code>user: "1000:1000"</code> (mnw).''' Without this, files on <code>/library/openbao-app/data</code> end up owned by UID 100 (<code>messagebus</code> on host) which is confusing.
# '''Must set <code>SKIP_CHOWN=1</code> and <code>SKIP_SETCAP=1</code> env vars.''' Without them, the entrypoint's <code>chown /openbao/logs</code> fails under <code>set -e</code> and the container restart-loops.
# '''<code>docker exec</code> to bao CLI needs <code>-e BAO_ADDR=http://127.0.0.1:8200</code>.''' The CLI defaults to https else and fails with "server gave HTTP response to HTTPS client".
# '''Sealed on every restart.''' Raft + Shamir means the box re-seals on container start. Auto-unseal via the systemd service. Don't delete <code>.init-output.json</code>.
# '''<code>bao kv put</code> replaces the whole record.''' Always pass all fields you want kept, not just the changed one.
# '''Multi-line values fail with <code>bao kv put</code> shell escaping.''' Use the HTTP API (curl/python urllib) directly for private keys, certs, etc.
# '''vault-mcp-server release binaries.''' GitHub releases page shows zero assets — download from <code>releases.hashicorp.com</code> instead (<code>https://releases.hashicorp.com/vault-mcp-server/0.2.0/vault-mcp-server_0.2.0_linux_amd64.zip</code>).
# '''<code>bao kv put field=@/path/to/file</code> reads from container fs, not host.''' Either copy the file into the container first or use the HTTP API.

----

== Related ==

* Setup plan (preserved for archaeology): <code>plans/openbao-setup.md</code>
* Memory note: <code>~/.claude/projects/.../memory/project_openbao.md</code>
* CLAUDE.md "OpenBao Secret Store" section

Services/OpenBao - Revision history

Wikibot: Migrated from services/OPENBAO.md