Troubleshooting

Overview

obscuro uses your OS keychain to store the master password so you don't need to type it on every command. Before storing or reading, it runs a quick preflight check by attempting a trial write to the keychain. If that fails, you'll see a keychain unavailable error with distro-specific instructions.

This page walks through how to satisfy the keychain prerequisite on each platform, how to verify keychain connectivity, common failure modes, and alternative authentication methods for environments where a keychain isn't available.

Prerequisites

Linux

Linux keychain support requires a running Secret Service provider. Install the one that matches your distro:

After installing, log out and back in (or start the daemon manually) to activate the keyring. Alternatively, KeePassXC with Tools → Settings → Secret Service Integration → Enable works on any distro.

macOS

Keychain is built into macOS. The login keychain must be unlocked — it usually unlocks automatically at login.

If you see a keychain error on macOS:

1. Open Keychain Access (/Applications/Utilities/Keychain Access.app)
2. Select login in the left panel
3. Choose File → Unlock Keychain "login" and enter your login password

# Verify keychain access from the terminal
security list-keychains

Windows

Credential Manager is built into Windows 10 and later. No installation is needed.

To verify it's accessible:

Get-Command cmdkey

If cmdkey is not found, check that Credential Manager is enabled in Control Panel → Credential Manager.

Verification

Use these commands to confirm keychain connectivity before running obscuro auth store.

Linux

dbus-send --session --dest=org.freedesktop.secrets \
  --type=method_call --print-reply /org/freedesktop/secrets \
  org.freedesktop.DBus.Properties.Get \
  string:org.freedesktop.Secret.Service string:Collections

A successful response lists your keychain collections. An error like The name org.freedesktop.secrets was not provided by any .service files means no Secret Service provider is running.

macOS

security list-keychains

The login keychain should appear. If it's locked, see the macOS section above.

Windows

Get-Command cmdkey

Common failure modes

Headless server

A headless server has no display manager to start the keychain daemon. Use one of the Alternatives instead, or run gnome-keyring-daemon --start --components=secrets as a background process (requires a D-Bus session).

Docker / Podman containers

Containers typically have no D-Bus session bus. Use the --password-file or OBSCURO_PASSWORD alternative.

WSL (Windows Subsystem for Linux)

WSL 2 runs a minimal Linux inside a Hyper-V VM without a native Secret Service. Options:

• Use --password-file or OBSCURO_PASSWORD
• Install gnome-keyring and start it manually with eval $(gnome-keyring-daemon --start)

SSH forwarding without keyring forwarding

When you SSH into a remote machine, your local keychain is not forwarded. The remote machine needs its own Secret Service provider.

SELinux / AppArmor blocking dbus

Hardened policies may block D-Bus calls to the Secret Service. Check audit logs (ausearch -m avc or journalctl -xe) and add the appropriate policy exception, or use an alternative.

Rootless containers

Running obscuro inside a rootless container (e.g., Podman in rootless mode) with no host D-Bus socket forwarded will fail. Use --password-file or OBSCURO_PASSWORD.

macOS: locked login keychain

If the login keychain is locked (common after a long idle or after a password change), unlock it via Keychain Access or:

security unlock-keychain ~/Library/Keychains/login.keychain-db

Windows: Group Policy blocking Credential Manager

On domain-joined machines, Group Policy may disable Credential Manager. Contact your IT administrator or use --password-file / OBSCURO_PASSWORD.

Alternatives

If a keychain isn't available, use one of these alternatives for every obscuro command that requires the master password:

--password-file /path/to/pw — read the password from a file (recommended mode: 600):

echo -n 'your-password' > ~/.obscuro-pw
chmod 600 ~/.obscuro-pw
obscuro get MY_SECRET --password-file ~/.obscuro-pw

--password-file - — read from stdin (useful in pipelines):

echo -n 'your-password' | obscuro inject --password-file -

OBSCURO_PASSWORD=... — pass via environment variable:

export OBSCURO_PASSWORD='your-password'
obscuro inject < helm-values.yaml

--password 'pw' — inline on the command line (last resort; visible in process lists and shell history):

obscuro get MY_SECRET --password 'your-password'

See configuration for the full password-resolution order.

Password backends

Obscuro now ships with two interchangeable backends for storing your master password between commands. Pick the one that matches your host, or switch at any time without re-initialising the vault.

The managed password file is stored at ${XDG_CONFIG_HOME:-~/.config}/obscuro/vaults/<hash>.pw (mode 0600). The hash is the first 16 hex characters of sha256(base64-encoded-salt), one file per vault. On Windows the path is %APPDATA%\obscuro\vaults\<hash>.pw.

To switch or set a backend, run obscuro auth store (interactive selector) or obscuro auth store --backend=file / --backend=keychain for non-interactive use. The choice is saved in .obscuro/config.json; subsequent obscuro get/inject calls use it automatically.

auth doctor

Run obscuro auth doctor at any time to see which backends are available on your host without modifying any state.

$ obscuro auth doctor
obscuro auth doctor — backend availability
[✓] keychain: OS keychain — ready
    DBUS_SESSION_BUS_ADDRESS: unix:path=/run/user/1000/bus
    XDG_SESSION_TYPE: x11
[✗] keychain: OS keychain — Secret Service reachable but login collection is locked/missing — try 'secret-tool store' first, or use file backend
[✓] file: managed file — ready — writes to /root/.config/obscuro/vaults/a1b2c3d4e5f6a7b8.pw

Secret Service collection locked

This is the classic Ubuntu-over-SSH case: gnome-keyring is installed and the D-Bus session bus is reachable, but the login collection was never unlocked because you never logged in through a graphical session. auth doctor reports the backend as reachable but locked.

Confirm with the secret-tool recipe:

secret-tool store --label="obscuro test" service obscuro username test

If this hangs or fails, your session doesn't have an unlocked keyring. Use --backend=file instead.

Related commands

• obscuro auth store — store the master password in the OS keychain
• obscuro auth status — check whether a password is currently stored
• obscuro auth clear — remove the stored password
• obscuro init — initialise a new vault