lds: Make listen socket options optional and improve docs

docs/root/configuration/listener_filters/original_dst_filter.rst

@@ -4,10 +4,11 @@ Original Destination
 ====================
 
 Original destination listener filter reads the SO_ORIGINAL_DST socket option set when a connection
-has been redirected by iptables REDIRECT. 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, :ref:`an original destination cluster
-<arch_overview_service_discovery_types_original_destination>` may be used to forward HTTP requests
-or TCP connections to the restored destination address.
+has been redirected by an iptables REDIRECT target, by or an iptables TPROXY target in combination
+with setting the listener's :ref:`transparent <envoy_api_field_Listener.transparent>` option.
+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, :ref:`an original
+destination cluster <arch_overview_service_discovery_types_original_destination>` may be used to
+forward HTTP requests or TCP connections to the restored destination address.
 
 * :ref:`v2 API reference <envoy_api_field_listener.Filter.name>`

docs/root/intro/version_history.rst

@@ -3,6 +3,7 @@ Version history
 
 1.6.0
 =====
+
 * http : added idle timeout for :ref:`upstream http connections
   <envoy_api_field_core.HttpProtocolOptions.idle_timeout>`.
 * health check: added setting for :ref:`no-traffic
@@ -13,6 +14,7 @@ Version history
 * tracing: when using the zipkin tracer, it is no longer necessary to propagate the
   :ref:`x-ot-span-context <config_http_conn_man_headers_x-ot-span-context>` header.
   See more on trace context propagation :ref:`here <arch_overview_tracing>`.
+* listeners: added :ref:`transparent <envoy_api_field_Listener.transparent>` option.
 
 1.5.0
 =====

envoy/api/v2/lds.proto

@@ -127,14 +127,27 @@ message Listener {
   // before a connection is created.
   repeated listener.ListenerFilter listener_filters = 9 [(gogoproto.nullable) = false];
 
-  // 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. Requires Envoy to run with the *CAP_NET_ADMIN* capability. Defaults to false.
-  bool transparent = 10;
+  // 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
+  // :ref:`an original_dst <config_listener_filters_original_dst>` :ref:`listener filter
+  // <envoy_api_field_Listener.listener_filters>` 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.
+  google.protobuf.BoolValue transparent = 10;
 
   // [#not-implemented-hide:] 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. Defaults to false.
-  bool freebind = 11;
+  // 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.
+  google.protobuf.BoolValue freebind = 11;
 }