.. _envoy_api_file_envoy/api/v2/lds.proto:

Listener
========

Listener :ref:`configuration overview <config_listeners>`

.. _envoy_api_msg_Listener:

Listener
--------

`[Listener proto] <https://github.com/envoyproxy/data-plane-api/blob/master/envoy/api/v2/lds.proto#L38>`_


.. code-block:: json

  {
    "name": "...",
    "address": "{...}",
    "filter_chains": [],
    "use_original_dst": "{...}",
    "per_connection_buffer_limit_bytes": "{...}",
    "metadata": "{...}",
    "drain_type": "...",
    "listener_filters": []
  }

.. _envoy_api_field_Listener.name:

name
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) 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 :ref:`LDS <config_listeners_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 :option:`--max-obj-name-len` command line argument to the desired
  value.
  
  
.. _envoy_api_field_Listener.address:

address
  (:ref:`core.Address <envoy_api_msg_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.
  
  
.. _envoy_api_field_Listener.filter_chains:

filter_chains
  (:ref:`listener.FilterChain <envoy_api_msg_listener.FilterChain>`, *REQUIRED*) A list of filter chains to consider for this listener. The
  :ref:`FilterChain <envoy_api_msg_listener.FilterChain>` with the most specific
  :ref:`FilterChainMatch <envoy_api_msg_listener.FilterChainMatch>` criteria is used on a
  connection.
  
  .. attention::
  
    In the current version, multiple filter chains are supported **only** so that SNI can be
    configured. See the :ref:`FAQ entry <faq_how_to_setup_sni>` on how to configure SNI for more
    information. When multiple filter chains are configured, each filter chain must have an
    **identical** set of :ref:`filters <envoy_api_field_listener.FilterChain.filters>`. If the
    filters differ, the configuration will fail to load. In the future, this limitation will be
    relaxed such that different filters can be used depending on which filter chain matches
    (based on SNI or some other parameter).
  
  
.. _envoy_api_field_Listener.use_original_dst:

use_original_dst
  (`BoolValue <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#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 :ref:`an original_dst <config_listener_filters_original_dst>`
    :ref:`listener filter <envoy_api_field_Listener.listener_filters>` instead.
  
    Note that hand off to another listener is *NOT* performed without this flag. Once
    :ref:`FilterChainMatch <envoy_api_msg_listener.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.
  
  
.. _envoy_api_field_Listener.per_connection_buffer_limit_bytes:

per_connection_buffer_limit_bytes
  (`UInt32Value <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#uint32value>`_) Soft limit on size of the listener’s new connection read and write buffers.
  If unspecified, an implementation defined default is applied (1MiB).
  
  
.. _envoy_api_field_Listener.metadata:

metadata
  (:ref:`core.Metadata <envoy_api_msg_core.Metadata>`) Listener metadata.
  
  

.. _envoy_api_field_Listener.drain_type:

drain_type
  (:ref:`Listener.DrainType <envoy_api_enum_Listener.DrainType>`) The type of draining to perform at a listener-wide level.
  
  
.. _envoy_api_field_Listener.listener_filters:

listener_filters
  (:ref:`listener.ListenerFilter <envoy_api_msg_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
  :ref:`filter_chains <envoy_api_field_Listener.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.
  
  



.. _envoy_api_enum_Listener.DrainType:

Enum Listener.DrainType
-----------------------

`[Listener.DrainType proto] <https://github.com/envoyproxy/data-plane-api/blob/master/envoy/api/v2/lds.proto#L109>`_


.. _envoy_api_enum_value_Listener.DrainType.DEFAULT:

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

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.