Conversion of old-style settings to YAML format

Running the command

rec_control show-yaml

will show the conversion of existing old-style settings into the new YAML format. The existing settings will be read from the default old-style settings file recursor.conf in the configuration directory. It is also possible to show the conversion of a specific old-style settings file by running

rec_control show-yaml path/to/recursor.conf

rec_control show-yaml will also show the conversions of any included .conf file (if include-dir is set) and other associated settings file, like forward-zones-file.

Example

Consider the old style configuration file recursor.conf:

dnssec=validate
include-dir=recursor.d
forward-zones = example=127.0.0.1:1024
forward-zones-file=fwzones.txt
local-address=128.66.23.4:5353, [::1]:53

With the contents of recursor.d/01.conf:

forward-zones += example.com=128.66.9.99
forward-zones += example.net=128.66.9.100;128.66.9.101
local-address = 0.0.0.0

And fwzones.txt:

^+example.org=127.0.0.1:1024

To show the conversion result, run:

cd example
rec_control show-yaml recursor.conf

Produces the following conversion report:

# Start of converted recursor.yml based on recursor.conf
dnssec:
  validation: validate
incoming:
  listen:
  - 128.66.23.4:5353
  - '[::1]:53'
recursor:
  forward_zones:
  - zone: example
    recurse: false
    forwarders:
    - 127.0.0.1:1024
  forward_zones_file: fwzones.txt
  include_dir: recursor.d
# Validation result: OK
# End of converted recursor.conf
#
# Found 1 .conf file in recursor.d
# Converted include-dir recursor.d/01.conf to YAML format:
incoming:
  listen: !override
  - 0.0.0.0
recursor:
  forward_zones:
  - zone: example.com
    recurse: false
    forwarders:
    - 128.66.9.99
  - zone: example.net
    recurse: false
    forwarders:
    - 128.66.9.100
    - 128.66.9.101
# Validation result: OK
# End of converted recursor.d/01.conf
#
# Converted fwzones.txt to YAML format for recursor.forward_zones_file: 
- zone: example.org
  forwarders:
  - 127.0.0.1:1024
  recurse: true
  notify_allowed: true
# Validation result: OK
# End of converted fwzones.txt
#

Note the !override tag for incoming.listen (corresponding to the = in recursor.d/01.conf. The recursor.forward_zones settings is extending the setting in the main recursord.yml file, as recursor.d/01.conf uses a += for the forward-zones settings. Consult PowerDNS Recursor New Style (YAML) Settings for details on how settings spread over multiple files are merged.

The contents of the report can be used to produce YAML settings equivalent to the old-style settings. This is a manual step and consists of copy-pasting the sections of the conversion report to individual files.

Any converted settings filename in the include directory should end with .yml. The names of associated files (like a recursor.forward_zones_file) should also end in .yml, but should not be put into the include directory, as they do not contain full configuration YAML clauses but YAML sequences of a specific type. The associated files can be put in the config directory, the directory that is searched for a recursor.conf or recursor.yml file.

API Managed Files

The format of API managed files was also changed to use YAML format. Specifically, the list of API managed zones is now a single file containing a sequence of auth_zones and a sequence of forward_zones instead of a settings file per zone. The list of ACLs is a YAML sequence of subnets or IP addresses.

When using YAML settings recursor.include_dir and webservice.api_dir must have a different value. When YAML settings are active the Recursor will read old-style API managed files from the include directory on startup, convert them to the new format and write them into the API config directory. After conversion, it will inactivate the old-style API managed config files in the include directory by renaming them.