# Test Zone Data ## Table of contents * [Introduction](#introduction) * [Installing mandatory parts](#installing-mandatory-parts) * [Installing Bind](#installing-bind) * [Updating and installing Perl DNS libraries](#updating-and-installing-perl-dns-libraries) * [Running instructions](#running-instructions) * [Start coredns in terminal 1](#start-coredns-in-terminal-1) * [Run zonemaster-cli in terminal 2](#run-zonemaster-cli-in-terminal-2) * [Run unit tests in terminal 2](#run-unit-tests-in-terminal-2) * [Running Bind](#running-bind) * [Files](#files) * [Directories](#directories) * [Resources](#resources) * [Test case based test zones](#test-case-based-test-zones) * [Other 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](#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][test-zone-data], 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. [address-plan.md]: address-plan.md [Address-TP/]: Address-TP/ [Basic-TP/]: Basic-TP/ [COMMON/]: COMMON/ [Consistency-TP/]: Consistency-TP/ [DNSSEC-TP/]: DNSSEC-TP/ [Engine/]: Engine/ [main.cfg]: main.cfg [MethodsV2/]: MethodsV2/ [Nameserver-TP/]: Nameserver-TP/ [README-Bind]: README-Bind.md [set-ip.sh]: set-ip.sh [start-coredns.sh]: start-coredns.sh [t]: https://github.com/zonemaster/zonemaster-engine/tree/develop/t [test-zone-data]: . [utils/]: utils/ [Zone-TP/]: Zone-TP/ [Zonemaster-Engine]: https://github.com/zonemaster/zonemaster-engine/