Configuration Reference¶
dotvault uses a YAML configuration file. The file location depends on your platform:
| Platform | Path |
|---|---|
| Linux | /etc/xdg/dotvault/config.yaml (also checks $XDG_CONFIG_DIRS) |
| macOS | /Library/Application Support/dotvault/config.yaml |
| Windows | %ProgramData%\dotvault\config.yaml |
That file is system-wide and normally administrator-owned. There is also an optional per-user file, which may carry only the fuse section and is merged over the system configuration:
| Platform | Path |
|---|---|
| Linux | ${XDG_CONFIG_HOME:-~/.config}/dotvault/config.yaml |
| macOS | ~/Library/Application Support/dotvault/config.yaml |
| Windows | %APPDATA%\dotvault\config.yaml |
Every other section is a hard error there, so the per-user file can never re-point the Vault, open a listener, or alter telemetry. See Per-user preferences.
You can override the config path with --config:
--config is gated by the system-wide configuration
--config is honoured only when there is no system-wide configuration, or the system-wide configuration explicitly opts in with bypass_system_config: true. If a system config is present and does not set the flag, dotvault refuses the override and exits with an error rather than silently loading the command-line file. This is identical on every platform; the "system-wide configuration" is the Windows Group Policy registry policy when present, otherwise the system YAML file. See bypass_system_config below.
Windows Group Policy
On Windows, if Group Policy registry keys exist at HKLM\SOFTWARE\Policies\goodtune\dotvault, dotvault loads all configuration from the registry and ignores the YAML file entirely. Pointing dotvault at a different file with --config requires bypass_system_config: true in that policy (the registry equivalent is a BypassSystemConfig REG_DWORD of 1 directly under the policy key). See Windows Group Policy for details.
Full example¶
vault:
address: "https://vault.example.com:8200"
auth_method: "oidc"
auth_role: "default"
auth_mount: "oidc"
oidc_callback_port: 8250
kv_mount: "kv"
user_prefix: "users/"
ca_cert: "/etc/ssl/certs/internal-ca.pem"
tls_skip_verify: false
sync:
interval: "15m"
web:
enabled: true
listen: "127.0.0.1:9000"
login_text: |
Welcome to dotvault. Click **Login** to authenticate via SSO.
secret_view_text: |
These secrets are synchronised from Vault to your local machine.
editable_paths:
- personal
api:
enabled: true
unix:
path: "" # default: $XDG_RUNTIME_DIR/dotvault/api.sock
fuse:
enabled: true
mountpoint: "~/.dotvault"
read_write: false
cache_ttl: "30s"
client_cert:
enabled: true
pki_role: "dotvault-tools" # a dedicated role; see the Client certificate section
ttl: "5m"
rules:
- name: gh
vault_key: "gh"
target:
path: "~/.config/gh/hosts.yml"
format: yaml
template: |
github.com:
oauth_token: "{{ .oauth_token }}"
- name: ssh-key
vault_key: "ssh"
target:
path: "~/.ssh/id_ed25519"
format: text
- name: netrc
vault_key: "netrc"
target:
path: "~/.netrc"
format: netrc
enrolments:
gh:
engine: github
settings:
scopes:
- repo
- read:org
- gist
Top-level options¶
| Field | Type | Default | Description |
|---|---|---|---|
bypass_system_config |
bool | false |
Permit the --config command-line override on this machine (see below) |
bypass_system_config¶
By default, when a system-wide configuration is present, the --config command-line flag is refused — a managed deployment (a Windows Group Policy registry policy, or a system config file shipped by configuration management) cannot be sidestepped from the command line. Setting bypass_system_config: true in the system-wide config re-enables the override on that machine.
The intended workflow: an administrator normally pins the system config, but flips this flag when they need to trial a hand-edited config without un-deploying the policy. It only has an effect when set in the authoritative system config — setting it inside a file passed to --config is meaningless, because that file is only loaded once the override has already been allowed.
The behaviour is identical on every platform. On Windows GPO the equivalent registry value is a BypassSystemConfig REG_DWORD of 1 directly under HKLM\SOFTWARE\Policies\goodtune\dotvault.
Vault section¶
| Field | Type | Default | Description |
|---|---|---|---|
address |
string | (required) | Vault server URL |
auth_method |
string | — | Authentication method: oidc, ldap, token, mtls, mtls+tpm, or mtls+os (any base method also accepts a +tpm suffix) |
auth_mount |
string | — | Vault auth mount path (e.g. oidc, ldap) |
auth_role |
string | — | Vault auth role to request |
oidc_callback_port |
int | 8250 |
Fixed local TCP port the OIDC CLI flow (dotvault login) binds for the OAuth redirect_uri; falls back to a random port if unavailable. See OIDC & SSO Authentication |
policies |
list | — | Least-privilege policy set the working token should carry (see below) |
no_default_policy |
bool | false |
Strip the implicit default policy from the working token (see below) |
kv_mount |
string | kv |
KVv2 secrets engine mount path |
user_prefix |
string | users/ |
Prefix for per-user secret paths (trailing slash enforced) |
ca_cert |
string | — | Path to CA certificate for TLS verification |
tls_skip_verify |
bool | false |
Skip TLS certificate verification (development only) |
disable_token_renewal |
bool | false |
Never call RenewSelf; TTL expiry still triggers re-auth |
token_socket |
string or list | ~/.ssh/dotvault.sock, ~/.ssh/dotvault.*.sock |
Peer dotvault socket patterns to borrow a token from and fan peer actions out to (see below); [] disables |
borrow_only |
bool | false |
Forbid this host from ever running its own fresh-auth flow; it only ever borrows a token via token_socket (see below) |
Secret paths are constructed as: {kv_mount}/data/{user_prefix}{username}/{vault_key}
policies / no_default_policy — least-privilege tokens¶
By default dotvault runs with whatever policies its auth role (OIDC/LDAP/cert) grants the user. For a human that is often the union of everything that user can do in Vault — far more than dotvault needs to mirror a handful of secrets. A token that is cached on disk (~/.dotvault-token) is a standing credential; over-provisioning it widens the blast radius if the file ever leaks.
Set policies to the minimal set dotvault actually needs (typically a read-only policy over the user's KV prefix). When it is non-empty, dotvault does not use the login token directly: immediately after authenticating it exchanges that token for a child token restricted to exactly those policies and runs with — and persists — the child. Vault enforces that the requested set is a subset of the login token's own policies, so this can only ever drop privilege, never escalate it. The narrowing applies identically on every auth path (CLI OIDC/LDAP/mTLS and the web UI). The token auth method is exempt — there you supply the token and own its scope.
no_default_policy: true additionally strips Vault's implicit default policy from the working token. Combine the two to pin the token to precisely the capabilities dotvault uses.
vault:
address: "https://vault.example.com:8200"
auth_method: "oidc"
policies:
- dotvault-sync # a read-only policy over kv/data/users/<you>/*
no_default_policy: true
Your policy must grant token self-management
Stripping the default policy also strips the token-self paths dotvault relies on, so any policy you name in policies must grant all three of the following. This is not optional — two of the three fail in ways that look like something else entirely:
# Downscope exchanges the login token for a least-privilege child.
# Missing: login fails closed with "permission denied" on auth/token/create.
path "auth/token/create" {
capabilities = ["create", "update"]
}
# The token lifecycle manager's health check, every 5 minutes.
# Missing: the check returns 403, which dotvault reads as "token invalid",
# so the daemon re-authenticates in a permanent loop while holding a
# perfectly good token. This is the nastiest of the three to diagnose.
path "auth/token/lookup-self" {
capabilities = ["read"]
}
# Renewal at 75% of TTL.
# Missing: every token runs to expiry and forces an avoidable re-auth.
path "auth/token/renew-self" {
capabilities = ["update"]
}
The dev stack's dotvault policy in docker-compose.yaml includes these three. The requirement is verified by test/integration/mtls_test.go, which exercises a real downscoped login end to end.
Certificate auth needs two more
Under mtls, mtls+tpm, or mtls+os the daemon also rotates its own certificate and retires the one it replaces, both headless and both using this same downscoped token. That needs pki/sign/<role> (mint the replacement) and pki/revoke (retire the superseded certificate) on top of the three above. Without pki/sign the certificate runs to expiry and the host needs a fresh human bootstrap; without pki/revoke rotation still works but each superseded certificate stays valid at the CA until its own TTL ends.
pki/revoke is not scopeable to a host's own certificates — read the trade-off in What your Vault admin must set up before granting it, and note that revoke_superseded: false is the supported way to decline it without collecting a warning on every rotation. The dev stack's dotvault policy grants both and is a working reference for the whole cert-auth lifecycle.
Client certificates need pki/sign/<role> too
When client_cert is enabled and the host signs short-lived certificates (every host except one using plain mtls, and always under borrow_only), the policy must also grant pki/sign/<client_cert.pki_role> — for example pki/sign/dotvault-tools. A policy without it makes the certificate fail with a permission error naming the role. The dev stack's dotvault policy grants it.
Downscoped tokens carry the parent's identity metadata
A child token minted by auth/token/create has no meta of its own, so a downscoped token would lose the username the login recorded. dotvault therefore reads the login token's meta with one extra lookup-self per login and passes the two identity keys — username and common_name, the ones {{.token_username}} reads — to the child it mints. No other metadata key is copied. That is what lets {{.token_username}} — the default client certificate common name — resolve on a downscoped token, and on one borrowed from a peer (borrowed tokens are downscoped workstation tokens). The read is best effort: if it fails, the child is minted without metadata and a DEBUG line says so, because refusing a least-privilege downscope over a convenience would trade a security property for it. A workstation must run a build that carries this before its borrowers can use {{.token_username}}.
This is a per-deployment concern — dotvault ships no default policy list, because the right policy name(s) depend entirely on your Vault policy layout. The downscoped child token is renewable and managed by the normal token lifecycle; when it expires dotvault re-authenticates and re-narrows.
Staged rollout toward 1.0
Today no_default_policy defaults to false and an unset policies keeps the historical "carry every granted policy" behaviour — so existing installs are unaffected. dotvault logs a one-line warning at each fresh login when no restriction is configured, nudging operators to opt in. A future release will flip the no_default_policy default to true, and the 1.0 release will remove the ability to run with the default policy attached at all. dotvault is pre-1.0, so this deliberately-breaking transition runs over a few releases; configure policies now to be ready. On Windows GPO the equivalents are a Policies REG_MULTI_SZ and a NoDefaultPolicy REG_DWORD under HKLM\SOFTWARE\Policies\goodtune\dotvault\Vault.
token_socket — dotvault-to-dotvault token sharing¶
When token_socket points at a Unix-domain socket served by another dotvault daemon's web API, dotvault tries to borrow a live Vault token from that peer before falling back to its own authentication. The borrow is attempted everywhere dotvault would otherwise authenticate interactively or block waiting for a token: on a fresh login (dotvault login, or daemon/CLI startup when no cached token is usable — a still-valid cached token short-circuits first and never reaches the borrow); during headless daemon startup, where a daemon with no web UI and no terminal borrows directly instead of idling until a token file is written; and on the lifecycle manager's recovery path after a cached token has gone invalid. A healthy token that is merely being renewed at 75% TTL (RenewSelf) does not trigger a borrow. It is the programmatic equivalent of:
token_socket is a list of patterns — literal paths or globs whose metacharacters sit in the final path segment (~/.ssh/dotvault.*.sock). A single string is still accepted. Every match is a member of a pool: token borrows try the most recently seen live socket first, while the peer actions (browse, notify, clipboard) are sent to every live socket and succeed if any accepts. A socket that cannot be reached within a few seconds is evicted from the pool — unless it appeared less than two seconds ago, since a forward's socket exists on bind() a moment before it listen()s and a refusal that fresh is a peer about to be fine — and readmitted when it is recreated (immediately on Linux via inotify; on the next attempt elsewhere) or after five minutes. When the key is absent the default is the pair above; set token_socket: [] to disable peer sockets entirely.
Why per-workstation sockets. A single shared path is a race the moment two workstations forward to the same remote: whichever connects last takes over the socket, and the other's forward is silently unbound. The observed case is a laptop and a desktop both managing a forward to the same headless host — the desktop is always up, the laptop wakes sporadically and steals the path, and when the laptop's lid closes the remote has nowhere to borrow from even though the desktop is right there. Naming each workstation's socket after itself (see managed SSH forwards) and letting the borrower hold a pool of every match removes the race instead of papering over it.
The intended deployment: a workstation (e.g. Windows) runs dotvault with the web UI enabled and authenticates interactively. You then SSH from the workstation to a second machine (e.g. a Linux dev box or server), and the SSH RemoteForward exposes the workstation daemon's loopback HTTP listener as a Unix socket created on the remote (devbox) side:
# ~/.ssh/config on the workstation, where `ssh devbox` runs
Host devbox
# Creates /home/me/.ssh/dotvault.laptop.sock ON devbox, forwarding to
# the workstation's web UI at 127.0.0.1:9000.
# One socket per workstation — see the managed-forwards guide.
RemoteForward /home/me/.ssh/dotvault.laptop.sock 127.0.0.1:9000
The remote dotvault then sets token_socket (or leaves the default) and borrows the workstation's token instead of needing its own browser or TTY to authenticate. If the RemoteForward above is itself managed by a keyless sync rule, note the daemon syncs those rules before it authenticates — the file that creates the socket cannot be made to wait on the token that arrives over it. Because the socket listener lives on the borrowing host, this side should be Linux or macOS, where AF_UNIX is fully supported; the workstation only needs the loopback TCP web UI.
On Linux the daemon also watches the socket (inotify) and re-borrows as soon as it materialises or is replaced — so an SSH RemoteForward that connects after the daemon started, or drops and reconnects, is picked up within moments rather than only on the next periodic check.
This socket dies with the SSH session
Everything above depends on the SSH connection being up. A process that outlives the session it was started in — a tmux job, a long-running service — will fail its next borrow once the forward is gone. Enable the api section on the remote host so the long-lived daemon serves the borrow endpoint from a stable path, and local clients keep working across disconnects.
One behaviour change for existing deployments: a peer's /api/v1/token now returns 401 once that peer's daemon knows its own token has gone invalid and is awaiting re-authentication, instead of handing out a credential it knows is dead. Borrowers already validate what they receive, so this only removes a known-bad answer earlier.
The borrow is best-effort and never fatal: if the socket path is empty, the socket file is missing, the socket is stale (left over from a dead SSH session, no listener), the peer is reachable but holds no token, or the response is malformed, dotvault silently carries on with its normal auth flow. A leading ~ is expanded to the user's home directory. The borrowed token is held in memory only — it is not written to the local token file, so the peer remains the single owner and the remote re-borrows on its next login or recovery rather than caching a copy that could go stale.
The same borrow is available to the dotvault client libraries (Go client/ and the Python bindings): their cached-auth entry point (AuthenticateCached) borrows from the configured peer socket after the DOTVAULT_TOKEN env var and token file come up empty, before reporting that a login is required. Because it is a plain socket read with no browser or prompt, a Go or Python program on a host with no local token but a live peer socket reads secrets without an interactive login of its own.
The socket carries traffic the other way too. dotvault browse <url> posts a URL to the peer's POST /api/v1/remote/browse endpoint so the browser opens on the workstation — the machine that actually has one — falling back to the local browser when the peer is unreachable. Set BROWSER="dotvault browse" on the headless host and OAuth login pages launched there land in the workstation's browser. dotvault notify <level> <title> [description] is the same shape for desktop notifications (POST /api/v1/remote/notify), so a long-running job on the headless box can raise a toast/notification on the workstation where a human is looking. dotvault clipboard [text] completes the set (POST /api/v1/remote/clipboard): it puts a value — a one-time token, a device code — on the workstation's clipboard, so after browse opens a login page the user's paste is already loaded with what the page asks for.
dotvault status reflects the borrow too. When no local token is present but the configured peer socket holds one, the auth line reports authenticated and adds a source: borrowed from peer socket (<path>) line, so a host that authenticates purely by borrowing — with no token file at rest — no longer misreports as not authenticated. If the socket is configured but the peer holds no token, status says so explicitly and prints the socket path rather than the bare no token message.
Change notices travel over the socket too. When a daemon rotates a credential (a GitHub, JFrog or Databricks token past its half-life) or a copy enrolment rewrites its target, it re-syncs its own files straight away rather than at the next poll, and announces the write — the key and the KVv2 version it produced, never the value — on GET /api/v1/events, a Server-Sent Events stream. A daemon that borrows over token_socket subscribes to that stream on every live peer. When a notice arrives it syncs its own files, then asks every other peer to sync through their POST /api/v1/sync, skipping the peer the notice came from. That relay is what lets two workstations that never talk to each other converge within seconds: a host both of them forward to sees the rotation on one and tells the other. It matters most on Vault Community, which has no event stream of its own, and for GitHub, which invalidates the old access token the moment it issues a new one — until a host re-syncs, the token in its gh config no longer works. A notice is acted on once per key and version, so the same write reported by two peers, or replayed after a reconnect, costs nothing extra, and a peer told to sync announces nothing of its own, so relays cannot loop. Syncs asked of each peer are single-flight and at least five seconds apart, so a misbehaving peer cannot turn a relaying host into an amplifier against the others. Relay activity appears only in the daemon's INFO log (peer events: …). A daemon also re-announces every notice it relays on its own GET /api/v1/events, so hosts chained further downstream — and programs using the Go or Python client's Subscribe — hear writes from every workstation upstream; each daemon announces a given write at most once, so a mesh of peers does not echo. Independently of the socket, every daemon's refresh check also notices when a refreshable secret's version has moved since its last look (every five minutes) and re-syncs, so a host that hears no notice still catches up well before its sync interval. A peer running an older dotvault without the events endpoint is retried every five minutes and otherwise ignored.
The socket grants the token to anyone who can connect
Any local process or user that can connect() to the forwarded socket can read the Vault token from it — and, via POST /api/v1/remote/browse, POST /api/v1/remote/notify, and POST /api/v1/remote/clipboard, open arbitrary web pages (including phishing pages) in the workstation's browser, raise arbitrary desktop notifications on it, and replace the workstation's clipboard contents (a paste-hijacking primitive — e.g. swapping a copied wallet address or command). dotvault does not create the socket and cannot enforce its permissions — that is the SSH RemoteForward's responsibility (it creates the socket owned by, and typically readable only by, the SSH user). Only enable token_socket on hosts whose other local users you trust, and rely on the remote host's filesystem permissions on the socket path.
borrow_only — forbid a fresh-auth flow entirely¶
borrow_only: true takes the borrow above and makes it the only way this host can ever obtain a Vault token. auth_method (and the mtls block, if present) is simply not consulted: no OIDC browser, no LDAP prompt, no certificate bootstrap, and the web login view shows a waiting card instead of any credential form. Validated to require a non-empty token_socket, since without one this host could never authenticate at all.
The use case is a fleet where one machine — an operator's desktop — is the sole holder of a Vault identity, and every other host it reaches must receive that identity only by borrowing it, never by minting one of its own:
# Remote/headless host's config — shares vault.address, kv_mount, etc. with
# the desktop's config; auth_method can even be left as whatever the desktop
# uses, since it is ignored here.
vault:
address: "https://vault.example.com:8200"
token_socket: "~/.ssh/dotvault.sock" # forwarded from the desktop
borrow_only: true
Reuse of an already-cached token (the token file or DOTVAULT_TOKEN) still applies first, exactly as in every other mode. What happens once that reuse comes up empty then differs by caller. The daemon (dotvault run) idles and keeps retrying the borrow, watching both the token file (for a manually-dropped override) and the socket, rather than failing startup — the same shape a headless host with no interactive facility already uses while waiting for dotvault login to run elsewhere. dotvault sync/--once and login-check's fallback have a job to do that only needs a token, borrowed included, so they make one borrow attempt and fail immediately only once that comes up empty. dotvault login and the Go client/ library's Login are different: their entire purpose — force a fresh login, ignoring the cache — has no meaning under this mode regardless of whether a borrow would happen to succeed right now, so both refuse unconditionally without even attempting one (AuthenticateCached, which never runs a fresh-auth flow to begin with, is unaffected and keeps borrowing normally; the Python bindings expose only AuthenticateCached, not Login).
On Windows GPO the equivalent registry value is a BorrowOnly REG_DWORD under HKLM\SOFTWARE\Policies\goodtune\dotvault\Vault.
For example, with defaults and username jane, the rule vault_key: "gh" reads from kv/data/users/jane/gh.
Sync section¶
| Field | Type | Default | Description |
|---|---|---|---|
interval |
string | 15m |
Polling interval as a Go duration (e.g. 5m, 1h, 30s) |
On Enterprise Vault, dotvault also subscribes to the Events API via WebSocket for near-instant sync on secret changes. The polling interval serves as a fallback.
Web section¶
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | false |
Enable the local web UI |
listen |
string | — | Listen address (must be loopback, e.g. 127.0.0.1:9000) |
login_text |
string | — | Markdown text displayed on the login page |
secret_view_text |
string | — | Markdown text displayed on the secret view page |
editable_paths |
list of strings | — | Folders of your own key space the web UI may create, edit and delete secrets in — one folder name per entry. Empty (the default) keeps the UI read-only |
Loopback only
The listen address must resolve to a loopback address (127.0.0.1, [::1], or localhost). dotvault will refuse to start if a non-loopback address is configured. This is a hard security invariant.
Editable key spaces¶
By default the web UI only reads. editable_paths opts a named part of your key space into full CRUD — see Editing secrets for what that looks like in the browser.
Each entry is a single folder name relative to kv/{user_prefix}{username}/ — your key space is one folder deep, so an entry names a folder and the secrets directly inside it become editable:
With user_prefix: users/ and a user of gary, that makes the secrets in users/gary/personal/ and users/gary/scratch/ editable — personal/token, scratch/todo and so on.
Four things are never editable, whatever this is set to:
- Anything more than one folder deep. Your key space is one folder deep and this setting is a view onto that layout, not a second one: an enrolment key is flat (
gh) or grouped exactly once (databricks/prod), so an entry here names a single folder and an editable secret sits directly inside it.personal/tokenis editable;personal/aws/devis not, and it says so rather than reporting the path as outside the subtree. An entry that is itself nested (scratch/notes) names a secret, not a folder, and is rejected at config load — accepting it would grant editing over a subtree that cannot exist. - The root of your key space.
personal/tokenis editable; a secret sitting at exactlyusers/gary/personalis not, and neither isusers/gary/gh. A root names a folder, and the secret that happens to share its name is a direct child of the key-space root like any other. Admitting the root would put every enrolment credential and every sync rule's source one gesture away from being replaced, which is the blast radius this setting exists to bound — so an entry naming it ("","/") is rejected at config load rather than quietly ignored. - Anything an enrolment writes. If
personal/ghis a configured enrolment key — a grouped enrolment whose group happens to be an editable subtree; a flat key likeghsits at the key-space root and is already excluded by the root rule below — it stays read-only even thoughpersonalis editable: the credential there belongs to the enrolment engine, which will overwrite an edit at its next run or refresh. The rule reads the configuration, not Vault, so it holds before the enrolment has ever run — the path cannot be created by hand and then silently overwritten the first time the engine claims it. The UI says so on the page rather than just omitting the controls. This is evaluated live, so an enrolment added by a remote config refresh takes a path out of reach without a restart. - Any other user's secrets. The path is always resolved beneath your own prefix, and
..segments are rejected rather than collapsed.
editable_paths is validated whether or not web.enabled is set, so a bad entry is reported when you stage the config rather than on the restart that turns the UI on. Entries are canonicalised (/personal/ becomes personal), and a duplicate is an error.
Each configured subtree is listed in the web UI's Secrets sidebar whether or not it exists in Vault yet — a subtree holds nothing until the first secret is written into it, and it has to be reachable for that first write to happen. A list denial or a 404 on a configured subtree is therefore treated as "empty" rather than reported, so a Vault policy that grants write on those paths without granting list on the folder above them still works. Listing failures outside the configured subtrees are still errors.
This is a UI capability, not a Vault permission
dotvault refuses a write outside these subtrees; Vault does not know about them. The token still carries whatever the auth role granted it, so this bounds what the browser can do, not what the daemon could. Narrow the token itself with vault.policies if that is what you need.
API section¶
The api section serves dotvault's web API over a per-user Unix domain socket, in addition to (or instead of) the loopback TCP listener the web section controls.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | false |
Serve the API over a Unix socket |
unix.path |
string | $XDG_RUNTIME_DIR/dotvault/api.sock |
Socket path; must be absolute (or ~-relative). Falls back to the cache directory when XDG_RUNTIME_DIR is unset (typical on macOS) |
Why it exists: surviving a dropped SSH session¶
vault.token_socket lets a headless host borrow a token from a workstation over an SSH RemoteForward. That socket dies with the SSH session. A process started inside that session but outliving it — a job in tmux, a long-running service — succeeds at first and then fails the moment it next needs a token, because the only socket it knew about is gone.
Recommended: let dotvault maintain the forward itself
The RemoteForward wiring below is a manual, external ssh process — it only exists while a human is sitting in the session that started it, which is the root cause of the problem this section exists to solve. Where the near-side host also runs dotvault (with agent.enabled), managed SSH forwards let the daemon maintain the connection itself instead: dotvault ssh add <host> registers the far end once, and the daemon reconnects with backoff on its own from then on, with no external process to babysit. The manual wiring below remains the right choice for a remote host that doesn't run a dotvault daemon at all.
Enabling api fixes that by putting a second, stable dotvault on the near side of the problem. The long-lived per-user daemon serves the same borrow endpoint from a path that no disconnect can take away, keeps its own token alive, and re-borrows across the forwarded socket whenever the SSH session comes back. Local clients borrow from the daemon instead of from the forward:
workstation (interactive login)
│ SSH RemoteForward → ~/.ssh/dotvault.<host>.sock ← comes and goes with the session
▼
devbox: dotvault daemon (vault.token_socket + api.enabled)
│ $XDG_RUNTIME_DIR/dotvault/api.sock ← always there while the daemon runs
▼
devbox: your tmux job, scripts, Python bindings
Configuration on the devbox is both settings together — borrow from the workstation, serve to everything local:
token_socket is deliberately absent here: the default pattern list already covers both the per-workstation sockets (~/.ssh/dotvault.*.sock) and the pre-0.34 shared path, so a devbox only needs the api half. Set it explicitly when the forwards live somewhere other than ~/.ssh, and set it as a list when you do:
vault:
token_socket:
- ~/.ssh/dotvault.*.sock # one socket per forwarding workstation
api:
enabled: true
Clients on that host need no extra configuration: they read the same config and derive the same socket path.
Borrow order¶
When both are configured, a token borrow tries the local API socket first, then the vault.token_socket pool, most-recently-seen first. The local socket is preferred because it is the more stable of the two, which is the entire point. This ordering applies to the daemon, the CLI, the Go client/ facade and the Python bindings alike. The daemon excludes its own socket from its list — it serves that one.
The peer actions (browse, notify, clipboard) deliberately keep using the vault.token_socket pool only, and are sent to every live peer in it. Their purpose is to reach the workstation where a human is looking; sending them to the local daemon would open a browser on the headless host nobody is sitting at.
Separate from web.enabled¶
The two surfaces are enabled independently because they have different audiences and different exposure. The TCP listener serves a browser UI and is reachable by every user on the machine; the Unix socket is created 0600 inside a 0700 directory and is reachable only by its owner. A headless host should not have to stand up a web UI to get the borrow endpoint, and turning the socket on does not widen anything web.enabled already exposes — if anything it is the tighter of the two.
With web.enabled: false, the socket serves the API routes (/api/v1/token, /api/v1/status, /healthz, /readyz, the peer actions, …) but not the browser-facing routes. The browser pages and the interactive login flows build redirect URIs from a bound TCP address that does not exist in that mode, so they are not registered at all rather than being published as a login flow that cannot complete.
systemd socket activation¶
On Linux, the packaged dotvault-api.socket unit (optional, not enabled by default) lets systemd bind this socket and hold the fd across daemon restarts, so borrowers queue instead of getting connection-refused while the daemon is down. api.enabled remains the master switch — the socket unit decides who binds, not whether the surface exists — and under activation the unit's ListenStream= path wins over unix.path, with the daemon logging any divergence and refusing an inherited socket whose mode is wider than 0600. See Socket activation in the deployment guide.
Running as a service¶
The socket lives in $XDG_RUNTIME_DIR, which systemd tears down when the user's last session ends — unless lingering is enabled:
This is required for any user service meant to outlive an SSH session, which is exactly the case here. The packaged dotvault.service also declares RuntimeDirectory=dotvault, so systemd creates $XDG_RUNTIME_DIR/dotvault at 0700 before the daemon starts and removes it on stop — a killed daemon leaves no stale socket behind.
dotvault status reports the socket path and whether it is currently present, which is the first thing to check when a client on the host cannot get a token.
The socket grants the token to anyone who can open it
Any process that can connect() to the socket can read the Vault token. The 0600/0700 permissions restrict that to the owning user, and dotvault enforces them on every bind (refusing to clobber a socket a live instance already owns). Do not relax them, and do not forward this socket onward unless you intend the far end to hold your token.
Unix only
api.enabled has no effect on Windows: the daemon logs a warning and serves nothing, so a config shared across a mixed-platform fleet is safe. The Windows analogue would be a named pipe with a protected DACL, as the SSH agent already serves; it is not implemented yet.
On Windows GPO, the equivalents are Enabled (REG_DWORD) and UnixPath (REG_SZ) under HKLM\SOFTWARE\Policies\goodtune\dotvault\API, and the section round-trips through reg-import/reg-export like every other.
Filesystem section¶
The fuse section mounts your Vault secrets as a filesystem: each secret becomes a .json file whose contents are its data section, so jq . ~/.dotvault/gh.json works and stat reports the secret's version timestamp as the file's mtime. The extension is what makes editors and IDEs treat the file as JSON rather than unknown text; directories carry none. See the Filesystem guide for the full write-up.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | false |
Mount the filesystem |
mountpoint |
string | ~/.dotvault |
Directory to mount on; must be absolute (or ~-relative). Created at mode 0700 if absent |
read_write |
bool | false |
Allow writing through the mount (replace, create, delete). Read-only otherwise, regardless of what the Vault token could do |
cache_ttl |
duration | 30s |
How long a listing or a rendered secret is reused before Vault is asked again. 0 disables caching; capped at 10 minutes, since the cache window is also how long a revoked secret stays readable |
Per-user preferences¶
Unusually for this file, the fuse section can also be set per-user, in ${XDG_CONFIG_HOME:-~/.config}/dotvault/config.yaml (macOS: ~/Library/Application Support/dotvault/config.yaml; Windows: %APPDATA%\dotvault\config.yaml) — a sibling of the env file and ssh.yaml. It is merged over the system configuration, and it is the only file a user can use to influence dotvault's configuration: every other section is a hard error there, so it can never re-point the Vault, open a listener, or alter telemetry.
The file must be a single YAML document, and dotvault refuses to read it if the file or its directory is group- or world-writable — it can turn a secrets mount on, so a path another account can rewrite is refused rather than warned about. A parse failure is fatal at startup and a skipped-with-warning overlay on later reloads, so a user's typo can never stop policy reaching the daemon.
Each field ratchets rather than overwriting: enabled may be turned on but not off, read_write may be turned off but not on, and mountpoint / cache_ttl are preferences the user's value simply wins. An omitted key is not a preference — only an explicitly written one is. See the Filesystem guide for the reasoning behind the two booleans ratcheting in opposite directions.
Downloads and exports carry the merged result
GET /api/v1/config/download and the /ui/config/ view show the running configuration, so a user preference that took effect appears there as though it were policy — the same way remote-config-merged rules do. Re-importing such a download as a system config would bake that preference in.
The mount root is your own KV prefix ({kv_mount}/{user_prefix}{username}/), bound at construction — a path through the mount cannot reach another user's secrets. The daemon mounts after its first successful Vault authentication and unmounts on shutdown; a mount failure is logged once and is never fatal.
Read-only is the default for a reason
The daemon's token can usually write to Vault. That capability exists for dotvault's own sync and enrolment work — exposing it through a filesystem makes every process running as you, and every mistyped shell redirect, one > away from replacing a credential. read_write: true is a separate decision from mounting.
One narrow filename collision
A secret and a folder sharing a KV name coexist fine — users/you/databricks is databricks.json and users/you/databricks/prod is databricks/prod.json. What does collide is a KV folder whose name already ends in .json, which competes with the secret of the same stem. The directory wins so the secrets underneath stay reachable, the daemon warns naming the path, and the shadowed secret has no path in the mount. The mount refuses to create such a directory, so it can only come from a KV tree already laid out that way.
Unix only
fuse.enabled has no effect on Windows: the daemon logs a warning and mounts nothing, so a config shared across a mixed-platform fleet is safe. There is no Windows equivalent planned — WinFsp is a DLL reached through cgo, and dotvault ships CGO_ENABLED=0 static binaries. Linux needs /dev/fuse and the fusermount3 helper (fuse3 package), and a systemd unit that does not set NoNewPrivileges= or any other seccomp-based sandbox directive, which disarm the helper — see Hardening and the FUSE mount; macOS needs macFUSE.
Reading a file in the mount calls Vault, so grep -r across the mount — or an editor indexing your home directory — reads every secret you have and puts each one in Vault's audit log. Reach for a specific path.
On Windows GPO, the equivalents are Enabled (REG_DWORD), Mountpoint (REG_SZ), ReadWrite (REG_DWORD) and CacheTTL (REG_SZ) under HKLM\SOFTWARE\Policies\goodtune\dotvault\FUSE, and the section round-trips through reg-import/reg-export like every other — an admin managing a mixed fleet from one policy sets it for the Linux and macOS machines that policy covers.
Client certificate section¶
The client_cert section makes a mutual-TLS client certificate available to other tools, so curl, a database driver or an internal API client can identify you to a service the way dotvault identifies you to Vault. The certificate and its key appear as client.crt, client.key and client.pem at the root of the filesystem mount, in Docker volumes that ask for them, and through the public Go package (client/) and the Python bindings (python/). The service on the far end is up to you; this section only supplies the client side.
On Windows only the Go package and the Python bindings serve the certificate: the filesystem mount and the Docker volume plugin are not available there, so the section has no files to put it in.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | false |
Serve a client certificate |
pki_mount |
string | vault.mtls.pki_mount, else pki |
PKI secrets engine mount that signs the certificate |
pki_role |
string | vault.mtls.pki_role |
PKI role to sign against. Required when the host signs and no vault.mtls.pki_role is there to inherit |
common_name |
string | {{.token_username}} |
Template for the subject common name (see below) |
ttl |
duration | 5m |
Lifetime requested for a signed certificate. At least 1m; no ceiling here, since the PKI role's max_ttl is the cap |
key_type |
string | ec |
ec (P-256) or rsa, for services that insist on RSA |
key_bits |
int | 0 |
RSA modulus (2048, 3072, 4096, 8192; 0 means 2048). Rejected with key_type: ec |
client_cert:
enabled: true
pki_mount: "pki"
pki_role: "dotvault-tools"
common_name: "{{.token_username}}"
ttl: "5m"
Where the certificate comes from¶
There are two sources, and the configured auth_method picks between them. It is never inferred from the key that happens to be in memory.
- Held. With
vault.auth_method: mtlsexactly (the software key backend) and a certificate already enrolled on the host, dotvault serves that certificate and key as they are. The pair follows the login certificate's own rotation (reissue_before): after a rotation the new pair is served. No token and nopki_roleare needed. Thepki_*,common_name,ttlandkey_*fields apply only if the held certificate is missing, expired or unreadable and a role is available, in which case dotvault falls back to the short-lived source; with no role it reports an error naming the cause. - Short-lived. Everywhere else —
oidc,ldap,token,mtls+tpm,mtls+os, a borrowed token, and always undervault.borrow_only— dotvault generates a key in memory, has<pki_mount>/sign/<pki_role>sign it with the current Vault token, and replaces it before it expires. The key lives only in the daemon's memory (the one place it reaches a filesystem is a Docker volume directory on the runtime tmpfs, deleted at the last unmount) and is never written to disk by dotvault.
mtls+tpm and mtls+os deliberately use the short-lived source: their login key is sealed in the TPM or kept in the OS certificate store precisely so that it cannot be taken out, and this feature never extracts it.
Under borrow_only the section is never "held": a borrow-only host runs no certificate login, so there is no credential on it to serve. It signs a short-lived certificate with the borrowed token, which is the motivating case: a remote host reached over SSH that holds a token but no certificate.
pki_mount and pki_role fall back to vault.mtls.pki_mount and vault.mtls.pki_role — including under borrow_only, which otherwise ignores the vault.mtls block, so one base config can serve the workstation and its remotes.
Rotation¶
A short-lived certificate is signed lazily on first use, and replaced when less than half of its issued lifetime remains (NotAfter − NotBefore, not the requested ttl, because the PKI role's max_ttl may shorten the request). Concurrent readers share one signing call. A held certificate is re-read from disk whenever the login credential is replaced.
Failed signs back off: after a failure no new sign is attempted for 10 seconds, doubling per consecutive failure up to 5 minutes, and a success or a different token resets it. Any two sign attempts made with the same token, whatever their outcome, are at least 10 seconds apart; a different token is not held to that interval, so a replacement for a token Vault rejected signs at once. While a sign is paced or backing off, a read returns the still-valid cached certificate. When there is none, it returns the error of the last failed sign, so a denial keeps reading as a denial (EIO from the filesystem, ErrDenied from the library); only when pacing has no failure on record — a PKI role whose max_ttl is shorter than 10 seconds, say — is the answer "try again shortly": EAGAIN from the filesystem, client.ErrSignPaced from the Go library (Python raises the base DotvaultError). This is what stops a policy that denies pki/sign from turning every ls -l of the mount, or every poll of client.pem, into a denied request at Vault.
In the daemon, signing follows the token lifecycle the way the SSH agent does. A sign that would start while the daemon is replacing its Vault token waits for the replacement, for up to 30 seconds, and then signs with the new token rather than the one Vault just rejected; if the replacement does not finish in time the read is told to try again (EAGAIN), not denied. If the daemon has instead given up on replacing the token and needs you to log in again, the read is told the same at once rather than after 30 seconds. A sign that Vault refuses because the token is no longer valid (a 403 or an expired token) makes the daemon check its token at once, and replace it if it is dead, instead of waiting for its next five-minute check; a role that simply denies pki/sign to a healthy token — the role missing from the token's policy, say — looks the same, a 403, so it is reported as a token rejection too and nudges one token lookup. Sign pacing bounds how often that happens, but the report shares the daemon's single rate-limit window (one report per 10 seconds) with the SSH agent's, so while the denial persists it can delay an agent-side report of a genuinely dead token by up to 10 seconds; fix the policy rather than leave it denying. The Go library and the Python bindings resolve their own token and are not affected.
Common name¶
common_name is a template with exactly two variables:
{{.token_username}}— the Vault identity of the token being used to sign:meta.usernamefromlookup-self, elsemeta.common_name. LDAP and userpass logins setmeta.username; an OIDC role sets it withclaim_mappings; a certificate login setsmeta.common_name. It is looked up once per token. If the token carries neither, signing fails with an error that names the cause and suggests{{.os_user}}. It never falls back silently to the OS account, because the service would then see a different person.{{.os_user}}— the OS account dotvault runs as, with anyDOMAIN\prefix stripped.
The default is the Vault identity rather than the OS account because on a borrowing remote the OS account (ubuntu, ec2-user) is usually not the person, and the far-end service identifies you by this name.
{{.user}} and {{.vault_username}} are refused at config load, with a message naming the two explicit variables. Those names mean the OS account elsewhere in dotvault (the Copy engine's {{.user}} and the SSH agent's {{.vault_username}} both expand to it), and a certificate subject is the one place where guessing wrong grants somebody else's identity.
OIDC needs a claim_mappings entry
A Vault OIDC role records no username by default, so {{.token_username}} fails on a plain OIDC login. Map a claim to username on the role, for example claim_mappings="email=username", or set common_name: "{{.os_user}}". The dev stack's OIDC role does the former.
The common name proves nothing unless the PKI role constrains it
A far-end service must not trust the certificate's common name as an identity unless the PKI role restricts which names a given Vault identity may request. Neither half of {{.token_username}} is a guarantee on its own. The token metadata it reads can be set by whoever creates the token: any holder of auth/token/create — which the least-privilege vault.policies setup requires — can mint a child token carrying meta.username of their choosing. And the PKI engine signs whatever common name the request asks for, if the role allows it: a user with pki/sign/<role> can call it directly with any name, bypassing dotvault entirely.
So the guarantee has to come from the role. Bind the allowed names to the caller's Vault identity, for example with allowed_domains naming an identity template ({{identity.entity.aliases.<auth mount accessor>.name}}) and allowed_domains_template=true, allow_bare_domains=true, and allow_any_name, allow_subdomains and allow_glob_domains all off — then a certificate can only carry the name of the entity whose token signed it. See Vault's PKI role documentation for the options your version supports. The dev stack's roles set allow_any_name=true so a test can request any identity; that is dev-only and must not be copied.
A held certificate keeps its own name
The held path serves whatever common name vault.mtls.common_name produced when the certificate was issued; this section's common_name does not apply to it.
Security properties and decisions¶
The held certificate is a Vault login credential
Under plain mtls, client.key is the key dotvault logs in to Vault with. Anything that can read it — a local process, or a container holding a volume — can log in to Vault as you until the certificate expires. This is accepted on the grounds that the device and its processes are trusted and the mount and volumes are reachable only by your own uid, but it is a real widening of what the file system exposes, and you should know it before enabling the section.
An inherited role means each short-lived certificate is a Vault login
When client_cert.pki_role is inherited from vault.mtls.pki_role, the certificates it signs are issued by the same CA the cert auth method trusts, so each one is also a Vault cert-auth login. The token that login yields is not bound to the certificate: it takes the cert auth role's TTL and is renewable, so it outlives the certificate's few minutes. dotvault logs a warning at startup naming both fields whenever a host signs under an inherited role. If you want the two kept apart, set a separate client_cert.pki_role whose CA the cert auth method does not trust (its own intermediate, or a different mount), and give that role no_store=true, a modest max_ttl, and client_flag=true, server_flag=false, plus the name constraints described under Common name. The dev stack's dotvault-tools role shows the no_store, max_ttl and flag settings, but it is not a starting point to copy: it sets allow_any_name=true, which is dev-only, and the dev stack trusts one CA for everything, so there the two are not separate.
This only applies to the short-lived source. Under plain mtls the held certificate is served whenever one is enrolled, and client_cert.pki_role is used only as a fallback when it is not, so a separate role does not keep plain mtls's service certificate apart from its Vault login. There is no opt-out under plain mtls: use a different auth_method (mtls+tpm, mtls+os, or a non-certificate method, all of which sign short-lived certificates) or accept that client.key is a Vault login.
Short-lived certificates are not revoked: they expire in minutes, which is why the recommended role uses no_store (Vault then does not even record them). A held certificate is different: when the login certificate rotates, vault.mtls.revoke_superseded (default on) revokes the one it replaced, so a long-lived process that loaded the old pair once loses it at rotation. Rotation happens reissue_before (default 7 days) ahead of expiry; have such a process re-read the files per connection rather than caching the pair.
Key material and PEM never appear in logs or errors. The log lines carry the serial, NotAfter, source and common name only.
Reading it¶
GET /api/v1/status carries a client_cert block (unauthenticated, like the sibling blocks): state (idle, serving, expired — the last certificate served is past its not_after and nothing has asked for a replacement since — or error), source (held or ephemeral), common_name, serial, not_after and last_error. It never carries the PEM or the key. dotvault status prints a config-derived section — which source applies, the PKI mount and role, the TTL, and for a held certificate what is on disk — and never signs and never contacts Vault; what the running daemon is actually serving is on the API.
The section is static (a change needs a restart), is refused in a remote-config document, and is not user-overridable through the per-user config file: a certificate is a credential a process can present to a service, a wider grant than the read-only view of your own secrets that fuse allows there. It is validated whether or not it is enabled. On Windows GPO the equivalents are Enabled (REG_DWORD), PKIMount, PKIRole, CommonName, TTL, KeyType (REG_SZ) and KeyBits (REG_DWORD) under HKLM\SOFTWARE\Policies\goodtune\dotvault\ClientCert, and it round-trips through reg-import/reg-export like every other section.
Docker volumes section¶
The docker section serves your secrets to containers as a Docker volume plugin (rootless Docker and Podman both consume the same protocol). A volume is a directory of plain files — gh.json per secret, rendered exactly as the filesystem renders it — that the daemon materialises when a container first mounts it, keeps current from Vault events (Enterprise) or on a refresh window (Community), and deletes when the last container lets go. See the Docker volumes guide for registration, the per-volume secrets/layout/mode/ttl options, and the refresh policy.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | false |
Serve the plugin |
socket |
string | $XDG_RUNTIME_DIR/dotvault/docker.sock |
Unix socket the engine connects to (0600 in a 0700 directory); must be absolute (or ~-relative). The engine is told about it by a one-line spec file, which the Linux packages create per user for rootless Docker — see the guide. Change this and you must write that file yourself, since the packaged drop-in names the default |
volume_dir |
string | $XDG_RUNTIME_DIR/dotvault/volumes |
Directory volumes are materialised under, one subdirectory each. Created at mode 0700 |
cache_ttl |
duration | 1m |
Default refresh window for a volume without its own ttl option. Governs Community, and Enterprise while the event subscription is down; must be positive and at most 10 minutes, since the window is also how long a rotated secret keeps being served to a container |
docker:
enabled: true
socket: "" # default: $XDG_RUNTIME_DIR/dotvault/docker.sock
volume_dir: "" # default: $XDG_RUNTIME_DIR/dotvault/volumes
cache_ttl: "1m"
The socket is deliberately not under an engine's own plugin directory: a rootless dockerd scans /run/docker/plugins inside its own mount namespace, which nothing outside it can populate, and a rootful one's is root-owned. Both engines accept a .spec file naming any socket, and dotvault status prints its path and contents. The daemon never writes that file — it does not edit another tool's configuration. The Linux packages do, for the rootless Docker case only, via a systemd user-tmpfiles drop-in that creates ~/.local/lib/docker/plugins/dotvault.spec at login; it never overwrites a file that already exists, and it is opted out of with ln -s /dev/null ~/.config/user-tmpfiles.d/dotvault-docker.conf. Note it names the default socket path, so a customised socket needs a hand-written spec. See Registering the plugin.
Linux only
docker.enabled has no effect on macOS or Windows: the daemon logs a warning and serves nothing. Docker Desktop and Podman machine run the engine in a virtual machine, where a host-side socket is unreachable, so there is nothing a build for those platforms could usefully bind. A config shared across a mixed-platform fleet is safe.
Volume definitions (names and options, never secret data) persist in {cache_dir}/docker-volumes.json, so a daemon restart under a running container resumes refreshing the directory that container still holds. The section is static — a change needs a restart — and is refused in a remote-config document, like every other section that opens a listener.
On Linux, the packaged dotvault-docker.socket unit (optional, not enabled by default) lets systemd bind this socket and hold the fd across daemon restarts, so an engine call landing mid-restart queues instead of failing. docker.enabled remains the master switch, and under activation the unit's ListenStream= path wins over socket — the .spec file must name that path. The unit's default ListenStream= and the default socket are the same path, so the packaged spec drop-in above is correct in both modes. See Socket activation and plugin registration.
On Windows GPO, the equivalents are Enabled (REG_DWORD), Socket (REG_SZ), VolumeDir (REG_SZ) and CacheTTL (REG_SZ) under HKLM\SOFTWARE\Policies\goodtune\dotvault\Docker, and the section round-trips through reg-import/reg-export like every other, for the same mixed-fleet reason as fuse.
Observability section¶
Exports OpenTelemetry metrics and logs over OTLP. Each signal is configured in its own nested metrics: / logs: block, so the two signals can go to separate backends or one can be switched off. See Observability in the deployment guide for the exported instruments and worked examples.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | false |
Master switch for both signals. A per-signal enabled: true cannot resurrect a disabled subsystem |
endpoint |
string | — | Deprecated shared default (see note below). OTLP collector endpoint; same value contract as the per-signal endpoint |
protocol |
string | — | Deprecated shared default. grpc or http/protobuf. Empty falls through to the standard OTEL_EXPORTER_OTLP_* env vars |
insecure |
bool | false |
Deprecated shared default. Disable transport TLS |
headers |
map | — | Deprecated shared default. OTLP headers, typically a vendor bearer token — treat as a credential |
export_interval |
string | SDK default | Metric export cadence as a Go duration (e.g. 30s). Not deprecated |
metrics / logs |
block | — | Per-signal configuration, fields below — the supported home for exporter settings |
Shared exporter fields are deprecated
The top-level endpoint / protocol / insecure / headers fields still work as shared defaults the per-signal blocks layer onto, but they are being retired in stages (#140): this release warns at startup and counts each use on the dotvault.config.deprecated metric (attribute field), a later release makes the warning louder, and 1.0 removes them. Configure each signal in its own block, or use the standard OTEL_EXPORTER_OTLP_* environment variables for values shared across both signals — the env-var fallthrough remains fully supported.
Per-signal override block (metrics: / logs:):
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | inherit | Tri-state: unset inherits the master switch, explicit false turns this signal off |
endpoint |
string | inherit | Non-empty overrides the shared endpoint (separate backend). A full URL is the recommended form: the scheme carries TLS intent (https → TLS, http → plaintext, on both protocols) and an explicit path is used verbatim — no mount path assumed; a path-less URL gets the standard /v1/metrics / /v1/logs appended (http/protobuf). Bare host:port (canonical gRPC) leaves TLS to insecure; dns:/// passes through to the gRPC resolver |
protocol |
string | inherit | Non-empty overrides the shared protocol |
insecure |
bool | inherit | Tri-state: unset inherits the shared value. Meaningful for scheme-less endpoints; an endpoint URL's scheme already carries the TLS intent, and an explicit true forces plaintext even over https:// — prefer stating the intent in the scheme |
headers |
map | inherit | Replaces the shared map wholesale — never merged, so one backend's token is not sent to the other. An explicitly empty headers: {} means "this signal sends no headers", distinct from omitting the field (inherit) |
temporality |
string | cumulative |
Metric temporality preference: cumulative, delta, or lowmemory — the OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE vocabulary and instrument-kind mapping (empty falls through to that env var). delta reports counters/observable counters/histograms as per-interval deltas, as Datadog and some other vendors expect. Metrics block only — setting it under logs: is a config error |
observability:
enabled: true
metrics:
endpoint: https://otel.internal.example
protocol: http/protobuf
temporality: delta # e.g. for a Datadog-fronted collector
headers:
authorization: "Bearer metrics-token"
logs:
endpoint: https://logs.vendor.example # separate backend
protocol: http/protobuf
headers: # with its own credentials
x-api-key: "logs-token"
Resource attributes¶
Every exported metric and every exported log record carries the same OTel resource, because the MeterProvider and the LoggerProvider share one. It identifies the emitting daemon: service.name (always dotvault), service.version, user.name, host.name, os.type, host.arch, and the process.runtime.* pair. These are process constants, so they add no time series — a backend that surfaces target_info (Prometheus, for instance) exposes them as one info series per daemon.
user.name and host.name leave the host
user.name is the OS account the daemon runs as (paths.Username(), DOMAIN\ prefix stripped) and host.name is this machine's fully-qualified name. Both are sent to whichever collector you configure, a third-party SaaS included. dotvault is a per-user daemon, so attributing a series to a user is the point of the attribute — a fleet view cannot otherwise answer "whose daemon is failing" — but it is a genuine disclosure of who is running the software and where. There is no per-attribute opt-out: the control is observability.enabled, which is false by default. A disabled deployment emits nothing at all and, per the note below, makes no DNS call either. Neither attribute ever carries secret material — no Vault path, key, or credential. If the account name is itself sensitive in your environment, run the daemon under a non-identifying service account or leave observability off.
host.name is resolved once at startup: os.Hostname(), and — only when that name has no dot — a single forward LookupCNAME to qualify it, the same mechanism hostname -f uses. This is an outbound DNS query at daemon startup, which matters on a locked-down or air-gapped network. It is bounded at two seconds and never fails startup: a resolver error, a timeout, an unqualified answer, or a localhost. alias all fall back to the short name, and an empty hostname omits the attribute entirely (as a failed user lookup omits user.name). No lookup happens when os.Hostname() is already qualified, and none happens at all when observability is disabled.
macOS often stays unqualified
dotvault ships as a pure-Go CGO_ENABLED=0 binary, so it uses Go's own resolver rather than the system one. On macOS that means scutil-managed search domains — the ones a VPN or corporate split-DNS profile installs — are not consulted, so host.name can stay the short name even where hostname -f in a shell returns the FQDN. The value is still correct, just less specific; treat host.name as possibly-short on macOS fleets.
Treat host.name as discovered, not attested. The CNAME answer comes from whatever resolver the host is pointed at, so a hostile or compromised one chooses the name your collector attributes the data to. Nothing is executed or connected to on the strength of it, and the guards above reject accidents rather than deliberate answers — a collector that needs trustworthy attribution should take it from the transport (mTLS, a per-host token), not from a resource attribute.
While the deprecated shared fields remain in play, a signal that overrides endpoint without setting its own headers inherits the shared map — including any shared bearer token, which then goes to the overridden backend. The daemon warns at startup when it sees that combination; state the intent with an explicit per-signal headers: ({} for none) to silence it. enabled: true with both signals explicitly off is rejected at config load.
Remote config section¶
See Remote Configuration for details. When remote_config.url is set, the local file/registry config becomes a base that is overlaid with dynamic sections (rules, enrolments, sync) fetched from a dotvault-config service.
Rules section¶
See Sync Rules for details.
Enrolments section¶
See Service Onboarding for details.
Validation¶
dotvault validates the configuration on startup and exits with an error if:
vault.addressis missing- No rules are defined (waived when
remote_config.urlis set — the remote document may supply them) - Rule names are not unique
- A rule omits
vault_key(a keyless rule) but also omitstarget.template— there is no secret data to write - A
target.formatis not one of:yaml,json,ini,toml,text,netrc,ssh_config - A rule sets
target.delete_nulls: trueon a format other thanjsonoryaml— the others have no null literal a template could render, and silently ignoring the flag would leave you believing a retired credential had been deleted (see Removing a field) web.listenresolves to a non-loopback address (when web is enabled)- A
web.editable_pathsentry names the root of your key space ("","/") rather than a folder in it — silently ignoring it would leave you believing you had granted editing that you had not - A
web.editable_pathsentry is more than one segment deep (scratch/notes) — your key space is one folder deep, so that names a secret rather than a folder; writescratch - A
web.editable_pathsentry is not a valid relative KV path (an empty segment,.,.., or an embedded NUL) - Two
web.editable_pathsentries name the same folder once canonicalised (personaland/personal/) - An enrolment entry has an empty
enginefield api.unix.pathis set to a relative path (it would resolve against each process's working directory, so the daemon and a client started elsewhere would disagree about where the socket is)fuse.mountpointis set to a relative path (same reason asapi.unix.path: the daemon and anyone reading the config would disagree about where the secrets appeared)fuse.cache_ttldoes not parse as a duration, or is negativedocker.socketordocker.volume_diris set to a relative path (same reason asapi.unix.path)docker.cache_ttldoes not parse as a duration, is zero or negative, or exceeds 10 minutesclient_cert.ttldoes not parse as a duration, or is under one minuteclient_cert.common_namedoes not parse as a template, or references a variable other than{{.token_username}}and{{.os_user}}({{.user}}and{{.vault_username}}are refused by name)client_cert.key_typeis notecorrsa, orclient_cert.key_bitsis not a valid RSA size or is set withecclient_cert.enabledis true, the host signs rather than holds, and neitherclient_cert.pki_rolenorvault.mtls.pki_rolenames a role