(trafficserver) 09/09: IP Allow: document when rules are applied (#11240)

[cm...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

cmcfarlen pushed a commit to branch 10.0.x
in repository https://gitbox.apache.org/repos/asf/trafficserver.git

commit eaf34fd330a3b858dfca72c9848ec065ca432e7e
Author: Brian Neradt <br...@gmail.com>
AuthorDate: Wed Apr 10 18:08:58 2024 -0500

    IP Allow: document when rules are applied (#11240)
    
    I have noticed when discussing the IP Allow feature that there is some
    confusion over when various types of rules are applied. This PR
    documents the three stages in which any given rule could be applied.
    
    (cherry picked from commit 10520b361a97d431e3f31991bf2c0a5287538700)
---
 doc/admin-guide/files/ip_allow.yaml.en.rst | 22 ++++++++++++++++++++++
 doc/admin-guide/files/remap.config.en.rst  |  2 ++
 2 files changed, 24 insertions(+)

diff --git a/doc/admin-guide/files/ip_allow.yaml.en.rst b/doc/admin-guide/files/ip_allow.yaml.en.rst
index 83b8458b9a..63e6d3ae2f 100644
--- a/doc/admin-guide/files/ip_allow.yaml.en.rst
+++ b/doc/admin-guide/files/ip_allow.yaml.en.rst
@@ -143,6 +143,28 @@ enables all methods for all outbound connections.
    since, while those are decrypted, they are not processed by |TS|.  For
    details, see :ref:`sni-routing` and :file:`sni.yaml`.
 
+Timing
+======
+
+IP allow rules are applied at different stages, depending on the type of rule:
+
+* **On connection accept:** At the beginning of accepting a connection, if the
+  source IP address matches an ``in`` rule and the rule denies all methods from
+  this client (meaning that all transactions from the client are denied), the
+  connection is immediately closed by |TS|. The idea is that since the
+  administrator wants to deny all transactions from the client, |TS| should just
+  reject any connection from the client and not even process data from it. Note
+  that this means that for these all-method rules, no transactions are ever
+  processed by |TS|, and thus there will be no transaction log entries for these
+  denied connections.
+* **Post remap:** ``in`` rules that are not all-method rules (meaning they apply
+  only to certain methods) are processed for each transaction after the client
+  headers are parsed and remap is applied. Processing the rules post-remap
+  allows for remap ACL modifications (see :ref:`Remap ACL Filters
+  <acl-filters>`).
+* **Preceding server connect:** ``out`` rules are applied after DNS resolution of
+  the upstream server but before the connection is established.
+
 Examples
 ========
 
diff --git a/doc/admin-guide/files/remap.config.en.rst b/doc/admin-guide/files/remap.config.en.rst
index 7988220b30..9bd479b830 100644
--- a/doc/admin-guide/files/remap.config.en.rst
+++ b/doc/admin-guide/files/remap.config.en.rst
@@ -435,6 +435,8 @@ You may configure Nexthop or Parent hierarchical caching rules by remap using th
 **@strategy** tag.  See :doc:`../configuration/hierarchical-caching.en` and :doc:`strategies.yaml.en`
 for configuration details and examples.
 
+.. _acl-filters:
+
 ACL Filters
 ===========