Install OpenBao on Debian and enable the UI
Goal: a persistent OpenBao server with TLS, integrated Raft storage, audit logging and the built-in web UI. This guide uses the upstream Debian package and its systemd unit, not a development-mode server.
See the series overview for architecture and example names. Next: administration and recovery.
1. Prepare the server
On a fresh Debian 12/13 server, you need sudo access, private DNS/networking, accurate time, disk space and a TLS certificate. The example server is bao.lab.example at 10.10.10.20.
cat /etc/os-release
dpkg --print-architecture
timedatectl status
sudo apt update
sudo apt install ca-certificates curl gnupg jq openssl
Before starting OpenBao, allow TCP 8200 only from your management/VPN network and intended application hosts in your existing firewall. Do not expose 8201 to clients; it is for Raft peers. Binding to a private IP does not replace firewall rules.
Existing installation? Stop here first
The configuration below replaces the package's example configuration and selects Raft storage. Do not apply it blindly to an existing server: changing storage paths/backends does not migrate data. Take backups and use the upstream migration procedure instead.
2. Download and verify the Debian package
The official downloads page provides .deb files. This example pins 2.7.2; intentionally choose a supported release instead of automatically following latest. It supports amd64 and arm64 below.
Run as your regular sudo-capable user:
VERSION=2.7.2
ARCH=$(dpkg --print-architecture)
case "$ARCH" in
amd64|arm64) ;;
*) echo "Choose an upstream package for architecture: $ARCH"; exit 1 ;;
esac
WORKDIR=$(mktemp -d)
cd "$WORKDIR"
PACKAGE="openbao_${VERSION}_linux_${ARCH}.deb"
BASE="https://github.com/openbao/openbao/releases/download/v${VERSION}"
curl -fLO "$BASE/$PACKAGE"
curl -fLO "$BASE/checksums.txt"
curl -fLO "$BASE/checksums.txt.gpgsig"
curl -fLO https://openbao.org/assets/openbao-gpg-pub-20240618.asc
gpg --show-keys --fingerprint openbao-gpg-pub-20240618.asc
Confirm the primary signing-key fingerprint against the official verification instructions, ideally through an independent trusted channel:
If the project rotates its key, verify the new fingerprint upstream; do not ignore a mismatch. Then verify the signature before trusting the checksum:
gpg --import openbao-gpg-pub-20240618.asc
gpg --verify checksums.txt.gpgsig checksums.txt
sha256sum --ignore-missing --check checksums.txt
Require a valid signature and an OK result for the exact .deb you downloaded. A checksum without an authenticated checksum file is not publisher verification.
The package provides /usr/bin/bao, the openbao service account, /etc/openbao/openbao.hcl and /etc/openbao/openbao.env. Inspect the installed service rather than creating a second one. Local .deb installation does not configure an automatic APT update feed; schedule verified package upgrades yourself.
3. Install TLS material
Obtain a server certificate from your internal CA or a trusted public CA. It must contain bao.lab.example in its subjectAltName, include server authentication usage, and have a matching private key. Include the IP SAN only if clients will connect by IP. Supply intermediates in fullchain.pem; clients separately trust the root CA.
On the server, using your actual certificate source paths:
sudo chown root:openbao /etc/openbao
sudo chmod 0750 /etc/openbao
sudo install -d -o root -g openbao -m 0750 /etc/openbao/tls
sudo install -o root -g openbao -m 0640 /secure/source/fullchain.pem /etc/openbao/tls/fullchain.pem
sudo install -o root -g openbao -m 0640 /secure/source/privkey.pem /etc/openbao/tls/privkey.pem
sudo -u openbao test -r /etc/openbao/tls/fullchain.pem
sudo -u openbao test -r /etc/openbao/tls/privkey.pem
sudo openssl x509 -in /etc/openbao/tls/fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
The package can initially assign /etc/openbao to the service account; making its parent directory root-owned prevents the daemon from replacing root-controlled configuration/TLS entries. Recheck ownership after upgrades.
Do not use a real private key in a Git-tracked config. Automate renewal and copy renewed material with these permissions. With unchanged file paths, sudo systemctl reload openbao sends HUP to reload the certificate/key without a restart; validate the new certificate and check logs afterward. Changing listener paths or other startup-only settings requires a restart and unsealing. The service user must also be able to traverse parent directories.
For an internal CA, install the public root CA on each Debian CLI/Agent host:
sudo install -m 0644 /secure/source/kafana-root-ca.crt /usr/local/share/ca-certificates/kafana-root-ca.crt
sudo update-ca-certificates
Also import it into the browser's trust store where necessary. Browser CA trust and CLI BAO_CACERT are separate settings.
4. Configure persistent storage, TLS, UI and auditing
Create private writable data/log directories on the server:
sudo install -d -o openbao -g openbao -m 0700 /var/lib/openbao /var/log/openbao
sudo cp -a /etc/openbao/openbao.hcl /etc/openbao/openbao.hcl.package-backup
sudoedit /etc/openbao/openbao.hcl
Replace the fresh-install example config with this; substitute your server's actual IP and DNS name:
ui = true
api_addr = "https://bao.lab.example:8200"
cluster_addr = "https://10.10.10.20:8201"
storage "raft" {
path = "/var/lib/openbao"
node_id = "bao-1"
}
listener "tcp" {
address = "10.10.10.20:8200"
cluster_address = "10.10.10.20:8201"
tls_cert_file = "/etc/openbao/tls/fullchain.pem"
tls_key_file = "/etc/openbao/tls/privkey.pem"
tls_min_version = "tls12"
}
audit "file" "local-file" {
description = "Local audit log; ship to protected central storage"
options {
file_path = "/var/log/openbao/audit.json"
mode = "0600"
}
}
Raft requires cluster_addr even for one node. The declarative audit stanza is supported by current OpenBao; keep it consistent across nodes. Current releases restrict API-created audit devices by default, so there is no need to enable unsafe_allow_api_audit_creation here.
sudo chown root:openbao /etc/openbao/openbao.hcl
sudo chmod 0640 /etc/openbao/openbao.hcl
sudo -u openbao bao operator validate-config -config=/etc/openbao/openbao.hcl
Check the package's service includes MemorySwapMax=0. OpenBao's current hardening guidance prevents its process from swapping rather than copying older mlock/CAP_IPC_LOCK instructions. On systemd with cgroup v2, add a drop-in if needed:
sudo systemctl daemon-reload
sudo systemctl enable --now openbao
sudo systemctl status openbao --no-pager
sudo journalctl -u openbao -n 50 --no-pager
systemctl show openbao -p MemorySwapMax -p LimitCORE
Check the actual cgroup/kernel support and prefer encrypted swap as defense in depth. Avoid memory overcommit; disabling swap does not prevent an OOM kill. A running process can still be sealed: service status alone is not readiness.
5. Initialize once and unseal
On a trusted administrator workstation with bao installed (or a trusted shell on the server), configure the non-secret connection settings:
export BAO_ADDR=https://bao.lab.example:8200
export BAO_CACERT=/path/to/kafana-root-ca.crt
unset BAO_TOKEN BAO_SKIP_VERIFY
bao status
Omit BAO_CACERT if your CA is already trusted system-wide. bao status normally exits 2 while sealed; do not treat that as a network failure.
Unseal shares and the initial root token are recovery credentials
Arrange encrypted, offline custody before initialization. Never put all shares alongside the server, in Git, in its backups, or only inside OpenBao itself. Anyone holding the threshold can unseal the data; the initial root token has unrestricted access. Avoid recorded terminals and CI logs.
On a trusted, non-recorded terminal, initialize the new storage once:
Securely hand each share to its assigned custodian immediately and place the initial root token in protected temporary custody. For real deployments, prefer encrypting shares at creation with each custodian's public PGP key using -pgp-keys and -root-token-pgp-key; see operator init.
Three custodians each submit a different share through the hidden prompt:
Enter the initial root token at the login prompt. Do not pass shares or tokens as command-line arguments. Root is only for bootstrap: follow administration next to create and test named administrator access before revoking it.
With Shamir sealing, repeat unsealing after every restart. Do not reinitialize. Recovery keys for auto-unseal are a different concept; choose an independent seal provider and follow the seal documentation if automating this.
6. Open the web UI
Visit:
ui = true serves the UI on the same listener as /v1/ API traffic. No second web server, UI port, or container is needed. Restart and unseal after changing the ui startup setting.
- Confirm the browser trusts the certificate without bypassing warnings.
- If sealed, the UI can accept unseal shares too; use the same custody precautions.
- After creating named logins, choose Username & Password with auth path
userpass(or your configured OIDC/LDAP method). - Secret engines, auth methods and policies visible in the UI depend on that login's policy. Missing buttons do not automatically mean the UI is broken.
For access only through an SSH tunnel, a loopback-bound listener is possible. Use the original certificate hostname in the client URL with appropriate local name resolution so certificate SAN validation remains correct. Do not replace TLS with an HTTP listener bound to all interfaces.
If you add a reverse proxy later, proxy both /ui/ and /v1/ at the same origin, preserve the host/request headers, retain TLS to the upstream or an appropriately protected loopback connection, and set api_addr to the externally usable origin. Avoid caching API responses. This guide's direct TLS listener needs none of that.
Verify and troubleshoot
bao status
bao audit list
bao operator raft list-peers
curl -sS -o /dev/null -w '%{http_code}\n' "$BAO_ADDR/v1/sys/health"
This curl check uses system CA trust. If the root CA is only in a separate file, add --cacert /path/to/kafana-root-ca.crt; curl does not read BAO_CACERT automatically.
On this initialized, unsealed single node, expect Sealed: false, one Raft voter, local-file/ audit output and health HTTP 200. A sealed node typically returns 503, an uninitialized one 501; standby status codes differ in clusters.
| Symptom | Check |
|---|---|
| Connection refused | Service logs, configured private IP, DNS, firewall and listening socket |
| TLS unknown authority / hostname mismatch | Correct CA, intermediates and certificate SAN; do not skip verification |
| Cannot read TLS key | Owner/group, file modes, parent-directory traversal and systemd sandbox |
| Service is running, UI says sealed | Submit the unseal threshold; startup is not unsealing |
| Audit errors / requests fail | Log-directory permissions and available disk space; audit failures can block operations |
| API redirects to the wrong host | api_addr, DNS and proxy configuration |