tcp listener
The TCP listener configures Boundary to listen on a TCP address/port.
The listener
stanza may be specified more than once to make Boundary listen on
multiple interfaces; however, only one listener marked for cluster
purpose is
allowed.
Listener's custom response headers
Boundary supports defining custom HTTP response headers for all requests on any Boundary controller.
Headers are defined based on the returned status code. For example, you 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, and so on. You can also define headers based on the hundred-level status
code. For example, a list of headers applied to the 4xx
code will be applied to 400, 401, 404, and
all other 400-level status codes. The more specific the status, the higher priority it has.
Default headers are overwritten by hundred-level headers, which are overwritten by status-specific
headers.
There are two different config parameters that define headers: custom_api_response_headers
and
custom_ui_response_headers
. API headers apply to API endpoints, currently all paths starting
with /v1/
. UI headers apply to all other paths. This allows for configuring headers specifically
for serving content to a web browser, such as CSP headers.
tcp
listener parameters
Refer to the following sections for tcp
listener parameters.
General
purpose
(string: "")
- Specifies the purpose. Can beapi
,cluster
,proxy
, orops
.address
(string: "127.0.0.1:9200")
– Specifies the address to bind to for listening.http_idle_timeout
(string: "5m")
- Specifies the maximum amount of time to wait for the next request when keep-alives are enabled. Ifhttp_idle_timeout
is zero, the value ofhttp_read_timeout
is used. If both are zero, the value ofhttp_read_header_timeout
is used. This is specified using a label suffix like"30s"
or"1h"
.http_read_header_timeout
(string: "10s")
- Specifies the amount of time allowed to read request headers. This is specified using a label suffix like"30s"
or"1h"
.http_read_timeout
(string: "30s")
- Specifies the maximum duration for reading the entire request, including the body. This is specified using a label suffix like"30s"
or"1h"
.http_write_timeout
(string: "0")
- Specifies the maximum duration before timing out writes of the response and is reset whenever a new request's header is read. The default value of"0"
means infinity. This is specified using a label suffix like"30s"
or"1h"
.
max_request_duration
(string: "90s")
– Specifies the maximum request duration allowed before Boundary cancels the request. This overridesdefault_max_request_duration
for this listener.cors_enabled
(boolean: true)
- Specifies if CORS should be enabled, which allows Boundary to support external browser-based clients (not including admin UI), such as Boundary Desktop. If not specified, CORS will be enabled with an allowed origin that grants access to Boundary Desktop, unless overridden withcors_disable_default_allowed_origin_values
.cors_disable_default_allowed_origin_values
(boolean: false)
- Specifies that Boundary should not append default allowed origin values to any specified incors_allowed_origins
, such as Boundary Desktop's origin. This also disables the behavior of enabling CORS ifcors_enabled
is not specified.cors_allowed_origins
(array(string): ["serve://boundary"])
- An array of allowed CORS origins. Origins must include protocol, host, and port (if port is different than the default for the specified protocol). To allow all origins, set to['*']
. By default, Boundary Desktop's originserve://boundary
is appended to any values included here, unlesscors_disable_default_allowed_origin_values
is specified.cors_allowed_headers
(array(string): [])
– An array specifying headers that are permitted to be on cross-origin requests. Headers set via this parameter will be appended to the list of headers that Boundary allows by default, such as"Content-Type"
,"X-Requested-With"
, and"Authorization"
.
custom_api_response_headers
parameters
default
(key-value-map: {})
- A map of string header names to an array of string values. The default headers are set on all endpoints regardless of the status code value. For an example, refer to the Configuring custom http response headers section.<collective status code>
(key-value-map: {})
- A map of string header names to an array of string values. These headers are set only when the response status code falls under the collective status code. For example,"2xx" = {"Header-A": ["Value1", "Value2"]}
,"Header-A"
is set when the http response status code is"200"
,"204"
, etc. This overrides headers defined at thedefault
level.<specific status code>
(key-value-map: {})
- A map of string header names to an array of string values. These headers are set only when the specific status code is returned. For example,"200" = {"Header-A": ["Value1", "Value2"]}
,"Header-A"
is set when the http response status code is"200"
. This overrides headers defined at thedefault
andcollective status code
level.
custom_ui_response_headers
parameters
default
(key-value-map: {})
- A map of string header names to an array of string values. The default headers are set on all endpoints regardless of the status code value. For an example, refer to the Configuring custom http response headers section.<collective status code>
(key-value-map: {})
- A map of string header names to an array of string values. These headers are set only when the response status code falls under the collective status code. For example,"2xx" = {"Header-A": ["Value1", "Value2"]}
,"Header-A"
is set when the http response status code is"200"
,"204"
, etc. This overrides headers defined at thedefault
level.<specific status code>
(key-value-map: {})
- A map of string header names to an array of string values. These headers are set only when the specific status code is returned. For example,"200" = {"Header-A": ["Value1", "Value2"]}
,"Header-A"
is set when the http response status code is"200"
. This overrides headers defined at thedefault
andcollective status code
level.
TLS
tls
parameters are valid for api
and ops
listeners. cluster
and proxy
connections use their own ephemeral TLS stacks. For more
information, see the connections security concepts
page.
tls_disable
(string: "false")
– Specifies if TLS will be disabled. Boundary assumes TLS by default, so you must explicitly disable TLS to opt-in to insecure communication.tls_cert_file
(string: <required-if-enabled, reloads-on-SIGHUP>)
– Specifies the path to the certificate for TLS. To configure the listener to use a CA certificate, concatenate the primary certificate and the CA certificate together. The primary certificate should appear first in the combined file. OnSIGHUP
, the path set here at Boundary startup will be used for reloading the certificate; modifying this value while Boundary is running will have no effect forSIGHUP
s.tls_key_file
(string: <required-if-enabled, reloads-on-SIGHUP>)
– Specifies the path to the private key for the certificate. If the key file is encrypted, you will be prompted to enter the passphrase on server startup. The passphrase must stay the same between key files when reloading your configuration usingSIGHUP
. OnSIGHUP
, the path set here at Boundary startup will be used for reloading the certificate; modifying this value while Boundary is running will have no effect forSIGHUP
s.tls_min_version
(string: "tls12")
– Specifies the minimum supported version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13".TLS 1.1 and lower are generally considered insecure.
tls_max_version
(string: "tls13")
– Specifies the maximum supported version of TLS, useful if appliances (e.g. load balancers) are not yet capable of higher levels. Accepted values are "tls10", "tls11", "tls12" or "tls13".TLS 1.1 and lower are generally considered insecure.
tls_cipher_suites
(string: "")
– Override the default list of supported ciphersuites (which varies by TLS version) with the the specified comma-delimited list. The list of all available ciphersuites is available in the Golang TLS documentation.tls_prefer_server_cipher_suites
(string: "false")
– Specifies to prefer the server's ciphersuite over the client ciphersuites.tls_require_and_verify_client_cert
(string: "false")
– Turns on client authentication for this listener; the listener will require a presented client cert that successfully validates against system CAs.tls_client_ca_file
(string: "")
– PEM-encoded Certificate Authority file used for checking the authenticity of client.
tcp
listener examples
Refer to the following sections for examples of tcp
listeners.
Configure TLS
This example shows enabling a TLS listener.
Configure custom http response headers
This example shows configuring custom http response headers. Operators can configure
"custom_api_response_headers"
and "custom_ui_response_headers"
sub-stanzas in the listener stanza to
set custom http headers that are 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 Boundary endpoints. Note that
vulnerability scans often examine such security related HTTP headers. In addition, you can configure
application-specific custom headers. For example, "X-Custom-Header"
has been configured in the example
below.
Note that Boundary requires script-src 'wasm-unsafe-eval'
for playback of session recordings.
In situations where a header is defined under several status code subsections,
Boundary returns the header matching the most specific response code. 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
.
There may also be situations where default or collective status headers have been defined, but you do not want them returned for a specific status code. You can unset headers at any level by defining the headers as an empty list.
Listen on mulitple interfaces
This example shows Boundary listening on a private interface, as well as localhost.