The top level Envoy configuration contains a list of listeners. Each individual listener configuration has the following format:

  "name": "...",
  "address": "...",
  "filters": [],
  "ssl_context": "{...}",
  "bind_to_port": "...",
  "use_proxy_proto": "...",
  "use_original_dst": "...",
  "per_connection_buffer_limit_bytes": "..."
(optional, 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.
(required, string) The address that the listener should listen on. Currently only TCP listeners are supported, e.g., “tcp://”. Note, “tcp://” is the wild card match for any IPv4 address with port 80.

(required, array) A list of individual network filters that make up the filter chain for connections established with the listener. Order matters as the filters are processed sequentially as connection events happen.

Note: If the filter list is empty, the connection will close by default.

(optional, object) The TLS context configuration for a TLS listener. If no TLS context block is defined, the listener is a plain text listener.
(optional, boolean) 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 parameter to true. Default is true.
(optional, boolean) Whether the listener should expect a PROXY protocol V1 header on new connections. If this option is enabled, the listener will assume that that remote address of the connection is the one specified in the header. Some load balancers including the AWS ELB support this option. If the option is absent or set to false, Envoy will use the physical peer address of the connection as the remote address.
(optional, boolean) If a connection is redirected using iptables, the port on which the proxy receives it might be different from the original destination port. When this flag is set to true, the listener hands off redirected connections to the listener associated with the original destination port. If there is no listener associated with the original destination port, the connection is handled by the listener that receives it. Default is false.
(optional, integer) Soft limit on size of the listener’s new connection read and write buffers. If unspecified, an implementation defined default is applied (1MiB).


The listener manager has a statistics tree rooted at listener_manager. with the following statistics. Any : character in the stats name is replaced with _.

Name Type Description
listener_added Counter Total listeners added (either via static config or LDS)
listener_modified Counter Total listeners modified (via LDS)
listener_removed Counter Total listeners removed (via LDS)
listener_create_success Counter Total listener objects successfully added to workers.
listener_create_failure Counter Total failed listener object additions to workers.
total_listeners_warming Gauge Number of currently warming listeners
total_listeners_active Gauge Number of currently active listeners
total_listeners_draining Gauge Number of currently draining listeners