This is an automated email from the ASF dual-hosted git repository.
masaori 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 97ea9faf67 Doc: Clarification of ACL filters (#11448)
97ea9faf67 is described below
commit 97ea9faf6700cc603f97a66cf792fed4a9172e5d
Author: Masaori Koshiba <[email protected]>
AuthorDate: Mon Jul 1 09:48:35 2024 +0900
Doc: Clarification of ACL filters (#11448)
* Doc: Clarification of ACL filters
* Fix syntax
* Fix sentences
* Adjust tables
* Add description of new matching policy
* Add more descriptions of policies
* Rename matching policies
* More example and notes
* Fix a mistake
---
doc/admin-guide/files/records.yaml.en.rst | 12 +++
doc/admin-guide/files/remap.config.en.rst | 171 ++++++++++++++++++++++++++----
2 files changed, 164 insertions(+), 19 deletions(-)
diff --git a/doc/admin-guide/files/records.yaml.en.rst
b/doc/admin-guide/files/records.yaml.en.rst
index b526999d6f..425d2e97a9 100644
--- a/doc/admin-guide/files/records.yaml.en.rst
+++ b/doc/admin-guide/files/records.yaml.en.rst
@@ -3545,6 +3545,18 @@ URL Remap Rules
This is dynamic to enable different requirements for startup and reloading.
+.. ts:cv:: CONFIG proxy.config.url_remap.acl_matching_policy INT 0
+ :reloadable:
+
+ This controls matching policy of ACL filters in :file:`remap.config`. See
:ref:`acl-filters` for more details.
+
+ ===== =============================
+ Value Description
+ ===== =============================
+ ``0`` Match on IP and Method Policy
+ ``1`` Match on IP only Policy
+ ===== =============================
+
.. _records-config-ssl-termination:
SSL Termination
diff --git a/doc/admin-guide/files/remap.config.en.rst
b/doc/admin-guide/files/remap.config.en.rst
index 0fc378598c..e76639e540 100644
--- a/doc/admin-guide/files/remap.config.en.rst
+++ b/doc/admin-guide/files/remap.config.en.rst
@@ -440,18 +440,16 @@ for configuration details and examples.
ACL Filters
===========
-ACL filters can be created to control access of specific remap lines. The
markup
+In-line Filter
+--------------
+
+In-line filters can be created to control access of specific remap lines. The
markup
is very similar to that of :file:`ip_allow.yaml`, with slight changes to
accommodate remap markup.
-**Note:** As of ATS v10.x, these filters are applied just as
:file:`ip_allow.yaml`,
-meaning once a filter matches the request, the action for that rule takes
effect.
-In previous versions, all filters for a remap rule were evaluated, and the
``deny``
-action took priority. Also, if an ACL filter matches, then
:file:`ip_allow.yaml` rules
-will not not apply to the request because the matched rule is the ACL filter.
Examples
---------
+~~~~~~~~
::
@@ -477,7 +475,7 @@ If no IP address is specified for ``@src_ip``,
``@src_ip_category``, or
can be explicitly stated with ``@src_ip=all``.
Named Filters
-=============
+-------------
Named filters can be created and applied to blocks of mappings using
the ``.definefilter``, ``.activatefilter``, and ``.deactivatefilter``
@@ -487,15 +485,13 @@ filter for all mappings that follow until deactivated with
``.deactivatefilter``.
The ``@internal`` operator can be used to filter on whether a request
-is generated by |TS| itself, usually by a plugin. This operator
+is generated by |TS| itself, usually by a plugin. This operator
is helpful for remapping internal requests without allowing access
to external users. By default both internal and external requests
are allowed.
-In-line ACL filters take priority over named active ACL filters.
-
Examples
---------
+~~~~~~~~
::
@@ -518,20 +514,157 @@ mapping rules. (It is activated before any mappings and
is never
deactivated.) The filter `local_only` will only be applied to the
second mapping.
-Implict IPAllow filter
-======================
+Special Filter and ip_allow Named Filter
+----------------------------------------
+
+If :file:`ip_allow.yaml` has a "deny all" filter, it is treated as a special
filter that is applied before remapping for
+optimizaion. To control this for specific remap rules, a named filter called
``ip_allow`` is pre-defined. This named filter is
+activated implicitly in default. To stop applying the special rule, disable
the ``ip_allow`` filter as shown below.
+
+::
-To allow control of :ref:`IP Allow<ip-allow>` it is treated as an implicitly
active and named
-filter. When this filter is active IP Allow checks are done before remap. To
prevent this for
-specific remap rules, this filter, named "ip_allow", must be disabled. The
common way of doing this
-would be ::
+ # ip_allow.yaml
+ ip_allow:
+ - apply: in
+ ip_addrs: 198.51.100.0/24
+ action: deny
+ method: ALL
+ # remap.config
.deactivatefilter ip_allow
map ...
map ...
.activatefilter ip_allow
-Note this entirely disables IP Allow checks for those remap rules.
+Note this entirely disables :file:`ip_allow.yaml` checks for those remap rules.
+
+Evaluation Order and Matching Policy
+------------------------------------
+
+ATS evaluates multiple ACL filters in the following order:
+
+1. Special "deny all" filter in :file:`ip_allow.yaml`
+2. In-line Filter in :file:`remap.config`
+3. Named Filters in :file:`remap.config`
+4. Filters in :file:`ip_allow.yaml`
+
+When an ACL filter is found, ATS stops processing subsequent ACL filters
depending on the mathcing policy configured by
+:ts:cv:`proxy.config.url_remap.acl_matching_policy`.
+
+Note the step 1 happens at the start of the connection before any transactions
are processed, unlike the other rules here.
+
+.. note::
+
+ ATS v10 introduced following matching policies. Prior to the change, ATS
traverses all matched ACL filters by IP and "deny"
+ action had priority.
+
+
+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.
+
+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.
+
+.. note::
+
+ This policy's behavior is similar to ATS v9 and older, but employs "first
match wins" 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.
+
+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.
+
+More realistic example is following:
+
+::
+
+ map http://www.example.com/ http://internal.example.com/ @action=allow
@method=GET @method=HEAD
+
+The implicit ``@src_ip`` is all client IP address, so this filter will apply
to all transactions matching this remap rule. Again,
+like an analogously crafted ip_allow allow rule, this will allow ``GET`` and
``HEAD`` requests while denying all other methods to
+the ``internal.example.com`` origin. No other ACL filters or ip_allow rules
will apply for this target.
+
+.. warning::
+
+ This policy has completly new behavior introduced by ATS v10. When the
``@action=deny`` is used with this policy, be careful to
+ list up **all** methods to deny. Otherwise, the cache control methods like
``PURGE`` and ``PUSH`` are allowed unintentionally.
+
+Example of ACL filter combinations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an example of in-line filter, named filters in :file:`remap.config`,
and :file:`ip_allow.yaml`.
+
+::
+
+ # ip_allow.yaml
+ ip_allow:
+ - apply: in
+ ip_addrs: [0/0, ::/0]
+ action: deny
+ method: [PURGE, PUSH]
+
+ # remap.config
+ .definefilter named-filter-1 @action=allow @method=HEAD
+ .definefilter named-filter-2 @action=deny @method=DELETE
+
+ .activatefilter named-filter-1
+ .activatefilter named-filter-2
+
+ map http://www.example.com/ http://internal.example.com/ @action=deny
@method=POST
+
+With the "Match on IP and Method Policy", the evaluation applied from left to
right until match is found:
+
+====== ============== ============== ============== ================
=============
+Method In-line Filter Named Filter 1 Named Filter 2 ip_allow.yaml result
+====== ============== ============== ============== ================
=============
+GET \- \- \- allow (implicit) allowed
(200)
+POST deny \- \- \- denied
(403)
+HEAD \- allow \- \- allowed
(200)
+DELETE \- \- deny \- denied
(403)
+PURGE \- \- \- deny denied
(403)
+PUSH \- \- \- deny denied
(403)
+====== ============== ============== ============== ================
=============
+
+With the "Match on IP only Policy", the in-line filter works like an
:file:`ip_allow.yaml` rule applies to all requests to
+``www.example.com`` that denies ``POST`` requests and implicitly allows all
other methods:
+
+====== ================ ============== ============== =============
=============
+Method In-line Filter Named Filter 1 Named Filter 2 ip_allow.yaml result
+====== ================ ============== ============== =============
=============
+GET allow (implicit) \- \- \- allowed
(200)
+POST deny \- \- \- denied
(403)
+HEAD allow (implicit) allow \- \- allowed
(200)
+DELETE allow (implicit) \- deny \- allowed
(200)
+PURGE allow (implicit) \- \- deny allowed
(200)
+PUSH allow (implicit) \- \- deny allowed
(200)
+====== ================ ============== ============== =============
=============
Including Additional Remap Files
================================
