OpenBao Setup Guide
This guide covers setting up OpenBao for use with Frappe Vault.
What is OpenBao?
OpenBao is an open-source fork of HashiCorp Vault, created after HashiCorp changed Vault's license from MPL-2.0 to BSL in 2023. It is governed by the Open Source Security Foundation (OpenSSF) and maintains API compatibility with Vault OSS v1.14.x.
- License: MPL-2.0 (Mozilla Public License 2.0)
- CLI Command:
bao(instead ofvault) - Environment Variables:
BAO_ADDR,BAO_TOKEN(also supports legacyVAULT_ADDR,VAULT_TOKEN)
Installation
See the official OpenBao installation guide for the latest instructions.
macOS (Homebrew)
brew install openbao
FreeBSD
pkg install openbao
Linux (Manual Download)
OpenBao does not yet have a Linux package repository. Download packages manually from the GitHub releases page:
# Example for Ubuntu/Debian (amd64)
VERSION="2.4.4" # Check for latest version
wget https://github.com/openbao/openbao/releases/download/v${VERSION}/bao-hsm_${VERSION}_linux_amd64.deb
sudo dpkg -i bao-hsm_${VERSION}_linux_amd64.deb
Container Images
OpenBao provides pre-built container images:
# Alpine-based (recommended)
docker pull quay.io/openbao/openbao:latest
# or
docker pull ghcr.io/openbao/openbao:latest
# or
docker pull docker.io/openbao/openbao:latest
# RHEL UBI-based
docker pull quay.io/openbao/openbao-ubi:latest
Precompiled Binaries
Download the appropriate binary for your system from the releases page, unzip, and place the bao binary on your PATH.
Development Setup
For development, use the automated setup command:
bench setup-openbao
This interactive command will:
- Create OpenBao configuration with static seal (auto-unseal on restart)
- Add
bench run-openbaoto your Procfile - Configure audit logging
Then start your bench:
bench start
On first start, OpenBao will automatically:
- Initialize itself
- Save the root token to your site config(s)
- Enable the kv-v2 secrets engine
- Display the recovery key (save this somewhere safe)
No manual configuration required! The token is automatically saved to both common_site_config.json and any site-specific configs.
Resetting OpenBao
To start fresh (deletes all secrets):
bench setup-openbao --reset
bench setup-openbao
bench start
Legacy Dev Mode
You can still run OpenBao in dev mode for quick testing, but data is lost on restart:
bao server -dev -dev-listen-address=127.0.0.1:8200
This outputs a root token to use in your site config. Warning: Dev mode should never be used in production.
Production Setup
OpenBao v2.4+ supports static seal auto-unseal, which allows OpenBao to automatically unseal on startup using a symmetric AES-256 key. This is the recommended configuration for Frappe deployments managed by Supervisor, as it ensures OpenBao remains available after bench restart.
Quick Setup (Recommended)
The easiest way to set up OpenBao is to use the Frappe Vault CLI, which creates all configuration files in your bench's config/ directory:
bench generate-seal-key
This creates:
config/openbao.hcl- OpenBao configuration fileconfig/openbao-seal.key- Static seal key for auto-unsealconfig/openbao-data/- Data storage directory
The command outputs the supervisor configuration to add. See the command output for next steps.
Manual Setup
If you prefer to configure OpenBao manually or need a system-wide installation:
1. Generate Seal Key
Generate a 32-byte (256-bit) seal key:
# Option 1: Using the CLI (shows configuration options)
bench generate-seal-key
# Option 2: Using openssl directly
openssl rand -hex 32
2. Choose Configuration Location
Option A: Bench Config Directory (Recommended)
Store OpenBao config alongside your bench. No sudo required.
- Config:
~/frappe-bench/config/openbao.hcl - Seal key:
~/frappe-bench/config/openbao-seal.key - Data:
~/frappe-bench/config/openbao-data/
Option B: System Directory
Traditional system-wide installation requiring root access.
- Config:
/etc/openbao/config.hcl - Seal key:
/etc/openbao/seal.key - Data:
/opt/openbao/data/
3. Create Configuration File
Example for bench config directory (~/frappe-bench/config/openbao.hcl):
ui = true
log_level = "info"
log_format = "standard"
storage "file" {
path = "/home/frappe/frappe-bench/config/openbao-data"
}
listener "tcp" {
address = "127.0.0.1:8200"
tls_disable = true # TLS handled by nginx reverse proxy
}
# Static seal for auto-unseal on restart
seal "static" {
current_key_id = "frappe-vault-1"
current_key = "file:///home/frappe/frappe-bench/config/openbao-seal.key"
}
api_addr = "http://127.0.0.1:8200"
Create the seal key file:
# Replace with your generated key
echo "YOUR_64_CHAR_HEX_KEY_HERE" > ~/frappe-bench/config/openbao-seal.key
chmod 600 ~/frappe-bench/config/openbao-seal.key
4. Create Data Directory
mkdir -p ~/frappe-bench/config/openbao-data
5. Create Systemd Service (for systemd deployments)
Create /etc/systemd/system/openbao.service:
[Unit]
Description=OpenBao
Documentation=https://openbao.org/docs/
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/openbao/config.hcl
[Service]
User=openbao
Group=openbao
ProtectSystem=full
ProtectHome=read-only
PrivateTmp=yes
PrivateDevices=yes
SecureBits=keep-caps
AmbientCapabilities=CAP_IPC_LOCK
NoNewPrivileges=yes
ExecStart=/usr/bin/bao server -config=/etc/openbao/config.hcl
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
LimitNOFILE=65536
LimitMEMLOCK=infinity
# For env-based seal key (Option A with systemd):
# Environment=BAO_SEAL_KEY=YOUR_64_CHAR_HEX_KEY_HERE
[Install]
WantedBy=multi-user.target
6. Start and Initialize OpenBao
# Start OpenBao
sudo systemctl enable openbao
sudo systemctl start openbao
# Set environment
export BAO_ADDR='http://127.0.0.1:8200'
# Initialize OpenBao (only once)
# With static seal, this generates recovery keys instead of unseal keys
bao operator init -recovery-shares=5 -recovery-threshold=3
# IMPORTANT: Save the recovery keys and root token securely!
# Recovery keys are for emergency access, not routine restarts.
# OpenBao will auto-unseal using the static seal key.
Note: With static seal configured, OpenBao automatically unseals on startup. The recovery keys are only needed for emergency situations (e.g., seal key rotation, disaster recovery).
7. Enable KV Secrets Engine
export BAO_TOKEN='bao.xxxxx' # Root token from init
# Enable KV v2 secrets engine
bao secrets enable -path=secret kv-v2
8. Create Frappe Policy
Create frappe-vault-policy.hcl:
# Allow full access to frappe secrets for all sites
# Secrets are stored at: secret/data/frappe/{site}/{doctype}/{name}/{fieldname}
# Example: secret/data/frappe/mysite.example.com/User/Administrator/password
path "secret/data/frappe/*" {
capabilities = ["create", "read", "update", "delete"]
}
path "secret/metadata/frappe/*" {
capabilities = ["list", "delete"]
}
For multi-tenant deployments, you can create site-specific policies:
# Policy for site1.example.com only
path "secret/data/frappe/site1.example.com/*" {
capabilities = ["create", "read", "update", "delete"]
}
path "secret/metadata/frappe/site1.example.com/*" {
capabilities = ["list", "delete"]
}
Apply and create token:
bao policy write frappe-vault frappe-vault-policy.hcl
bao token create -policy=frappe-vault -period=768h -display-name="frappe-app"
9. Enable Audit Logging
When using bench setup-openbao, audit logging is automatically configured in the HCL config file. Logs are written to logs/openbao-audit.log in your bench directory.
For manual setups, add the audit device to your openbao.hcl:
audit_device "file" {
path = "file"
file_path = "/var/log/openbao/audit.log"
}
Note: OpenBao 2.4+ requires audit devices to be configured declaratively in the config file, not via the API.
Supervisor Integration
For Frappe deployments using Supervisor (recommended), add OpenBao as a managed service.
Create /etc/supervisor/conf.d/openbao.conf:
For bench config directory setup (recommended):
[program:openbao]
command=/usr/bin/bao server -config=/home/frappe/frappe-bench/config/openbao.hcl
autostart=true
autorestart=true
directory=/home/frappe/frappe-bench
stdout_logfile=/var/log/openbao/openbao.log
stderr_logfile=/var/log/openbao/openbao-error.log
For system directory setup with env-based seal key:
[program:openbao]
command=/usr/bin/bao server -config=/etc/openbao/config.hcl
autostart=true
autorestart=true
user=openbao
stdout_logfile=/var/log/openbao/openbao.log
stderr_logfile=/var/log/openbao/openbao-error.log
environment=HOME="/etc/openbao",BAO_SEAL_KEY="YOUR_64_CHAR_HEX_KEY_HERE"
With static seal configured:
bench restartwill restart OpenBao and it will automatically unseal- No manual intervention required after restarts
- Recovery keys are only needed for emergencies
Create log directory and reload supervisor:
sudo mkdir -p /var/log/openbao
sudo supervisorctl reread
sudo supervisorctl update
Seal Key Storage
Choose the storage method that best fits your security requirements:
Environment Variable (env://)
seal "static" {
current_key_id = "frappe-vault-1"
current_key = "env://BAO_SEAL_KEY"
}
Pros:
- Key not persisted as a separate file on disk
- Integrates well with container orchestration (K8s Secrets, Docker Secrets)
- Easy to manage with Supervisor
Cons:
- Visible to root via
/proc/<pid>/environ - Supervisor config file must be protected (0600 permissions)
File-Based (file://)
seal "static" {
current_key_id = "frappe-vault-1"
current_key = "file:///etc/openbao/seal.key"
}
Pros:
- Simpler setup for traditional deployments
- Easier to audit file access
- Works without modifying supervisor config
Cons:
- Key persists on disk (must secure with permissions)
- Must ensure file permissions are correct (0600, owned by openbao)
Security Notes
Both methods require trusting the host system. Anyone with root access to the host can access the seal key. For high-security environments, consider:
Seal Key Rotation
To rotate the seal key:
- Generate a new key:
openssl rand -hex 32 - Update config with both keys:
seal "static" {
current_key_id = "frappe-vault-2"
current_key = "env://BAO_SEAL_KEY"
previous_key_id = "frappe-vault-1"
previous_key = "env://BAO_SEAL_KEY_OLD"
}
- Update environment with both keys
- Restart OpenBao - it will re-wrap data with the new key
- After confirming success, remove
previous_keyentries
Alternative: Manual Unsealing (Shamir)
If you prefer manual unsealing with Shamir secret sharing (not recommended for Supervisor deployments), omit the seal "static" block from your configuration:
ui = true
storage "file" {
path = "/opt/openbao/data"
}
listener "tcp" {
address = "127.0.0.1:8200"
tls_disable = true
}
api_addr = "http://127.0.0.1:8200"
Initialize with unseal keys:
bao operator init -key-shares=5 -key-threshold=3
After every restart, you must manually unseal:
bao operator unseal # Run 3 times with different keys
Warning: With Shamir unsealing, bench restart will leave OpenBao sealed until manually unsealed. This breaks automated deployments and requires human intervention.
Health Checks
Verify OpenBao is running correctly:
# Check health (no auth required)
curl -s https://localhost:8200/v1/sys/health | jq .
# Expected response for healthy, unsealed OpenBao:
{
"initialized": true,
"sealed": false,
"standby": false,
"performance_standby": false,
"replication_performance_mode": "disabled",
"replication_dr_mode": "disabled",
"server_time_utc": 1234567890,
"version": "2.0.0"
}
Troubleshooting
OpenBao is Sealed After Restart
If OpenBao is sealed after restart with static seal configured:
- Check seal key availability:
- For
env://: VerifyBAO_SEAL_KEYis set in supervisor/systemd config - For
file://: Verify the key file exists and has correct permissions
- For
- Check OpenBao logs:
sudo journalctl -u openbao -f # Or for supervisor: tail -f /var/log/openbao/openbao-error.log - Verify key format: The key must be exactly 64 hex characters (32 bytes)
- Emergency unseal with recovery keys (if static seal fails):
bao operator unseal -recovery # Enter recovery key (repeat as needed based on threshold)
OpenBao is Sealed (Manual Shamir Setup)
If using manual Shamir unsealing (not recommended):
bao operator unseal
# Enter unseal key (repeat 3 times with different keys)
Connection Refused
Check OpenBao is running:
sudo systemctl status openbao
# Or for supervisor:
sudo supervisorctl status openbao
Certificate Errors
If using TLS (not via nginx proxy):
export BAO_SKIP_VERIFY=true
# Or
export BAO_CACERT=/path/to/ca.crt
Permission Denied
Verify token has correct policy:
bao token lookup
Seal Key File Permissions
If using file-based seal key:
ls -la /etc/openbao/seal.key
# Should show: -rw------- 1 openbao openbao
# Fix if needed:
sudo chmod 600 /etc/openbao/seal.key
sudo chown openbao:openbao /etc/openbao/seal.key
Migration from HashiCorp Vault
If you are migrating from HashiCorp Vault, OpenBao provides API compatibility with Vault OSS v1.14.x. Key differences:
- CLI command:
baoinstead ofvault - Environment variables:
BAO_ADDR,BAO_TOKEN(legacyVAULT_*still supported) - Token format: OpenBao tokens start with
bao.instead ofhvs.
See the OpenBao migration guide for detailed instructions.