Listener

Listener configuration overview

Listener

[Listener proto]

{
  "name": "...",
  "address": "{...}",
  "filter_chains": [],
  "use_original_dst": "{...}",
  "per_connection_buffer_limit_bytes": "{...}",
  "metadata": "{...}",
  "drain_type": "...",
  "listener_filters": [],
  "listener_filters_timeout": "{...}",
  "transparent": "{...}",
  "freebind": "{...}",
  "socket_options": [],
  "tcp_fast_open_queue_length": "{...}"
}

name

(string) The unique name by which this listener is known. If no name is provided, Envoy will allocate an internal UUID for the listener. If the listener is to be dynamically updated or removed via LDS a unique name must be provided. By default, the maximum length of a listener’s name is limited to 60 characters. This limit can be increased by setting the --max-obj-name-len command line argument to the desired value.

address

(core.Address, REQUIRED) The address that the listener should listen on. In general, the address must be unique, though that is governed by the bind rules of the OS. E.g., multiple listeners can listen on port 0 on Linux as the actual port will be allocated by the OS.

filter_chains

(listener.FilterChain, REQUIRED) A list of filter chains to consider for this listener. The FilterChain with the most specific FilterChainMatch criteria is used on a connection.

Example using SNI for filter chain selection can be found in the FAQ entry.

use_original_dst

(BoolValue) If a connection is redirected using iptables, the port on which the proxy receives it might be different from the original destination address. When this flag is set to true, the listener hands off redirected connections to the listener associated with the original destination address. If there is no listener associated with the original destination address, the connection is handled by the listener that receives it. Defaults to false.

Attention

This field is deprecated. Use an original_dst listener filter instead.

Note that hand off to another listener is NOT performed without this flag. Once FilterChainMatch is implemented this flag will be removed, as filter chain matching can be used to select a filter chain based on the restored destination address.

per_connection_buffer_limit_bytes

(UInt32Value) Soft limit on size of the listener’s new connection read and write buffers. If unspecified, an implementation defined default is applied (1MiB).

metadata

(core.Metadata) Listener metadata.

drain_type

(Listener.DrainType) The type of draining to perform at a listener-wide level.

listener_filters

(listener.ListenerFilter) Listener filters have the opportunity to manipulate and augment the connection metadata that is used in connection filter chain matching, for example. These filters are run before any in filter_chains. Order matters as the filters are processed sequentially right after a socket has been accepted by the listener, and before a connection is created.

listener_filters_timeout

(Duration) The timeout to wait for all listener filters to complete operation. If the timeout is reached, the accepted socket is closed without a connection being created. Specify 0 to disable the timeout. If not specified, a default timeout of 15s is used.

transparent

(BoolValue) Whether the listener should be set as a transparent socket. When this flag is set to true, connections can be redirected to the listener using an iptables TPROXY target, in which case the original source and destination addresses and ports are preserved on accepted connections. This flag should be used in combination with an original_dst listener filter to mark the connections’ local addresses as “restored.” This can be used to hand off each redirected connection to another listener associated with the connection’s destination address. Direct connections to the socket without using TPROXY cannot be distinguished from connections redirected using TPROXY and are therefore treated as if they were redirected. When this flag is set to false, the listener’s socket is explicitly reset as non-transparent. Setting this flag requires Envoy to run with the CAP_NET_ADMIN capability. When this flag is not set (default), the socket is not modified, i.e. the transparent option is neither set nor reset.

freebind

(BoolValue) Whether the listener should set the IP_FREEBIND socket option. When this flag is set to true, listeners can be bound to an IP address that is not configured on the system running Envoy. When this flag is set to false, the option IP_FREEBIND is disabled on the socket. When this flag is not set (default), the socket is not modified, i.e. the option is neither enabled nor disabled.

socket_options

(core.SocketOption) Additional socket options that may not be present in Envoy source code or precompiled binaries.

tcp_fast_open_queue_length

(UInt32Value) Whether the listener should accept TCP Fast Open (TFO) connections. When this flag is set to a value greater than 0, the option TCP_FASTOPEN is enabled on the socket, with a queue length of the specified size (see details in RFC7413). When this flag is set to 0, the option TCP_FASTOPEN is disabled on the socket. When this flag is not set (default), the socket is not modified, i.e. the option is neither enabled nor disabled.

On Linux, the net.ipv4.tcp_fastopen kernel parameter must include flag 0x2 to enable TCP_FASTOPEN. See ip-sysctl.txt.

On macOS, only values of 0, 1, and unset are valid; other values may result in an error. To set the queue length on macOS, set the net.inet.tcp.fastopen_backlog kernel parameter.

Enum Listener.DrainType

[Listener.DrainType proto]

DEFAULT

(DEFAULT) ⁣Drain in response to calling /healthcheck/fail admin endpoint (along with the health check filter), listener removal/modification, and hot restart.

MODIFY_ONLY

⁣Drain in response to listener removal/modification and hot restart. This setting does not include /healthcheck/fail. This setting may be desirable if Envoy is hosting both ingress and egress listeners.