Server

The long-running daemon started by vault server -config=…. This is the process that hosts the storage barrier, the API handler, every backend, and the cluster's place in the HA quorum. Source: command/server.go (3,480 lines), with helpers in command/server/ and internalshared/configutil/.

Purpose

ServerCommand parses configuration, opens listeners, builds a vault.Core, runs the seal/unseal lifecycle, and serves HTTP until shutdown signals (SIGINT, SIGTERM, SIGHUP for reloads, SIGUSR2 for stack dumps). It is the only Vault subcommand that owns persistent state.

Directory layout

command/
├── server.go                # ServerCommand and run loop
├── server_profile.go        # pprof handlers (build-tag gated)
├── server_noprofile.go      # stub when the pprof tag is off
├── server_util.go           # small helpers
├── commands.go              # registers "server" alongside every other CLI command
└── server/
    ├── config.go            # HCL/JSON server config parsing
    ├── config_test.go       # … and its many fixtures
    └── test-fixtures/
internalshared/
├── configutil/              # shared parsers for storage/seal/listener/telemetry blocks
└── listenerutil/            # listener creation and TLS plumbing

Key abstractions

Symbol	File	Description
ServerCommand	command/server.go	The CLI command struct. Holds backends, channels, run options.
vaultHandlers	command/commands.go	Maps backend type → factory for physical, audit, credential, logical, service-registration backends.
Server config	command/server/config.go	Parsed server config (storage, listeners, seals, telemetry, …).
setSeal / setupCluster	command/server.go	Build the seal stack from config and bind cluster ports.
runUnseal	command/server.go	Runs the auto-unseal or Shamir loop until the core is unsealed.
Reload* functions	command/server.go	Handle SIGHUP reloads of TLS, audit, and telemetry.

Startup sequence

sequenceDiagram
    participant Main as command.Run
    participant SC as ServerCommand
    participant Cfg as server.Config
    participant Phys as physical.Backend
    participant Seal as vault.Seal
    participant Core as vault.Core
    participant HTTP as http.Handler

    Main->>SC: Run(args)
    SC->>Cfg: LoadConfig(file or dir)
    SC->>Phys: PhysicalBackends[type](cfg)
    SC->>Seal: setSeal(cfg.Seals)
    SC->>Core: NewCore(CoreConfig{Phys, Seal, ...})
    SC->>HTTP: http.Handler(core)
    SC->>SC: Open listeners (TLS, sockets)
    SC->>Core: runUnseal()
    SC-->>Main: blocks on shutdown channels

The vaultHandlers struct, populated in command/commands.go, wires together every pluggable subsystem:

• physicalBackends: inmem, inmem_ha, inmem_transactional, raft, plus the physical/<name> packages.
• auditBackends: file, socket, syslog from audit/.
• credentialBackends: minimal set (approle, cert, jwt, oidc, userpass); the rest come from helper/builtinplugins/.
• logicalBackends: minimal set (kv, pki, ssh, transit); the rest come from helper/builtinplugins/.
• serviceRegistrations: consul, kubernetes from serviceregistration/.

Lifecycle hooks

• Init: when storage is empty, vault operator init triggers vault.Core.Initialize from vault/init.go. The server itself just exposes the API endpoint.
• Unseal: runUnseal repeatedly calls core.Unseal with each provided key share or KMS-wrapped key.
• Active node: once unsealed and elected, core.runStandby transitions to active, mounts every backend, starts the expiration manager, and begins serving writes.
• Reload (SIGHUP): re-reads listeners' TLS certs, audit destinations, telemetry pipes, and license; logged through helper/reloadutil shims.
• Shutdown (SIGINT/SIGTERM): closes listeners, drains in-flight requests, seals the core, exits.
• Diagnose dump (SIGUSR2): writes goroutine stacks and a diagnostic snapshot.

Configuration

command/server/config.go defines the top-level config. Block parsers live in internalshared/configutil/:

• storage — chosen physical backend.
• ha_storage — separate HA backend if storage backend isn't HA-capable.
• listener — HTTP/HTTPS listeners; TLS, CORS, rate limits.
• seal — Shamir or one of the auto-unseal types.
• telemetry — Prometheus, StatsD, Circonus, Datadog.
• service_registration — Consul or Kubernetes.
• cluster_addr, api_addr, disable_mlock, ui, experiments, replication, entropy, …

The full grammar is documented in Reference / configuration.

Integration points

• Storage: opens the configured physical backend; passes it to vault.NewCore.
• HTTP: http.Handler(core) returns the http.Handler defined in http/handler.go.
• Cluster: server initializes the cluster listener (used for HA forwarding) on cluster_addr.
• Plugins: passes helper/builtinplugins.Registry to vault.NewCore.
• License (Enterprise): stubbed in OSS; vault/version_store.go and _ce.go siblings.

Entry points for modification

• Adding a new top-level config block: extend command/server/config.go and the corresponding parser in internalshared/configutil/.
• Adding a new physical backend: register it in command/commands.go's extendAddonHandlers.
• Hooking into reload: implement reloadutil.Reloadable and register in ServerCommand.Reload.
• Server-side flag: add to command/server.go's Flags() builder.

For diagnostics see Debugging and vault operator diagnose.