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

Warning

While you can insert all kinds of records and rules into local-data:, they won’t work exactly as in real zones on authoritative servers. For example, wildcards won’t get expanded and DNAMEs won’t cause occlusion.

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).