Repository navigation
Releases
OpenBao 1.2.0
NS8 OpenID Connect
- Choose a published NethServer IdP, Keycloak, or LemonLDAP::NG provider and user domain in Settings. OIDC can run alongside LDAP, including with a different domain, or serve as the only external sign-in method.
- Run
runagent -m openbao1 openbao-auth applyon the node to register the client and configure OpenBao. OIDC is disabled by default. The default OIDC role grants no secret or administrator access.
Shared identities
When both methods use the same NS8 user domain, an administrator can link verified LDAP and OIDC aliases to one OpenBao entity. Each method continues to issue its own tokens and method-specific policies.
Local recovery
Run runagent -m openbao1 openbao-auth recovery set while OpenBao is unsealed and you have an administrator token. This creates an optional local breakglass account that works when both external providers are unavailable. Rotating the password revokes earlier recovery tokens. Keep the unseal or recovery material required by your initialization mode.
Compatibility and verification
The upstream OpenBao image remains at 2.7.2. Debian 13 and Rocky 9 passed QEMU testing. A local HTTPS fixture also verified the OIDC callback and sign-in.
Configuration and recovery guide · Promotion PR · QEMU results · Full changelog
1.1.1
What's Changed
- build: align module with NS8 standards by @compgeniuses in #15
- build: align module with NS8 standards by @compgeniuses in #17
- release: promote dev to main (NS8 standards) by @compgeniuses in #16
Full Changelog: 1.1.0...1.1.1
1.1.0
What's Changed
- feat: experimental high availability (discover, join, Raft cluster) by @compgeniuses in #12
- feat: on-demand plugin catalog; docs: slim README, topics in docs/ by @compgeniuses in #13
- Release 1.1.0: plugin catalog, CLI initialization, experimental HA, docs restructure by @compgeniuses in #14
Full Changelog: 1.0.1...1.1.0
1.1.0-testing.1
What's Changed
- feat: experimental high availability (discover, join, Raft cluster) by @compgeniuses in #12
- feat: on-demand plugin catalog; docs: slim README, topics in docs/ by @compgeniuses in #13
- Release 1.1.0: plugin catalog, CLI initialization, experimental HA, docs restructure by @compgeniuses in #14
Testing pre-release of 1.1.0.
What's new
openbao-init: initialize OpenBao from the server. Keys and root token are printed on the terminal only (never stored); with manual unseal it also unseals. Recommended by the wizard and the Status page.- Plugin catalog: new Plugins page with the official openbao-plugins (6 auth methods, 7 secrets engines, MongoDB). Nothing is downloaded until a plugin is enabled; images are pinned by digest; credentials stay in OpenBao.
- High availability (experimental): instances can accept members or join an existing OpenBao through NS8 service discovery. Standalone stays the default.
- Documentation: README slimmed to an overview with an index; topics in docs/.
Upgrading from 1.0.x
In-place update, nothing to do. With manual unseal, unseal again after the update. All new features are off until enabled.
Details: #14
Full Changelog: 1.0.1...1.1.0-testing.1
1.0.1
What's Changed
- fix: ship the LDAP auth plugin and make self-initialization safe by @compgeniuses in #3
- feat: LDAP group policies, IP allow-list and starter kits by @compgeniuses in #4
- feat: module token (snapshots, root-token check), cluster network API, Transit unseal by @compgeniuses in #5
- fix: register the LDAP auth plugin; fix the IP allow-list test by @compgeniuses in #7
- feat: seal migration, snapshot restore, cluster-network-only mode (HA designed) by @compgeniuses in #6
- fix: keep admin access with other group policies; fix Robot JSON parsing by @compgeniuses in #8
- feat(ui): propose domain admins group; refine HA plan by @compgeniuses in #9
- fix: recover 1.0.0 instances stuck after a failed self-initialization by @compgeniuses in #10
- Release: fix 1.0.0, directory login, group policies, snapshots, Transit, VPN-only by @compgeniuses in #11
Fixes to 1.0.0
-
LDAP auth plugin shipped with the module.
The pinned image ghcr.io/openbao/openbao-plugin-auth-ldap:v0.2.0 is listed in org.nethserver.images, so the node pulls it and Renovate tracks it. -
Before each start the binary is copied out, its SHA-256 checked, and it is declared in the server configuration (plugin "auth" "ldap").
Plugin registration. plugin_auto_register = true is now set explicitly: OpenBao merges the files of the configuration directory into an empty base, which silently turned the documented default into false.
Safe self-initialization. -
Only the administrator policy and a break-glass administrator token are mandatory steps. It never leaves the node and expires after 32 days.
-
Directory login, the module token, policies and starter kits use allow_failure. A wrong or unavailable directory can no longer lock everybody out.
-
Administrators keep full access with other group policies.
OpenBao applies only the most specific path among a token's policies; capabilities merge only for identical paths.
ns8-admin repeats the paths of the built-in policies, so mapping one of them to administrators can't make secret/ read-only for them.
Settings UI. The saved user domain is no longer shown empty (a NsComboBox value/options ordering issue).
New features
-
Directory login and access control
Directory login (LDAP/AD) through the node ldapproxy, with OpenLDAP and Samba AD search settings mirroring the NethServer core.
Status page button: Log in with directory account opens the web UI with the LDAP method selected. -
Default administrators group.
Settings and the wizard preselect the builtin domain admins group, which both NethServer account providers create with the domain administrator as its member. -
The README documents the default domain accounts. There is no default password.
Group policies. Map directory groups to the built-in policies (ns8-admin, ns8-secrets-rw, ns8-secrets-ro, ns8-pki-issuer) or to any policy name.
Applied at self-initialization, or later with runagent -m openbao-apply-config and an administrator token. openbao-setup-ldap is kept as an alias. -
Mappings removed from Settings are revoked; mappings created by hand are untouched.
-
Starter kits, optional:
kv: a secret/ KV v2 store;
pki: an internal CA and the ns8-server role;
approle: the AppRole auth method.
IP allow-list for the public route (Traefik). -
Unseal, storage and recovery
-
Unseal modes: manual (Shamir), automatic (static key on the node) and Transit (another OpenBao/Vault).
-
The Transit token is given on the node with openbao-transit-token, never through an action.
Seal migration between manual, automatic and Transit (openbao-seal-migrate), with a Status notice while it runs. -
Module token with a narrow ns8-module policy, created by self-initialization or openbao-module-token create. It allows:
-
consistent Raft snapshots in backups;
detection of active root tokens; -
Raft status.
It can't read secrets or change configuration.
Snapshots.
- Backups include a consistent Raft snapshot.
Scheduled local snapshots with retention, listed in Settings. - openbao-snapshot-restore, with --force for snapshots of another OpenBao.
Root token check. The Status page warns while a root token is active; openbao-root-tokens lists and revokes them.
Network and monitoring
- Cluster network API. The API can be published on the node VPN address for other modules and nodes, and announced as the NS8 service openbao (module//srv/http/openbao, event openbao-changed).
- VPN-only mode: turn off the public Traefik route and reach OpenBao only on the cluster network.
- Prometheus metrics for the NS8 metrics module.
A dedicated metrics-only listener on the VPN address, published as a scrape target, plus alert rules (sealed, down, uninitialized).
The public listener never serves metrics. - Notifications by email through the cluster smarthost, when OpenBao is sealed, down or not initialized, with a Send test email button.
Setup and documentation - Setup wizard for simple setups: it opens automatically on a new instance; advanced users go to Settings.
Documentation: - full README: first-time setup paths A–D (with and without directory login), lost credentials, unseal modes, group policies, starter kits, snapshots, metrics, security notes, troubleshooting;
docs/high-availability.md: design notes, not implemented in this release.
Security model (unchanged principles)
No secret is ever passed through an NS8 action: unseal keys, root and admin tokens, the Transit token and bind passwords never are. Redis keeps task payloads for 8 hours, readable by all modules.
Secrets are never stored with agent.set_env. The token, key and seal files are owner-only.
Rootless container: all capabilities dropped, no-new-privileges. API published on loopback only; Traefik terminates TLS.
Upgrading from 1.0.0
1.0.0 setup After updating
- Manual unseal Updated in place: unseal again after the restart
- Automatic unseal, no automatic initialization Updated in place; it unseals itself
Automatic unseal with automatic initialization Storage locked by the 1.0.0 defect and never usable: run runagent -m openbao-reset-failed-init (from #10), or remove and reinstall the app - Ports: the TCP port demand rises from 2 to 3; NS8 updates the allowance on update. The third port is allocated only when the cluster network API is turned on (node:portsadm).
- Defaults: new settings start disabled, or keep the 1.0.0 behaviour.
Requirement: core ≥ 3.13.0.
Testing
- Rocky 9 QEMU install tests: all suites pass (10 Openbao, 20 Auto Unseal, 30 Directory Login, 40 Transit) on the latest dev content (run).
- Debian 13: the job fails before the VM boots, at Fetch and verify the cloud image (HTTP 404 from Debian's cloud image server). It is an infrastructure issue that fails on every branch, unrelated to the module.
- Not covered by CI: upgrade from 1.0.0, a real Transit server on another host, multi-node setups. Please test on a real server: an in-place update of a 1.0.0 instance, and a fresh install with the wizard.
Full Changelog: 1.0.0...1.0.1
1.0.0
What's Changed
- feat!: production-grade OpenBao module for NethServer 8 by @compgeniuses in #1
- Release: production-grade OpenBao module (dev → main) by @compgeniuses in #2
New Contributors
- @compgeniuses made their first contribution in #1
Full Changelog: https://github.com/geniusdynamics/ns8-openbao/commits/1.0.0