1--- 2layout: docs 3page_title: TCP - Listeners - Configuration 4description: |- 5 The TCP listener configures Vault to listen on the specified TCP address and 6 port. 7--- 8 9# `tcp` Listener 10 11The TCP listener configures Vault to listen on a TCP address/port. 12 13```hcl 14listener "tcp" { 15 address = "127.0.0.1:8200" 16} 17``` 18 19The `listener` stanza may be specified more than once to make Vault listen on 20multiple interfaces. If you configure multiple listeners you also need to 21specify [`api_addr`][api-addr] and [`cluster_addr`][cluster-addr] so Vault will 22advertise the correct address to other nodes. 23 24## `tcp` Listener Parameters 25 26- `address` `(string: "127.0.0.1:8200")` – Specifies the address to bind to for 27 listening. 28 29- `cluster_address` `(string: "127.0.0.1:8201")` – Specifies the address to bind 30 to for cluster server-to-server requests. This defaults to one port higher 31 than the value of `address`. This does not usually need to be set, but can be 32 useful in case Vault servers are isolated from each other in such a way that 33 they need to hop through a TCP load balancer or some other scheme in order to 34 talk. 35 36- `http_idle_timeout` `(string: "5m")` - Specifies the maximum amount of time to 37 wait for the next request when keep-alives are enabled. If `http_idle_timeout` 38 is zero, the value of `http_read_timeout` is used. If both are zero, the value 39 of `http_read_header_timeout` is used. This is specified using a label suffix 40 like `"30s"` or `"1h"`. 41 42- `http_read_header_timeout` `(string: "10s")` - Specifies the amount of time 43 allowed to read request headers. This is specified using a label suffix like 44 `"30s"` or `"1h"`. 45 46- `http_read_timeout` `(string: "30s")` - Specifies the maximum duration for 47 reading the entire request, including the body. This is specified using a 48 label suffix like `"30s"` or `"1h"`. 49 50- `http_write_timeout` `string: "0")` - Specifies the maximum duration before 51 timing out writes of the response and is reset whenever a new request's header 52 is read. The default value of `"0"` means inifinity. This is specified using a 53 label suffix like `"30s"` or `"1h"`. 54 55- `max_request_size` `(int: 33554432)` – Specifies a hard maximum allowed 56 request size, in bytes. Defaults to 32 MB if not set or set to `0`. 57 Specifying a number less than `0` turns off limiting altogether. 58 59- `max_request_duration` `(string: "90s")` – Specifies the maximum 60 request duration allowed before Vault cancels the request. This overrides 61 `default_max_request_duration` for this listener. 62 63- `proxy_protocol_behavior` `(string: "")` – When specified, enables a PROXY 64 protocol version 1 behavior for the listener. 65 Accepted Values: 66 67 - _use_always_ - The client's IP address will always be used. 68 - _allow_authorized_ - If the source IP address is in the 69 `proxy_protocol_authorized_addrs` list, the client's IP address will be used. 70 If the source IP is not in the list, the source IP address will be used. 71 - _deny_unauthorized_ - The traffic will be rejected if the source IP 72 address is not in the `proxy_protocol_authorized_addrs` list. 73 74- `proxy_protocol_authorized_addrs` `(string: <required-if-enabled> or array: <required-if-enabled> )` – 75 Specifies the list of allowed source IP addresses to be used with the PROXY protocol. 76 Not required if `proxy_protocol_behavior` is set to `use_always`. Source IPs should 77 be comma-delimited if provided as a string. At least one source IP must be provided, 78 `proxy_protocol_authorized_addrs` cannot be an empty array or string. 79 80- `tls_disable` `(string: "false")` – Specifies if TLS will be disabled. Vault 81 assumes TLS by default, so you must explicitly disable TLS to opt-in to 82 insecure communication. 83 84- `tls_cert_file` `(string: <required-if-enabled>, reloads-on-SIGHUP)` – 85 Specifies the path to the certificate for TLS. It requires a PEM-encoded file. 86 To configure the listener to use a CA certificate, concatenate the primary certificate and the CA 87 certificate together. The primary certificate should appear first in the 88 combined file. On `SIGHUP`, the path set here _at Vault startup_ will be used 89 for reloading the certificate; modifying this value while Vault is running 90 will have no effect for `SIGHUP`s. 91 92- `tls_key_file` `(string: <required-if-enabled>, reloads-on-SIGHUP)` – 93 Specifies the path to the private key for the certificate. It requires a PEM-encoded file. 94 If the key file is encrypted, you will be prompted to enter the passphrase on server startup. 95 The passphrase must stay the same between key files when reloading your 96 configuration using `SIGHUP`. On `SIGHUP`, the path set here _at Vault 97 startup_ will be used for reloading the certificate; modifying this value 98 while Vault is running will have no effect for `SIGHUP`s. 99 100- `tls_min_version` `(string: "tls12")` – Specifies the minimum supported 101 version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13". 102 103 ~> **Warning**: TLS 1.1 and lower are generally considered insecure. 104 105- `tls_cipher_suites` `(string: "")` – Specifies the list of supported 106 ciphersuites as a comma-separated-list. The list of all available ciphersuites 107 is available in the [Golang TLS documentation][golang-tls]. 108 109- `tls_prefer_server_cipher_suites` `(string: "false")` – Specifies to prefer the 110 server's ciphersuite over the client ciphersuites. 111 112- `tls_require_and_verify_client_cert` `(string: "false")` – Turns on client 113 authentication for this listener; the listener will require a presented 114 client cert that successfully validates against system CAs. 115 116- `tls_client_ca_file` `(string: "")` – PEM-encoded Certificate Authority file 117 used for checking the authenticity of client. 118 119- `tls_disable_client_certs` `(string: "false")` – Turns off client 120 authentication for this listener. The default behavior (when this is false) 121 is for Vault to request client certificates when available. 122 123- `x_forwarded_for_authorized_addrs` `(string: <required-to-enable>)` – 124 Specifies the list of source IP CIDRs for which an X-Forwarded-For header 125 will be trusted. Comma-separated list or JSON array. This turns on 126 X-Forwarded-For support. 127 128- `x_forwarded_for_hop_skips` `(string: "0")` – The number of addresses that will be 129 skipped from the _rear_ of the set of hops. For instance, for a header value 130 of `1.2.3.4, 2.3.4.5, 3.4.5.6`, if this value is set to `"1"`, the address that 131 will be used as the originating client IP is `2.3.4.5`. 132 133- `x_forwarded_for_reject_not_authorized` `(string: "true")` – If set false, 134 if there is an X-Forwarded-For header in a connection from an unauthorized 135 address, the header will be ignored and the client connection used as-is, 136 rather than the client connection rejected. 137 138- `x_forwarded_for_reject_not_present` `(string: "true")` – If set false, if 139 there is no X-Forwarded-For header or it is empty, the client address will be 140 used as-is, rather than the client connection rejected. 141 142### `telemetry` Parameters 143 144- `unauthenticated_metrics_access` `(bool: false)` - If set to true, allows 145 unauthenticated access to the `/v1/sys/metrics` endpoint. 146 147### `profiling` Parameters 148 149- `unauthenticated_pprof_access` `(bool: false)` - If set to true, allows 150 unauthenticated access to the `/v1/sys/pprof` endpoint. 151 152## `tcp` Listener Examples 153 154### Configuring TLS 155 156This example shows enabling a TLS listener. 157 158```hcl 159listener "tcp" { 160 tls_cert_file = "/etc/certs/vault.crt" 161 tls_key_file = "/etc/certs/vault.key" 162} 163``` 164 165### Listening on Multiple Interfaces 166 167This example shows Vault listening on a private interface, as well as localhost. 168 169```hcl 170listener "tcp" { 171 address = "127.0.0.1:8200" 172} 173 174listener "tcp" { 175 address = "10.0.0.5:8200" 176} 177 178# Advertise the non-loopback interface 179api_addr = "https://10.0.0.5:8200" 180cluster_addr = "https://10.0.0.5:8201" 181``` 182 183### Configuring unauthenticated metrics access 184 185This example shows enabling unauthenticated metrics access. 186 187```hcl 188listener "tcp" { 189 telemetry { 190 unauthenticated_metrics_access = true 191 } 192} 193``` 194 195### Configuring unauthenticated profiling access 196 197This example shows enabling unauthenticated profiling access. 198 199```hcl 200listener "tcp" { 201 profiling { 202 unauthenticated_pprof_access = true 203 } 204} 205``` 206 207 208### Listening on all IPv6 & IPv4 Interfaces 209 210This example shows Vault listening on all IPv4 & IPv6 interfaces including localhost. 211 212```hcl 213listener "tcp" { 214 address = "[::]:8200" 215 cluster_address = "[::]:8201" 216} 217``` 218 219### Listening to specific IPv6 address 220 221This example shows Vault only using IPv6 and binding to the interface with the IP address: `2001:1c04:90d:1c00:a00:27ff:fefa:58ec` 222 223```hcl 224listener "tcp" { 225 address = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200" 226 cluster_address = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201" 227} 228 229# Advertise the non-loopback interface 230api_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200" 231cluster_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201" 232``` 233 234[golang-tls]: https://golang.org/src/crypto/tls/cipher_suites.go 235[api-addr]: /docs/configuration#api_addr 236[cluster-addr]: /docs/configuration#cluster_addr 237