.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. .. include:: ../../common.defs .. highlight:: yaml .. _ip-allow: =============== ip_allow.yaml =============== .. configfile:: ip_allow.yaml The :file:`ip_allow.yaml` file controls client access to |TS| and |TS| connections to upstream servers. This control is specified via rules. Each rule has: * A direction (inbound or out). * A range of IP address to which the rule applies. * An action, either accept or deny. * A list of HTTP methods. Inbound rules control access to |TS| from user agents. Outbound rules control access to upstream destinations from |TS|. The IP addresses always apply to the remote address for |TS|. 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. |TS| can be updated for changes to the rules in :file:`ip_allow.yaml` file, by running the :option:`traffic_ctl config reload`. Format ====== :file:`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`` or ``out``. Inbound application means the rule is applied to inbound user agent connections. Outbound application means the rule is applied to outbound connections from |TS| 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. This is a required key. ``action`` The action, which must be ``allow`` or ``deny``. This is a required key. ``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 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 |TS|. This applies as well to TLS connections which are forwarded via ``forward_route`` since, while those are decrypted, they are not processed by |TS|. For details, see :ref:`sni-routing` and :file:`sni.yaml`. 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. As a final example, 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 ] } ] .. 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.