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