Outside of development mode, Vault servers are configured using a file. The format of this file is HCL or JSON.

Set the environment variable VAULT_ENABLE_FILE_PERMISSIONS_CHECK to have the Vault process automatically verify that the user running Vault owns and can access the configuration directory and all related files.

The file permission check also confirms that no other group or user has write or execute permissions on the configuration directory or files.

You can set explicit users and permissions on the plugin directory and plugin binaries with the plugin_file_uid and plugin_file_permissions parameters in your Vault configuration if the users or permissions need to be different from the Vault process.

Vault does not verify file permissions by default.

An example configuration is shown below:

ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"
disable_mlock = true

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_id"
}

listener "tcp" {
  address       = "127.0.0.1:8200"
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
}

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 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 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.

• 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.

• reporting ([Reporting][reporting]: nil) - Configures options relating to license reporting in Vault.

• cluster_name (string: <generated>) – Specifies a human-readable identifier for the Vault cluster. If omitted, Vault will generate a value. The cluster name is included as a label in some telemetry metrics. The cluster name is safe to update on an existing Vault cluster.

• 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: <required>) – Stops Vault from executing the mlock syscall. mlock prevents data swaps from memory to disk. You must set an explicit value for disable_mlock if you use integrated storage. We do not recommend disabling mlock for deployments that do not use 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 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.

  If you enable mlock, the Vault executable and each plugin executable in your plugins directory must have the ability to use the mlock syscall.

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

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

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

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.

  Set the environment variable VAULT_ENABLE_FILE_PERMISSIONS_CHECK to have the Vault process automatically verify that the user running Vault owns and can access the configuration directory and all related files.

  The file permission check also confirms that no other group or user has write or execute permissions on the configuration directory or files.

  You can set explicit users and permissions on the plugin directory and plugin binaries with the plugin_file_uid and plugin_file_permissions parameters in your Vault configuration if the users or permissions need to be different from the Vault process.

  Vault does not verify file permissions 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 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.

• plugin_tmpdir (string: "") - A directory Vault uses for temporary files when starting containerized external plugins. Vault does not use plugin_tmpdir with non containerized plugins. Set plugin_tmpdir to a path accessible to both Vault and the plugin container when the default OS temporary directory is not shared between them. Set VAULT_PLUGIN_TMPDIR to configure the directory with an environment variable.

• 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 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 the max_request_duration value.

• detect_deadlocks (string: "") - A comma separated string indicating which internal mutex locks Vault should monitor for potential deadlocks. Vault logs a POTENTIAL DEADLOCK: warning for the configured value whenever an attempt at a core state lock appears to be deadlocked. Enabling detect_deadlocks can negatively impact performance due to the tracking of each lock attempt. Currently supported values:

  • statelock
  • quotas
  • expiration
  • sealwrap

• 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.

• ui_settings ([UISettings][ui-settings]: <none>) – Configures options for the Vault web UI, such as UI telemetry.

• 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.

• log_file - Equivalent to the -log-file command-line flag.

• log_rotate_duration - Equivalent to the -log-rotate-duration command-line flag.

• log_rotate_bytes - Equivalent to the -log-rotate-bytes command-line flag.

• log_rotate_max_files - Equivalent to the -log-rotate-max-files command-line flag.

• 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 flag.

• imprecise_lease_role_tracking (bool: "false") - Skip lease counting by role if there are no role based quotas enabled. When imprecise_lease_role_tracking is set to true and a new role-based quota is enabled, subsequent lease counts start from 0. imprecise_lease_role_tracking affects role-based lease count quotas, but reduces latencies when not using role based quotas.

• enable_post_unseal_trace (bool: false) - Enables the server to generate a Go trace during the execution of the core.postUnseal function for debug purposes. The resulting trace can be viewed with the go tool trace command. The output directory can be specified with the post_unseal_trace_directory parameter. This should only be enabled temporarily for debugging purposes as it can have a significant performance impact. This can be updated on a running Vault process with a SIGHUP signal.

• post_unseal_trace_directory (string: "") - Specifies the directory where the trace file will be written, which must exist and be writable by the Vault process. If not specified it will create a subdirectory vault-traces under the result from os.TempDir() (usually /tmp on Unix systems). This can be updated on a running Vault process with a SIGHUP signal.

• disable_goroutine_trace_dump (bool: false) - When set to true, suppresses the goroutine pprof dump that Vault automatically writes during a normal shutdown (SIGTERM or SIGINT). You can update disable_goroutine_trace_dump on a running Vault process with a SIGHUP signal.

  The dump writes a file named goroutine that includes a pprof goroutine profile readable by go tool pprof to a randomly named directory inside os.TempDir(). For example, on Linux the dump writes to /tmp/vault-goroutine-dump-2738451092. If you want to redirect the goroutine file to a different location, set VAULT_STACKTRACE_FILE_PATH to an existing directory path.

  Note

  You can trigger a separate goroutine dump on demand by sending SIGUSR2 to the Vault process if you set the VAULT_STACKTRACE_WRITE_TO_FILE environment to any non-empty value before Vault starts. You cannot use the disable_goroutine_trace_dump configuration parameter to affect the SIGUSR2 dump.

• allow_audit_log_prefixing (bool: false) - Enable to allow prefixes on audit log entries for file sinks.

• enable_unauthenticated_access (string array: []) - A list of authenticated endpoint family names that you want Vault to treat as unauthenticated. The enable_unauthenticated_access parameter provides backward compatability for endpoints that were unauthenticated in older versions of Vault. You can use a SIGHUP signal to update enable_unauthenticated_access on a running Vault process. Supported endpoint families: "rekey", "generate-root", "generate-operation-token".

• deny_slash_in_templated_paths (bool: false) - Controls whether Vault returns "permission denied" when templated policy paths. include slashes (/). You can also set the environment variable, VAULT_DENY_SLASH_IN_TEMPLATED_PATHS.

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 variable VAULT_API_ADDR. In general this should be set as a full URL that points to the value of the listener 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 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 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 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.

• administrative_namespace_path (string: "") - Specifies the absolute path to the Vault namespace to be used as an Administrative namespace.

• remove_irrevocable_lease_after (string: "") - Enables the automatic deletion of irrevocable leases. When the configured duration exceeds the expiry time of an irrevocable lease, Vault deletes the lease. The minimum value for remove_irrevocable_lease_after is 2 days (2d). If you set the removal window to a value less than the minimum, Vault overwrites the value to 2d. Deleting a lease may cause Vault to orphan external resources.