Router and mounts

The router is what turns a URL path into a backend call. Mounts are the bindings between a URL prefix, a backend factory, and an entry in the persistent mount tables. Source: vault/router.go (1,144 lines) and vault/mount.go (2,121 lines).

Purpose

• Mounts persist the operator's intent: "the AWS secret engine lives at aws/, the userpass auth method at auth/userpass/, with these tune options." There are three mount tables: secret mounts, auth mounts, and audit mounts.
• The router is the in-memory radix tree that performs the actual lookup at request time: given a path, find the longest matching mount and forward the request to its backend.

Directory layout

vault/
├── router.go                 # Router struct + radix prefix tree
├── router_access.go          # Restricted view passed to backends
├── router_testing.go         # Helpers
├── mount.go                  # MountTable, MountEntry, mounting logic
├── mount_stubs_oss.go        # CE stubs (e.g., filtered mounts)
├── mount_util.go, mount_util_shared.go
└── mountmigrationstatus_enumer.go

The router itself is not persisted; it's reconstructed at unseal time from the mount tables stored under core/mounts, core/auth, and core/audit.

Key abstractions

Symbol	File	Description
Router	vault/router.go	The radix tree. Concurrent reads, write-locked mutations.
Router.MatchingBackend	vault/router.go	Returns the backend for a given path.
Router.MatchingMountByUUID	vault/router.go	Reverse lookup by mount accessor.
MountEntry	vault/mount.go	Persisted record: path, type, accessor, UUID, options, tune fields.
MountTable	vault/mount.go	Slice of MountEntry plus a lock.
Core.mounts, Core.auth, Core.audit	vault/core.go	Three live mount tables.
Core.setupMounts	vault/mount.go	Reads tables from storage and rebuilds the router at unseal time.
Core.mount / Core.unmount	vault/mount.go	Live add/remove of a mount. Forwards if standby.
Core.tuneMount	vault/mount.go	Updates a mount's tunable options (TTL, listing visibility, …).
RouterAccess	vault/router_access.go	Limited view of the router exposed to backends through their system view.

How a mount becomes routable

sequenceDiagram
    participant Op as Operator
    participant CLI as vault secrets enable
    participant Core as Core.mount
    participant Tab as MountTable
    participant Phys as Storage barrier
    participant R as Router
    participant B as Backend factory
    Op->>CLI: secrets enable -path=db database
    CLI->>Core: POST /sys/mounts/db
    Core->>Tab: append MountEntry
    Core->>Phys: persist mount table
    Core->>B: Factory(BackendConfig{StorageView: viewForUUID})
    B-->>Core: logical.Backend
    Core->>R: Mount("db/", backend, mountEntry)
    Core-->>CLI: 204 No Content

The factory comes from helper/builtinplugins/registry.go (built-ins) or vault/plugincatalog/ (external). Each backend gets a barrier view keyed by the mount's UUID — backends never see paths outside their own subtree.

Mount tunables

Operators can change these post-mount via vault {secrets|auth} tune:

Field	Stored in	Notes
default_lease_ttl, max_lease_ttl	MountEntry.Config	Override system defaults.
audit_non_hmac_request_keys, audit_non_hmac_response_keys	MountEntry.Config	Keys excluded from audit HMAC.
listing_visibility	MountEntry.Config	Whether the UI lists this mount.
passthrough_request_headers, allowed_response_headers	MountEntry.Config	HTTP header passthrough.
description	MountEntry	Human-readable.
plugin_version, override_pinned_version	MountEntry.Config	Plugin pinning.
delegated_auth_accessors	MountEntry.Config	Accessors that may delegate auth.
user_lockout_threshold, user_lockout_duration, …	MountEntry.Config	Lockout policy for auth methods.

Special paths

vault/mount.go and vault/path_registry.go define a few reserved root paths:

• cubbyhole/ — per-token storage; mounted automatically (vault/logical_cubbyhole.go).
• sys/ — the in-process system backend (vault/logical_system.go, 7,766 lines).
• auth/token/ — the token store mount (vault/token_store.go).
• identity/ — the identity store (vault/identity_store.go).
• secret/ — the default KV v1 mount in dev mode.

Filtered mounts (Enterprise)

vault/mount_stubs_oss.go is the OSS stub for performance-replication "filtered mounts" — Enterprise lets you exclude specific mounts from being replicated. In OSS the filter list is always empty.

Integration points

• Core: holds the three mount tables and the router.
• Backends: created via factories registered in command/commands.go and helper/builtinplugins/.
• Plugin catalog: external plugins are looked up in vault/plugincatalog/ before mount.
• Storage: the mount tables live under core/mounts, core/auth, core/audit.
• Replication: Enterprise replicates these tables; OSS does not.

Entry points for modification

• Add a new built-in mount type: register the factory in command/commands.go and helper/builtinplugins/registry.go.
• Add a new tunable: extend MountConfig in vault/mount.go and persist it.
• Add a new reserved path: register in vault/path_registry.go so the router won't hand it out.
• Hook into mount lifecycle: Core.setupMounts and Core.unmount are the choke points.