ip_allow.yaml¶
The ip_allow.yaml
file controls client access to Traffic Server and Traffic Server connections to upstream servers.
This control is specified via rules. Each rule has:
A direction (inbound or out).
A range of IP addresses or an IP category to which the rule applies.
An action, either accept or deny.
A list of HTTP methods.
Inbound rules control access to Traffic Server from user agents. Outbound rules control access to upstream destinations from Traffic Server. The IP addresses always apply to the remote address for Traffic Server. That is, the user agent IP address for inbound rules and the upstream destination address for outbound rules. The rule can apply at the connection level or just to specific methods.
Traffic Server can be updated for changes to the rules in ip_allow.yaml
file, by running the
traffic_ctl config reload
.
Format¶
ip_allow.yaml
is YAML format. The default configuration is:
# YAML
ip_allow:
- apply: in
ip_addrs: 127.0.0.1
action: allow
methods: ALL
- apply: in
ip_addrs: ::1
action: allow
methods: ALL
- apply: in
ip_addrs: 0/0
action: deny
methods:
- PURGE
- PUSH
- DELETE
- TRACE
- apply: in
ip_addrs: ::/0
action: deny
methods:
- PURGE
- PUSH
- DELETE
- TRACE
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:
apply
This is where the rule is applied, either
in
orout
. Inbound application means the rule is applied to inbound user agent connections. Outbound application means the rule is applied to outbound connections from Traffic Server to an upstream destination. This is a required key.ip_addrs
IP addresses to match for the rule to be applied. This can be either an address range or an array of address ranges. Either this or
ip_categories
are required keys for a rule.ip_categories
A user defined string identifying a category of IP addresses relevant to a particular network. For example,
ACME_INTERNAL
might represent the set of IP addresses for hosts within a company’s network.ACME_EXTERNAL
might represet hosts belonging to the company’s network, but which are outside the company’s firewall.ACME_ALL
could be used to represent the set of both of these categories. Multiple categories can be specified as an array of strings.The set of IP ranges belonging to each category is specified via the separate
ip_categories
root level node. Theip_allow.yaml
parser also supports supplying the IP categories via an external file specified with theproxy.config.cache.ip_categories.filename
configuration.Either this or
ip_addrs
are required keys for a rule.action
The action describing the behavior of the rule. This can be either
set_allow
orset_deny
.set_allow
provides a list of allowed methods, while all requests with other methods are denied.set_deny
provides a list of denied methods, while all requests with other methods are allowed. This is a required key.
Note
Prior to Traffic Server 10.x, these actions were named allow
and deny
. In order to bring alignment
to the action names in remap ACL actions (see ACL Filters for more details), these have
been renamed to set_allow
and set_deny
. If
proxy.config.url_remap.acl_behavior_policy
is set to 0, which is the default, the old
allow
and deny
actions are still supported in order to provide backwards compatibility to
Traffic Server 9.x ip_allow.yaml
files. If it is set to 1, then the use of allow
and deny
will result in a fatal error with a message asking the user to use set_allow
and set_deny
instead.
methods
This is optional. If not present, the rule action applies to all methods. If present, the rule 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.
An IP address range for ip_addrs
or ip_categories
can be specified in several ways. A range
is always IPv4 or IPv6, it is not allowed to have a range that contains addresses from different IP
address families.
A single address, which specifies a range of size 1, e.g. “127.0.0.1”.
A minimum and maximum address separated by a dash, e.g. “10.1.0.0-10.1.255.255”.
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,
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”, “DELETE”, and “TRACE”, 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.
A major difference in application between in
and out
rules is that by default,
inbound connections are denied and therefore if there is no rule that matches, the connection is
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 Traffic Server. This
applies as well to TLS connections which are forwarded via forward_route
since, while those are decrypted, they are not processed by Traffic Server. For
details, see SNI Routing and 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 Traffic Server. The idea is that since the administrator wants to deny all transactions from the client, Traffic Server 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 Traffic Server, 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 Remap ACL Filters).Preceding server connect:
out
rules are applied after DNS resolution of the upstream server but before the connection is established.
Examples¶
The following example enables all clients access:
apply: in
ip_addrs: 0.0.0.0-255.255.255.255
action: allow
The following example allows access to all clients on addresses in a subnet:
apply: in
ip_addrs: 123.12.3.000-123.12.3.123
action: allow
The following example denies access all clients on addresses in a subnet:
apply: in
ip_addrs: 123.45.6.0-123.45.6.123
action: deny
If the entire subnet were to be denied, that would be:
apply: in
ip_addrs: 123.45.6.0/24
action: deny
The following example allows any method to any upstream servers:
apply: out
ip_addrs: 0.0.0.0-255.255.255.255
action: allow
Alternatively this can be done with:
apply: out
ip_addrs: 0/0
action: allow
Or also by having no rules at all, as outbound by default is allow.
The following example denies to access all servers on a specific subnet:
apply: out
ip_addr: 10.0.0.0-10.0.255.255
action: deny
Alternatively:
apply: out
ip_addrs: 10.0.0.0/16
action: deny
The ip_addrs
can be an array of ranges, so that:
- apply: in
ip_addrs: 10.0.0.0/8
action: deny
- apply: in
ip_addrs: 172.16.0.0/20
action: deny
- apply: in
ip_addrs: 192.168.1.0/24
action: deny
can be done more simply as:
apply: in
ip_addrs:
- 10.0.0.0/8
- 172.16.0.0/20
- 192.168.1.0/24
action: deny
If the goal is to allow only GET
and HEAD
requests to those servers, it would be:
apply: out
ip_addrs: 10.0.0.0/16
methods: [ GET, HEAD ]
action: allow
Alternatively:
apply: out
ip_addrs: 10.0.0.0/16
methods:
- GET
- HEAD
action: allow
This will match the IP address for the target servers on the outbound connection. Then, if the
method is GET
or HEAD
the connection will be allowed, otherwise the connection will be
denied.
For the purposes of illustration, here is the default configuration in compact form:
ip_allow: [
{ apply: in, ip_addrs: 127.0.0.1, action: allow },
{ apply: in, ip_addrs: "::1", action: allow },
{ apply: in, ip_addrs: 0/0, action: deny, methods: [ PURGE, PUSH, DELETE, TRACE ] },
{ apply: in, ip_addrs: "::/0", action: deny, methods: [ PURGE, PUSH, DELETE, TRACE ] }
]
The following example demonstrates how to use ip_categories
. In this example, the
ip_categories
is ACME_INTERNAL
which is presumably associated with trusted internal IP
addresses and thus are allowed to POST
and DELETE
resources.
Note this example demonstrates that it is OK to mix ip_categories
and ip_addrs
rules in a
single ip_allow.yaml
file. In this case all other IPv4 addresses not matched on
ACME_INTERNAL
match on 0/0
and can only perform GET
and HEAD
requests:
- apply: in
ip_categories: ACME_INTERNAL
action: allow
methods:
- GET
- HEAD
- POST
- DELETE
- apply: in
ip_addrs: 0/0
action: allow
methods:
- GET
- HEAD
The set of IP addresses associated with ACME_INTERNAL
can be specified
using the ip_categories
node like so:
ip_categories:
- name: ACME_INTERNAL
ip_addrs:
- 10.0.0.0/8
- 172.16.0.0/20
- 192.168.1.0/24
ip_allow:
- apply: in
# ...
The ip_categories
node will generally be at the start of the ip_allow.yaml
file.
Alternatively, the same content with the ip_categories
root node can exist in a separate file
specified with the proxy.config.cache.ip_categories.filename
configuration.
Note
For ATS 9.0, this file is (almost) backwards compatible. If the first line is a single ‘#’ character, or contains only “# ats”, then the file will be read in the version 8.0 format. This is true for the default format and so if that has not been changed it should still work. This allows a grace period before ATS 10.0 which will drop the old format entirely.