Skip to content

OpenBao: secrets for the Kafana lab

OpenBao is an open-source secrets manager: one place to control who can read credentials, issue short-lived credentials, and audit access. The command-line tool is bao; the built-in web UI uses the same API and permissions.

This how-to series starts with a Debian 12/13 server, then connects Linux users and Docker workloads. Examples follow the official OpenBao 2.7.x documentation, with 2.7.2 as the pinned installation example (checked November 2026). Review current releases and security advisories before deploying.

Pick a guide

Guide What you will build
Install on Debian and enable the UI Verified Debian package, systemd service, TLS, persistent Raft storage, initialization and unsealing
Administration and recovery Named administrators, policies, audit-log rotation, backups, restore planning and upgrades
KV secrets and everyday examples Versioned API tokens, database passwords, registry credentials, SSH keys and scoped access
SSH certificates for Linux A signing CA and 15-minute certificates for a non-root deploy account
Docker secrets and example project AppRole → OpenBao Agent → secret files → Docker Compose, plus a Swarm handoff example

Start with installation → administration → KV secrets. SSH and Docker are independent integrations after that foundation.

How the pieces fit

Human administrator / CLI / browser
              │ TLS + a named login
              ▼
     Debian OpenBao server
     ├── Auth methods: userpass, AppRole (or OIDC/LDAP)
     ├── Policies: allowed API paths and operations
     ├── Secrets: KV v2, SSH signing CA, other engines
     ├── Raft: encrypted persistent data
     └── Audit: request/response records
              │ TLS + narrow workload policy
              ▼
       Agent on a Docker host
              │ renders files
              ▼
       Container /run/secrets/*

OpenBao is not a passwordless replacement for trust: users and workloads still need an initial authentication method. AppRole's SecretID, TLS private keys, backup access and unseal shares all need protection outside the secret store.

Example names

Replace these consistently throughout the series:

Example Meaning
bao.lab.example / 10.10.10.20 OpenBao server DNS / private IP
https://bao.lab.example:8200 API and UI origin
secret/ KV v2 mount
secret/team/demo A human-managed example secret
secret/apps/docker-demo The Docker application's secret
ssh-client-signer/ SSH certificate engine
deploy A restricted Linux account on authorized SSH targets

Commands use Bash. sudo commands modify the machine identified by the section; bao commands run on an administrator workstation unless stated otherwise. Linux root and an OpenBao root token are different privileges.

A single node is not high availability

This is a persistent, TLS-enabled single-server baseline, not a complete production architecture. A reboot requires manual unsealing with the Shamir setup, and a server failure makes OpenBao unavailable. For critical workloads, plan a three- or five-voter Raft cluster across failure domains, independent monitoring, tested recovery and a suitable auto-unseal mechanism. Never use bao server -dev for real secrets.

Good habits from day one

  • Restrict port 8200 to intended users/workloads over a private network or VPN. The UI exposes the API too.
  • Port 8201 is cluster traffic: allow only peer nodes, not browsers or containers.
  • Keep TLS verification enabled. Trust your internal CA; do not use BAO_SKIP_VERIFY or curl -k as a fix.
  • Bootstrap with the initial root token, create named administrator access, test it, then revoke root.
  • Use separate read-only application policies; do not give containers a human administrator token.
  • Keep secret values out of Git, shell arguments, .env, logs, screenshots and build layers.
  • Static KV values do not expire or rotate at their upstream provider merely because you delete them in OpenBao.

Official references

These pages adapt upstream workflows to the Kafana lab; the upstream documentation remains the version-specific reference.

Related Kafana pages: Linux, SSH basics, systemd.