You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by rr...@apache.org on 2020/05/26 18:20:15 UTC
[trafficserver] branch master updated: Doc updates for tunnel_route
and ip_allow interaction.
This is an automated email from the ASF dual-hosted git repository.
rrm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 612881a Doc updates for tunnel_route and ip_allow interaction.
612881a is described below
commit 612881a5664678dd27d272d51f5e94c3d0af184b
Author: bneradt <bn...@verizonmedia.com>
AuthorDate: Thu May 21 16:59:17 2020 +0000
Doc updates for tunnel_route and ip_allow interaction.
---
doc/admin-guide/files/ip_allow.yaml.en.rst | 19 ++++++++++++++-----
doc/admin-guide/files/sni.yaml.en.rst | 6 +++---
doc/admin-guide/layer-4-routing.en.rst | 9 +++++----
3 files changed, 22 insertions(+), 12 deletions(-)
diff --git a/doc/admin-guide/files/ip_allow.yaml.en.rst b/doc/admin-guide/files/ip_allow.yaml.en.rst
index e8e98ba..4c4553c 100644
--- a/doc/admin-guide/files/ip_allow.yaml.en.rst
+++ b/doc/admin-guide/files/ip_allow.yaml.en.rst
@@ -21,7 +21,7 @@ ip_allow.yaml
.. configfile:: ip_allow.yaml
The :file:`ip_allow.yaml` file controls client access to |TS| and |TS| connections to upstream servers.
-This control is specified rules. Each rule has
+This control is specified via rules. Each rule has:
* A direction (inbound or out).
* A range of IP address to which the rule applies.
@@ -69,7 +69,7 @@ Format
Each rule is a mapping. The YAML data must have a top level key of "ip_allow" and its value must
be a mapping or a sequence of mappings, each of those being one rule.
-The keys in a rule are
+The keys in a rule are:
``apply``
This is where the rule is applied, either ``in`` or ``out``. Inbound application means
@@ -85,7 +85,7 @@ The keys in a rule are
``methods``
This is optional. If not present, the rule action applies to all methods. If present, the rule
- action is applied connections using those methods and its opposite to all other connections. The
+ action is applied to connections using those methods and its opposite to all other connections. The
keyword "ALL" means all methods, making the specification of any other method redundant. All
methods comparisons are case insensitive. This is an optional key.
@@ -97,14 +97,14 @@ allowed to have a range that contains addresses from different IP address famili
* A CIDR based value, e.g. "10.1.0.0/16", which is a range containing exactly the specified network.
A rule must have the ``apply``, ``ip_addrs``, and ``action`` keys. Rules match based on
-IP addresses only, and are then applied to all matching sessions. If the rule is an ``allow`` rule,
+IP addresses only and are then applied to all matching sessions. If the rule is an ``allow`` rule,
the specified methods are allowed and all other methods are denied. If the rule is a ``deny`` rule,
the specified methods are denied and all other methods are allowed.
For example, from the default configuration, the rule for ``127.0.0.1`` is ``allow`` with all
methods. Therefore an inbound connection from the loopback address (127.0.0.1) is allowed to use any
method. The general IPv4 rule, covering all IPv4 address, is a ``deny`` rule and therefore when it
-matches the methods "PURGE", "PUSH", and "DELETE" are denied, any other method is allowed.
+matches the methods "PURGE", "PUSH", and "DELETE", these methods are denied and any other method is allowed.
The rules are matched in order, by IP address, therefore the general IPv4 rule does not apply to the
loopback address because the latter is matched first.
@@ -114,6 +114,15 @@ inbound connections are denied and therefore if there is no rule that matches, t
denied. Outbound rules allow by default, so the absence of rules in the default configuration
enables all methods for all outbound connections.
+.. note::
+
+ Be aware that ip_allow rules will not, and indeed cannot, be applied to TLS
+ connections which are tunneled via ``tunnel_route`` to the upstream target.
+ Such connections are not decrypted and thus are not processed by |TS|. This
+ applies as well to TLS connections which are forwarded via ``forward_route``
+ since, while those are decrypted, they are not processed by |TS|. For
+ details, see :ref:`sni-routing` and :file:`sni.yaml`.
+
Examples
========
diff --git a/doc/admin-guide/files/sni.yaml.en.rst b/doc/admin-guide/files/sni.yaml.en.rst
index b6e3780..016d029 100644
--- a/doc/admin-guide/files/sni.yaml.en.rst
+++ b/doc/admin-guide/files/sni.yaml.en.rst
@@ -30,10 +30,10 @@ connections. The configuration is driven by the SNI values provided by the inbou
file consists of a set of configuration items, each identified by an SNI value (``fqdn``).
When an inbound TLS connection is made, the SNI value from the TLS negotiation is matched against
the items specified by this file and if there is a match, the values specified in that item override
-the defaults. This is done during the inbound connection processing and be some outbound properties
+the defaults. This is done during the inbound connection processing; some outbound properties
can be overridden again later, such as via :file:`remap.config` or plugins.
-By default this is named :file:`sni.yaml`. The file can be changed by setting
+By default this is named :file:`sni.yaml`. The filename can be changed by setting
:ts:cv:`proxy.config.ssl.servername.filename`. This file is loaded on start up and by
:option:`traffic_ctl config reload` if the file has been modified since process start.
@@ -239,7 +239,7 @@ Use FQDN captured group to match in ``tunnel_route``.
FQDN ``some.foo.com`` will match and the captured string will be replaced in the ``tunnel_route`` which will end up being
``some.myfoo``.
Second part is using multiple groups, having ``bob.bar.example.com`` as FQDN, ``tunnel_route`` will end up being
-``bar.some.example.yahoo``.
+``bar.some.bob.yahoo``.
See Also
========
diff --git a/doc/admin-guide/layer-4-routing.en.rst b/doc/admin-guide/layer-4-routing.en.rst
index 188eafa..b652897 100644
--- a/doc/admin-guide/layer-4-routing.en.rst
+++ b/doc/admin-guide/layer-4-routing.en.rst
@@ -61,7 +61,10 @@ the option of interest is ``tunnel_route``. If this is set then |TS| synthesizes
request to itself with the ``tunnel_route`` host and port as the upstream. That is, the inbound
connection is treated as if the user agent had sent a
``CONNECT`` to the upstream and forwards the "`CLIENT HELLO
-<https://tools.ietf.org/html/rfc5246#section-7.4.1.2>`__" to it.
+<https://tools.ietf.org/html/rfc5246#section-7.4.1.2>`__" to it. In addition to the method appearing
+as ``CONNECT``, be aware that logs printing the URL via the ``<%cquc>`` field format will show the
+scheme in the URL as ``tunnel``. The scheme as printed via ``<%cqus>``, however, will show the
+scheme used in the original client request.
Example
-------
@@ -108,12 +111,10 @@ The :file:`sni.yaml` contents would be
- tunnel_route: app-server-56:4443
fqdn: service-2.example.com
-In addition to this, in the :file:`records.config` file, edit the following variables:
+In addition to this, in the :file:`records.config` file, edit ``connect_ports`` like so:
- :ts:cv:`proxy.config.http.connect_ports`: ``443 4443`` to allow |TS| to connect
to the destination port
- - :ts:cv:`proxy.config.url_remap.remap_required`: ``0`` to permit |TS| to process requests
- for hosts not explicitly configured in the remap rules
The sequence of network activity for a Client connecting to ``service-2`` is