Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 ยท Concepts and Setup

The Vault Configuration File

Learn the Vault server config file in HCL: the storage, listener, seal, api_addr and cluster_addr stanzas, UI and telemetry, with a runnable config checker.

A production Vault server is started with vault server -config=vault.hcl. The file, written in HCL (the same configuration language as Terraform), tells Vault where to store data, which addresses to listen on, how to unseal, and how to behave in a cluster. A wrong value here can leave Vault unreachable or insecure, so it is worth knowing every common stanza.

This lesson explains the core stanzas and shows an annotated example. A runnable checker flags common mistakes.

Vault itself is not available here. The example file is read-only and the Python checker is a simplified stand-in that understands just the few settings it names; it is not a real HCL parser or a substitute for vault server -config validation.

A complete minimal file

HCL
ui            = true
disable_mlock = true            # with Raft integrated storage, see the docs
api_addr      = "https://vault-1.example.internal:8200"
cluster_addr  = "https://vault-1.example.internal:8201"

storage "raft" {
  path    = "/opt/vault/data"
  node_id = "vault-1"
}

listener "tcp" {
  address       = "0.0.0.0:8200"
  tls_cert_file = "/etc/vault/tls/vault.crt"
  tls_key_file  = "/etc/vault/tls/vault.key"
}

telemetry {
  prometheus_retention_time = "30s"
  disable_hostname          = true
}

The stanzas

  • storage: where encrypted data lives. raft (integrated storage) is the recommended choice: no external system, built-in replication and snapshots. Others include consul, file (single node only, not recommended for HA) and inmem (dev only).
  • listener "tcp": the API socket. In production always set tls_cert_file and tls_key_file. Setting tls_disable = true is only for tests.
  • seal: auto-unseal configuration (for example seal "awskms", seal "azurekeyvault", seal "gcpckms", seal "transit"). Omit it to use Shamir shares.
  • api_addr: the address clients should use to reach this node. Standbys redirect clients to it.
  • cluster_addr: the address other nodes use for request forwarding and replication, by default on port 8201.
  • ui: enables the built-in web UI.
  • telemetry: metrics output (Prometheus, StatsD, Datadog).
  • log_level, log_format: logging.
  • default_lease_ttl and max_lease_ttl: global lease defaults (768 hours default maximum).
  • disable_mlock: Vault locks memory to keep secrets out of swap. With Raft, the guidance is to disable mlock and disable swap instead; check the current documentation for your version.
flowchart LR
    F["vault.hcl"] --> ST["storage: raft"]
    F --> L["listener: tcp + TLS"]
    F --> SE["seal: awskms (optional)"]
    F --> AD["api_addr / cluster_addr"]
    F --> T["telemetry, ui, log_level"]

The server reads one file (or a directory of files) at startup.

Starting with a config

Terminal
vault server -config=/etc/vault/vault.hcl

-config can also name a directory; all .hcl and .json files in it are merged. Vault reads the config only at start: change a listener or storage setting and you must restart. A small set of items, such as log level, can be reloaded by sending SIGHUP. Run it as a systemd service under its own user, not root.

A tiny config checker

This stand-in reads a simplified dictionary form and reports typical problems.

Python Check a Vault config for common mistakes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Extracting settings from simple HCL

HCL blocks can be nested, but many config lines are plain key = "value" pairs. This stand-in extracts the top-level ones so a script could compare environments.

Python Read top-level key = value lines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The stand-in tracks brace depth so the path inside storage is not mistaken for a top-level setting.

Secrets in the config file

Do not put cloud credentials in the file; give the machine an IAM role or managed identity. When a value must be secret, pass it through an environment variable (many seal settings can read them). Restrict the file's permissions so only the Vault user can read it, and keep it in version control without secrets.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which storage option is recommended for a new production cluster?

    Integrated storage needs no external system and provides replication and snapshots.
  2. 2. What is api_addr used for?

    Standby nodes redirect clients to the active node's api_addr.
  3. 3. Which listener setting must never be used in production?

    Disabling TLS sends tokens and secrets in clear text.
  4. 4. When does Vault read its config file?

    Restart to apply storage and listener changes; SIGHUP reloads a few settings.

Summary

  • The config file in HCL sets storage, listeners, seal, addresses, UI and telemetry.
  • Use Raft integrated storage and TLS everywhere in production.
  • api_addr is for clients; cluster_addr is for node-to-node traffic.
  • Add a seal stanza for auto-unseal; otherwise Shamir shares are used.
  • Restart to apply most changes; keep credentials out of the file.

Next: Secrets Engines Overview