Vault configuration
Outside of development mode, Vault servers are configured using a file. The format of this file is HCL or JSON.
Enabling the file permissions check via the environment variable VAULT_ENABLE_FILE_PERMISSIONS_CHECK
allows Vault to check if the config directory and files are owned by the user running Vault.
It also checks if there are no write or execute permissions for group or others.
Vault allows operators to specify the user and permissions of the plugin directory and binaries
using parameters plugin_file_uid
and plugin_file_permissions
in config if an operator needs those to be different. This check is disabled by default.
An example configuration is shown below:
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 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 separateha_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 thestorage
parameter. This parameter is not required if the storage backend supports HA coordination and if HA specific options are already specified withstorage
parameter. (Refer to Use Integrated Storage for HA Coordination for a usage example.)listener
([Listener][listener]: <required>)
– Configures how Vault is listening for API requests.seal
([Seal][seal]: nil)
– Configures the seal type to use for auto-unsealing, as well as for seal wrapping 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 themlock
syscall.mlock
prevents memory from being swapped to disk. Disablingmlock
is not recommended unless using integrated storage. Follow the additional security precautions outlined below when disablingmlock
. This can also be provided via the environment variableVAULT_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 due to the fact thatmlock
does not interact well with memory mapped files such as those created by BoltDB, which is used by Raft to track state. When usingmlock
, 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:Note: Since each plugin runs as a separate process, you need to do the same for each plugin in your plugins directory.
If you use a Linux distribution with a modern version of systemd, you can add the following directive to the "[Service]" configuration section:
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.Enabling the file permissions check via the environment variable
VAULT_ENABLE_FILE_PERMISSIONS_CHECK
allows Vault to check if the config directory and files are owned by the user running Vault. It also checks if there are no write or execute permissions for group or others. Vault allows operators to specify the user and permissions of the plugin directory and binaries using parametersplugin_file_uid
andplugin_file_permissions
in config if an operator needs those to be different. This check is disabled by default.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 variableVAULT_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 variableVAULT_ENABLE_FILE_PERMISSIONS_CHECK
.telemetry
([Telemetry][telemetry]: <none>)
– Specifies the telemetry reporting system.log_level
(string: "")
– Specifies the log level to use; overridden by CLI and env var parameters. On SIGHUP (sudo kill -s HUP
pid of vault), Vault will update the log level to the current value specified here (including overriding the CLI/env var parameters). Not all parts of Vault's logging can have its level be changed dynamically this way; in particular, secrets/auth plugins are currently not updated dynamically. Supported log levels: Trace, Debug, Error, Warn, Info.log_format
(string: "")
– Specifies the log format to use; overridden by CLI and env var parameters. Supported log formats: "standard", "json".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 thanmax_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 themax-lease-ttl
flag of the auth or secret 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 themax_request_duration
value.raw_storage_endpoint
(bool: false)
– Enables thesys/raw
endpoint which allows the decryption/encryption of raw data into and out of the security barrier. This is a highly privileged endpoint.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 variableVAULT_UI
. For more information, please see the ui configuration documentation.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 theX-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.
High availability parameters
The following parameters are used on backends that support 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. This can also be provided via the environment variableVAULT_API_ADDR
. In general this should be set as a full URL that points to the value of thelistener
address. This can be dynamically defined with a 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 variableVAULT_CLUSTER_ADDR
. This is a full URL, likeapi_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 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 totrue
ifraft
is the storage type.
Vault enterprise parameters
The following parameters are only used with Vault Enterprise
disable_sealwrap
(bool: false)
– Disables using seal wrapping 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 variableVAULT_LICENSE_PATH
, or the license itself can be provided in the environment variableVAULT_LICENSE
.