Configure Vault
There are different ways to configure a Vault server depending on the server environment and your intended use case. You can think of Vault server configuration as belonging to one of these three categories, depending on how and where they are used:
- Command line flags are passed to the vault binary as part of the complete command line at runtime, and are limited to defining only a small subset of configuration as detailed in the command options documentation.
- Configuration files are read by the vault process at runtime and when reloaded by sending the process a hangup signal (SIGHUP); they are the most generally useful and most popular way to configure Vault.
- Environment variables: Set in the environment for the shell of the user that executes the vault process and can only configure a limited set of options. They are most helpful for special environments like Docker.
This topic dives a bit deeper these configuration types, and shares some specific examples, which newcomers to Vault configuration should find helpful.
If you'd like to learn more about configuring Vault, you are in the right place.
Command Line Flags
If you have been learning about Vault through the Getting Started tutorials and started a Vault dev server or you have previous Vault experience, then you might be familiar with one command line flag: -dev
.
You can always start a dev server by passing the -dev
flag to the vault server
command line as shown in the following example command for Linux.
$ vault server -dev
The same command for Windows PowerShell resembles this example.
PS C:\Users\learn> vault.exe server -dev
Warning
When using a dev mode server, and also passing in configuration via environment variables or a file, you can encounter an error condition if you attempt to configure a TCP listener that overlaps with the default dev mode listener.
What about other flags?
While there are only a small number of flags, they typically define critical configuration when used. This section details some of the most commonly used flags.
-config
The most common command line flag you will encounter is the -config
flag.
You can use this flag three different ways to specify the full path to your Vault configuration file or files.
- Use the flag once to name the path to a single specific configuration file.
- Use the flag multiple times to name multiple configuration files, which will be composed at runtime.
- Use the flag to name a directory of configuration files, the contents of which will be composed at runtime.
Here is a Linux example that names one configuration file, /etc/vault/vault-server.hcl
. This file contains all of the actual Vault server configuration.
$ vault server -config vault-server.hcl
Suppose that your Vault configuration consists of modular configuration files, and you have a directory, /etc/vault
that contains just these 3 files:
You could start your Vault server in two different ways for this scenario. Either by explicitly naming all the files like this example.
$ vault server \
-config /etc/vault/main.hcl \
-config /etc/vault/storage.hcl \
-config /etc/vault/tcp-listeners.hcl
or if all the .hcl
files in the directory are intended to be used only for Vault configuration, you could pass in only the directory name by itself instead, as in this example.
$ vault server \
-config /etc/vault
Either way, in the case of the previous two examples, Vault will compose the individual configuration files into one configuration at runtime.
-log-level
Another popular flag is -log-level
, which allows you to specify a log level from one of one of these levels, listed from most to least verbose: "trace", "debug", "info", "warn", or "err".
Vault will log at the "info" level by default, but if you are doing troubleshooting or otherwise need some additional log detail, you could start Vault with a command line like this to increase the log level to "trace".
$ vault server -config vault-server.hcl -log-level=trace
Consult the command options documentation for the full list of flags.
Configuration Files
Vault can be configured with one or more HashiCorp Configuration Language (HCL) files.
You can think of a Vault configuration file as having two scopes, a global scope for general configuration, and per-object configuration for sections of the configuration defined by HCL objects, known in Vault configuration files as a stanzas.
The following diagram illustrates this with an example Vault configuration file, vault-server.hcl:.
In the Vault documentation, global configuration options appear on the configuration overview page, and options for configuration objects like listener, storage, and telemetry are found in their respective pages.
From the previous command line flags example, you learned how to pass a configuration file name to the Vault server at runtime.
Here is the complete example configuration file.
disable_mlock = true
ui = true
listener "tcp" {
address = "127.0.0.1:8200"
tls_disable = "true"
}
storage "file" {
path = "/tmp/vault-data"
}
This is a simple and portable configuration example that will work as-is in the majority of environments for learning purposes which require persisting data between restarts of the vault
process.
NOTE: The above example disables TLS (tls_disable = "true"
) for testing
and learning. However, Vault should always be used with
TLS
in production to provide secure communication between clients and the Vault
server. It requires a certificate file and key file on each host where Vault is
running.
listener "tcp" {
address = "0.0.0.0:8200"
tls_cert_file = "/path/to/fullchain.pem"
tls_key_file = "/path/to/privkey.pem"
}
Here is a line-by-line description of each option in the file:
- disable_mlock - By default, Vault will use mlock() to lock its process memory pages, preventing them from being swapped to disk. You should always strive to have it enabled (it is enabled by default) as described in production hardening when operating Vault in production. However, this option is not supported on certain platforms like macOS or Windows, so for this to be a most portable and useful example, it disables
mlock()
. - ui - By default, the Vault web UI is not enabled; this example enables it.
- listener - Currently only the tcp listener is supported.
- address configures the bind address in host+port format, where the host value can be a fully qualified domain name (FQDN) or IP address, and the port represents the Vault API port, which is 8200 by default.
- tls_disable TLS is disabled for this simplistic example so that it is readily usable without the need for generating a server certificate and private key. In production, you should always strive to operate Vault with TLS enabled.
- storage - used to specify the storage backend for Vault persisted data. In this case, filesystem storage is specified with file.
- path specifies a filesystem path where the vault process can write persisted data for the filesystem storage backend. In this example, the data will be written to
/tmp/vault-data
.
- path specifies a filesystem path where the vault process can write persisted data for the filesystem storage backend. In this example, the data will be written to
On a Linux or macOS system, you can write the file out as vault-server.hcl
to the present working directory with this command.
$ cat > vault-server.hcl <<EOF
disable_mlock = true
ui = true
listener "tcp" {
address = "127.0.0.1:8200"
tls_disable = "true"
}
storage "file" {
path = "/tmp/vault-data"
}
EOF
Then, you can start Vault with the configuration file and "err" level logging for the absolute minimal possible output as an example. This configuration will only output errors as part of the Vault operational logging.
$ vault server -config vault-server.hcl -log-level=err
The entirety of expected output from starting Vault with this configuration and log level will resemble this example.
==> Vault server configuration:
Cgo: disabled
Go Version: go1.14.7
Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", max_request_duration: "1m30s", max_request_size: "33554432", tls: "disabled")
Log Level: err
Mlock: supported: false, enabled: false
Recovery Mode: false
Storage: file
Version: Vault v1.5.2
Version Sha: 685fdfa60d607bca069c09d2d52b6958a7a2febd
==> Vault server started! Log data will stream in below:
Environment Variables
Now that you have learned more about command line flags and configuration files, let's take a look at the environment variables you can use to configure Vault servers.
Environment variables are a fairly specialized form of configuration useful for certain circumstances as described in this section.
Here are some of the most commonly used environment variables related to configuring a Vault server.
VAULT_API_ADDR
The VAULT_API_ADDR environment variable is used to specify the address (as a full URL plus port) to advertise to other Vault servers in the cluster for client redirection purposes. As such it is unnecessary when starting a single Vault server, but you will encounter a warning if it is not configured in a configuration file or with the environment variable.
In the following example server startup output, a warning is emitted: "no api_addr value specified in config or in VAULT_API_ADDR". Vault will try to detect the appropriate value to use, but if you cannot edit the server configuration file, you can still set it by exporting a proper VAULT_API_ADDR
environment variable value.
==> Vault server configuration:
Cgo: disabled
Go Version: go1.14.7
Log Level: info
Mlock: supported: false, enabled: false
Recovery Mode: false
Storage: file
Version: Vault v1.5.2
Version Sha: 685fdfa60d607bca069c09d2d52b6958a7a2febd
==> Vault server started! Log data will stream in below:
2020-08-31T15:11:04.461-0400 [INFO] proxy environment: http_proxy= https_proxy= no_proxy=
2020-08-31T15:11:04.461-0400 [WARN] no `api_addr` value specified in config or in VAULT_API_ADDR; falling back to detection if possible, but this value should be manually set
Specify the value as a URL with port (TCP/8200 by default) as shown in this simple example:
$ export VAULT_API_ADDR=http://127.0.0.1:8200
or you can also specify the environment variable within a systemd unit:
[Service]
Environment=VAULT_API_ADDR=http://127.0.0.1:8200
VAULT_CLUSTER_ADDR
The VAULT_CLUSTER_ADDR environment variable is used to specify the address (as a full URL plus port) to advertise to other Vault servers in the cluster for request forwarding purposes in the same way that the cluster_addr
configuration file option does.
Specify the value as a URL with port (TCP/8201 by default) as shown in this simple example:
$ export VAULT_CLUSTER_ADDR=http://127.0.0.1:8201
or you can also specify the environment variable within a systemd unit:
[Service]
Environment=VAULT_CLUSTER_ADDR=http://127.0.0.1:8201
HTTP_PROXY
Vault supports the HTTP_PROXY
environment variable and if this environment variable is set in the vault process user environment prior to starting the vault process, then Vault will proxy its HTTP requests through the specified address.
Specify the value as a URL as shown in this simple example:
$ export HTTP_PROXY=http://proxy.example.com:8080
or you can also specify the environment variable within a systemd unit:
[Service]
Environment=HTTP_PROXY=http://proxy.example.com:8080
...
HTTPS_PROXY
Vault supports the HTTPS_PROXY
environment variable and if this environment variable is set in the vault process user environment prior to starting the vault process, then Vault will proxy its HTTPS requests through the specified address.
Specify the value as a URL as shown in this simple example:
$ export HTTPS_PROXY=https://proxy-tls.example.com:8080
or you can also specify the environment variable within a systemd unit:
[Service]
Environment=HTTPS_PROXY=https://proxy-tls.example.com:8080
...
NO_PROXY
Vault supports the NO_PROXY
environment variable and if this environment variable is set in the vault process user environment prior to starting the vault process, then Vault will not use a proxy for the specified address values.
Specify the value as an IP address prefix (1.2.3.4), an IP address prefix in CIDR notation (1.2.3.4/8), a domain name, or a special DNS label (*). An IP address prefix and domain name can also include a literal port number (1.2.3.4:80).
Examples:
$ export NO_PROXY='*.example.com,1.2.3.4:80,1.2.3.4/8'
or you can also specify the environment variable within a systemd unit:
[Service]
Environment=NO_PROXY="*.example.com,1.2.3.4:80,1.2.3.4/8"
...
Next
You have learned more about Vault server configuration options and the different ways to configure a Vault server.
Check out the resource links for more configuration related documentation, or continue on to Your First Secret as the next step in getting started with Vault.