Local Data and RPZ¶

Local overrides for DNS data may be defined in the local-data configuration tree. It provides various input formats described in following subsections.

# Some typical use cases:
local-data:
  addresses:
    a1.example.com: 2001:db8::1
    a2.example.org: [ 192.0.2.2, 192.0.2.3, 2001:db8::4 ]
  addresses-files:
    - /etc/hosts
  records: |
    www.google.com.  CNAME  forcesafesearch.google.com.
  rpz:
    - file: /tmp/blocklist.rpz

local-data:¶

ttl: <time ms|s|m|h|d>¶: Optional, this allows to write the new TTL value for records generated by the local-data.

nodata: true|false¶

Default: true

Enabling NODATA synthesis, false if disabling. If set to true (the default), an empty answer will be synthesised for matching name but mismatching type (e.g. AAAA query when only A hint exists).

Records¶

The typical use case is to define some name-address pairs, which also generate corresponding reverse PTR records.

addresses: <dict[hostname, address]>¶: Optional, direct addition of hostname and IP address pairs.

addresses-files: <list of paths>¶: Optional, direct addition of hostname and IP address pairs from files in /etc/hosts like format.

local-data:
  addresses:
    a1.example.com: 2001:db8::1
    a2.example.com: 2001:db8::2
  addresses-files:
    - /etc/hosts
  # some options
  ttl: 5m
  nodata: false # don't force empty answer for missing record types on mentioned names

records: <zonefile format string>¶: Optional, direct addition of records in DNS zonefile format. The zonefile syntax is more flexible, e.g. it can define any type of records.

local-data:
  records: |
    www.google.com.  CNAME  forcesafesearch.google.com.
    example.com  TXT  "an example text record"
    34.example.com  AAAA  2001:db8::3
    34.example.com  AAAA  2001:db8::4

Response Policy Zones (RPZ)¶

RPZ files are another way of adding rules.

rpz: <list>¶

file: <path>¶: Path to a RPZ zonefile.

tags: <list of tags>¶: Optional, restrict when this RPZ applies. See Tags.

local-data:
  rpz:
    - file: /tmp/adult.rpz
      tags: [ adult ]
      # security blocklist applied for everyone
    - file: /tmp/security.rpz

So far, RPZ support is limited to the most common features:

just files which are not automatically reloaded when changed
rules with rpz-* labels are ignored, e.g. .rpz-client-ip
CNAME *.some.thing does not expand the wildcard

Advanced rules¶

rules: <list>¶

This allows defining more complex sets of rules for records and subtrees. For example, it allows blocking whole subtrees.

name: <domain name or list>¶: Optional, hostname(s)/subtree(s) to which the rule applies.

address: <address or list>¶

Optional, IP address(es) to pair with hostname(s).

local-data:
  rules:
    # hostname and IP address pair
    - name: a3.example.com
      address: 2001:db8::3
      tags: [example]
      ttl: 10m

subtree: empty|nxdomain|redirect¶

Optional, type of this subtree:

empty is an empty zone with just SOA and NS at the top

nxdomain replies NXDOMAIN everywhere, though in some cases that looks slightly weird

redirect answers with local-data records from the top of the zone, inside the whole virtual subtree

local-data:
  rules:
    - name: [ evil.example.org, malware.example.net ]
      subtree: empty
      tags: [ malware ]
    - name: a5.example
      subtree: redirect
      address: 2001:db8::5

file: <path or list>¶

Optional, direct addition of hostname and IP address pairs from files in /etc/hosts like format.

local-data:
  rules:
    - file: custom.hosts
      tags: [ malware ]
      ttl: 20m
      nodata: false

records: <zonefile format string>¶

Optional, direct addition of records in DNS zonefile format. The zonefile syntax is more flexible, e.g. it can define any type of records.

local-data:
  rules:
    - records: |
        www.google.com.  CNAME  forcesafesearch.google.com.
      tags: [ adult ]

tags: <list of tags>¶: Optional, restrict when this rule applies. See Tags.

ttl: <time s|m|h|d>¶: Optional, TTL of answers from this rule. Uses /local-data/ttl if unspecified.

nodata: true|false¶: Optional, enabling NODATA synthesis, false if disabling. Uses /local-data/nodata if unspecified. If set to true, an empty answer will be synthesised for matching name but mismatching type (e.g. AAAA query when only A hint exists).