From eecfb700132bf7adee93c9e0928b368b047de491 Mon Sep 17 00:00:00 2001 From: Romain Lenglet Date: Fri, 16 Mar 2018 14:18:35 -0700 Subject: [PATCH 1/4] lds: Redefine the transparent and freebind listener options Document the behavior when each option is set to true, set to false, or unset. Document that the transparent option should be used in conjunction the original_dst_filter to restore the original destination address. Signed-off-by: Romain Lenglet --- .../listener_filters/original_dst_filter.rst | 11 ++++---- envoy/api/v2/lds.proto | 28 +++++++++++++------ 2 files changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/root/configuration/listener_filters/original_dst_filter.rst b/docs/root/configuration/listener_filters/original_dst_filter.rst index 50aa7c1cc..f347aae53 100644 --- a/docs/root/configuration/listener_filters/original_dst_filter.rst +++ b/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 -` 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 ` 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 ` may be used to +forward HTTP requests or TCP connections to the restored destination address. * :ref:`v2 API reference ` diff --git a/envoy/api/v2/lds.proto b/envoy/api/v2/lds.proto index b6de9dae3..c7b7f70bc 100644 --- a/envoy/api/v2/lds.proto +++ b/envoy/api/v2/lds.proto @@ -127,14 +127,26 @@ 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 ` :ref:`listener filter + // ` to hand off redirected connections to the + // listener associated with the original 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; } From cb6afc6237c558024dc8bbb5b018bb40cd996ddb Mon Sep 17 00:00:00 2001 From: Romain Lenglet Date: Fri, 16 Mar 2018 14:19:53 -0700 Subject: [PATCH 2/4] lds: Mention transparent and freebind options in version history Signed-off-by: Romain Lenglet --- docs/root/intro/version_history.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/root/intro/version_history.rst b/docs/root/intro/version_history.rst index 5783190f0..81dbb1051 100644 --- a/docs/root/intro/version_history.rst +++ b/docs/root/intro/version_history.rst @@ -4,7 +4,8 @@ Version history 1.6.0 ===== - +* listeners: added :ref:`transparent ` option. +* listeners: added :ref:`freebind ` option. 1.5.0 ===== From 5d5eb0c37c461bafafdf38a754572223b437e66a Mon Sep 17 00:00:00 2001 From: Romain Lenglet Date: Fri, 16 Mar 2018 15:08:30 -0700 Subject: [PATCH 3/4] lds: Remove mention of freebind listener option Signed-off-by: Romain Lenglet --- docs/root/intro/version_history.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/root/intro/version_history.rst b/docs/root/intro/version_history.rst index 81dbb1051..24fe86487 100644 --- a/docs/root/intro/version_history.rst +++ b/docs/root/intro/version_history.rst @@ -5,7 +5,6 @@ Version history ===== * listeners: added :ref:`transparent ` option. -* listeners: added :ref:`freebind ` option. 1.5.0 ===== From 1dacb3c24f686933f50fb1a697495e52d44d2399 Mon Sep 17 00:00:00 2001 From: Romain Lenglet Date: Fri, 16 Mar 2018 16:59:12 -0700 Subject: [PATCH 4/4] lds: Clarified the effects of marking TPROXYed connections as restored Signed-off-by: Romain Lenglet --- envoy/api/v2/lds.proto | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/envoy/api/v2/lds.proto b/envoy/api/v2/lds.proto index c7b7f70bc..73edcb27a 100644 --- a/envoy/api/v2/lds.proto +++ b/envoy/api/v2/lds.proto @@ -132,10 +132,11 @@ message Listener { // *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 ` :ref:`listener filter - // ` to hand off redirected connections to the - // listener associated with the original 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. + // ` 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