masaori335 commented on code in PR #11633:
URL: https://github.com/apache/trafficserver/pull/11633#discussion_r1699225005
##########
doc/admin-guide/files/remap.config.en.rst:
##########
@@ -581,67 +581,159 @@ Note the step 1 happens at the start of the connection
before any transactions a
ATS v10 introduced following matching policies. Prior to the change, ATS
traverses all matched ACL filters by IP and "deny"
action had priority.
+ACL Action Behavior Changes for 10.x
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before |TS| 10.x, ACL filters used the same action names as
:file:`ip_allow.yaml` (``allow`` and ``deny``) but these
+actions behaved differently.
+
+- As described in :file:`ip_allow.yaml`, for any transaction matching an
:file:`ip_allow.yaml` rule whose action is
+ ``allow``, any request with a method in the allow list will be accepted,
while all other methods are denied. ``deny``
+ actions instead list methods which are denied, while all other methods are
implicitly allowed.
+- These same action names for ACL filters, on the other hand, functioned
essentially additively in nature. For instance,
+ an ``allow`` ACL filter action would list a set of methods which would be
allowed in addition to any other allowed
+ methods specified by :file:`ip_allow.yaml` rules. Similarly, a ``deny`` ACL
filter action would list a set of methods
+ which would be denied in addition to any other denied methods specified by
:file:`ip_allow.yaml` rules.
+
+This difference in behavior lead at times to confusion as users would expect
the two actions having the same name to
+behave the same across the ACL filter and :file:`ip_allow.yaml` rule systems.
+
+For |TS| 10.x, these ACL filter actions are transitioning to be more
consistent with :file:`ip_allow.yaml` rules while
+still allowing additive action behavior via two new rules: ``add_allow`` and
``add_deny``:
+
+- ``allow``: as with ``allow`` actions for :file:`ip_allow.yaml` rules, this
action specifies a list of HTTP methods
+ which are allowed. All requests with a methods in this list will be allowed,
requests with methods not in this list
+ will be denied, and no other filters or :file:`ip_allow.yaml` rules will be
applied.
+- ``deny``: as with ``deny`` actions for :file:`ip_allow.yaml` rules, this
action now specifies a list of HTTP methods
+ which are denied. All requests with a method in this list will be denied,
all other requests will be allowed, and no
+ other filters or :file:`ip_allow.yaml` rules will be applied.
+- ``add_allow``: this action, new to |TS| 10.x, behaves like ``allow`` used to
behave for ACL filters pre |TS| 10.x:
+ that is, it adds methods which are allowed to the :file:`ip_allow.yaml` rule
otherwise matched for the given
+ transaction.
+- ``add_deny``: this action, new to |TS| 10.x, behaves like ``deny`` used to
behave for ACL filters pre |TS| 10.x: that
+ is, it adds methods which are denied the :file:`ip_allow.yaml` rule
otherwise matched for the given transaction.
+
+This change to ``allow`` and ``deny`` ACL filter actions is backwards
incompatible with pre |TS| 10.x releases. In order
+to avoid surprises when transitioning to |TS| 10.x, by default, the ``allow``
and ``deny`` ACL filter actions rather
+behave like they did in |TS| 9.x: that is, they behave the same as
``add_allow`` and ``add_deny``. This behavior is
+deprecated in |TS| 10.x with the ``allow`` and ``deny`` ACL filter actions
acting like they do for :file:`ip_allow.yaml`
+being the default behavior for the future |TS| 11.x release. The behavior is
configurable via the
+:ts:cv:`proxy.config.url_remap.acl_matching_policy` described below.
Match on IP and Method Policy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This is the default matching policy. With this policy, ACL filters, in-line or
named, only take effect if both IP address and HTTP
-method match the incoming request. If there is no match, ATS proceeds to the
next ACL filter to find a matching one.
-
-This policy is useful for organizations that want ACL rules to additively
allow or deny specific methods in addition to other ACL
-filters and :file:`ip_allow.yaml` rules.
+This is the default ACL matching policy and it is configured by setting
+:ts:cv:`proxy.config.url_remap.acl_matching_policy` to ``0``. With this
policy, ACL filter ``allow`` and ``deny``
+actions behave like they did pre |TS| 10.x: they additively add allowed or
denied methods for transactions.
+Functionally, this means that with this legacy policy configured, ``allow`` is
a synonym for ``add_allow`` and ``deny``
+is a synonym for ``add_deny``. Because of this, an organization can easily,
and incrementally prepare for the modern
+ACL filter action behavior by transitioning a rule one at a time by simply
replacing ``allow`` with ``add_allow`` and
+``deny`` with ``add_deny``. Once all actions are transitioned, an organization
can then switch to the modern policy.
Consider a filter like the following:
::
map http://www.example.com/ http://internal.example.com/ @action=deny
@method=POST
-The implicit ``@src_ip`` is all client IP addresses, so this filter will match
on any ``POST`` request matched by this remap rule
-from any client and its action will be to deny such POST requests. For all
other methods, the filter will not take effect, thus
-allowing other active ACL filters or an :file:`ip_allow.yaml` rule to
determine the action to take for any other transaction.
+The implicit ``@src_ip`` is all client IP addresses, so this filter will match
on any ``POST`` request matched by this
+remap rule from any client and its action will be to deny such POST requests.
For all other methods, the filter will not
+take effect, thus allowing other active ACL filters or an
:file:`ip_allow.yaml` rule to determine the action to take for
+any other transaction.
+
+With the legacy policy being described here, this filter acts identically with
an ``add_deny`` action. Thus, the above
+rule is identical with:
+
+::
+
+ map http://www.example.com/ http://internal.example.com/ @action=add_deny
@method=POST
.. note::
This policy's behavior is similar to ATS v9 and older, but employs "first
match wins" policy.
-Match on IP only Policy
+Match on IP Only Policy
~~~~~~~~~~~~~~~~~~~~~~~
-With this policy, ACL filters match solely based upon IP address, meaning that
ACL filters match like :file:`ip_allow.yaml` rules.
-When a filter is processed, the action is applied to the specified methods and
its opposite to **all other** methods.
-
-This policy is useful for organizations that want to have ACL filters behave
like :file:`ip_allow.yaml` rules specific to remap
-targets.
+As described above, with this policy, ACL filter ``allow`` and ``deny``
actions function as they do for
+:file:`ip_allow.yaml` rules. Filters that instead want to additively allow or
deny methods to base
+:file:`ip_allow.yaml` rules should use the ``add_allow`` and ``add_deny``
actions. Match on IP only ACL action policy
+is configured by setting :ts:cv:`proxy.config.url_remap.acl_matching_policy`
to ``1``.
Consider a filter like the following (the same as above):
::
map http://www.example.com/ http://internal.example.com/ @action=deny
@method=POST
-The implicit ``@src_ip`` is all client IP address, so this filter will apply
to **all** requests matching this remap rule. Again,
-like an analogously crafted :file:`ip_allow.yaml` action rule, this will deny
``POST`` request while allowing **all** other methods
-to the ``www.example.com``. No other ACL filters or :file:`ip_allow.yaml`
rules will be applied for any request to this target.
+The implicit ``@src_ip`` is all client IP address, so this filter will apply
to **all** requests matching this remap
+rule. Again, like an analogously crafted :file:`ip_allow.yaml` action rule,
this will deny ``POST`` requests while
+allowing **all** other methods to the ``www.example.com``. No other ACL
filters or :file:`ip_allow.yaml` rules will be
+applied for any request to this target.
-More realistic example is following:
+On the other hand, if one wants to instead additively deny ``POST`` requests
like they can in match on IP and method
+policy, they would simply use the ``add_deny`` action:
+
+::
+
+ map http://www.example.com/ http://internal.example.com/ @action=add_deny
@method=POST
+
+This rule behaves identically with the corresponding ``@action=deny`` rule
described above in the "Match on IP Only
+Policy" section: it will ensure that ``POST`` requests are denied while
leaving all other methods to other
+:file:`ip_allow.yaml` rules or ACL filters to determine how they should be
handled.
+
+Considering again the ``@action=deny`` example, it is naturally not very
likely that someone will simply want to deny
+just ``POST`` methods while allowing all other methods. A more realistic
``@action=deny`` example is the following:
Review Comment:
the following example is `@action=allow` not `@action=deny`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
