acl

Name

acl - enforces access control policies

Description

With acl, users are able to block or filter suspicious DNS queries by configuring IP filter rule sets, i.e. allowing authorized queries or blocking unauthorized queries.

When evaluating the rule sets, acl uses the source IP adresss, unless the ecs handler has added an address to the context.

Syntax

acl {
    ACTION [QTYPE]... [NET]...
    ACTION CTX VALUE...
}

• ACTION defines the way to deal with DNS queries matched by this rule. The default action is allow, DNS query not matched by any rules will be allowed to continue. The following actions are defined:

  • allow forward the query to the next handler.
  • block stop the query and return a refused response with the extended error (EDE) 'blocked'.
  • filter stop the query and returns noerror response with the extended error (EDE) 'filtered'.
  • drop stop the query and don't send any reply.

• QTYPE is the query type to match for the requests to be allowed or blocked. If QTYPE is omitted it matches all types.

• NET is the source IP address requests to be allowed or blocked. Typical CIDR notation and single IP addresses are supported.

• CTX must be used in the format xxx/yyy, i.e. two words seperated by a slash. The geoip handler for instance writes data under (among other) the key geoip/city, that can be used here. If the key does not return any data it will considered a positive match and ACTION is performed.

• VALUE is the value to match CTX to. Again with the geoip handler and using Cambridge here you can have access control on a city level.

Examples

Block everything

. {
    acl {
        block
    }
}

Filter all DNS queries with record type A from 192.168.0.0/16：

. {
    acl {
        filter A 192.168.0.0/16
    }
}

Block all DNS queries from 192.168.0.0/16 except for 192.168.1.0/24:

. {
    acl {
        allow 192.168.1.0/24
        block 192.168.0.0/16
    }
}

Drop all queries from Cambridge, this requires the geoip handler to have populated the context for this query. Allow all countries that are in the EU.

. {
    acl {
        block geoip/city Cambridge
        allow geoip/country/eu true
    }
}

Metrics

If monitoring is enabled (via the metrics handler) then the following metrics are exported:

• atomdns_acl_blocked_requests_total{zone, network, family} - counter of DNS requests being blocked.
• atomdns_acl_filtered_requests_total{zone, network, family} - counter of DNS requests being filtered.
• atomdns_acl_allowed_requests_total{zone, network, family} - counter of DNS requests being allowed.
• atomdns_acl_dropped_requests_total{zone, network, family} - counter of DNS requests being dropped.

The zone,network and family labels are explained in the metrics handler documentation. These metrics follow the global's metric \N setup, and as such should be multiplied by N to get the actual value.

Also See

See the ecs handler that can added a better source address.

Bugs

acl should also check TSIG and other signed messages, see https://codeberg.org/miekg/dns/issues/426.