TCP listener configuration | Vault | HashiCorp Developer (original) (raw)

The TCP listener configures Vault to listen on a TCP address/port.

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

The listener stanza may be specified more than once to make Vault listen on multiple interfaces. If you configure multiple listeners you also need to specify api_addr and cluster_addr so Vault will advertise the correct address to other nodes.

Unauthenticated API endpoints may return the following sensitive information:

Vault offers the ability to configure each tcp listener stanza such that, when appropriate, these values are redacted from responses.

The following API endpoints support redaction based on listener stanza configuration:

Vault replaces redacted information with an empty string (""). Some Vault APIs also omit keys from the response when the corresponding value is empty ("").

Redacting values affects responses to all API clients

The Vault CLI and UI consume Vault API responses. As a result, your redaction settings will apply to CLI and UI output in addition to direct API calls.

By default, Vault TCP listeners only accept TLS 1.2 or 1.3 connections and will drop connection requests from clients using TLS 1.0 or 1.1.

Vault uses the following ciphersuites by default:

You can configure Vault with any cipher supported by thetls andtlsutilGo packages. Vault uses the tlsutil package to parse ciphersuite configurations.

Sweet32 and 3DES

The Go team and HashiCorp believe that the set of cyphers supported by tlsand tlsutil is appropriate for modern, secure usage. However, some vulnerability scanners may flag issues with your configuration.

In particular, Sweet32 (CVE-2016-2183) is an attack against 64-bit block size ciphers including 3DES that may allow an attacker to break the encryption of long lived connections. According to thevulnerability disclosure, Sweet32 took a single HTTPS session with 785 GB of traffic to break the encryption.

As of May 2024, the Go team does not believe the risk of Sweet32 is sufficient to remove existing client compatibility by deprecating 3DES support, however, the team did de-prioritize 3DESin favor of AES-based ciphers.

Before overriding Vault defaults, we recommend reviewing the recommended Go teamapproach to TLS configuration with particular attention to their ciphersuite selections.

