open-vault/website/content/docs/configuration/index.mdx

---
layout: docs
page_title: Server Configuration
description: Vault server configuration reference.
---

# Vault Configuration

Outside of development mode, Vault servers are configured using a file.
The format of this file is [HCL](https://github.com/hashicorp/hcl) or JSON.

@include 'plugin-file-permissions-check.mdx'

An example configuration is shown below:

```javascript
storage "consul" {
  address = "127.0.0.1:8500"
  path    = "vault/"
}

listener "tcp" {
  address     = "127.0.0.1:8200"
  tls_disable = 1
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}
```

After the configuration is written, use the `-config` flag with `vault server`
to specify where the configuration is.

## Parameters

- `storage` `([StorageBackend][storage-backend]: <required>)` –
  Configures the storage backend where Vault data is stored. Please see the
  [storage backends documentation][storage-backend] for the full list of
  available storage backends. Running Vault in HA mode would require
  coordination semantics to be supported by the backend. If the storage backend
  supports HA coordination, HA backend options can also be specified in this
  parameter block. If not, a separate `ha_storage` parameter should be
  configured with a backend that supports HA, along with corresponding HA
  options.

- `ha_storage` `([StorageBackend][storage-backend]: nil)` – Configures
  the storage backend where Vault HA coordination will take place. This must be
  an HA-supporting backend. If not set, HA will be attempted on the backend
  given in the `storage` parameter. This parameter is not required if the
  storage backend supports HA coordination and if HA specific options are
  already specified with `storage` parameter. (Refer to [Use Integrated Storage
  for HA
  Coordination](/vault/tutorials/raft/raft-ha-storage)
  for a usage example.)

- `listener` `([Listener][listener]: <required>)` – Configures how
  Vault is listening for API requests.

- `user_lockout` `([UserLockout][user-lockout]: nil)` –
  Configures the user-lockout behaviour for failed logins. For more information, please see the
  [user lockout configuration documentation](/vault/docs/configuration/user-lockout). 

- `seal` `([Seal][seal]: nil)` – Configures the seal type to use for
  auto-unsealing, as well as for
  [seal wrapping][sealwrap] as an additional layer of data protection.

- `cluster_name` `(string: <generated>)` – Specifies the identifier for the
  Vault cluster. If omitted, Vault will generate a value. When connecting to
  Vault Enterprise, this value will be used in the interface.

- `cache_size` `(string: "131072")` – Specifies the size of the read cache used
  by the physical storage subsystem. The value is in number of entries, so the
  total cache size depends on the size of stored entries.

- `disable_cache` `(bool: false)` – Disables all caches within Vault, including
  the read cache used by the physical storage subsystem. This will very
  significantly impact performance.

- `disable_mlock` `(bool: false)` – Disables the server from executing the
  `mlock` syscall. `mlock` prevents memory from being swapped to disk. Disabling
  `mlock` is not recommended unless using [integrated storage](/vault/docs/internals/integrated-storage).
  Follow the additional security precautions outlined below when disabling `mlock`.
  This can also be provided via the environment variable `VAULT_DISABLE_MLOCK`.

  Disabling `mlock` is not recommended unless the systems running Vault only
  use encrypted swap or do not use swap at all. Vault only supports memory
  locking on UNIX-like systems that support the mlock() syscall (Linux, FreeBSD, etc).
  Non UNIX-like systems (e.g. Windows, NaCL, Android) lack the primitives to keep a
  process's entire memory address space from spilling to disk and is therefore
  automatically disabled on unsupported platforms.

  Disabling `mlock` is strongly recommended if using [integrated
  storage](/vault/docs/internals/integrated-storage) due to
  the fact that `mlock` does not interact well with memory mapped files such as
  those created by BoltDB, which is used by Raft to track state. When using
  `mlock`, memory-mapped files get loaded into resident memory which causes
  Vault's entire dataset to be loaded in-memory and cause out-of-memory
  issues if Vault's data becomes larger than the available RAM. In this case,
  even though the data within BoltDB remains encrypted at rest, swap should be
  disabled to prevent Vault's other in-memory sensitive data from being dumped
  into disk.

  On Linux, to give the Vault executable the ability to use the `mlock`
  syscall without running the process as root, run:

  ```shell
  sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault))
  ```

  ~> Note: Since each plugin runs as a separate process, you need to do the same
  for each plugin in your [plugins
  directory](/vault/docs/plugins/plugin-architecture#plugin-directory).

  If you use a Linux distribution with a modern version of systemd, you can add
  the following directive to the "[Service]" configuration section:

  ```ini
  LimitMEMLOCK=infinity
  ```

- `plugin_directory` `(string: "")` – A directory from which plugins are
  allowed to be loaded. Vault must have permission to read files in this
  directory to successfully load plugins, and the value cannot be a symbolic link.

  @include 'plugin-file-permissions-check.mdx'

- `plugin_file_uid` `(integer: 0)` – Uid of the plugin directories and plugin binaries if they
  are owned by an user other than the user running Vault. This only needs to be set if the
  file permissions check is enabled via the environment variable `VAULT_ENABLE_FILE_PERMISSIONS_CHECK`.

- `plugin_file_permissions` `(string: "")` – Octal permission string of the plugin
  directories and plugin binaries if they have write or execute permissions for group or others.
  This only needs to be set if the file permissions check is enabled via the environment variable
  `VAULT_ENABLE_FILE_PERMISSIONS_CHECK`.

- `telemetry` `([Telemetry][telemetry]: <none>)` – Specifies the telemetry
  reporting system.

- `default_lease_ttl` `(string: "768h")` – Specifies the default lease duration
  for tokens and secrets. This is specified using a label suffix like `"30s"` or
  `"1h"`. This value cannot be larger than `max_lease_ttl`.

- `max_lease_ttl` `(string: "768h")` – Specifies the maximum possible lease
  duration for tokens and secrets. This is specified using a label
  suffix like `"30s"` or `"1h"`. Individual mounts can override this value
  by tuning the mount with the `max-lease-ttl` flag of the
  [auth](/vault/docs/commands/auth/tune#max-lease-ttl) or
  [secret](/vault/docs/commands/secrets/tune#max-lease-ttl) commands.

- `default_max_request_duration` `(string: "90s")` – Specifies the default
  maximum request duration allowed before Vault cancels the request. This can
  be overridden per listener via the `max_request_duration` value.

- `detect_deadlocks` `(string: "")` - Specifies the internal mutex locks that should be monitored for
potential deadlocks. Currently supported value is `statelock`, which will cause "POTENTIAL DEADLOCK:"
to be logged when an attempt at a core state lock appears to be deadlocked. Enabling this can have
a negative effect on performance due to the tracking of each lock attempt.

- `raw_storage_endpoint` `(bool: false)` – Enables the `sys/raw` endpoint which
  allows the decryption/encryption of raw data into and out of the security
  barrier. This is a highly privileged endpoint.

- `introspection_endpoint` `(bool: false)` - Enables the `sys/internal/inspect` endpoint
  which allows users with a root token or sudo privileges to inspect certain subsystems inside Vault.

- `ui` `(bool: false)` – Enables the built-in web UI, which is available on all
  listeners (address + port) at the `/ui` path. Browsers accessing the standard
  Vault API address will automatically redirect there. This can also be provided
  via the environment variable `VAULT_UI`. For more information, please see the
  [ui configuration documentation](/vault/docs/configuration/ui).

- `pid_file` `(string: "")` - Path to the file in which the Vault server's
  Process ID (PID) should be stored.

- `enable_response_header_hostname` `(bool: false)` - Enables the addition of an HTTP header
  in all of Vault's HTTP responses: `X-Vault-Hostname`. This will contain the
  host name of the Vault node that serviced the HTTP request. This information
  is best effort and is not guaranteed to be present. If this configuration
  option is enabled and the `X-Vault-Hostname` header is not present in a response,
  it means there was some kind of error retrieving the host name from the
  operating system.

- `enable_response_header_raft_node_id` `(bool: false)` - Enables the addition of an HTTP header
  in all of Vault's HTTP responses: `X-Vault-Raft-Node-ID`. If Vault is participating
  in a Raft cluster (i.e. using integrated storage), this header will contain the
  Raft node ID of the Vault node that serviced the HTTP request. If Vault is not
  participating in a Raft cluster, this header will be omitted, whether this configuration
  option is enabled or not.

- `log_level` `(string: "info")` - Log verbosity level.
  Supported values (in order of descending detail) are `trace`, `debug`, `info`, `warn`, and `error`.
  This can also be specified via the `VAULT_LOG_LEVEL` environment variable.

  ~> Note: On SIGHUP (`sudo kill -s HUP` _pid of vault_), if a valid value is specified, Vault will update the existing log level,
  overriding (even if specified) both the CLI flag and environment variable.

  ~> Note: Not all parts of Vault's logging can have its log level be changed dynamically this way; in particular,
  secrets/auth plugins are currently not updated dynamically.

- `log_format` - Equivalent to the [`-log-format` command-line flag](/vault/docs/commands/server#_log_format).

- `log_file` - Equivalent to the [`-log-file` command-line flag](/vault/docs/commands/server#_log_file).

- `log_rotate_duration` - Equivalent to the [`-log-rotate-duration` command-line flag](/vault/docs/commands/server#_log_rotate_duration).

- `log_rotate_bytes` - Equivalent to the [`-log-rotate-bytes` command-line flag](/vault/docs/commands/server#_log_rotate_bytes).

- `log_rotate_max_files` - Equivalent to the [`-log-rotate-max-files` command-line flag](/vault/docs/commands/server#_log_rotate_max_files).

- `experiments` `(string array: [])` - The list of experiments to enable for this node.
  Experiments should NOT be used in production, and the associated APIs may have backwards
  incompatible changes between releases. Additional experiments can also be specified via
  the `VAULT_EXPERIMENTS` environment variable as a comma-separated list, or via the
  [`-experiment`](/vault/docs/commands/server#experiment) flag.

### High Availability Parameters

The following parameters are used on backends that support [high availability][high-availability].

- `api_addr` `(string: "")` – Specifies the address (full URL) to advertise to
  other Vault servers in the cluster for client redirection. This value is also
  used for [plugin backends][plugins]. This can also be provided via the
  environment variable `VAULT_API_ADDR`. In general this should be set as a full
  URL that points to the value of the [`listener`](#listener) address.
  This can be dynamically defined with a
  [go-sockaddr template](https://pkg.go.dev/github.com/hashicorp/go-sockaddr/template)
  that is resolved at runtime.

- `cluster_addr` `(string: "")` – Specifies the address to advertise to other
  Vault servers in the cluster for request forwarding. This can also be provided
  via the environment variable `VAULT_CLUSTER_ADDR`. This is a full URL, like
  `api_addr`, but Vault will ignore the scheme (all cluster members always
  use TLS with a private key/certificate).
  This can be dynamically defined with a
  [go-sockaddr template](https://pkg.go.dev/github.com/hashicorp/go-sockaddr/template)
  that is resolved at runtime.

- `disable_clustering` `(bool: false)` – Specifies whether clustering features
  such as request forwarding are enabled. Setting this to true on one Vault node
  will disable these features _only when that node is the active node_. This
  parameter cannot be set to `true` if `raft` is the storage type.

### Vault Enterprise Parameters

The following parameters are only used with Vault Enterprise

- `disable_sealwrap` `(bool: false)` – Disables using [seal wrapping][sealwrap]
  for any value except the root key. If this value is toggled, the new
  behavior will happen lazily (as values are read or written).

- `disable_performance_standby` `(bool: false)` – Specifies whether performance
  standbys should be disabled on this node. Setting this to true on one Vault
  node will disable this feature when this node is Active or Standby. It's
  recommended to sync this setting across all nodes in the cluster.

- `license_path` `(string: "")` - Path to license file. This can also be
  provided via the environment variable `VAULT_LICENSE_PATH`, or the license
  itself can be provided in the environment variable `VAULT_LICENSE`.

[storage-backend]: /vault/docs/configuration/storage
[listener]: /vault/docs/configuration/listener
[seal]: /vault/docs/configuration/seal
[sealwrap]: /vault/docs/enterprise/sealwrap
[telemetry]: /vault/docs/configuration/telemetry
[sentinel]: /vault/docs/configuration/sentinel
[high-availability]: /vault/docs/concepts/ha
[plugins]: /vault/docs/plugins