Original Destination


Original destination listener filter reads the SO_ORIGINAL_DST socket option set when a connection has been redirected by an iptables REDIRECT target, or by an iptables TPROXY target in combination with setting the listener’s transparent option.


Original destination listener filter reads the SO_ORIGINAL_DST socket option set when a connection has been redirected by an HNS policy applied to a container endpoint. For this filter to work the traffic_direction must be set on the listener. This means that a separate listener is needed to handle inbound and outbound traffic.

Redirection is not available for use with all types of network traffic. The types of packets that are supported for redirection are shown in the following list:

  • TCP/IPv4

  • UDP

  • Raw UDPv4 without the header include option

  • Raw ICMP

For more info see Using Bind or Connect Redirection


At the time of writing (February 2021) the OS support for original destination is only available through the Windows insider program. The feature will be fully supported in the upcoming Windows Server release, see Windows Server Release info.

Later processing in Envoy sees the restored destination address as the connection’s local address, rather than the address at which the listener is listening at. Furthermore, an original destination cluster may be used to forward HTTP requests or TCP connections to the restored destination address.

Internal listeners

Original destination listener filter reads the dynamic metadata and the filter state objects on the user space sockets handled by the internal listeners instead of the system socket options.

Dynamic metadata for the destination address is expected to be placed into the key envoy.filters.listener.original_dst under the field local and should contain a string with an IP and a port address. In the absence of the dynamic metadata, the filter state is consulted.

The filter state objects consumed by this filter are:

  • envoy.filters.listener.original_dst.local_ip for the destination address

  • envoy.filters.listener.original_dst.source_ip for the source address

Note that internal upstream transport should be used for passing the dynamic metadata from an endpoint host to the socket metadata and/or the filter state objects that are shared with the upstream connection through a user space socket to the internal listeners.

  • This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.listener.original_dst.v3.OriginalDst.

  • v3 API reference