As of version 1.9, Vault supports defining custom HTTP response headers for the root path (/) and also on API endpoints (/v1/*). The headers are defined based on the returned status code. For example, a user can define a list of custom response headers for the 200 status code, and another list of custom response headers for the 307 status code. There is a "/sys/config/ui" API endpoint which allows users to set UI specific custom headers. If a header is configured in a configuration file, it is not allowed to be reconfigured through the "/sys/config/ui" API endpoint. In cases where a custom header value needs to be modified or the custom header needs to be removed, the Vault's configuration file needs to be modified accordingly, and a SIGHUP signal needs to be sent to the Vault process.

If a header is defined in the configuration file and the same header is used by the internal processes of Vault, the configured header is not accepted. For example, a custom header which has the X-Vault- prefix will not be accepted. A message will be logged in the Vault's logs upon start up indicating the header with X-Vault- prefix is not accepted.

Order of precedence

If the same header is configured in both the configuration file and in the "/sys/config/ui" API endpoint, the header in the configuration file takes precedence. For example, the "Content-Security-Policy" header is defined by default in the"/sys/config/ui" API endpoint. If that header is also defined in the configuration file, the value in the configuration file is set in the response headers instead of the default value in the "/sys/config/ui" API endpoint.

telemetry parameters

profiling parameters

inflight_requests_logging parameters

custom_response_headers parameters

Configuring TLS

This example shows enabling a TLS listener.

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

Listening on multiple interfaces

This example shows Vault listening on a private interface, as well as localhost.

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

listener "tcp" {
  address = "10.0.0.5:8200"
}

# Advertise the non-loopback interface
api_addr = "https://10.0.0.5:8200"
cluster_addr = "https://10.0.0.5:8201"

Configuring unauthenticated metrics access

This example shows enabling unauthenticated metrics access.

listener "tcp" {
  telemetry {
    unauthenticated_metrics_access = true
  }
}

Configuring unauthenticated profiling access

This example shows enabling unauthenticated profiling access.

listener "tcp" {
  profiling {
    unauthenticated_pprof_access = true
    unauthenticated_in_flight_request_access = true
  }
}

Configuring custom http response headers

Note: Requires Vault version 1.9 or newer. This example shows configuring custom http response headers. Operators can configure "custom_response_headers" sub-stanza in the listener stanza to set custom http headers appropriate to their applications. Examples of such headers are "Strict-Transport-Security"and "Content-Security-Policy" which are known HTTP headers, and could be configured to harden the security of an application communicating with the Vault endpoints. Note that vulnerability scans often examine such security related HTTP headers. In addition, application specific custom headers can also be configured. For example, "X-Custom-Header" has been configured in the example below.

listener "tcp" {
  custom_response_headers {
    "default" = {
      "Strict-Transport-Security" = ["max-age=31536000","includeSubDomains"],
      "Content-Security-Policy" = ["connect-src https://clusterA.vault.external/"],
      "X-Custom-Header" = ["Custom Header Default Value"],
    },
    "2xx" = {
      "Content-Security-Policy" = ["connect-src https://clusterB.vault.external/"],
      "X-Custom-Header" = ["Custom Header Value 1", "Custom Header Value 2"],
    },
    "301" = {
      "Strict-Transport-Security" = ["max-age=31536000"],
      "Content-Security-Policy" = ["connect-src https://clusterC.vault.external/"],
    },
  }
}

In situations where a header is defined under several status code subsections, the header matching the most specific response code will be returned. For example, with the config example below, a 307 response would return 307 Custom header value, while a 306 would return 3xx Custom header value.

listener "tcp" {
  custom_response_headers {
    "default" = {
       "X-Custom-Header" = ["default Custom header value"]
    },
    "3xx" = {
       "X-Custom-Header" = ["3xx Custom header value"]
    },
    "307" = {
       "X-Custom-Header" = ["307 Custom header value"]
    }
  }
}

Listening on all IPv6 & IPv4 interfaces

This example shows Vault listening on all IPv4 & IPv6 interfaces including localhost.

listener "tcp" {
  address         = "[::]:8200"
  cluster_address = "[::]:8201"
}

Listening to specific IPv6 address

This example shows Vault only using IPv6 and binding to the interface with the IP address: 2001:1c04:90d:1c00:a00:27ff:fefa:58ec

listener "tcp" {
  address         = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200"
  cluster_address = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201"
}

# Advertise the non-loopback interface
api_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200"
cluster_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201"

Please see redaction settings above, for details on each redaction setting.

Example configuration for the tcp listener, enabling redact_addresses,redact_cluster_name andredact_version.

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_1"
}

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

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

API: /sys/health

In the following call to /sys/health/ notice that cluster_name and versionare both redacted. The cluster_name field is fully omitted from the response and version is the empty string ("").

$ curl -s https://127.0.0.1:8200/v1/sys/health | jq`:

{
  "initialized": true,
  "sealed": false,
  "standby": true,
  "performance_standby": false,
  "replication_performance_mode": "disabled",
  "replication_dr_mode": "disabled",
  "server_time_utc": 1696598650,
  "version": "",
  "cluster_id": "a1a7a078-0ae1-7fb9-41ec-2f4f583c773e"
}

API: sys/leader

In the following call to /sys/leader/ notice that leader_address and leader_cluster_addressare both redacted and set to the empty string ("").

$ curl -s https://127.0.0.1:8200/v1/sys/leader | jq`:

{
  "ha_enabled": true,
  "is_self": false,
  "active_time": "0001-01-01T00:00:00Z",
  "leader_address": "",
  "leader_cluster_address": "",
  "performance_standby": false,
  "performance_standby_last_remote_wal": 0,
  "raft_committed_index": 164,
  "raft_applied_index": 164
}

API: sys/seal-status

In the following call to /sys/seal-status/ notice that cluster_name, build_date, and version are all redacted. The cluster_name field is fully omitted from the response while build_date and version are empty strings ("").

$ curl -s https://127.0.0.1:8200/v1/sys/seal-status | jq`:

{
  "type": "shamir",
  "initialized": true,
  "sealed": false,
  "t": 1,
  "n": 1,
  "progress": 0,
  "nonce": "",
  "version": "",
  "build_date": "",
  "migration": false,
  "cluster_id": "a1a7a078-0ae1-7fb9-41ec-2f4f583c773e",
  "recovery_seal": false,
  "storage_type": "raft"
}

CLI: vault status

The CLI command vault status uses endpoints that support redacting data, so the output redacts Version, Build Date, HA Cluster, and Active Node Address.Version, Build Date, HA Cluster show n/a because the underlying endpoint returned the empty string, and Active Node Address shows as <none> because it was omitted from the API response.


$ vault status

Key                     Value
---                     -----
Seal Type               shamir
Initialized             true
Sealed                  false
Total Shares            5
Threshold               3
Version                 n/a
Build Date              n/a
Storage Type            raft
HA Enabled              true
HA Cluster              n/a
HA Mode                 standby
Active Node Address     <none>
Raft Committed Index    219
Raft Applied Index      219