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 35bc37f38ad549dba0fdb5e24d44731c4d24c57c 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 (cherry picked from commit 97ea9faf6700cc603f97a66cf792fed4a9172e5d) --- 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 62eeccb1ea..198b014e4f 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 aaee196fa9..32f97a3db9 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 ... .activateefilter 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 ================================
