Workflow keyctl + BWS

The scripts on this host, like nb.sh (which queries NetBox), need API tokens. Instead of keeping them in environment variables, they live in Bitwarden Secrets Manager and each script requests them right when it needs them. It relies on three pieces: bws, the Bitwarden program that talks to the cloud; a set of bash functions bws_* (defined in bws_lib.sh) that call it for us; and keyctl (from the keyutils package), which manages the kernel's native keyring where the only local credential lives: the token that opens the vault.

Why this exists

What it avoids: export NETBOX_TOKEN="value" in ~/.bashrc and ~/.bash_aliases.
Where the secrets live: in a Bitwarden Secrets Manager project, shared by the users on the host.
What stays local: only the bws access token, in the kernel keyring (keyctl), never in plain text and never visible with echo $VARIABLE.

~/.bashrc→ bashrc.sh→ bws_lib.sh→ bws_* functions→ keyctl + bws→ Bitwarden

binary

bws

The official Bitwarden Secrets Manager CLI, a program installed at /usr/local/bin/bws. With an access token it queries the cloud and returns secrets. It is not a bash function.

bash functions

bws_unlock · bws_lock · bws_secret · bwsrun · bws_status

Our own functions that wrap keyctl and bws. They are defined in /shared/scripts/bitwarden/bws_lib.sh. They only exist in shells (or scripts) that loaded that file with source; they are not system commands.

shell script

bashrc.sh

/shared/scripts/bash/bashrc.sh does not define the bws_* functions: it sources bws_lib.sh, adds the /shared scripts to PATH and runs bws_status when an interactive shell opens. Each personal ~/.bashrc includes it with one line.

binario

keyctl

Command from the keyutils package (/usr/bin/keyctl). It manages the kernel's native keyring. The @u keyring is per user: it is not shared between users and is lost on reboot.

script / wrapper

nb.sh

A bash wrapper around our NetBox API (https://netbox.example.com), to query and operate faster than the web UI, e.g. nb.sh list ips 10.0.0. It is the example script that uses the secrets: it loads bws_lib.sh and requests NETBOX_TOKEN with bws_secret.

That is why sudo bws_unlock does not work: sudo starts another process where those functions do not exist. A script that needs secrets has to source bws_lib.sh and then call bws_secret.

The block above is printed by 20-vminfra01 as root (pam_motd). The BWS line is added by bws_status from the user's shell, because root looks at its own keyring and would always see it as missing.