From 025eaafdcf756de453569438373a327cb4d9549a Mon Sep 17 00:00:00 2001 From: Kyle Larose Date: Fri, 4 Jan 2019 13:04:24 -0500 Subject: [PATCH 1/6] Add documentation for original_src filter Signed-off-by: Kyle Larose --- api/docs/BUILD | 1 + .../original_src/v2alpha1/original_src.proto | 1 - docs/build.sh | 1 + docs/root/api-v2/config/filter/filter.rst | 1 + .../config/filter/listener/listener.rst | 8 +++ .../listener_filters/listener_filters.rst | 1 + .../listener_filters/original_src_filter.rst | 71 +++++++++++++++++++ 7 files changed, 83 insertions(+), 1 deletion(-) create mode 100644 docs/root/api-v2/config/filter/listener/listener.rst create mode 100644 docs/root/configuration/listener_filters/original_src_filter.rst diff --git a/api/docs/BUILD b/api/docs/BUILD index bca5ebfbe680d..5aec21c802c3b 100644 --- a/api/docs/BUILD +++ b/api/docs/BUILD @@ -49,6 +49,7 @@ proto_library( "//envoy/config/filter/http/transcoder/v2:transcoder", "//envoy/config/filter/network/client_ssl_auth/v2:client_ssl_auth", "//envoy/config/filter/network/ext_authz/v2:ext_authz", + "//envoy/config/filter/listener/original_src/v2alpha1:original_src", "//envoy/config/filter/network/http_connection_manager/v2:http_connection_manager", "//envoy/config/filter/network/mongo_proxy/v2:mongo_proxy", "//envoy/config/filter/network/rate_limit/v2:rate_limit", diff --git a/api/envoy/config/filter/listener/original_src/v2alpha1/original_src.proto b/api/envoy/config/filter/listener/original_src/v2alpha1/original_src.proto index 8fba8ebb99644..8725ef500b2a7 100644 --- a/api/envoy/config/filter/listener/original_src/v2alpha1/original_src.proto +++ b/api/envoy/config/filter/listener/original_src/v2alpha1/original_src.proto @@ -10,7 +10,6 @@ import "validate/validate.proto"; // [#protodoc-title: Original Src Filter] // Use the Original source address on upstream connections. -// TODO(klarose): Add ref to docs // The Original Src filter binds upstream connections to the original source address determined // for the connection. This address could come from something like the Proxy Protocol filter, or it diff --git a/docs/build.sh b/docs/build.sh index d2bed5cd023d9..e121fb52eacc9 100755 --- a/docs/build.sh +++ b/docs/build.sh @@ -96,6 +96,7 @@ PROTO_RST=" /envoy/config/filter/http/router/v2/router/envoy/config/filter/http/router/v2/router.proto.rst /envoy/config/filter/http/squash/v2/squash/envoy/config/filter/http/squash/v2/squash.proto.rst /envoy/config/filter/http/transcoder/v2/transcoder/envoy/config/filter/http/transcoder/v2/transcoder.proto.rst + /envoy/config/filter/listener/original_src/v2alpha1/original_src/envoy/config/filter/listener/original_src/v2alpha1/original_src.proto.rst /envoy/config/filter/network/client_ssl_auth/v2/client_ssl_auth/envoy/config/filter/network/client_ssl_auth/v2/client_ssl_auth.proto.rst /envoy/config/filter/network/ext_authz/v2/ext_authz/envoy/config/filter/network/ext_authz/v2/ext_authz.proto.rst /envoy/config/filter/network/http_connection_manager/v2/http_connection_manager/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto.rst diff --git a/docs/root/api-v2/config/filter/filter.rst b/docs/root/api-v2/config/filter/filter.rst index 92a54a9504580..88385094a2f44 100644 --- a/docs/root/api-v2/config/filter/filter.rst +++ b/docs/root/api-v2/config/filter/filter.rst @@ -10,3 +10,4 @@ Filters thrift/thrift accesslog/v2/accesslog.proto fault/v2/fault.proto + listener/listener diff --git a/docs/root/api-v2/config/filter/listener/listener.rst b/docs/root/api-v2/config/filter/listener/listener.rst new file mode 100644 index 0000000000000..d66039048e7ae --- /dev/null +++ b/docs/root/api-v2/config/filter/listener/listener.rst @@ -0,0 +1,8 @@ +Listener filters +================ + +.. toctree:: + :glob: + :maxdepth: 2 + + */v2alpha1/* diff --git a/docs/root/configuration/listener_filters/listener_filters.rst b/docs/root/configuration/listener_filters/listener_filters.rst index 4f3e2f353398c..0ddd775100ae7 100644 --- a/docs/root/configuration/listener_filters/listener_filters.rst +++ b/docs/root/configuration/listener_filters/listener_filters.rst @@ -9,5 +9,6 @@ Envoy has the follow builtin listener filters. :maxdepth: 2 original_dst_filter + original_src_filter proxy_protocol tls_inspector diff --git a/docs/root/configuration/listener_filters/original_src_filter.rst b/docs/root/configuration/listener_filters/original_src_filter.rst new file mode 100644 index 0000000000000..e0819df473342 --- /dev/null +++ b/docs/root/configuration/listener_filters/original_src_filter.rst @@ -0,0 +1,71 @@ +.. _config_listener_filters_original_src: + +Original Source +=============== + +* :ref:`Listener filter v2 API reference ` +* This filter should be configured with the name *envoy.listener.original_src*. + +The original source listener filter replicates the downstream remote address of +the connection on the upstream side of Envoy. For example, if a downstream +connection connects to Envoy with IP address ``10.1.2.3``, then Envoy will +connect to the upstream with source IP ``10.1.2.3``. + +Interfaction with Proxy Protocol +-------------------------------- + +If the connection has not had its source address translated or proxied, then +Envoy can simply use the existing connection information to build the correct +downstream remote address. However, if this is not true, a +:ref:`Proxy Protocol filter ` may be +used to extract the downstream remote address. + +Extra Setup +----------- + +The downstream remote address used will likely be globally routable. By default, +packets returning from the upstream host to that address will not route through +Envoy. The network must be configured to forcefully route any traffic whose IP +was replicated by Envoy back through the Envoy host. + +If Envoy and the upstream are on the same host -- e.g. in an sidecar deployment +--, then iptables and routing rules can be used to ensure correct behaviour. + +The filter has an unsigned integer configuration, ``mark``. Setting this to *X* +causes Envoy to *mark* all upstream packets originating from this listener with +value *X*. + +We can use the following set of commands to ensure that all ipv4 and ipv6 +traffic marked with *X* (assumed to be 123 in the example) routes correctly. + +.. code-block:: text + + iptables -t mangle -I PREROUTING -m mark --mark 123 -j CONNMARK --save-mark + iptables -t mangle -I OUTPUT -m connmark --mark 123 -j CONNMARK --restore-mark + ip6tables -t mangle -I PREROUTING -m mark --mark 123 -j CONNMARK --save-mark + ip6tables -t mangle -I OUTPUT -m connmark --mark 123 -j CONNMARK --restore-mark + ip rule add fwmark 123 lookup 100 + ip route add local 0.0.0.0/0 dev lo table 100 + ip -6 rule add fwmark 123 lookup 100 + ip -6 route add local ::/0 dev lo table 100 + + +Example Listener configuration +------------------------------ + +The following example configures Envoy to use the original source for all +connections made on port 8888. It uses Proxy Protocol to determine the +downstream remote address. All upstream packets are marked with 123. + +.. code-block:: yaml + + listeners: + - address: + socket_address: + address: 0.0.0.0 + port_value: 8888 + listener_filters: + - name: envoy.listener.proxy_protocol + - name: envoy.listener.original_src + config: + mark: 123 From b8b7ce6dc8ca27a5ecf1eac14695e352c450e0d3 Mon Sep 17 00:00:00 2001 From: Kyle Larose Date: Fri, 4 Jan 2019 16:23:46 -0500 Subject: [PATCH 2/6] Fix bad ordering for docs build Signed-off-by: Kyle Larose --- api/docs/BUILD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/docs/BUILD b/api/docs/BUILD index 5aec21c802c3b..0deafc4e04915 100644 --- a/api/docs/BUILD +++ b/api/docs/BUILD @@ -47,9 +47,9 @@ proto_library( "//envoy/config/filter/http/router/v2:router", "//envoy/config/filter/http/squash/v2:squash", "//envoy/config/filter/http/transcoder/v2:transcoder", + "//envoy/config/filter/listener/original_src/v2alpha1:original_src", "//envoy/config/filter/network/client_ssl_auth/v2:client_ssl_auth", "//envoy/config/filter/network/ext_authz/v2:ext_authz", - "//envoy/config/filter/listener/original_src/v2alpha1:original_src", "//envoy/config/filter/network/http_connection_manager/v2:http_connection_manager", "//envoy/config/filter/network/mongo_proxy/v2:mongo_proxy", "//envoy/config/filter/network/rate_limit/v2:rate_limit", From 69f6c5faea74013ea1ab07cde4f634621f15c5ca Mon Sep 17 00:00:00 2001 From: Kyle Larose Date: Tue, 8 Jan 2019 08:49:05 -0500 Subject: [PATCH 3/6] Misc docs fixes - Clean up formatting (100 column lines) - Fix some typos - Talk about ip version Signed-off-by: Kyle Larose --- .../listener_filters/listener_filters.rst | 2 +- .../listener_filters/original_src_filter.rst | 50 +++++++++---------- 2 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/root/configuration/listener_filters/listener_filters.rst b/docs/root/configuration/listener_filters/listener_filters.rst index 0ddd775100ae7..7357976c500b5 100644 --- a/docs/root/configuration/listener_filters/listener_filters.rst +++ b/docs/root/configuration/listener_filters/listener_filters.rst @@ -3,7 +3,7 @@ Listener filters ================ -Envoy has the follow builtin listener filters. +Envoy has the following builtin listener filters. .. toctree:: :maxdepth: 2 diff --git a/docs/root/configuration/listener_filters/original_src_filter.rst b/docs/root/configuration/listener_filters/original_src_filter.rst index e0819df473342..370a5b31c4f6a 100644 --- a/docs/root/configuration/listener_filters/original_src_filter.rst +++ b/docs/root/configuration/listener_filters/original_src_filter.rst @@ -6,37 +6,37 @@ Original Source * :ref:`Listener filter v2 API reference ` * This filter should be configured with the name *envoy.listener.original_src*. -The original source listener filter replicates the downstream remote address of -the connection on the upstream side of Envoy. For example, if a downstream -connection connects to Envoy with IP address ``10.1.2.3``, then Envoy will -connect to the upstream with source IP ``10.1.2.3``. +The original source listener filter replicates the downstream remote address of the connection on +the upstream side of Envoy. For example, if a downstream connection connects to Envoy with IP +address ``10.1.2.3``, then Envoy will connect to the upstream with source IP ``10.1.2.3``. -Interfaction with Proxy Protocol +Interaction with Proxy Protocol -------------------------------- -If the connection has not had its source address translated or proxied, then -Envoy can simply use the existing connection information to build the correct -downstream remote address. However, if this is not true, a -:ref:`Proxy Protocol filter ` may be -used to extract the downstream remote address. +If the connection has not had its source address translated or proxied, then Envoy can simply use +the existing connection information to build the correct downstream remote address. However, if this +is not true, a :ref:`Proxy Protocol filter ` may be used to +extract the downstream remote address. + +IP Version Support +------------------ +The filter supports both IPv4 and IPv6 as addresses. Note that the upstream connection must support +the version used. Extra Setup ----------- -The downstream remote address used will likely be globally routable. By default, -packets returning from the upstream host to that address will not route through -Envoy. The network must be configured to forcefully route any traffic whose IP -was replicated by Envoy back through the Envoy host. - -If Envoy and the upstream are on the same host -- e.g. in an sidecar deployment ---, then iptables and routing rules can be used to ensure correct behaviour. +The downstream remote address used will likely be globally routable. By default, packets returning +from the upstream host to that address will not route through Envoy. The network must be configured +to forcefully route any traffic whose IP was replicated by Envoy back through the Envoy host. -The filter has an unsigned integer configuration, ``mark``. Setting this to *X* -causes Envoy to *mark* all upstream packets originating from this listener with -value *X*. +If Envoy and the upstream are on the same host -- e.g. in an sidecar deployment --, then iptables +and routing rules can be used to ensure correct behaviour. The filter has an unsigned integer +configuration, ``mark``. Setting this to *X* causes Envoy to *mark* all upstream packets originating +from this listener with value *X*. -We can use the following set of commands to ensure that all ipv4 and ipv6 -traffic marked with *X* (assumed to be 123 in the example) routes correctly. +We can use the following set of commands to ensure that all ipv4 and ipv6 traffic marked with *X* +(assumed to be 123 in the example) routes correctly. .. code-block:: text @@ -53,9 +53,9 @@ traffic marked with *X* (assumed to be 123 in the example) routes correctly. Example Listener configuration ------------------------------ -The following example configures Envoy to use the original source for all -connections made on port 8888. It uses Proxy Protocol to determine the -downstream remote address. All upstream packets are marked with 123. +The following example configures Envoy to use the original source for all connections made on port +8888. It uses Proxy Protocol to determine the downstream remote address. All upstream packets are +marked with 123. .. code-block:: yaml From 20f2ce2eb98c95fd6380ff0cf8ee9a93d9f49ec5 Mon Sep 17 00:00:00 2001 From: Kyle Larose Date: Tue, 8 Jan 2019 10:13:49 -0500 Subject: [PATCH 4/6] Add IP Transparency documentation Signed-off-by: Kyle Larose --- .../intro/arch_overview/arch_overview.rst | 1 + .../intro/arch_overview/ip_transparency.rst | 70 +++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 docs/root/intro/arch_overview/ip_transparency.rst diff --git a/docs/root/intro/arch_overview/arch_overview.rst b/docs/root/intro/arch_overview/arch_overview.rst index e638fcf157afd..0a118df54b1ae 100644 --- a/docs/root/intro/arch_overview/arch_overview.rst +++ b/docs/root/intro/arch_overview/arch_overview.rst @@ -39,3 +39,4 @@ Architecture overview scripting ext_authz_filter overload_manager + ip_transparency diff --git a/docs/root/intro/arch_overview/ip_transparency.rst b/docs/root/intro/arch_overview/ip_transparency.rst new file mode 100644 index 0000000000000..788d9e6fdda9a --- /dev/null +++ b/docs/root/intro/arch_overview/ip_transparency.rst @@ -0,0 +1,70 @@ +.. _arch_overview_ip_transparency: + +IP Transparency +=============== + +What is IP Transparency +----------------------- + +As a proxy, Envoy is an IP endpoint: it has its own IP address, distinct from that of any downstream +requests. Consequently, when Envoy establishes connections to upstream hosts, the IP address of that +connection will be different from that of any proxied connections. + +Sometimes the upstream server or network may need to know the original IP address of the connection, +called the *downstream remote address*, for many reasons. Some examples include: + +* the the IP address being used to form part of an identity, +* the IP address being used to enforce network policy, or +* the IP address being included in an audit. + +Envoy supports multiple methods for providing the downstream remote address to the upstream host. +These techniques vary in complexity and applicability. + +HTTP Headers +------------ + +HTTP headers may carry the original IP address of the request in the +:ref:`x-forwarded-for ` header. The upstream server +can use this header to determine the downstream remote address. + +The HTTP header approach has a few downsides: + +* It is only applicable to HTTP. +* It may not be supported by the upstream host. +* It requires careful configuration. + +Proxy Protocol +-------------- + +`HAProxy Proxy Protocol `_ defines a +protocol for communicating metadata about a connection over TCP, prior to the main TCP stream. This +metadata includes the source IP. Envoy supports consuming this information using +:ref:`Proxy Protocol filter `, which may be used to recover +the downstream remote address for propagation into an x-forwarded-for header. It can also be used +in conjunction with the +:ref:`Original Src Listener Filter `. + +Some drawbacks to Proxy Protocol: + +* It only supports TCP protocols. +* It requires upstream host support. +* Envoy cannot yet send it to the upstream. + +.. _arch_overview_ip_transparency_original_src_listener: + +Original Source Listener Filter +------------------------------- + +In controlled deployments, it may be possible to replicate the downstream remote address on the +upstream connection by using a +:ref:`Original Source listener filter `. No metadata is added +to the upstream request or stream. Rather, the upstream connection itself will be established with +the downstream remote address as its source address. This filter will work with any upstream +protocol or host. However, it requires fairly complex configuration, and it may not be supported in +all deployments due to routing constraints. + +Some drawbacks to the Original Source filter: + +* It requires that Envoy have access to the downstream remote address. +* Its configuration is relatively complex. +* It may introduce a slight performance hit due to restrictions on connection pooling. From 572a2c69612a0e69724638cb9d658bb95c65e1f6 Mon Sep 17 00:00:00 2001 From: Kyle Larose Date: Tue, 8 Jan 2019 10:28:12 -0500 Subject: [PATCH 5/6] Mention route_localnet This is needed so that we can force the non-local IPv4 addresses to route locally. Signed-off-by: Kyle Larose --- .../configuration/listener_filters/original_src_filter.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/root/configuration/listener_filters/original_src_filter.rst b/docs/root/configuration/listener_filters/original_src_filter.rst index 370a5b31c4f6a..7236cfb535fd8 100644 --- a/docs/root/configuration/listener_filters/original_src_filter.rst +++ b/docs/root/configuration/listener_filters/original_src_filter.rst @@ -36,7 +36,8 @@ configuration, ``mark``. Setting this to *X* causes Envoy to *mark* all upstream from this listener with value *X*. We can use the following set of commands to ensure that all ipv4 and ipv6 traffic marked with *X* -(assumed to be 123 in the example) routes correctly. +(assumed to be 123 in the example) routes correctly. Note that this example assumes that *eth0* is +the default outbound interface. .. code-block:: text @@ -48,6 +49,7 @@ We can use the following set of commands to ensure that all ipv4 and ipv6 traffi ip route add local 0.0.0.0/0 dev lo table 100 ip -6 rule add fwmark 123 lookup 100 ip -6 route add local ::/0 dev lo table 100 + echo 1 > /proc/sys/net/ipv4/conf/eth0/route_localnet Example Listener configuration From 0f0a59ad007e9395bc6ad9a058122aabab2dfee7 Mon Sep 17 00:00:00 2001 From: Kyle Larose Date: Tue, 15 Jan 2019 15:15:32 -0500 Subject: [PATCH 6/6] Add some references to docs Review requested that some references be added. This change does so. Signed-off-by: Kyle Larose --- .../configuration/listener_filters/original_src_filter.rst | 6 ++++-- docs/root/intro/arch_overview/ip_transparency.rst | 5 +++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/root/configuration/listener_filters/original_src_filter.rst b/docs/root/configuration/listener_filters/original_src_filter.rst index 7236cfb535fd8..06778fb4db689 100644 --- a/docs/root/configuration/listener_filters/original_src_filter.rst +++ b/docs/root/configuration/listener_filters/original_src_filter.rst @@ -32,8 +32,10 @@ to forcefully route any traffic whose IP was replicated by Envoy back through th If Envoy and the upstream are on the same host -- e.g. in an sidecar deployment --, then iptables and routing rules can be used to ensure correct behaviour. The filter has an unsigned integer -configuration, ``mark``. Setting this to *X* causes Envoy to *mark* all upstream packets originating -from this listener with value *X*. +configuration, +:ref:`mark `. Setting +this to *X* causes Envoy to *mark* all upstream packets originating from this listener with value +*X*. We can use the following set of commands to ensure that all ipv4 and ipv6 traffic marked with *X* (assumed to be 123 in the example) routes correctly. Note that this example assumes that *eth0* is diff --git a/docs/root/intro/arch_overview/ip_transparency.rst b/docs/root/intro/arch_overview/ip_transparency.rst index 788d9e6fdda9a..7a270e940c726 100644 --- a/docs/root/intro/arch_overview/ip_transparency.rst +++ b/docs/root/intro/arch_overview/ip_transparency.rst @@ -40,8 +40,9 @@ Proxy Protocol protocol for communicating metadata about a connection over TCP, prior to the main TCP stream. This metadata includes the source IP. Envoy supports consuming this information using :ref:`Proxy Protocol filter `, which may be used to recover -the downstream remote address for propagation into an x-forwarded-for header. It can also be used -in conjunction with the +the downstream remote address for propagation into an +:ref:`x-forwarded-for ` header. It can also be used in +conjunction with the :ref:`Original Src Listener Filter `. Some drawbacks to Proxy Protocol: