zonemaster.es/zonemaster/test-zone-data

Test Zone Data

Table of contents

• Introduction
• Installing mandatory parts
• Installing Bind
• Updating and installing Perl DNS libraries
• Running instructions
  • Start coredns in terminal 1
  • Run zonemaster-cli in terminal 2
  • Run unit tests in terminal 2
  • Running Bind
• Files
• Directories
• Resources
• Test case based test zones
• Other test zones

Introduction

When loading coredns configuration the test-zone-data directory should be the working directory, else it will not find all included data files. That directory structure holds directories with zone files and coredns configurations for the test zone scenarios.

Installing mandatory parts

1. Only Ubuntu 22.04 is supported.
2. Install Zonemaster-CLI on the computer. Install current develop branch or the latest version of Zonemaster (it will not work with older version than v2022.2, first version with support for --hint).
3. Clone this repository or copy its contents to the computer.
4. Install go (here version 1.20 is assumed):

   sudo apt install golang-go 
   

5. Install unbound

   sudo apt install libunbound-dev
   

6. Install coredns:
   1. Reference https://github.com/coredns/coredns
   2. Clone coredns:

   git clone https://github.com/coredns/coredns
   cd coredns
   

   3. Add the line "unbound:github.com/coredns/unbound" to the plugin.cfg file found in the top of the repository, e.g.

   echo "unbound:github.com/coredns/unbound" >> plugin.cfg
   

   4. Add support for CHAOS class in more plugins. In coredns/core/dnsserver/server.go find EnableChaos at the end of the file. Add "template" and "acl" to the plugins that accepts CHAOS class. For reference see https://github.com/coredns/coredns/discussions/6373
   5. Generate and compile

   go get github.com/coredns/unbound
   go generate
   CGO_ENABLED=1 make
   

   6. coredns is now in top of repository. Add it to PATH and repeat this step every time coredns is recompiled (or create a symlink instead).

   sudo cp coredns  /usr/local/bin/
   

Installing Bind

This step can be skipped unless you will create or update DNS record with the help of Bind, e.g. for test zones for scenarios for DNSSEC10.

sudo apt install bind9

Make sure Bind is off and will not automatically start after restart.

sudo systemctl stop named
sudo systemctl disable named

We will need to start named with configuration files in different locations so apparmor must be disabled for named. The change is permanent.

sudo ln -s /etc/apparmor.d/usr.sbin.named /etc/apparmor.d/disable/
sudo apparmor_parser -R /etc/apparmor.d/disable/usr.sbin.named

Updating and installing Perl DNS libraries

Utilities for DNSSEC handling at test zone creation for some test cases, e.g. DNSSEC10, require updated Net::DNS and installed Net::DNS::SEC. This update and installation, respectively, is not needed unless the scripts are to be run. See utils/ for the scripts requiring these libraries.

sudo cpanm -i Net::DNS
sudo cpanm -i Net::DNS::SEC

Running instructions

Two terminal windows to the computer are needed.

Start coredns in terminal 1

1. Change to the test-zone-data directory (where this README file is).
2. If new IP addresses have been taken into use, address-plan.md must be updated.
3. Create all virtual interfaces. This step has to be done once for each session or again if additional interfaces have been added. (Reboot the computer to remove the interfaces, if needed.)

   sudo ./set-ip.sh
   

4. Start coredns. It will use main.cfg and be running in the foreground until terminated. Only one instance can run at a time.

   sudo ./start-coredns.sh
   

Run zonemaster-cli in terminal 2

1. Change directory to where this README file is.
2. Use zonemaster-cli with --hint and the appropriate name.root hint file. Example:

   zonemaster-cli UNEXPECTED-RCODE-MX.zone09.xa --raw  --test Zone/zone09 --hints COMMON/hintfile --level info
   

   with output

   0.00 INFO      GLOBAL_VERSION   version=v4.5.1
   0.07 WARNING   Z09_UNEXPECTED_RCODE_MX   ns_ip_list=ARRAY(0x5638fec55130); rcode=NOTIMPL
   0.07 NOTICE    Z09_MISSING_MAIL_TARGET
   

For more examples and information on how to interpret the example above, go to section “Directories” below, find the test module, then the test case within the module, and read the test case’s README file.

Run unit tests in terminal 2

Unit tests based on these test zones for Zonemaster-Engine can now be run in terminal 2 and the data can be recorded and saved as data files. See the t directory in Zonemaster-Engine for more details.

Running Bind

For the test zones for some scenarios DNS records are created by Bind, e.g. DNSSEC10. For more information see the [Bind README][README-Bind.md].

Files

The following files are found in this directory, i.e. the same directory as this README file.

• address-plan.md
  • A document that explains the IP plan and that also contains the IP plan in a markdown table.
• main.cfg
  • The default main coredns configuration file that includes all other data files.
• [README-Bind.md]
  • Instructions for running Bind.
• set-ip.sh
  • A script to populate the loopback based on the content of address-plan.md.
• start-coredns.sh
  • A script to start CoreDNS correctly.

More files are found in the directories below.

Directories

The following directories are found in this directory, i.e. the same directory as this README file. More files and sub-directories are found in those directories.

Resources

Directories not holding direct test zone data, but resources for the test zone data.

• COMMON/

  • Holds zone files and configuration that are shared between several scenarios for different test cases.

• utils/

  • Holds utility scripts for test zone construction, e.g. DNSSEC10 test zones.

Test case based test zones

• Address-TP/
  • Directory structure for scenarios for test cases in the Address-TP test module.
• Basic-TP/
  • Directory structure for scenarios for test cases in the Basic-TP test module.
• Connectivity-TP/ (not yet available)
  • Directory structure for scenarios for test cases in the Connectivity-TP test module.
• Consistency-TP/
  • Directory structure for scenarios for test cases in the Consistency-TP test module.
• DNSSEC-TP/
  • Directory structure for scenarios for test cases in the DNSSEC-TP test module.
• Delegation-TP/ (not yet available)
  • Directory structure for scenarios for test cases in the Delegation-TP test module.
• Nameserver-TP/
  • Directory structure for scenarios for test cases in the Nameserver-TP test module.
• Syntax-TP/ (not yet available)
  • Directory structure for scenarios for test cases in the Syntax-TP test module.
• Zone-TP/
  • Directory structure for scenarios for test cases in the Zone-TP test module.

Other test zones

• Engine/
  • Directory structure for test zones for Perl modules in Zonemaster-Engine.
• MethodsV2/
  • Direcotry structure for scenarios for the shared methods for the test cases.