Listener configuration

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

api/v2/listener.proto

Listener configuration overview

config.listener.v3.Listener

[config.listener.v3.Listener proto]

  1. {
  2.   "name": "...",
  3.   "address": "{...}",
  4.   "stat_prefix": "...",
  5.   "filter_chains": [],
  6.   "filter_chain_matcher": "{...}",
  7.   "use_original_dst": "{...}",
  8.   "default_filter_chain": "{...}",
  9.   "per_connection_buffer_limit_bytes": "{...}",
  10.   "metadata": "{...}",
  11.   "drain_type": "...",
  12.   "listener_filters": [],
  13.   "listener_filters_timeout": "{...}",
  14.   "continue_on_listener_filters_timeout": "...",
  15.   "transparent": "{...}",
  16.   "freebind": "{...}",
  17.   "socket_options": [],
  18.   "tcp_fast_open_queue_length": "{...}",
  19.   "traffic_direction": "...",
  20.   "udp_listener_config": "{...}",
  21.   "api_listener": "{...}",
  22.   "connection_balance_config": "{...}",
  23.   "reuse_port": "...",
  24.   "enable_reuse_port": "{...}",
  25.   "access_log": [],
  26.   "tcp_backlog_size": "{...}",
  27.   "bind_to_port": "{...}",
  28.   "enable_mptcp": "...",
  29.   "ignore_global_conn_limit": "..."
  30. }

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.

address

(config.core.v3.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.

stat_prefix

(string) Optional prefix to use on listener stats. If empty, the stats will be rooted at listener.<address as string>.. If non-empty, stats will be rooted at listener.<stat_prefix>..

filter_chains

(repeated config.listener.v3.FilterChain) 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.

filter_chain_matcher

(.xds.type.matcher.v3.Matcher) Matcher API resolving the filter chain name from the network properties. This matcher is used as a replacement for the filter chain match condition filter_chain_match. If specified, all filter_chains must have a non-empty and unique name field and not specify filter_chain_match field.

Note

Once matched, each connection is permanently bound to its filter chain. If the matcher changes but the filter chain remains the same, the connections bound to the filter chain are not drained. If, however, the filter chain is removed or structurally modified, then the drain for its connections is initiated.

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

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.

default_filter_chain

(config.listener.v3.FilterChain) The default filter chain if none of the filter chain matches. If no default filter chain is supplied, the connection will be closed. The filter chain match is ignored in this field.

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).

Attention

This field should be configured in the presence of untrusted downstreams.

Example configuration for untrusted environments:

  1. per_connection_buffer_limit_bytes: 32768.0

metadata

(config.core.v3.Metadata) Listener metadata.

drain_type

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

listener_filters

(repeated config.listener.v3.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. UDP Listener filters can be specified when the protocol in the listener socket address in protocol is UDP.

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 unless continue_on_listener_filters_timeout is set to true. Specify 0 to disable the timeout. If not specified, a default timeout of 15s is used.

continue_on_listener_filters_timeout

(bool) Whether a connection should be created when listener filters timeout. Default is false.

Attention

Some listener filters, such as Proxy Protocol filter, should not be used with this option. It will cause unexpected behavior when a connection is created.

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

(repeated config.core.v3.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.

traffic_direction

(config.core.v3.TrafficDirection) Specifies the intended direction of the traffic relative to the local Envoy. This property is required on Windows for listeners using the original destination filter, see Original Destination.

udp_listener_config

(config.listener.v3.UdpListenerConfig) If the protocol in the listener socket address in protocol is UDP, this field specifies UDP listener specific configuration.

api_listener

(config.listener.v3.ApiListener) Used to represent an API listener, which is used in non-proxy clients. The type of API exposed to the non-proxy application depends on the type of API listener. When this field is set, no other field except for name should be set.

Note

Currently only one ApiListener can be installed; and it can only be done via bootstrap config, not LDS.

connection_balance_config

(config.listener.v3.Listener.ConnectionBalanceConfig) The listener’s connection balancer configuration, currently only applicable to TCP listeners. If no configuration is specified, Envoy will not attempt to balance active connections between worker threads.

In the scenario that the listener X redirects all the connections to the listeners Y1 and Y2 by setting use_original_dst in X and bind_to_port to false in Y1 and Y2, it is recommended to disable the balance config in listener X to avoid the cost of balancing, and enable the balance config in Y1 and Y2 to balance the connections among the workers.

reuse_port

(bool) Deprecated. Use enable_reuse_port instead.

enable_reuse_port

(BoolValue) When this flag is set to true, listeners set the SO_REUSEPORT socket option and create one socket for each worker thread. This makes inbound connections distribute among worker threads roughly evenly in cases where there are a high number of connections. When this flag is set to false, all worker threads share one socket. This field defaults to true.

Attention

Although this field defaults to true, it has different behavior on different platforms. See the following text for more information.

  • On Linux, reuse_port is respected for both TCP and UDP listeners. It also works correctly with hot restart.

  • On macOS, reuse_port for TCP does not do what it does on Linux. Instead of load balancing, the last socket wins and receives all connections/packets. For TCP, reuse_port is force disabled and the user is warned. For UDP, it is enabled, but only one worker will receive packets. For QUIC/H3, SW routing will send packets to other workers. For “raw” UDP, only a single worker will currently receive packets.

  • On Windows, reuse_port for TCP has undefined behavior. It is force disabled and the user is warned similar to macOS. It is left enabled for UDP with undefined behavior currently.

access_log

(repeated config.accesslog.v3.AccessLog) Configuration for access logs emitted by this listener.

tcp_backlog_size

(UInt32Value) The maximum length a tcp listener’s pending connections queue can grow to. If no value is provided net.core.somaxconn will be used on Linux and 128 otherwise.

bind_to_port

(BoolValue) Whether the listener should bind to the port. A listener that doesn’t bind can only receive connections redirected from other listeners that set use_original_dst to true. Default is true.

enable_mptcp

(bool) Enable MPTCP (multi-path TCP) on this listener. Clients will be allowed to establish MPTCP connections. Non-MPTCP clients will fall back to regular TCP.

ignore_global_conn_limit

(bool) Whether the listener should limit connections based upon the value of global_downstream_max_connections.

config.listener.v3.Listener.ConnectionBalanceConfig

[config.listener.v3.Listener.ConnectionBalanceConfig proto]

Configuration for listener connection balancing.

  1. {
  2.   "exact_balance": "{...}"
  3. }

exact_balance

(config.listener.v3.Listener.ConnectionBalanceConfig.ExactBalance, REQUIRED) If specified, the listener will use the exact connection balancer.

config.listener.v3.Listener.ConnectionBalanceConfig.ExactBalance

[config.listener.v3.Listener.ConnectionBalanceConfig.ExactBalance proto]

A connection balancer implementation that does exact balancing. This means that a lock is held during balancing so that connection counts are nearly exactly balanced between worker threads. This is “nearly” exact in the sense that a connection might close in parallel thus making the counts incorrect, but this should be rectified on the next accept. This balancer sacrifices accept throughput for accuracy and should be used when there are a small number of connections that rarely cycle (e.g., service mesh gRPC egress).

Enum config.listener.v3.Listener.DrainType

[config.listener.v3.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.