Public documentation

Zonemaster is a software package that validates the quality of a DNS delegation. The ambition of the Zonemaster project is to develop and maintain an open source DNS validation tool, offering improved performance over existing tools and providing extensive documentation which could be re-used by similar projects in the future.

Zonemaster consists of several modules or components. The components will help different types of users to check domain servers for configuration errors and generate a report that will assist in fixing the errors.

Zonemaster is developed by Afnic and IIS.

A public instance is running at https://zonemaster.net.

The public documentation is divided into the following main categories:

• Release information gives release information of latest release.
• Installation contains documents that explain how to install the different components of Zonemaster.
• Upgrading contains documents that explain how to upgrade a Zonemaster installation.
• Configuration contains documents that explain how a Zonemaster installation can be configured.
• Using contains user guides to the different components of Zonemaster.
• Specifications contains specifications of the Zonemaster test cases, test types and test zones.
• Development contains information for developers both in and outside the Zonemaster project.
• License gives the license information for Zonemaster.

Release v2024.2 (2024-12-09)

[Release information]

• Translations have not been fully updated in this release. They will be updated in an upcoming extra release.
• User documentation for the current and past releases will now also be published on https://doc.zonemaster.net

[Breaking changes]

• Refactors ASNLookup code in Zonemaster-Engine

[Features]

• Updates global cache documentationand makes the feature being supported and not experimental (#1327, #1303). Also see Zonemaster-Engine release notes
• Updates or adds specification of test cases or test scenarios for test cases Connectivity04 (#1311, #1299, #1298). Also see Zonemaster-Engine release notes for updates implementation
• Updates specification of test case Connectivity03 (#1297). Also see Zonemaster-Engine release notes for updated implementation
• Updates or adds specification of test cases or test scenarios for test cases DNSSEC10 (#1294, #1179). Also see Zonemaster-Engine release notes for updated implementation
• Corrects display when running 'zonemaster-cli'. See Zonemaster-CLI release notes
• Makes utilities zmb() and zmtest supported. See Zonemaster-Backend release notes
• Rebuild Zonemaster-GUI distribution package to remove potential vulnerabilities. See Zonemaster-GUI release notes

[Fixes]

• Updates installation instructions (#1334, #1332, #1330, #1331, #1322, #1321, #1314, #1307)
• Updates translations instructions (#1320)
• Updates general documents (#1319, #1318, #1317, #1316)
• Updates usage document for CLI (#1309)
• Adds specification of test scenarios for test cases Delegation01, Delegation02 and Delegation03 (#1305)
• Removes unimplemented test case Nameserver14 (#1300)
• Updates and adds usage document for Backend and batch testing (#1310, #1303)
• Updates or adds specification of MethodsV2 (shared between test cases) or test scenarios for MethodsV2 (#1290, #1287, #1254)
• Corrects spelling i various documents (external controbution from @jsoref) (#1278)
• Adds specification of test scenarios for the CNAME function in Recursor.pm in Engine (#1220)

[Zonemaster product]

This version of Zonemaster also consists of the following components. For each component, see its Changes file or Github release notes for complete release information.

For more information on previous versions of the Zonemaster product see the Changes file or the releases page on Github. For general information ses the README file.

Installation instructions

Manual installation

Before installing Zonemaster, check the prerequisites first.

Start by installing the following components, in order:

• Zonemaster-LDNS;
• Zonemaster-Engine;
• Zonemaster-CLI.

At this point, tests can be run from the command-line on the local machine. To install the Web GUI, install the following additional components, in order:

• Zonemaster-Backend;
• Zonemaster-GUI.

Docker

Alternatively, Zonemaster-CLI is available on Docker Hub, and can be conveniently downloaded and run without any installation. Through Docker Zonemaster-CLI can be run on Linux, macOS and Windows. See Using the CLI for how to run Zonemaster-CLI on Docker.

To build your own Docker image, see the Docker Image Creation documentation.

Prerequisites

Zonemaster comes with documentation for and has been tested on the operating systems and processor architecture listed below.

Supported processor architectures

• x86_64 / amd64

Supported operating system versions

• Debian 12
• Docker
• FreeBSD 14
• Rocky Linux 8
• Rocky Linux 9
• Ubuntu 20.04
• Ubuntu 22.04
• Ubuntu 24.04

Only the latest long-term supported version of Debian and FreeBSD, respectively, is supported. All long-term supported versions of Rocky Linux and Ubuntu are supported, unless such a version has end of support before the expected next release of Zonemaster.

Only the Docker images provided by the Zonemaster project on Docker Hub are supported. Currently only Zonemaster-CLI is supported on Docker. Docker itself can run on any of the Docker supported OSs (Linux, macOS and Windows).

Rocky Linux has replaced CentOS in Zonemaster version v2021.2 since CentOS 8 is not supported anymore and CentOS 7 is old and does not support modern OpenSSL required by Zonemaster. Rocky Linux is also a Red Hat derivative and is available at large cloud providers.

Supported database engine versions

• (*) FreeBSD uses MySQL, not MariaDB.
• SQLite is bundled in Perl DBD::SQLite and loaded as a dependency to Zonemaster-Backend.
• Zonemaster Backend has been tested with the combination of OS and database engine version listed in the table above.
• Zonemaster depends on functionality introduced in PostgreSQL version 10, and earlier versions of PostgreSQL are as such not supported.
• Zonemaster Backend has not been published on Docker Hub.

Supported Perl versions

• Zonemaster technically requires Perl version 5.16 or higher, but has only been tested with the versions in the table above.
• Zonemaster has been tested with the default version of Perl in the OSs as listed in the table above.
• (*) Perl is included in the Docker image published on Docker Hub.

Supported Client Browser versions

Zonemaster GUI is tested on the browsers in the table below. The latest version of the browser at the time of testing is used.

Zonemaster GUI is tested manually and with testing tools. See the Zonemaster-gui repository for more details.

Installation: Zonemaster-LDNS

Recommended installation

The recommended way to install Zonemaster::LDNS is to follow the installation instructions for Zonemaster::Engine where you will find all prerequisites and dependencies for Zonemaster::LDNS before installing it.

Installation from source

Override the default set of features by appending --FEATURE and/or --no-FEATURE options to the perl Makefile.PL command.

git clone https://github.com/zonemaster/zonemaster-ldns
cd zonemaster-ldns
perl Makefile.PL
make
make test
make install

Note: The source ZIP files downloaded from GitHub are broken with respect to this instruction.

Optional features

When installing from source, you can choose to enable or disable a number of optional features using command line options to the perl Makefile.PL commands.

Ed25519

Enabled by default. Disabled with --no-ed25519

Requires support for algorithms Ed25519 and Ed448 in both openssl and ldns.

Note: Zonemaster Engine relies on this feature for its analysis when Ed25519 (DNSKEY algorithm 15) or Ed448 (DNSKEY algorithm 16) is being used in DNSSEC signatures.

IDN

Enabled by default. Disable with --no-idn.

If the IDN feature is enabled, the GNU libidn2 library will be used to add a simple function that converts strings from Perl's internal encoding to IDNA domain name format. In order to convert strings from whatever encoding you have to Perl's internal format, use L. If you need any kind of control or options, use Net::LibIDN. The included function here is only meant to assist in the most basic case, although that should cover a lot of real-world use cases.

Note: The Zonemaster Engine test suite assumes this feature is enabled.

Internal ldns

Enabled by default. Disable with --no-internal-ldns.

When enabled, an included version of ldns is statically linked into Zonemaster::LDNS. When disabled, libldns is dynamically linked just like other dependencies.

Randomized capitalization

Disabled by default. Enable with --randomize.

Note: This feature is experimental.

Randomizes the capitalization of returned domain names.

Custom OpenSSL

Disabled by default. Enabled with --prefix-openssl=/path/to/openssl or --openssl-inc=/path/to/openssl_inc or --openssl-lib=/path/to/openssl_lib.

Enabling this makes the build tools look for OpenSSL in a non-standard place.

Technically this does two things:

• Libcrypto is sought in the lib directory under the given directory.
• The include directory under the given directory is added to the include path.

Note: The lib directory under the given path must be known to the dynamic linker or feature checks will fail.

If both headers and libraries directories (include and lib) are not in the same parent directory, use --openssl-inc and --openssl-lib options to specify both paths.

Custom LDNS

Disabled by default. Enabled with --ldns-inc=/path/to/ldns_inc or --ldns-lib=/path/to/ldns_lib.

Enabling this makes the build tools look for LDNS in a non-standard place.

Requires Internal LDNS to be disabled.

Custom Libidn

Disabled by default. Enabled with --libidn-inc=/path/to/libidn_inc or --libidn-lib=/path/to/ldns_lib.

Enabling this makes the build tools look for Libidn in a non-standard place.

Requires IDN to be enabled.

Debug

Disabled by default. Enabled with --debug.

Gives a more verbose output.

Post-installation sanity check

perl -MZonemaster::LDNS -E 'say Zonemaster::LDNS->new("8.8.8.8")->query("zonemaster.net")->string'

The above command should print some dig-like output.

Testing

Some of the unit tests depend on data on the Internet, which may change. To avoid false fails, those unit tests are only run if the environment variable TEST_WITH_NETWORK is true. By default that variable is unset (those tests are not run). To run all tests, execute

TEST_WITH_NETWORK=1 make test

Installation: Zonemaster-Engine

Table of contents

• Local installation
  • Installation on Rocky Linux
  • Installation on Debian and Ubuntu
  • Installation on FreeBSD
• Post-installation sanity check
• Troubleshooting installation
• Global cache
• What to do next

Local installation

Installation on Rocky Linux

1. Install the EPEL repository:

   sudo dnf install --assumeyes epel-release
   sudo crb enable
   

2. Enable SHA-1 in the crypto policy:

   # Only on Rocky Linux 9:
   sudo update-crypto-policies --set DEFAULT:SHA1
   

3. Install locales:

   sudo dnf install --assumeyes glibc-all-langpacks
   

4. Install binary packages:

   sudo dnf install --assumeyes cpanminus gcc libidn2-devel openssl-devel perl-Class-Accessor perl-Clone perl-core perl-Devel-CheckLib perl-Email-Valid perl-ExtUtils-PkgConfig perl-File-ShareDir perl-File-Slurp perl-libintl perl-IO-Socket-INET6 perl-List-Compare perl-List-MoreUtils perl-Mail-SPF perl-Module-Find perl-Module-Install perl-Net-DNS perl-Pod-Coverage perl-Readonly perl-Sub-Override perl-Test-Differences perl-Test-Exception perl-Test-Fatal perl-Test-NoWarnings perl-Test-Pod perl-Text-CSV perl-Test-Simple
   

5. Install packages from CPAN:

   sudo cpanm --notest Locale::PO Log::Any MIME::Base32 Module::Install::XSUtil Net::IP::XS YAML::XS
   

6. Install Zonemaster::LDNS and Zonemaster::Engine:

   sudo cpanm --notest Zonemaster::LDNS Zonemaster::Engine
   

Installation on Debian and Ubuntu

Using pre-built packages is the preferred method for Debian and Ubuntu.

Installation from pre-built packages

1. Upgrade to latest patch level

   sudo apt update && sudo apt upgrade
   

2. Add Zonemaster packages repository to repository list

   curl -LOs https://package.zonemaster.net/setup.sh
   sudo sh setup.sh
   

3. Install Zonemaster Engine

   sudo apt install libzonemaster-engine-perl
   

Installation from CPAN

1. Upgrade to latest patch level

   sudo apt update && sudo apt upgrade
   

2. Install dependencies from binary packages:

   sudo apt install autoconf automake build-essential cpanminus libclass-accessor-perl libclone-perl libdevel-checklib-perl libemail-valid-perl libextutils-pkgconfig-perl libfile-sharedir-perl libfile-slurp-perl libidn2-dev libintl-perl libio-socket-inet6-perl liblist-compare-perl liblist-moreutils-perl liblocale-po-perl liblog-any-perl libmail-spf-perl libmime-base32-perl libmodule-find-perl libmodule-install-perl libmodule-install-xsutil-perl libnet-dns-perl libnet-ip-xs-perl libpod-coverage-perl libreadonly-perl libssl-dev libsub-override-perl libtest-differences-perl libtest-exception-perl libtest-fatal-perl libtest-nowarnings-perl libtest-pod-perl libtext-csv-perl libyaml-libyaml-perl libtool m4
   

3. Install Zonemaster::LDNS and Zonemaster::Engine.

   sudo cpanm --notest Zonemaster::LDNS Zonemaster::Engine
   

Installation on FreeBSD

1. Become root:

   su -l
   

2. Update list of package repositories:

   Create the file /usr/local/etc/pkg/repos/FreeBSD.conf with the following content, unless it is already updated:

   FreeBSD: {
   url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
   }
   

3. Check or activate the package system:

   Run the following command, and accept the installation of the pkg package if suggested.

   pkg info -E pkg
   

4. Update local package repository:

   pkg update -f
   

5. Install dependencies from binary packages:

   pkg install devel/gmake dns/ldns libidn2 p5-App-cpanminus p5-Class-Accessor p5-Clone p5-Devel-CheckLib p5-Email-Valid p5-ExtUtils-PkgConfig p5-File-ShareDir p5-File-Slurp p5-IO-Socket-INET6 p5-List-Compare p5-List-MoreUtils p5-Locale-libintl p5-Locale-PO p5-Log-Any p5-Mail-SPF p5-MIME-Base32 p5-Module-Find p5-Module-Install p5-Module-Install-XSUtil p5-Net-DNS p5-Net-IP-XS p5-Pod-Coverage p5-Readonly p5-Sub-Override p5-Test-Differences p5-Test-Exception p5-Test-Fatal p5-Test-NoWarnings p5-Test-Pod p5-Text-CSV p5-YAML-LibYAML
   

6. Install Zonemaster::LDNS:

   cpanm --notest --configure-args="--no-internal-ldns" Zonemaster::LDNS
   

7. Install Zonemaster::Engine:

   cpanm --notest Zonemaster::Engine
   

Post-installation sanity check

Make sure Zonemaster::Engine is properly installed.

time perl -MZonemaster::Engine -E 'say join "\n", Zonemaster::Engine->test_module("BASIC", "zonemaster.net")'

The command is expected to take a few seconds and print some results about the delegation of zonemaster.net.

Troubleshooting installation

If you have any issue with installation, and installed with cpanm, redo the installation above but without the --notest and with the --verbose option. Installation will take longer time.

Global cache

Global cache is a feature that can be enabled in Zonemaster-Engine and consists in a shared, persistent cache. It can increase the performance when many tests are run within a short time frame. See global cache configuration.

What to do next

• For a command line interface, follow the Zonemaster::CLI installation instruction.
• For a web interface, follow the Zonemaster::Backend installation and Zonemaster::GUI installation instructions.
• For a JSON-RPC API, follow the Zonemaster::Backend installation instruction.
• For a Perl API, see the Zonemaster::Engine API documentation.

Installation: Zonemaster-CLI

Table of contents

• Overview
• Prerequisites for CPAN installation
• Local installation
  • Installation on Rocky Linux
  • Installation on Debian and Ubuntu
  • Installation on FreeBSD
• Post-installation sanity check
• Using Zonemaster-CLI
• Global cache
• What to do next?

Overview

Zonemaster-CLI provides a CLI (command line interface) to Zonemaster. To install follow the instructions below. An alternative to installing Zonemaster-CLI is to run it under Docker. See Using the CLI for run it under Docker.

Prerequisites for CPAN installation

Before installing Zonemaster::CLI from CPAN, you should install Zonemaster::Engine, unless you are to install on Debian using pre-built packages (see below).

Note: Zonemaster::Engine and Zonemaster::LDNS are dependencies of Zonemaster::CLI. Zonemaster::LDNS has a special installation requirement, and Zonemaster::Engine has a list of dependencies that you may prefer to install from your operating system distribution (rather than CPAN). We recommend following the Zonemaster::Engine installation instruction.

Prerequisite for FreeBSD is that the package system is updated and activated (see the FreeBSD section of Zonemaster::Engine installation).

For details on supported versions of Perl and operating system for Zonemaster::CLI, see the declaration of prerequisites.

Local installation

Installation on Rocky Linux

1. Install dependencies:

   sudo dnf install --assumeyes perl-JSON-XS perl-Try-Tiny perl-Test-Deep perl-Mojolicious
   

   sudo cpanm --notest JSON::Validator
   

Note: Test::Deep and Mojolicious are indirect dependencies. They are dependencies of JSON::Validator.

2. Install Zonemaster::CLI

   sudo cpanm --notest Zonemaster::CLI
   

Installation on Debian and Ubuntu

Using pre-built packages is the preferred method for Debian and Ubuntu.

Installation from pre-built packages

1. Add Zonemaster packages repository to repository list

   curl -LOs https://package.zonemaster.net/setup.sh
   sudo sh setup.sh
   

2. Install Zonemaster CLI

   sudo apt install zonemaster-cli
   

3. Update configuration of "locale"

   sudo perl -pi -e 's/^# (da_DK\.UTF-8.*|en_US\.UTF-8.*|es_ES\.UTF-8.*|fi_FI\.UTF-8.*|fr_FR\.UTF-8.*|nb_NO\.UTF-8.*|sv_SE\.UTF-8.*)/$1/' /etc/locale.gen
   sudo locale-gen
   

   After the update, locale -a should at least list the following locales:

   da_DK.utf8
   en_US.utf8
   es_ES.utf8
   fi_FI.utf8
   fr_FR.utf8
   nb_NO.utf8
   sv_SE.utf8
   

Installation from CPAN

1. Install dependencies:

   sudo apt-get install locales libmodule-install-perl libtry-tiny-perl libjson-validator-perl
   

2. Install Zonemaster::CLI:

   sudo cpanm --notest Zonemaster::CLI
   

3. Update configuration of "locale"

   sudo perl -pi -e 's/^# (da_DK\.UTF-8.*|en_US\.UTF-8.*|es_ES\.UTF-8.*|fi_FI\.UTF-8.*|fr_FR\.UTF-8.*|nb_NO\.UTF-8.*|sv_SE\.UTF-8.*)/$1/' /etc/locale.gen
   sudo locale-gen
   

   After the update, locale -a should at least list the following locales:

   da_DK.utf8
   en_US.utf8
   es_ES.utf8
   fi_FI.utf8
   fr_FR.utf8
   nb_NO.utf8
   sv_SE.utf8
   

Installation on FreeBSD

1. Become root:

   su -l
   

2. Install dependencies available from binary packages:

   pkg install gmake p5-JSON-XS p5-Locale-libintl p5-Try-Tiny p5-JSON-Validator
   

3. Install Zonemaster::CLI:

   cpanm --notest Zonemaster::CLI
   

Post-installation sanity check

Run the zonemaster-cli command:

zonemaster-cli --test basic zonemaster.net

The command is expected to take a few seconds and print some results about the delegation of zonemaster.net.

Also, verify that the manual page is properly installed:

man zonemaster-cli

Using Zonemaster-CLI

See Using the CLI for an overview on how to use zonemaster-cli after installation.

Global cache

If Zonemaster-CLI is to be used for large batches, global cache can improve performance. See Global cache in Zonemaster-Engine.

What to do next?

• For a web GUI, follow the Zonemaster::Backend and Zonemaster::GUI installation instructions.
• For a JSON-RPC frontend, follow the Zonemaster::Backend installation instruction.

Installation: Zonemaster-Backend

Table of contents

• 1. Overview
• 2. Prerequisites
• 3. Installation on Rocky Linux
  • 3.1 Install Zonemaster::Backend and related dependencies (Rocky Linux)
  • 3.2 Database engine installation (Rocky Linux)
  • 3.3 Database configuration (Rocky Linux)
  • 3.4 Service configuration and startup (Rocky Linux)
  • 3.5 Post-installation (Rocky Linux)
• 4. Installation on Debian and Ubuntu
  • 4.1 Install Zonemaster::Backend and related dependencies (Debian/Ubuntu)
  • 4.2 Database engine installation (Debian/Ubuntu)
  • 4.3 Database configuration (Debian/Ubuntu)
  • 4.4 Service configuration and startup (Debian/Ubuntu)
  • 4.5 Post-installation (Debian/Ubuntu)
• 5. Installation on FreeBSD
  • 5.1 Install Zonemaster::Backend and related dependencies (FreeBSD)
  • 5.2 Database engine installation (FreeBSD)
  • 5.3 Database configuration (FreeBSD)
  • 5.4 Service startup (FreeBSD)
  • 5.5 Post-installation (FreeBSD)
• 6. Post-installation
  • 6.1 Smoke test
  • 6.2 Troubleshooting installation
  • 6.3 What to do next?
• 7. Installation with MariaDB
  • 7.1 MariaDB (Rocky Linux)
  • 7.2. MariaDB (Debian/Ubuntu)
  • 7.3. MySQL (FreeBSD)
• 8. Installation with PostgreSQL
  • 8.1. PostgreSQL (Rocky Linux)
  • 8.2. PostgreSQL (Debian/Ubuntu)
  • 8.3. PostgreSQL (FreeBSD)
• 9. Cleaning up the database
  • 9.1. MariaDB and MySQL
  • 9.2. PostgreSQL
  • 9.3. SQLite
• 10. Optional features
  • 10.1. Metrics
  • 10.2 Global cache

1. Overview

This document contains all steps needed to install Zonemaster::Backend. For an overview of the Zonemaster product, please see the main Zonemaster Repository.

If you upgrade your Zonemaster installation with a newer version of Zonemaster::Backend instead, and want to keep the database, then see the Upgrade document. Otherwise remove the database and continue with this installation document.

2. Prerequisites

Before installing Zonemaster::Backend, you should install Zonemaster::Engine .

Note: Zonemaster::Engine and Zonemaster::LDNS are dependencies of Zonemaster::Backend. Zonemaster::LDNS has a special installation requirement, and Zonemaster::Engine has a list of dependencies that you may prefer to install from your operating system distribution (rather than CPAN). We recommend following the Zonemaster::Engine installation instruction.

Prerequisite for FreeBSD is that the package system is updated and activated (see the FreeBSD section of Zonemaster::Engine installation).

For details on supported versions of Perl, database engine and operating system for Zonemaster::Backend, see the declaration of prerequisites.

3. Installation on Rocky Linux

3.1 Install Zonemaster::Backend and related dependencies (Rocky Linux)

Note: Zonemaster::LDNS and Zonemaster::Engine are not listed here as they are dealt with in the prerequisites section.

Install dependencies available from binary packages:

sudo dnf install --assumeyes jq perl-Class-Method-Modifiers perl-Config-IniFiles perl-DBD-SQLite perl-DBI perl-File-ShareDir perl-File-Slurp perl-HTML-Parser perl-JSON-PP perl-libwww-perl perl-Log-Dispatch perl-Mojolicious perl-Moose perl-Parallel-ForkManager perl-Plack perl-Plack-Middleware-ReverseProxy perl-Plack-Test perl-Role-Tiny perl-Test-Differences perl-Test-Exception perl-Test-Mojo perl-Test-NoWarnings perl-Try-Tiny perl-libintl perl-LWP-Protocol-https

Install dependencies not available from binary packages:

sudo cpanm --notest Daemon::Control JSON::RPC JSON::Validator Log::Any Log::Any::Adapter::Dispatch Net::IP::XS Router::Simple Starman

For Rocky Linux 8 only, install DBD::SQLite from CPAN as the one in the system packages repository is too old:

sudo cpanm --notest DBD::SQLite

Install Zonemaster::Backend:

sudo cpanm --notest Zonemaster::Backend

The command above might try to install "DBD::Pg" and "DBD::mysql". You can ignore if it fails. The relevant libraries are installed further down in these instructions.

Add Zonemaster user (unless it already exists):

sudo useradd -r -c "Zonemaster daemon user" zonemaster

Install files to their proper locations:

cd `perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")'`
sudo install -v -m 755 -d /etc/zonemaster
sudo install -v -m 640 -g zonemaster ./backend_config.ini /etc/zonemaster/
sudo install -v -m 775 -g zonemaster -d /var/log/zonemaster
sudo install -v -m 644 ./tmpfiles.conf /usr/lib/tmpfiles.d/zonemaster.conf
sudo install -v -m 644 ./zm-rpcapi.service /etc/systemd/system/
sudo install -v -m 644 ./zm-testagent.service /etc/systemd/system/

3.2 Database engine installation (Rocky Linux)

Check the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.

The installation instructions below assumes that this is a new installation.

3.2.1 Instructions for SQLite (Rocky Linux)

Note: Zonemaster with SQLite is not meant for an installation with heavy load.

Create database directory:

sudo install -v -m 755 -o zonemaster -g zonemaster -d /var/lib/zonemaster

Some parameters can be changed, see the backend configuration documentation for details.

3.2.2 Instructions for other engines (Rocky Linux)

See sections for MariaDB and PostgreSQL.

3.3 Database configuration (Rocky Linux)

Create the database tables:

sudo -u zonemaster $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')/create_db.pl

3.4 Service configuration and startup (Rocky Linux)

Make sure our tmpfiles configuration takes effect:

sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/zonemaster.conf

Enable services at boot time and start them:

sudo systemctl enable zm-rpcapi
sudo systemctl enable zm-testagent
sudo systemctl start zm-rpcapi
sudo systemctl start zm-testagent

If you have changed database daemon, restart the services:

sudo systemctl restart zm-rpcapi
sudo systemctl restart zm-testagent

3.5 Post-installation (Rocky Linux)

To check if the daemons are running, do:

sudo systemctl status zm-rpcapi
sudo systemctl status zm-testagent

See the post-installation section for post-installation matters.

4. Installation on Debian and Ubuntu

4.1 Install Zonemaster::Backend and related dependencies (Debian/Ubuntu)

Note: Zonemaster::LDNS and Zonemaster::Engine are not listed here as they are dealt with in the prerequisites section.

Install required locales:

sudo perl -pi -e 's/^# (da_DK\.UTF-8.*|en_US\.UTF-8.*|es_ES\.UTF-8.*|fi_FI\.UTF-8.*|fr_FR\.UTF-8.*|nb_NO\.UTF-8.*|sv_SE\.UTF-8.*)/$1/' /etc/locale.gen
sudo locale-gen

After the update, locale -a should at least list the following locales:

da_DK.utf8
en_US.utf8
es_ES.utf8
fi_FI.utf8
fr_FR.utf8
nb_NO.utf8
sv_SE.utf8

Install dependencies available from binary packages:

sudo apt install jq libclass-method-modifiers-perl libconfig-inifiles-perl libdbd-sqlite3-perl libdaemon-control-perl libdbi-perl libfile-sharedir-perl libfile-slurp-perl libhtml-parser-perl libmojolicious-perl libio-stringy-perl libjson-pp-perl libjson-rpc-perl libjson-validator-perl liblog-any-adapter-dispatch-perl liblog-any-perl liblog-dispatch-perl libmoose-perl libparallel-forkmanager-perl libplack-perl libplack-middleware-debug-perl libplack-middleware-reverseproxy-perl librole-tiny-perl librouter-simple-perl libtest-nowarnings-perl libtest-differences-perl libtest-exception-perl libtry-tiny-perl libintl-perl perl-doc starman

Note: libio-stringy-perl is listed here even though it's not a direct dependency. It's an undeclared dependency of libconfig-inifiles-perl.

For Ubuntu 20.04 only, install JSON::Validator from CPAN as the one in the system packages repository is too old:

sudo cpanm --notest JSON::Validator

Install Zonemaster::Backend:

sudo cpanm --notest Zonemaster::Backend

The command above might try to install "DBD::Pg" and "DBD::mysql". You can ignore if it fails. The relevant libraries are installed further down in these instructions.

Add Zonemaster user (unless it already exists):

sudo useradd -r -c "Zonemaster daemon user" zonemaster

Install files to their proper locations:

cd `perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")'`
sudo install -v -m 755 -d /etc/zonemaster
sudo install -v -m 775 -g zonemaster -d /var/log/zonemaster
sudo install -v -m 640 -g zonemaster ./backend_config.ini /etc/zonemaster/
sudo install -v -m 755 ./zm-rpcapi.lsb /etc/init.d/zm-rpcapi
sudo install -v -m 755 ./zm-testagent.lsb /etc/init.d/zm-testagent
sudo install -v -m 644 ./tmpfiles.conf /usr/lib/tmpfiles.d/zonemaster.conf

If this is an update of Zonemaster-Backend, you should remove any /etc/init.d/zm-backend.sh (script from previous version of Zonemaster-Backend).

4.2 Database engine installation (Debian/Ubuntu)

Check the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.

The installation instructions below assumes that this is a new installation.

4.2.1 Instructions for SQLite (Debian/Ubuntu)

Note: Zonemaster with SQLite is not meant for an installation with heavy load.

Create database directory:

sudo install -v -m 755 -o zonemaster -g zonemaster -d /var/lib/zonemaster

Some parameters can be changed, see the backend configuration documentation for details.

4.2.2 Instructions for other engines (Debian/Ubuntu)

See sections for MariaDB and PostgreSQL.

4.3 Database configuration (Debian/Ubuntu)

Create the database tables:

sudo -u zonemaster $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')/create_db.pl

4.4 Service configuration and startup (Debian/Ubuntu)

Make sure our tmpfiles configuration takes effect:

sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/zonemaster.conf

Enable services at boot time and start them:

sudo systemctl enable zm-rpcapi
sudo systemctl enable zm-testagent
sudo systemctl start zm-rpcapi
sudo systemctl start zm-testagent

If you have changed database daemon, restart the services:

sudo systemctl restart zm-rpcapi
sudo systemctl restart zm-testagent

4.5 Post-installation (Debian/Ubuntu)

To check if the daemons are running, do:

sudo systemctl status zm-rpcapi
sudo systemctl status zm-testagent

See the post-installation section for post-installation matters.

5. Installation on FreeBSD

For all commands below, acquire privileges, i.e. become root:

su -l

5.1 Install Zonemaster::Backend and related dependencies (FreeBSD)

Note: Zonemaster::LDNS and Zonemaster::Engine are not listed here as they are dealt with in the prerequisites section.

Install dependencies available from binary packages:

pkg install jq p5-Class-Method-Modifiers p5-Config-IniFiles p5-Daemon-Control p5-DBI p5-File-ShareDir p5-File-Slurp p5-HTML-Parser p5-JSON-PP p5-JSON-RPC p5-Mojolicious p5-Moose p5-Parallel-ForkManager p5-Plack p5-Plack-Middleware-ReverseProxy p5-Role-Tiny p5-Router-Simple p5-Starman p5-DBD-SQLite p5-Log-Dispatch p5-Log-Any p5-Log-Any-Adapter-Dispatch p5-JSON-Validator p5-YAML-LibYAML p5-Test-NoWarnings p5-Test-Differences p5-Test-Exception p5-Locale-libintl gmake

Install Zonemaster::Backend:

cpanm --notest Zonemaster::Backend

The command above might try to install "DBD::Pg" and "DBD::mysql". You can ignore if it fails. The relevant libraries are installed further down in these instructions.

Unless they already exist, add zonemaster user and zonemaster group (the group is created automatically):

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
pw useradd zonemaster -C freebsd-pwd.conf -s /sbin/nologin -d /nonexistent -c "Zonemaster daemon user"

Install files to their proper locations:

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
install -v -m 755 -d /usr/local/etc/zonemaster
install -v -m 640 -g zonemaster ./backend_config.ini /usr/local/etc/zonemaster/
install -v -m 775 -g zonemaster -d /var/log/zonemaster
install -v -m 775 -g zonemaster -d /var/run/zonemaster
install -v -m 755 ./zm_rpcapi-bsd /usr/local/etc/rc.d/zm_rpcapi
install -v -m 755 ./zm_testagent-bsd /usr/local/etc/rc.d/zm_testagent

5.2 Database engine installation (FreeBSD)

Check the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.

The installation instructions below assumes that this is a new installation.

5.2.1 Instructions for SQLite (FreeBSD)

Note: Zonemaster with SQLite is not meant for an installation with heavy load.

Configure Zonemaster::Backend to use the correct database path:

sed -i '' '/[[:<:]]database_file[[:>:]]/ s:=.*:= /var/db/zonemaster/db.sqlite:' /usr/local/etc/zonemaster/backend_config.ini

Create database directory:

install -v -m 755 -o zonemaster -g zonemaster -d /var/db/zonemaster

Some parameters can be changed, see the backend configuration documentation for details.

5.2.2 Instructions for other engines (FreeBSD)

See sections for MySQL and PostgreSQL.

5.3 Database configuration (FreeBSD)

Create the database tables:

su -m zonemaster -c "`perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir(qw(Zonemaster-Backend))'`/create_db.pl"

5.4 Service startup (FreeBSD)

Enable services at startup and start service:

sysrc zm_rpcapi_enable="YES"
sysrc zm_testagent_enable="YES"
service zm_rpcapi start
service zm_testagent start

If you have changed database daemon, restart the services:

service zm_rpcapi restart
service zm_testagent restart

5.5 Post-installation (FreeBSD)

To check that the running daemons run:

service zm_rpcapi status
service zm_testagent status

See the post-installation section for post-installation matters.

6. Post-installation

6.1 Smoke test

If you have followed the installation instructions for Zonemaster::Backend above, you should be able to use the API on localhost port 5000 as below.

zmtest zonemaster.net

The command is expected to immediately print out a testid, followed by a percentage ticking up from 0% to 100%. Once the number reaches 100% a JSON object is printed and zmtest terminates.

6.2 Troubleshooting installation

If you have any issue with installation, and installed with cpanm, redo the installation above but without the --notest and with the --verbose option. Installation will take longer time.

6.3. What to do next?

• For the Zonemaster-Backend functions see the following documents:
  • Using Zonemaster-Backend JSON-RPC API
  • Backend JSON-RPC API documentation
  • Using Zonemaster-Backend for batch testing
  • Backend configuration
  • Zonemaster Profiles
  • Backend Environment variables
• For a web interface, follow the Zonemaster::GUI installation instructions.
• For a command line interface, follow the Zonemaster::CLI installation instruction.

7. Installation with MariaDB

First follow the installation instructions for the OS in question, and then go to this section to install MariaDB.

7.1. MariaDB (Rocky Linux)

Configure Zonemaster::Backend to use the correct database engine:

sudo sed -i '/\bengine\b/ s/=.*/= MySQL/' /etc/zonemaster/backend_config.ini

Note: See the backend configuration documentation for details.

Install database engine:

sudo dnf -y install mariadb-server perl-DBD-mysql

To create the database and the database user (unless you keep an old database). Edit the commands first if you want a non-default database name, user name or password. To be safe, run the commands one by one.

sudo systemctl start mariadb
sudo mysql -e "CREATE DATABASE zonemaster;"
sudo mysql -e "CREATE USER 'zonemaster'@'localhost' IDENTIFIED BY 'zonemaster';"
sudo mysql -e "GRANT ALL ON zonemaster.* TO 'zonemaster'@'localhost';"

Update the /etc/zonemaster/backend_config.ini file with database name, username and password if non-default values are used.

Now go back to "Database configuration" to create the database tables and then continue with the steps after that.

7.2. MariaDB (Debian/Ubuntu)

Configure Zonemaster::Backend to use the correct database engine:

sudo sed -i '/\bengine\b/ s/=.*/= MySQL/' /etc/zonemaster/backend_config.ini

Note: See the backend configuration documentation for details.

Install the database engine and its dependencies:

sudo apt install mariadb-server libdbd-mysql-perl

To create the database and the database user (unless you keep an old database). Edit the commands first if you want a non-default database name, user name or password. To be safe, run the commands one by one.

sudo mysql -e "CREATE DATABASE zonemaster;"

sudo mysql -e "CREATE USER 'zonemaster'@'localhost' IDENTIFIED BY 'zonemaster';"

sudo mysql -e "GRANT ALL ON zonemaster.* TO 'zonemaster'@'localhost';"

Update the /etc/zonemaster/backend_config.ini file with database name, username and password if non-default values are used.

Now go back to "Database configuration" to create the database tables and then continue with the steps after that.

7.3. MySQL (FreeBSD)

MariaDB is not compatible with Zonemaster on FreeBSD. MySQL is used instead.

Configure Zonemaster::Backend to use the correct database engine:

sed -i '' '/[[:<:]]engine[[:>:]]/ s/=.*/= MySQL/' /usr/local/etc/zonemaster/backend_config.ini

Note: See the backend configuration documentation for details.

Install, configure and start database engine (and Perl bindings):

pkg install mysql80-server p5-DBD-mysql

sysrc mysql_enable="YES"
service mysql-server start

By default the MySQL root password is empty. Just press ENTER if prompted for password. The advice is to set a password.

To create the database and the database user (unless you keep an old database). Edit the command first if you want a non-default database name, user name or password. Run the command on one line. Use the MySQL root password when prompted.

mysql -u root -p -e "CREATE DATABASE zonemaster;" -e "CREATE USER 'zonemaster'@'localhost' IDENTIFIED BY 'zonemaster';" -e "GRANT ALL ON zonemaster.* TO 'zonemaster'@'localhost';"

Update the /usr/local/etc/zonemaster/backend_config.ini file with database name, username and password if non-default values are used.

Now go back to "Database configuration" to create the database tables and then continue with the steps after that.

8. Installation with PostgreSQL

First follow the installation instructions for the OS in question, and then go to this section to install PostgreSQL.

8.1. PostgreSQL (Rocky Linux)

Configure Zonemaster::Backend to use the correct database engine:

sudo sed -i '/\bengine\b/ s/=.*/= PostgreSQL/' /etc/zonemaster/backend_config.ini

Note: See the backend configuration documentation for details.

Install, initialize and configure database engine:

sudo dnf -y install postgresql-server perl-DBD-Pg
sudo postgresql-setup --initdb --unit postgresql
sudo sed -i '/^[^#]/ s/ident$/md5/' /var/lib/pgsql/data/pg_hba.conf

To create the database and the database user (unless you keep an old database). Edit the command first if you want a non-default database name, user name or password. To be safe run the commands one by one.

sudo systemctl start postgresql
sudo -u postgres psql -c "CREATE USER zonemaster WITH PASSWORD 'zonemaster';"
sudo -u postgres psql -c "CREATE DATABASE zonemaster WITH OWNER 'zonemaster' ENCODING 'UTF8';"

Note: You may get error messages from these commands about lack of permission to change directory. You can safely ignore those messages.

Update the /etc/zonemaster/backend_config.ini file with database name, username and password if non-default values are used.

Now go back to "Database configuration" to create the database tables and then continue with the steps after that.

8.2. PostgreSQL (Debian/Ubuntu)

Configure Zonemaster::Backend to use the correct database engine:

sudo sed -i '/\bengine\b/ s/=.*/= PostgreSQL/' /etc/zonemaster/backend_config.ini

Install the database engine and Perl bindings:

sudo apt install postgresql libdbd-pg-perl

Note: See the backend configuration documentation for details.

To create the database and the database user (unless you keep an old database). Edit the command first if you want a non-default database name, user name or password. To be safe run the commands one by one.

sudo -u postgres psql -c "CREATE USER zonemaster WITH PASSWORD 'zonemaster';"

sudo -u postgres psql -c "CREATE DATABASE zonemaster WITH OWNER 'zonemaster' ENCODING 'UTF8';"

Update the /etc/zonemaster/backend_config.ini file with database name, username and password if non-default values are used.

Now go back to "Database configuration" to create the database tables and then continue with the steps after that.

8.3. PostgreSQL (FreeBSD)

Configure Zonemaster::Backend to use the correct database engine:

sed -i '' '/[[:<:]]engine[[:>:]]/ s/=.*/= PostgreSQL/' /usr/local/etc/zonemaster/backend_config.ini

Note: See the backend configuration documentation for details.

Install, configure and start database engine and Perl bindings:

pkg install p5-DBD-Pg

The Perl bindings library (p5-DBD-Pg) has a dependency to a specific version of postgresql-client. Determine what version was installed:

pkg info | grep postgresql | grep client

Replace XX in the command below to install postgresql-server with the same major version as the installed postgresql-client, e.g. 16.

pkg install postgresqlXX-server

Enable daemon, initiate and start:

sysrc postgresql_enable="YES"
service postgresql initdb
service postgresql start

To create the database and the database user (unless you keep an old database). Edit the commands first if you want a non-default database name, user name or password.

psql -U postgres -c "CREATE USER zonemaster WITH PASSWORD 'zonemaster';"
psql -U postgres -c "CREATE DATABASE zonemaster WITH OWNER 'zonemaster' ENCODING 'UTF8';"

Update the /usr/local/etc/zonemaster/backend_config.ini file with database name, username and password if non-default values are used.

Now go back to "Database configuration" to create the database tables and then continue with the steps after that.

9. Cleaning up the database

If, at some point, you want to delete all traces of Zonemaster in the database, you can run the file cleanup-mysql.sql or file cleanup-postgres.sql as a database administrator. Commands for locating and running the file are below. It removes the user and drops the database (obviously taking all data with it).

Each script uses default values, you may need to adapt them to your setup.

9.1. MariaDB and MySQL

Rocky Linux, Debian and Ubuntu:

sudo mysql --user=root < `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`/cleanup-mysql.sql

FreeBSD (you will get prompted for MySQL password):

mysql --user=root -p < `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`/cleanup-mysql.sql

9.2. PostgreSQL

Rocky Linux, Debian and Ubuntu:

sudo -u postgres psql -f $(perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")')/cleanup-postgres.sql

FreeBSD (as root):

psql -U postgres -f `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`/cleanup-postgres.sql

9.3. SQLite

Remove the database file and recreate it following the installation instructions above.

10. Optional features

10.1 Metrics

Statsd metrics are available, to enable the feature install the additional Net::Statsd module. See the configuration to configure the receiver.

The list of metrics is available in the Telemetry document.

10.1.1 Installation on Rocky Linux

sudo cpanm --notest Net::Statsd

10.1.2 Installation on Debian / Ubuntu

sudo apt install libnet-statsd-perl

10.1.3 Installation on Freebsd

cpanm --notest Net::Statsd

10.2 Global cache

If Zonemaster-Backend is to be used for large batches, global cache can improve performance. See Global cache in Zonemaster-Engine.

Installation: Zonemaster-GUI

Prerequisites

Before installing Zonemaster Web GUI, you should install Zonemaster::Engine and Zonemaster::Backend.

Prerequisite for FreeBSD is that the package system is updated and activated, see FreeBSD section of install Zonemaster::Engine.

Installation

This instruction covers the following operating systems:

1. Rocky Linux
2. Debian and Ubuntu
3. FreeBSD

1. Rocky Linux

Install Apache

sudo dnf update
sudo dnf -y install httpd unzip

Install Zonemaster Web GUI

curl -L -O https://github.com/zonemaster/zonemaster-gui/releases/download/v4.3.1/zonemaster_web_gui.zip
sudo install -vd /var/www/html/zonemaster-web-gui
sudo install -vd /var/log/zonemaster
sudo unzip -d /var/www/html/zonemaster-web-gui zonemaster_web_gui.zip
rm -f zonemaster_web_gui.zip

Configure Apache site

sudo chcon -R -t httpd_sys_content_t /var/www/html/zonemaster-web-gui/dist
sudo chcon -R -t httpd_sys_rw_content_t /var/log/zonemaster
sudo setsebool -P httpd_can_network_connect=1
sudo install -v /var/www/html/zonemaster-web-gui/zonemaster.conf-example /etc/httpd/conf.d/zonemaster.conf

Optionally update the zonemaster.conf. E.g. if Zonemaster-Backend RPCAPI runs on another server or on another port (not port 5000), update ProxyPass and ProxyPassReserve. Or if you want provide your own settings for ServerName, ServerAlias and ServerAdmin.

sudoedit /etc/httpd/conf.d/zonemaster.conf

Start Apache and allow remote access

sudo systemctl enable httpd
sudo systemctl start httpd
sudo firewall-cmd --add-service http --permanent
sudo firewall-cmd --reload

2. Debian and Ubuntu

Install Apache

sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y apache2 unzip

Basic Apache configuration

sudo a2enmod proxy proxy_http rewrite
sudo a2dissite 000-default
sudo systemctl enable apache2
sudo systemctl restart apache2

Install Zonemaster Web GUI

wget https://github.com/zonemaster/zonemaster-gui/releases/download/v4.3.1/zonemaster_web_gui.zip -O zonemaster_web_gui.zip
sudo unzip -d /var/www/html/zonemaster-web-gui zonemaster_web_gui.zip
sudo install -vd /var/log/zonemaster
sudo install -v /var/www/html/zonemaster-web-gui/zonemaster.conf-example /etc/apache2/sites-available/zonemaster.conf
rm -f zonemaster_web_gui.zip

Configure Zonemaster Web GUI

sudo a2ensite zonemaster #Activate the website

Then update the zonemaster.conf file with your own ServerName, ServerAlias and ServerAdmin. For testing on a local machine, you can edit zonemaster.conf and change the "*:80" part of to the host's IP or using localhost as ServerName if that is appropriate.

Reload Apache

sudo systemctl reload apache2

3. FreeBSD

For all commands below become root:

su -l

Update list of package repositories

Create the file /usr/local/etc/pkg/repos/FreeBSD.conf with the following content, unless it is already updated:

FreeBSD: {
url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
}

Check or activate the package system

Run the following command, and accept the installation of the pkg package if suggested.

pkg info -E pkg

Update local package repository:

pkg update -f

Install Apache and its dependencies

See tutorial on Apache on FreeBSD.

pkg install apache24

Enable Apache as a service

sysrc apache24_enable=yes

Enable three apache modules in Apache configuration file

perl -pi -e 's/^#(LoadModule (proxy_module|proxy_http_module|rewrite_module) libexec)/$1/' /usr/local/etc/apache24/httpd.conf

Start Apache

service apache24 start

If you want Apache to listen to an external IP address and it says that it only listens to localhost (127.0.0.1/::1) then you have to set ServerName in /usr/local/etc/apache24/httpd.conf, e.g. ServerName 192.0.2.246:80, and restart Apache.

Install Zonemaster Web GUI

fetch https://github.com/zonemaster/zonemaster-gui/releases/download/v4.3.1/zonemaster_web_gui.zip
mkdir -p /var/www/html/zonemaster-web-gui
mkdir -p /var/log/zonemaster
unzip -d /var/www/html/zonemaster-web-gui zonemaster_web_gui.zip
rm zonemaster_web_gui.zip

Basic Apache configuration

install /var/www/html/zonemaster-web-gui/zonemaster.conf-example /usr/local/etc/apache24/Includes/zonemaster.conf

Then update /usr/local/etc/apache24/Includes/zonemaster.conf with your own ServerAdmin. If Zonemaster-Backend RPCAPI runs on another server or on another port (not port 5000) then update the URL for the ProxyPass and ProxyPassReverse keys in the same file so that it points to correct IP address or server name and correct port.

Restart Apache

service apache24 restart

Post-installation sanity check

Make sure Zonemaster-GUI is properly installed.

1. Point your browser at http://localhost/ (or the address of the server where you installed Zonemaster Web GUI).

2. Verify that the Zonemaster Web GUI is shown with the text "Program versions" in its page footer.

3. Verify that when you mouse over this text the versions of the following Zonemaster components are shown: Zonemaster-LDNS, Zonemaster-Engine, Zonemaster-Backend and Zonemaster-GUI.

What to do next?

• For a JSON-RPC API, see the Zonemaster::Backend JSON-RPC API documentation.
• For a command line interface, follow the Zonemaster::CLI installation instruction.
• For a Perl API, see the Zonemaster::Engine API documentation.
• For HTTPS, see Let's Encrypt / Certbot.

Serving the GUI and API from a custom base url

In some cases you may want to customize the application to change the base URL from wich the GUI is served.

1. In the index.html files, (/var/www/html/zonemaster-web-gui/dist/*/index.html if you followed this installation guide), locate the line <base href="/"> and replace the href value with the path you want to server the GUI from. You can use the following command to update the base URL in all files:

   export BASE_URL=/zonemaster; find /var/www/html/zonemaster-web-gui/dist -name index.html | xargs sed -r "s%<base href=\"[^\"]*/([a-z]{2})/\">%<base href=\"$BASE_URL/\1/\">%" -i
   

   You can change the BASE_URL variable to the path (without trailing slash) that you want.

2. When serving the application from a different base, you will also need to change the Web server configuration in zonemaster.conf (location is found in the installation instructions above) by updating the BASE_URL variable and adding an Alias directive as in the following example:

   Define BASE_URL "/zonemaster/"
   
   Alias "/zonemaster" "/var/www/html/zonemaster-web-gui/dist"
   

3. Update or create app.config.json ( /var/www/html/zonemaster-web-gui/dist/assets/app.config.json in a default installation) by setting apiEndpoint to /zonemaster/api as below. See Configuration.md and the example configuration app.config.sample.json.

   {
      "apiEndpoint": "/zonemaster/api"
   }
   

4. Reload Apache.

5. Point you browser to the new base URL.

NOTE: Don't forget to apply the changes to the index.html and Web server configuration after each update as those files will be overwritten.

Change default language

To change the default language update the Apache configuration in zonemaster.conf that was installed in a previous section. Locate the last RewriteRule:

# Default locale
RewriteRule ^$ /en/ [R,L]

and change it to

# Default locale
RewriteRule ^$ /<LANG>/ [R,L]

where <LANG> is the language code of you choice.

Docker

Zonemaster-CLI is available on Docker Hub, and can be conveniently downloaded and run without any installation. Through Docker Zonemaster-CLI can be run on Linux, macOS and Windows. See USING Zonemaster-CLI for how to run Zonemaster-CLI on Docker.

To build your own Docker image, see the Docker Image Creation documentation.

Upgrading

Upgrading Zonemaster is usually a straightforward process. The only component that may require manual intervention is Zonemaster-Backend. See the instructions on upgrading Zonemaster-Backend for more information.

For other components, simply re-run the installation steps to get the updated version.

Upgrade Backend

1. Overview

This document contains pointer to instructions on how to upgrade the Zonemaster::Backend component. An upgrade usually consist of an upgrade script to upgrade the database, and instructions to install new dependencies.

When upgrading from a version < v6.2.0 to a version ≥ v8.0.0, it is recommended to install the desired version following the Installation instructions skipping the part about the database if you want to keep it. To upgrade the database, apply each upgrade instructions one after another (see table below).

2. Prerequisites

Upgrade Zonemaster::LDNS and Zonemaster::Engine first following instructions within the Zonemaster::Engine installation document.

3. Upgrading Zonemaster::Backend

To upgrade Zonemaster::Backend perform the following tasks:

1. stop the zm-rpcapi and zm-testagent daemons (zm_rpcapi and zm_testagent on FreeBSD)
2. remove old files with cpanm --uninstall Zonemaster::Backend
3. install any new dependencies (see corresponding upgrade document below)
4. install the latest version from CPAN with cpanm Zonemaster::Backend
5. apply any remaining instructions specific to this new release
6. start the zm-rpcapi and zm-testagent daemons (zm_rpcapi and zm_testagent on FreeBSD)

Specific upgrade instructions

Always make a backup of the database before upgrading it.

When upgrading Zonemaster::Backend, it might be needed to upgrade the database and/or install new dependencies. Such instructions are available in the upgrade document coming with the release. See table below to refer to the right document.

When upgrading from an older version than the previous release, apply each upgrade instructions one after another.

4. Find current version

The following command will report the version of Zonemaster-Backend currently installed. If an error is report Zonemaster-Backend is not installed or not available for the user. If so, consider tunning the command as root or with sudo.

perl -E 'use Zonemaster::Backend; say $Zonemaster::Backend::VERSION;'

Upgrade to 1.0.3

Upgrading the database

If your Zonemaster database was created by a Zonemaster-Backend version smaller than v1.0.3, and not upgraded, use the following instructions.

FreeBSD

If the installation is on FreeBSD, then the environment maybe has to be set before running any of the commands below. Check where backend_config.ini is located.

export ZONEMASTER_BACKEND_CONFIG_FILE="/usr/local/etc/zonemaster/backend_config.ini"

MySQL

Run

cd $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')
perl patch/patch_mysql_db_zonemaster_backend_ver_1.0.3.pl

PostgreSQL

Run

cd $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')
perl patch/patch_postgresql_db_zonemaster_backend_ver_1.0.3.pl

Upgrade to 1.1.0

Upgrading the database

If your Zonemaster database was created by a Zonemaster-Backend version smaller than v1.1.0, and not upgraded, use the following instructions.

MySQL

  ALTER TABLE test_results ADD queue INTEGER DEFAULT 0;

PostgreSQL

  ALTER TABLE test_results ADD queue INTEGER DEFAULT 0;

Upgrade to 5.0.0

Upgrading the database

If your Zonemaster database was created by a Zonemaster-Backend version smaller than v5.0.0, and not upgraded, use the following instructions.

FreeBSD

If the installation is on FreeBSD, then set the environment before running any of the commands below:

export ZONEMASTER_BACKEND_CONFIG_FILE="/usr/local/etc/zonemaster/backend_config.ini"

MySQL (or MariaDB)

Run

cd $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')
perl patch/patch_mysql_db_zonemaster_backend_ver_5.0.0.pl

PostgreSQL

Run

cd $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')
perl patch/patch_postgresql_db_zonemaster_backend_ver_5.0.0.pl

Upgrade to 5.0.2

Upgrading the database

If your Zonemaster database was created by a Zonemaster-Backend version smaller than v5.0.2, and not upgraded, use the following instructions.

FreeBSD

If the installation is on FreeBSD, then set the environment before running any of the commands below:

export ZONEMASTER_BACKEND_CONFIG_FILE="/usr/local/etc/zonemaster/backend_config.ini"

MySQL (or MariaDB)

Run

cd $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')
perl patch/patch_mysql_db_zonemaster_backend_ver_5.0.2.pl

PostgreSQL

No patching (upgrading) is needed on zonemaster database on PostgreSQL for this version of Zonemaster-Backend.

Upgrade to 8.0.0

On FreeBSD run the following command first to become root:

su -l

New dependencies

Zonemaster::Backend requires new dependencies. Depending on the used OS, run the corresponding command.

Rocky Linux

sudo dnf install perl-libintl perl-Mojolicious

sudo cpanm Plack::Middleware::ReverseProxy

Debian / Ubuntu

sudo apt-get install libplack-middleware-reverseproxy-perl libintl-perl libmojolicious-perl

Specific to Ubuntu

sudo cpanm JSON::Validator

FreeBSD

pkg install p5-Plack-Middleware-ReverseProxy p5-Locale-libintl p5-Mojolicious

Changes in the ini file

New sections and properties have been added to the backend_config.ini file. By default the add_api_user method is disabled. To enable it, add the following to your backend_config.ini file:

[RPCAPI]
enable_add_api_user = yes

See the Configuration document for more information.

Upgrading init scripts

The zm-rpcapi (zm_rpcapi on FreeBSD) init script has been updated. It needs to be reinstalled.

Rocky Linux

cd `perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")'`
sudo install -v -m 755 ./zm-rpcapi.lsb /etc/init.d/zm-rpcapi

Debian / Ubuntu

cd `perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")'`
sudo install -v -m 755 ./zm-rpcapi.lsb /etc/init.d/zm-rpcapi

FreeBSD

cd `perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")'`
install -v -m 755 ./zm_rpcapi-bsd /usr/local/etc/rc.d/zm_rpcapi

Upgrading the database

If your Zonemaster database was created by a Zonemaster-Backend version smaller than v8.0.0, and not upgraded, use the following instructions.

Depending on the database size this upgrade can take some time (around 30 minutes for a database with 1 million entries)

You may need to run the command with sudo.

SQLite

Run

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
perl patch/patch_sqlite_db_zonemaster_backend_ver_8.0.0.pl

MySQL (or MariaDB)

First update the privileges of the zonemaster user:

• Linux

  sudo mysql -e "GRANT ALL ON zonemaster.* TO 'zonemaster'@'localhost';"
  

• FreeBSD

  mysql -u root -p -e "GRANT ALL ON zonemaster.* TO 'zonemaster'@'localhost';"
  

then run

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
perl patch/patch_mysql_db_zonemaster_backend_ver_8.0.0.pl

PostgreSQL

Run

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
perl patch/patch_postgresql_db_zonemaster_backend_ver_8.0.0.pl

Upgrade to 9.0.0

Upgrading the database

If your Zonemaster database was created by a Zonemaster-Backend version smaller than v9.0.0, and not upgraded, use the following instruction.

You may need to run these command with root privileges.

Preparation when using MariaDB

If you're using MariaDB you need to make a backup of your database before upgrading its schema.

mysqldump zonemaster > backup-file.sql

In case the schema upgrade fails you may need to restore the backup before trying again.

mysql zonemaster < backup-file.sql

Upgrade database schema

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
perl patch/patch_db_zonemaster_backend_ver_9.0.0.pl

Upgrade to 11.1.0

Upgrading the database

If your Zonemaster database was created by a Zonemaster-Backend version smaller than v11.1.0, and not upgraded, use the following instruction.

You may need to run these command with root privileges.

Warning: this database update will result in an increase of the used size. Make sure you have enough free disk space before upgrading. Depending on the database engine, you may need up to 5 times the database size of free space.

Upgrade database schema

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
perl patch/patch_db_zonemaster_backend_ver_11.1.0.pl

Upgrade to 11.2.0

Upgrading the database

If your Zonemaster database was created by a Zonemaster-Backend version smaller than v11.2.0, and not upgraded, use the following instructions.

You may need to run these command with root privileges.

Migration script

The following script fixes existing untranslated entries that were missed between Zonemaster-Backend v11.1.0 (release v2023.2) and this version (release v2024.1).

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
perl patch/patch_db_zonemaster_backend_ver_11.2.0.pl

Configuration

This section contains information about configuration of the different components of Zonemaster:

• Setting up or modifying the profile in Zonemaster-Engine.
• Enabling the global cache feature (experimental)
• Configuring Zonemaster-Backend in the Backend configuration file.
• Using environment variables for Zonemaster-Backend.
• Configuring Zonemaster-GUI in the GUI configuration file.

Profiles

Default profile

The default profile is documented in the profile properties section of the Zonemaster::Engine::Profile module.

The default profile can be extracted from Zonemaster-Engine to a file using this command.

perl -MZonemaster::Engine::Test -E 'say Zonemaster::Engine::Profile->default->to_json' | jq -S . > profile.json

Creating profiles

Some properties are empty by default such as logfilter and test_cases_vars. Those properties are not present in the default profile. For an example of their usage, refer to the additional file, profile_additional_properties.json.

The content of the two files, as-is or modified, can be merged into a custom profile file that can be loaded by Zonemaster-Engine. Both Zonemaster-CLI and Zonemaster-Backend have direct options for loading a custom profile file.

A custom profile file only has to contain those properties that it should override.

Configuration: Global cache in Zonemaster-Engine

Table of contents

• Introduction
• Prerequisites
• Installation for global cache
• Create directory for custom profile
• Enable global cache
• Using global cache

Introduction

Global cache is a feature that can increase performance when many tests are run within a short time frame, especially when they share some data such as using the same name server names. The global cache is meant for batch testing rather than single tests through the GUI. In the latter case it is desirable that Zonemaster checks again since the zone may have been corrected due to the report in a very recent test.

The global cache improves the caching function by making the DNS lookups from one test to be available for further tests. The cache is stored in Redis, a cache service running in a separate daemon.

To enable global caching, additional software has to be installed and custom profile has to be created, where global caching is enabled.

Prerequisites

Before installing or enabling global cache you must follow the Zonemaster::Engine installation first. The feature is available from version v5.0.0 of Zonemaster-Engine.

For installation on FreeBSD being user root is assumed.

Installation for global cache

Install the Redis daemon and needed Perl library. And then start the Redis daemon. It will listen to localhost and default port.

Rocky Linux

sudo dnf --assumeyes install redis perl-Redis perl-Data-MessagePack
sudo systemctl enable redis
sudo systemctl start redis

Debian and Ubuntu

sudo apt install redis libredis-perl libdata-messagepack-perl
sudo systemctl enable redis
sudo systemctl start redis

FreeBSD

pkg install -y redis p5-Redis p5-Data-MessagePack
sysrc redis_enable="YES"
service redis start

Create directory for custom profile

Create a directory to be used for a custom profile, which is here the same directory as used by Zonemaster-Backend. And then copy the default profile to this directory.

Rocky Linux, Debian and Ubuntu

test -d /etc/zonemaster || sudo mkdir -v /etc/zonemaster
perl -MZonemaster::Engine::Test -E 'say Zonemaster::Engine::Profile->default->to_json' | jq -S . | sudo tee /etc/zonemaster/profile.json > /dev/null

FreeBSD

test -d /usr/local/etc/zonemaster || mkdir -v /usr/local/etc/zonemaster
perl -MZonemaster::Engine::Test -E 'say Zonemaster::Engine::Profile->default->to_json' | jq -S . > /usr/local/etc/zonemaster/profile.json

Enable global cache

Update /etc/zonemaster/profile.json (or /usr/local/etc/zonemaster/profile.json for FreeBSD) by adding a cache section. If the profile already has an empty cache section (i.e. "cache": {}) then it must be removed. Add the following section,

    "cache": {
        "redis": {
            "server": "127.0.0.1:6379",
            "expire": 7200
        }
    },

The expire value can be increased or decreased to increase or decrease the time in seconds that Redis will cache the data. Caching of specific DNS data is never longer than the normal DNS TTL value.

Using global cache

If Zonemaster-CLI has been installed, then run zonemaster-cli with --profile /etc/zonemaster/profile.json (or --profile /usr/local/etc/zonemaster/profile.json for FreeBSD) to use the global cache. Caching will persist between test unless it has expired.

See man zonemaster-cli and look for cli.args for how to make it the custom profile being the default profile for zonemaster-cli.

See Zonemaster::Backend configuration for how to make the custom profile being used for Zonemaster-Backend and Zonemaster-GUI.

For more documentation on profiles, see profile documentation.

Configuration

Table of contents

• Introduction
• RPCAPI section
  • enable_batch_create
  • enable_user_create
  • enable_add_batch_job
  • enable_add_api_user
• DB section
  • engine
  • polling_interval
• MYSQL section
  • host
  • port
  • user
  • password
  • database
• POSTGRESQL section
  • host
  • port
  • user
  • password
  • database
• SQLITE section
  • database_file
• LANGUAGE section
  • locale
• METRICS section
  • statsd_host
  • statsd_port
• PUBLIC PROFILES and PRIVATE PROFILES sections
• ZONEMASTER section
  • max_zonemaster_execution_time
  • number_of_processes_for_frontend_testing
  • number_of_processes_for_batch_testing
  • lock_on_queue
  • age_reuse_previous_test

Introduction

Zonemaster Backend is configured in /etc/zonemaster/backend_config.ini (Linux) or /usr/local/etc/zonemaster/backend_config.ini (FreeBSD). Following Installation instructions will create the file with factory settings.

Restart the zm-rpcapi and zm-testagent daemons to load the changes made to the backend_config.ini file.

The backend_config.ini file uses a file format in the INI family that is described in detail here. Repeating a key name in one section is forbidden.

Each section in backend_config.ini is documented below.

In addition to the configuration file, some settings can configured using environment variables.

RPCAPI section

Available keys: enable_batch_create, enable_user_create, enable_add_batch_job, enable_add_api_user.

enable_add_batch_job

Boolean value to enable the add_batch_job and batch_create methods of the API.

Accepted values: yes (or true) or no (or false), default to yes (enabled).

enable_add_api_user

Boolean value to enable the add_api_user and user_create method of the API.

Accepted values: yes (or true) or no (or false), default to no (disabled).

enable_batch_create

An experimental alias for enable_add_batch_job.

enable_user_create

An experimental alias for enable_add_api_user.

DB section

Available keys : engine, user, password, database_name, database_host, polling_interval.

engine

Specifies what database engine to use.

The value must be one of the following, case-insensitively: MySQL, PostgreSQL and SQLite.

This table declares what value to use for each supported database engine.

polling_interval

A strictly positive decimal number. Max 5 and 3 digits in the integer and fraction components respectively.

Time in seconds between database lookups by Test Agent. Default value: 0.5.

MYSQL section

Available keys : host, port, user, password, database.

host

An LDH domain name or IP address.

The host name of the machine on which the MySQL server is running.

port

The port the MySQL server is listening on. Default value: 3306.

If MYSQL.host is set to localhost (but neither 127.0.0.1 nor ::1), then the value of the MYSQL.port property is discarded as the driver connects using a UNIX socket (see the DBD::mysql documentation).

user

An ASCII-only MariaDB unquoted identifier. Max length 80 characters.

The name of the user with sufficient permission to access the database.

password

A string of US ASCII printable characters. The first character must be neither space nor <. Max length 100 characters.

The password of the configured user.

database

A US ASCII-only MariaDB unquoted identifier. Max length 64 characters.

The name of the database to use.

POSTGRESQL section

Available keys : host, port, user, password, database.

host

An LDH domain name or IP address.

The host name of the machine on which the PostgreSQL server is running.

port

The port the PostgreSQL server is listening on. Default value: 5432.

user

A US ASCII-only PostgreSQL identifier. Max length 63 characters.

The name of the user with sufficient permission to access the database.

password

A string of US ASCII printable characters. The first character must be neither space nor <. Max length 100 characters.

The password of the configured user.

database

A US ASCII-only PostgreSQL identifier. Max length 63 characters.

The name of the database to use.

SQLITE section

Available keys : database_file.

database_file

An absolute path.

The full path to the SQLite main database file.

LANGUAGE section

The LANGUAGE section has one key, locale.

locale

A string representing a space-separated list of one or more locale tags. Each tag consists of a two-lowercase-letter language code, an underscore character, and a two-uppercase-letter country code (i.e. it matches the regular expression /^[a-z]{2}_[A-Z]{2}$/). Each locale tag must have a unique language code.

Default value: en_US.

Design

The language code of a locale tag is intended to be an ISO 639-1 code. The country code is intended to be an ISO 3166-1 alpha-2 code. A locale tag is a locale setting for the available translation of messages without ".UTF-8", which is implied.

Usage

Removing a language from the configuration file just blocks that language from being allowed.

English is the Zonemaster default language, but it can be blocked from being allowed by RPC-API by including some locale tag in the configuration, but none starting with language code for English ("en").

Out-of-the-box support

The default installation and configuration supports the following languages.

Setting in the default configuration file:

locale = da_DK en_US es_ES fi_FI fr_FR nb_NO sv_SE

Installation considerations

If a new locale tag is added to the configuration then the equivalent MO file should be added to Zonemaster-Engine at the correct place so that gettext can retrieve it, or else the added locale tag will not add any actual language support. The MO file should be created for the language code of the locale tag (see the table above), not the entire locale tag. E.g. if the locale configuration key includes "sv_SE" then a MO file for "sv" should be included in the installation.

Use of MO files based on the entire locale tag is deprecated.

See the Zonemaster-Engine share directory for the existing PO files that are converted to MO files during installation. (Here we should have a link to documentation instead.)

Each locale set in the configuration file, including the implied ".UTF-8", must also be installed or activate on the system running the RPCAPI daemon for the translation to work correctly.

METRICS section

statsd_host

An LDH domain name or IP address.

The host name of the machine on which the StatsD receiver is running.

Leave unspecified to disable the metrics.

Note that this feature requires the Net::Statsd module to be installed.

statsd_port

The port the StatsD receiver is listening on. Default value: 8125.

PUBLIC PROFILES and PRIVATE PROFILES sections

The PUBLIC PROFILES and PRIVATE PROFILES sections together define the available profiles.

Keys in both sections are profile names, and values are absolute file system paths to profile JSON files. The key must conform to the character limitation specified for profile name as specified in the API document Profile name section. Keys that only differ in case are considered to be equal. Keys must not be duplicated between or within the sections, and the key default must not be present in the PRIVATE PROFILES section.

There is a default profile that is special. It is always available even if not specified. If it is not explicitly mapped to a profile JSON file, it is implicitly mapped to the Zonemaster Engine default profile.

Each profile JSON file contains a (possibly empty) set of overrides to the Zonemaster Engine default profile. Specifying a profile JSON file that contains a complete set of profile data is equivalent to specifying a profile JSON file with only the parts that differ from the Zonemaster Engine default profile.

Specifying a profile JSON file that contains no profile data is equivalent to specifying a profile JSON file containing the entire Zonemaster Engine default profile.

ZONEMASTER section

The ZONEMASTER section has several keys :

• max_zonemaster_execution_time
• number_of_processes_for_frontend_testing
• number_of_processes_for_batch_testing
• lock_on_queue
• age_reuse_previous_test

max_zonemaster_execution_time

A strictly positive integer. Max length 5 digits.

Time in seconds before reporting an unfinished test as failed. Default value: 600.

number_of_processes_for_frontend_testing

A strictly positive integer. Max length 5 digits.

Number of processes allowed to run in parallel (added with number_of_processes_for_batch_testing). Default value: 20.

Despite its name, this key does not limit the number of process used by the frontend, but is used in combination of number_of_processes_for_batch_testing.

number_of_processes_for_batch_testing

A non-negative integer. Max length 5 digits.

Number of processes allowed to run in parallel (added with number_of_processes_for_frontend_testing). Default value: 20.

Despite its name, this key does not limit the number of process used by any batch pool of tests, but is used in combination of number_of_processes_for_frontend_testing.

lock_on_queue

A non-negative integer. Max length 5 digits.

A label to associate a test to a specific Test Agent. Default value: 0.

age_reuse_previous_test

A strictly positive integer. Max length 5 digits.

The shelf life of a test in seconds after its creation. Default value: 600.

If a new test is requested for the same zone name and parameters within the shelf life of a previous test result, that test result is reused. Otherwise a new test request is enqueued.

Environment variables

Variable used by both RPCAPI daemon and Test Agent daemon

• ZONEMASTER_BACKEND_CONFIG_FILE: Set a custom path for the backend configuration file.

Variables used by RPCAPI daemon only

• ZM_BACKEND_RPCAPI_LOGLEVEL: Configure the log level, trace by default. Accepted values are:
  • trace
  • debug
  • info (also accepted: inform)
  • notice
  • warning (also accepted: warn)
  • error (also accepted: err)
  • critical (also accepted: crit, fatal)
  • alert
  • emergency
• ZM_BACKEND_RPCAPI_LOGJSON: Setting it to any thruthy value (non-empty string or non-zero number) will configure the logger to log in JSON format, undefined by default.

Variables used by unit test scripts

• TARGET: Set the database to use. If empty or undefined, "SQLite" will be assumed. Accepted values are:

  • SQLite
  • PostgreSQL
  • MySQL

• ZONEMASTER_RECORD: Setting it to any thruthy value (non-empty string or non-zero number) will record the data from the test to a file. Otherwise the data is loaded from a file.

Configuration

The GUI can be configured by creating the file DISTBASE/dist/assets/app.config.json. "DISTBASE" is where the Zonemaster Web GUI zip file is installed, which is /var/www/html/zonemaster-web-gui by default installation (see Installation instructions).

This file can by created by copying app.config.sample.json found in DISTBASE/dist/assets:

cp app.config.sample.json app.config.json

The supported configuration items are the following.

• "apiEndpoint": The URL to use to contact the API, default "/api". It could be either a full URL to use an API endpoint not located on the same origin as the one serving the GUI or just a path, like the default value, when both the API and GUI are served from the same origin.
• "defaultLanguage": (Deprecated) This does not work anymore, to change the default language update the Apache configuration as mentioned in the installation instructions.
• "enabledLanguages": An array of the languages enabled in the GUI, default [ "da", "en", "es", "fi", "fr", "nb", "sv" ].
• "contactAddress": The contact email address displayed in the footer, default "contact@zonemaster.net".
• "logoUrl": The URL to the image displayed in the navigation bar, default "assets/images/zonemaster_logo_2021_color.png".
• "msgBanner": A message to display to the user, if empty or undefined no banner will be shown. HTML formatting is supported (such as <a> tag) and some characters such as &>< need to be written as HTML codes to be properly rendered.
• "pollingInterval": Time between each test progress query in millisecond, default: 5000 (5 seconds).
• "footerLogo": Optional logotype in the footer, default none (""), but else path to file.
• "footerLogoAlt": Optional alternative text for the "footerLogo", only meaningful if "footerLogo" is defined. Typical "footerLogoAlt" is the name in "footerLogo".

Zonemaster users guide

The purpose of the Zonemaster project is to develop a DNS validation software. There are three ways one can use the Zonemaster software:

• Using the Web user Interface: In this case, there is no installation of the Zonemaster software needed. A user types the URL https://zonemaster.net, provides as input a domain name, and then can view the results.
• From the Command Line Interface (CLI): In this case, the user has to install two components of the Zonemaster software, i.e. the Zonemaster-Engine and the Zonemaster-CLI.
• There are cases, wherein an organisation or a user, that wants to have the results of their DNS validation stored and can be viewed later. In that case, in addition to the Zonemaster-Engine and Zonemaster-CLI, the user has to install the Zonemaster-Backend and the Zonemaster-GUI.

User guides:

• Use Zonemaster-CLI
• Use Zonemaster Backend
• Use Zonemaster-GUI

Using the CLI

Table of contents

• Docker or local installation
• Invoking the command line tool using Docker
• Invoking the command line tool using local installation
• More details on the command line tool invocation
• Test reports
• Translation
• Advanced use
• Docker on Mac with M1 chip

Docker or local installation

The zonemaster-cli tool can be run from the command line of any computer that meets one of the following requirements:

• Docker is installed on the computer, or
• Zonemaster-CLI has been installed on the computer.

Using Docker

To run Zonemaster-CLI on Docker you have to make sure that Docker is installed on the computer and that you can run Docker on it.

• Instructions for installation are found on Docker get started page.
• Run the command docker ps on the command line to verify that you can run Docker on the computer.

When Docker has been correctly installed, no more installation is needed to run zonemaster-cli. Just follow the examples below.

There is a limitation in Docker regarding IPv6. Unless IPv6 has been enabled in the Docker daemon, there is no support for IPv6. To avoid meaningless errors, use --no-ipv6 if there is no IPv6 support. Also see "Enable IPv6 support".

Local installation

To have an local installation of Zonemaster-CLI follow the installation instruction. When installed, the examples below can be followed.

If the network has no IPv6 support (common in home networks) then turn off IPv6. Use --no-ipv6 to avoid meaningless errors if there is no IPv6 support.

Invoking the command line tool using Docker

The most basic use of the zonemaster-cli command is to just test a domain, e.g. "zonemaster.net".

docker run -t --rm zonemaster/cli zonemaster.net --no-ipv6

or

docker run -t --rm zonemaster/cli zonemaster.net

To make sure that Docker uses the latest version, add --pull always, e.g.

docker run -t --rm --pull always zonemaster/cli zonemaster.net --no-ipv6

If --pull always is skipped, the invocation is quicker. The recommendation is to include --pull always in the first command of a session to make sure latest version is used, and then to exclude it to improve performance.

Invoking the command line tool using local installation

The most basic use of the zonemaster-cli command is to just test a domain, e.g. "zonemaster.net".

zonemaster-cli zonemaster.net

or

zonemaster-cli zonemaster.net --no-ipv6

More details on the command line tool invocation

The output of any of the commands above comes continuously as the tests (test cases) are performed.

Seconds Level     Message
======= ========= =======
  21.39 WARNING   The DNSKEY with tag 54636 uses an algorithm number 5 (RSA/SHA1) which is not recommended to be used.
  21.80 WARNING   DNSKEY with tag 26280 and using algorithm 5 (RSA/SHA1) has a size (1024) smaller than the recommended one (2048).
  23.61 NOTICE    SOA 'refresh' value (10800) is less than the recommended one (14400).

The test and output can be modified with different options:

• If your machine is not configured for use with IPv6 you want to disable the use of IPv6 with the --no-ipv6 option.
• If you want to have the test case from which the message is printed then include the --show-testcase option.
• If you want to see the messages translated into another language (see "Translation" section below) then include e.g. --locale da (Docker) or --locale da_DK.UTF-8 (local installation).

The same test as above with the three options included:

docker run -t --rm zonemaster/cli zonemaster.net --no-ipv6 --show-testcase --locale=da

zonemaster-cli zonemaster.net --no-ipv6 --show-testcase --locale=da_DK.UTF-8

To get brief descriptions of a selection of the most important command line options run:

zonemaster-cli --help

For complete reference documentation, see the manual page. This includes an exhaustive list of options and in-depth documentation for each one, as well as examples and additional context.

man zonemaster-cli

Using Docker or local installation

The difference between running zonemaster-cli on Docker or local installation is the invocation string, docker run -t --rm zonemaster/cli vs. zonemaster-cli. To simplify this document, from now on the shorter zonemaster-cli will be used and for Docker the longer string will be assumed. To simplify repeated invocation on Docker an alias can be created for the shell.

Test reports

The severity level of the different messages is CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG, DEBUG2 or DEBUG3. The default reporting level is NOTICE and higher. To change the level of reporting you can use a command line option, e.g --level=INFO includes level INFO and higher in the report. See "Severity Level Definitions" for more information on the levels.

By default the output is formatted as plain text in English (or some other language), but other more "technical" output formats are also available with options --raw and json, respectively.

Translation

In Docker

By default all messages are in English. By using the --locale=LANG option another language can be selected. Select "LANG" from the table below to have Zonemaster translated into that language.

E.g.:

docker run -t --rm zonemaster/cli zonemaster.net --locale=da

An alternative is to set the LC_ALL environment variable with correct language value when the command is invoked, which can be useful if a shell alias is created. E.g.

docker run -e LC_ALL=da -t --rm zonemaster/cli zonemaster.net

If environment variable LC_ALL is set in the local shell with the correct "LANG" or with the equivalent "LOCALE" in from next section, then the following command will export LC_ALL with the that value to the docker container.

docker run -e LC_ALL -t --rm zonemaster/cli zonemaster.net

Environment variables LANG and LC_MESSAGES can be used in the same way as LC_ALL.

In local installation

By default all messages are in the language set in the local environment (if available in Zonemaster) or else in English. By using the --locale=LOCALE option another language can be selected. Select "LOCALE" from the table below to have Zonemaster translated into that language.

E.g.:

docker run -t --rm zonemaster/cli zonemaster.net --locale=da_DK.UTF-8

If the environment variable LANGUAGE is set with correct LOCALE then no option is needed, e.g. LANGUAGE=da_DK.UTF-8. zonemaster-cli also respects LC_ALL, LC_MESSAGES and LANG. LANGUAGE takes precedence over the other, and then the order is LC_ALL, LC_MESSAGES and last LANG.

Advanced use

There are some nice features available that can be of some use for advanced users.

Only run specific test cases

If you only want to run a specific test case rather than the whole suite of tests, you can do that as well. E.g. test only test case Connectivity03:

zonemaster-cli --test Connectivity/connectivity03 example.com

Or all test case in the Connectivity test level:

zonemaster-cli --test Connectivity example.com

For more information on the available tests, you can list them right from the command line tool:

zonemaster-cli --list_tests

Use custom root hints

You can override the built-in list of root servers that zonemaster-cli uses by providing a path to a custom root hints file with the --hints HINTS-FILE option. For example:

zonemaster-cli --hints /path/to/custom.hints example.com

If you are running zonemaster-cli using Docker, you must mount your custom root hints file inside the container using a volume so that zonemaster-cli can access it, like so:

docker run -t --rm \
    -v /path/to/custom.hints:/hints \
    zonemaster/cli --hints /hints example.com

Undelegated test

Before you do any delegation change at the parent, either changing the NS records, glue address records or DS records, you might want to perform a check of your new child zone configuration so that everything you plan to change is in order. Zonemaster can do this for you. All you have to do is give Zonemaster all the parent data you plan to have for your new configuration. Any DNS lookups going for the parent will instead be answered by the data you entered. E.g.

zonemaster-cli --ns ns1.example.com/192.168.23.23 \
  --ns ns2.example.com/192.168.24.24 \
  --ds 12345,3,1,123456789abcdef67890123456789abcdef67890

Any number of NS records and DS records can be given multiple times. The syntax of the NS records is name/address, and the address can be both IPv4 and IPv6. The DS syntax is keytag,algorithm,type,digest.

You can also choose to do a undelegated test using only the new DS record, but keep the NS records from the parent by only specifying the DS record and no NS records on the command line.

Docker on Mac with M1 chip

If you run the Docker commands above on a Mac computer with the M1 chip, then you will get the following warning:

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

The warning says that the image is created for Intel/AMD64 architecture, and that is not what your computer has. To get rid of the warning, add --platform linux/amd64 to docker run, e.g.

docker run --platform linux/amd64 -t --rm zonemaster/cli zonemaster.net --no-ipv6

If you search for the error messages you will get suggestions for how to automatically include the --platform linux/amd64 option every time you run docker run.

Using the Backend

• Using Zonemaster-Backend JSON-RPC API
• Using Zonemaster-Backend for batch testing
• RPCAPI reference
• Collecting metrics

Using Zonemaster-Backend JSON-RPC API

Table of contents

• Introduction
• Check that the RPC API daemon is running and answering properly
• Run a test of the zonemaster.net zone using zmtest
• Run a test of the zonemaster.net zone using zmb
  • Enqueue a test
  • Check the progress
  • Fetch the results
• Find available languages
• Find previous tests
• Other APIs
• IDN domain names
• Using curl instead

Introduction

This is a guide for getting started with the Zonemaster JSON-RPC API service (running as a daemon).

Note that this guide makes a number of assumptions about your setup:

• That it is a Unix-like environment.
• That you have Zonemaster-Backend installed according to the installation guide
• That Zonemaster-Backend is running. See installation guide for how to start Zonemaster-Backend.
• If you have changed IP address (default 127.0.0.1) or port (default 5000) then you must specify that in the commands below. Here we assume default.

For this guide we will use the two Zonemaster-Backend tools zmb and zmtest. Both are installed when Zonemaster-Backend is installed. To get more information what parameters they expect, run zmb -h and zmtest -h.

With zmtest you can start a domain test and get the result directly. With zmb you can also do that, but in several steps, but on the other hand, zmb offers many more possibilities. Actually, zmtest uses zmb behind the scen.

The zmb tool uses the JSON-RPC API to interact with Zonemaster-Backend. Zonemaster-GUI also uses the same JSON-RPC API to start tests and fetch the test results.

Check that the JSON-RPC API service is running and answering properly

zmb version_info

To get a more readable output, pipe the command through jq:

zmb version_info | jq

If there is no response from the JSON-RPC API service, go to the installation guide for how to start or restart it.

Below most commands will be piped through jq, but for processing you might want to have the JSON on one line, or you might want to look at the options for jq to extract fields (see jq -h).

Run a test of the zonemaster.net zone using zmtest

To just run a test zmtest is the simple tool to use:

zmtest zonemaster.net

The tool will also display the result, which will be a large JSON object (here truncated).

testid: 879d13569db70fde
100% done
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "created_at": "2024-10-25T09:28:38Z",
    "hash_id": "879d13569db70fde",
    "params": {
      "domain": "zonemaster.net",
      "ds_info": [],
      "ipv4": true,
      "ipv6": true,
      "nameservers": [],
      "priority": 10,
      "profile": "default",
      "queue": 0
    },
    "results": [
      {
        "level": "INFO",
        "message": "Using version v6.0.0 of the Zonemaster engine.\n",
        "module": "System",
        "testcase": "Unspecified"
      },
      {
        "level": "INFO",
        "message": "The parent zone is \"net\" as returned from name servers \"a.gtld-servers.net/192.5.6.30; a.gtld-servers.net/2001:503:a83e::2:30; b.gtld-servers.net/192.33.14.30; b.gtld-servers.net/2001:503:231d::2:30; c.gtld-servers.net/192.26.92.30; c.gtld-servers.net/2001:503:83eb::30; d.gtld-servers.net/192.31.80.30; d.gtld-servers.net/2001:500:856e::30; e.gtld-servers.net/192.12.94.30; e.gtld-servers.net/2001:502:1ca1::30; f.gtld-servers.net/192.35.51.30; f.gtld-servers.net/2001:503:d414::30; g.gtld-servers.net/192.42.93.30; g.gtld-servers.net/2001:503:eea3::30; h.gtld-servers.net/192.54.112.30; h.gtld-servers.net/2001:502:8cc::30; i.gtld-servers.net/192.43.172.30; i.gtld-servers.net/2001:503:39c1::30; j.gtld-servers.net/192.48.79.30; j.gtld-servers.net/2001:502:7094::30; k.gtld-servers.net/192.52.178.30; k.gtld-servers.net/2001:503:d2d::30; l.gtld-servers.net/192.41.162.30; l.gtld-servers.net/2001:500:d937::30; m.gtld-servers.net/192.55.83.30; m.gtld-servers.net/2001:501:b1f9::30\".\n",
        "module": "Basic",
        "testcase": "Basic01"
      },
      {
        "level": "INFO",
        "message": "The zone \"zonemaster.net\" is found.\n",
        "module": "Basic",
        "testcase": "Basic01"
      },
      {
        "level": "INFO",
        "message": "Authoritative answer on SOA query for \"zonemaster.net\" is returned by name servers \"ns2.nic.fr/192.93.0.4; ns2.nic.fr/2001:660:3005:1::1:2; nsa.dnsnode.net/194.58.192.46; nsa.dnsnode.net/2a01:3f1:46::53; nsp.dnsnode.net/194.58.198.32; nsp.dnsnode.net/2a01:3f1:3032::53; nsu.dnsnode.net/185.42.137.98; nsu.dnsnode.net/2a01:3f0:400::32\".\n",
        "module": "Basic",
        "testcase": "Basic02"
      },
(...)

You will find the meaning of all fields in the outputs in Zonemaster-Backend JSON-RPC API reference.

Run a test of the zonemaster.net zone using zmb

If we instead use zmb then this will be done in three steps (that happen behind the scen when using zmtest):

1. Enqueue test.
2. Check if testing has completed (progress) - maybe several times.
3. Fetch result (maybe several times with different translations).

Enqueue a test

To enqueue a test of zonemaster.net we run zmb start_domain_test --domain zonemaster.net | jq and immediately get the response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "879d13569db70fde"
}

The results field holds the test ID which we need for further steps. It always consists of 16 hexadecimal digits.

Check the progress

To check the progress we run zmb test_progress --test-id 879d13569db70fde | jq with the test ID from enqueueing, and get the response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 8
}

Now the results field holds the progress of testing, an integer between 0 and 100 to mean 0% to 100%. 0% means that testing has not started (maybe many tests in the queue) and 100% means that testing has completed.

We have to stay in the check step until the test has reached 100%. In our example above, it is 8%, so we run the command again and now we get the response

{
  "result": 100,
  "jsonrpc": "2.0",
  "id": 1
}

Fetch the results

When the test has completed the test results can be fetched. The test ID is found above and then the language has to be chosen. Here en is used. More about languages below. Run zmb get_test_results --test-id 879d13569db70fde --lang en | jq and get a JSON structure with data (as with zmtest). Again, the JSON structure is long and is truncated here.

{
  "id": 1,
  "result": {
    "results": [
      {
        "message": "Using version v6.0.0 of the Zonemaster engine.\n",
        "testcase": "Unspecified",
        "level": "INFO",
        "module": "System"
      },
      {
        "module": "Basic",
        "level": "INFO",
        "testcase": "Basic01",
        "message": "The parent zone is \"net\" as returned from name servers \"a.gtld-servers.net/192.5.6.30; a.gtld-servers.net/2001:503:a83e::2:30; b.gtld-servers.net/192.33.14.30; b.gtld-servers.net/2001:503:231d::2:30; c.gtld-servers.net/192.26.92.30; c.gtld-servers.net/2001:503:83eb::30; d.gtld-servers.net/192.31.80.30; d.gtld-servers.net/2001:500:856e::30; e.gtld-servers.net/192.12.94.30; e.gtld-servers.net/2001:502:1ca1::30; f.gtld-servers.net/192.35.51.30; f.gtld-servers.net/2001:503:d414::30; g.gtld-servers.net/192.42.93.30; g.gtld-servers.net/2001:503:eea3::30; h.gtld-servers.net/192.54.112.30; h.gtld-servers.net/2001:502:8cc::30; i.gtld-servers.net/192.43.172.30; i.gtld-servers.net/2001:503:39c1::30; j.gtld-servers.net/192.48.79.30; j.gtld-servers.net/2001:502:7094::30; k.gtld-servers.net/192.52.178.30; k.gtld-servers.net/2001:503:d2d::30; l.gtld-servers.net/192.41.162.30; l.gtld-servers.net/2001:500:d937::30; m.gtld-servers.net/192.55.83.30; m.gtld-servers.net/2001:501:b1f9::30\".\n"
      },
      {
        "message": "The zone \"zonemaster.net\" is found.\n",
        "module": "Basic",
        "testcase": "Basic01",
        "level": "INFO"
      },
      {
        "level": "INFO",
        "testcase": "Basic02",
        "module": "Basic",
        "message": "Authoritative answer on SOA query for \"zonemaster.net\" is returned by name servers \"ns2.nic.fr/192.93.0.4; ns2.nic.fr/2001:660:3005:1::1:2; nsa.dnsnode.net/194.58.192.46; nsa.dnsnode.net/2a01:3f1:46::53; nsp.dnsnode.net/194.58.198.32; nsp.dnsnode.net/2a01:3f1:3032::53; nsu.dnsnode.net/185.42.137.98; nsu.dnsnode.net/2a01:3f0:400::32\".\n"
      },
(...)

Find available languages

The result can be presented in several languages, depending on installation. To find out what languages that are available, run zmb get_language_tags | jq.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "da",
    "en",
    "es",
    "fi",
    "fr",
    "nb",
    "sv"
  ]
}

Find previous tests

It is possible to find previous tests of a specific domain (zone). Run zmb get_test_history --domain zonemaster.net |jq to get all tests of zonemaster.net. The output looks like the following:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "undelegated": false,
      "created_at": "2024-10-25T09:54:38Z",
      "id": "00669309ac7887c3",
      "overall_result": "ok"
    },
    {
      "overall_result": "ok",
      "id": "879d13569db70fde",
      "undelegated": false,
      "created_at": "2024-10-25T09:28:38Z"
    }
  ],
  "id": 1
}

Now you can get the results of any of the listed tests by running get_test_results with selected test ID and language as above.

Other APIs

There are a few other APIs that can be used throught zmb, and can be found by zmb -h and in Zonemaster-Backend JSON-RPC API reference. The APIs for batch testing are covered in Using Zonemaster Backend for batch testing.

IDN domain names

When enqueuing a test of an IDN domain name with zmb start_domain_test it is possible to provide the domain name as either A-label or U-label. E.g. both "räksmörgås.se" or "xn--rksmrgs-5wao1o.se" (the same domain name) work as well.

The same is also true if using Curl instead (see below).

Using Curl instead

Instead of using zmb it is possible to run the commands by curl, which requires that the JSON structure is created, but can give greater flexibility. The method can also be copied into different programming languages when scripting.

The same enqueuing of the zonemaster.net zone as above will then be:

curl -sS -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id": 2, "method": "start_domain_test", "params": {"domain": "zonemaster.net"}}' http://localhost:5000/ | jq .

And fetching the result, when completed, will be:

curl -sS -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id": 5, "method": "get_test_results", "params": {"id": "879d13569db70fde", "language": "en"}}' http://localhost:5000/ | jq .

The format of the JSON structure for every method is found in the Zonemaster-Backend JSON-RPC API reference.

Using Zonemaster-Backend for batch testing

Table of contents

• Introduction
• Combining GUI and batch
• Configuration to run batches
• Create batch user
• Run a batch job
  • Start a batch job
  • Status of a batch job
• Scale out
  • Enable global cache
  • Increase the worker pool size
  • Add more Test Agent services
  • Add more test servers
• Queues
• Appendix: Add more JSON-RPC API services

Introduction

In Using the Backend JSON-RPC API it is shown how a test of a single domain name (zone) can be started using the JSON-RPC API to Zonemaster-Backend. It is also possible to start a batch of domain names at the same time. In principle such a batch is the same thing as running the start_domain_test individually for each domain name in the batch.

This document describes how batches of domain name tests can be run and what to think about when running batches, especially large ones.

Zonemaster-Backend uses a database to store enqueued tests and results from tests. It is possible to use SQLite as the database backend for small installations and test installations, but that is not appropriate for running real batches on. Therefore in this document it is assumed that Backend has been installed with MariaDB/MySQL or PostgreSQL.

Combining GUI and batch

Both GUI and batch uses Zonemaster-Backend that stores the data in the database. If the same database is used, then all tests run, regardless if they are started via GUI or a batch, will be available in the GUI interface using the get_test_history (see relevant section in Using the Backend JSON-RPC API). Depending on the situation, running batches on the same Backend as GUI may be desirable or not recommended. If the results are expected to be available through GUI then the batches must be run on the same Backend. If the batches are run with a reduced set of test cases then it can be confusing since the results are not fully comparable with those from tests started from GUI. If the results from batch tests should not be mixed with tests from normal GUI tests, a separate installation of Backend is required, and that might not need any GUI at all.

Test prioritization is another aspect of mixing tests from batches and GUI on the same Backend. By default Backend will run tests from GUI (or rather by start_domain_test) before test from a batch. In this way interactive GUI users run tests do not have to wait for a batch to complete. A large batch might run for days.

Configuration to run batches

To start a batch job, setting enable_add_batch_job in backend_config.ini must be enabled (enabled by default). Moreover a special user must also be available. To create that user setting enable_add_api_user must be enabled (disabled by default). (See below for how to create the user.) Note that this setting only needs to be enabled while creating the user(s), not when starting a batch job.

After changing these settings, the JSON-RPC API service (running as a daemon) must be restarted.

It is not recommended to enable enable_add_api_user for an JSON-RPC API service that can be used by untrusted users, e.g. via GUI. If the installation for the batch jobs is a dedicated installation, then it is not an issue. If it is used by a public GUI that could be closed while the batch user or users are created, then that could be an option. Creating the user only takes as long time as it takes to type the command in, i.e. seconds.

Another option is to set up an additional JSON-RPC API service using the same database. Zonemaster-Backend can have several parallel JSON-RPC API services with different configuration, see Appendix: Add more JSON-RPC API services.

Create batch user

The Using the Backend JSON-RPC API guide shows how zmb can be used for several JSON-RPC API methods. It can also be used for the creation of the batch user. It is here assumed that enable_add_api_user has been enabled or else the following will be included in the response to the zmb add_api_user command:

"message": "Procedure 'add_api_user' not found"

Run zmb add_api_user --username myuser --api-key mykey | jq where myuser is a user name of your choice and mykey the password, which should probably be longer and more complex. The output is simply

{
  "jsonrpc": "2.0",
  "result": 1,
  "id": 1
}

Now enable_add_api_user can be disabled.

Run a batch job

The zmb tool is used for that purpose. A batch job can be started with just a few domain names or a list of millions of domain names.

Start a batch job

Batches are created using add_batch_job:

$ zmb add_batch_job --username myuser --api-key mykey --domain zonemaster.net --domain zonemaster.se --domain zonemaster.fr | jq
{
  "jsonrpc": "2.0",
  "result": 2,
  "id": 1
}

Options that are mandatory are --username, --api-key and --domain. Option --domain is repeated for every domain name in the batch. The other options are optional. For all options see zmb man.

The batch ID is found in "result", which is "2" in this case.

Listing the domain names one by one is however cumbersome unless it is a very small batch as above. A better alternative for a larger batch is to create text file of the domain names to test, one domain name per line. Comments starting with # is permitted, which makes it possible to add meta information to the file.

cat batchfile.txt
# Example batch
zonemaster.net
zonemaster.se
zonemaster.fr

Now we can run the same batch as above, but from the file:

$ zmb add_batch_job --username myuser --api-key mykey --file batchfile | jq
{
  "jsonrpc": "2.0",
  "result": 3,
  "id": 1
}

Starting the batch with the domain names one by one or in the file gives exactly the same result. Also in this case, IDN domain names can be entered both with A-label and U-label (UTF-8 is assumed).

Status of a batch job

To check the status of a batch job the batch ID is required ("2" in the case above), using get_batch_job_result:

$ zmb get_batch_job_result --batch-id 2 | jq
{
  "id": 1,
  "result": {
    "nb_running": 3,
    "nb_finished": 0
  },
  "jsonrpc": "2.0"
}

Three tests are running, none has been completed yet. After some time running the command again gives:

{
  "jsonrpc": "2.0",
  "result": {
    "nb_running": 0,
    "finished_test_ids": [
      "b26b874493ed4b57",
      "9af528070fa2551a",
      "708f82b5176261dc"
    ],
    "nb_finished": 3
  },
  "id": 1
}

Now all tests in the batch are completed. The test IDs in finished_test_ids can be used to get the results with get_test_results.

Scale out

Running a batch can take a long time and if that is a problem then it is possible to increase the performance by:

• Enabling global cache
• Increasing number_of_processes_for_batch_testing
• Adding one or more Test Agent service
• Adding one or more test servers

Enable global cache

For each domain name in a batch job, a test run is executed. Each test run keeps its own cache to avoid sending the same query twice. However these caches are never shared between test runs. This may result in large numbers of redundant queries for large batches where the domain name directly (or indirectly) share data with other domain names. To share responses between test runs, you can enable the global cache feature which works like a second level cache.

For interactive tests via GUI the global cache is probably not desired. If a user changes the DNS configuration of a domain then the following tests results should not be based on old data.

To enable global cache a custom profile must be used. See the instructions in Configuration: Global cache in Zonemaster-Engine.

The custom profile is assumed to be /etc/zonemaster/profile-batch.json (Linux) or /etc/local/zonemaster/profile-batch.json (FreeBSD).

The custom profile file, say profile-batch.json, must be added to the Backend configuration to be made available for the tests. In backend_config.ini look for the section [PRIVATE PROFILES]. Under that add the following line for Linux:

batch=/etc/zonemaster/profile-batch.json

For FreeBSD add:

batch=/usr/local/etc/zonemaster/profile-batch.json

After updating the Backend configuration, restart both JSON-RPC API service and Test Agent service (all daemons of both services if there are more than one of each).

Now you can start a batch -- using the same batch file as above -- with:

$ zmb add_batch_job --profile batch --username myuser --api-key mykey --file batchfile | jq
{
  "jsonrpc": "2.0",
  "result": 4,
  "id": 1
}

Increase the worker pool size

A standard Backend installation has a single Test Agent service. Each Test Agent service maintains a pool of workers. Test Agents monitor the Backend database for tests and assigns them to workers.

Increasing the size of the worker pool can improve the testing performance. The improvement is limited by CPU, I/O, memory and the ability of the Test Agent service to keep its workers busy, so monitor these factors to find the best configuration.

To adjust the worker pool size, set number_of_processes_for_batch_testing in the backend_config.ini configuration file.

Add more Test Agent services

If the increase of number_of_processes_for_batch_testing does not help anymore and the server has free resources (IO, CPU and RAM) then adding another Test Agent services (with its pool of workers) can help.

The default Test Agent service is started by the start script /etc/systemd/system/zm-testagent.service (Rocky Linux), /etc/init.d/zm-testagent (Debian/Ubuntu) or /usr/local/etc/rc.d/zm_testagent (FreeBSD). Create a copy so that the additional Test Agent service has a new name, new PID file and new log file. Also see the Backend installation instructions. Each Test Agent service will be its own daemon.

Start the new daemon and now a second Test Agent service is running. Additional Test Agent services can be added by repeating the steps above.

Unless the different Test Agent services should process different queues the same configuration file can be used.

Add more test servers

Adding more servers is a generalization of adding more Test Agent daemons.

• Configure the database to listen on an external interface. The database can also be moved to a dedicated server.
• Install Backend on the new Test Agent server, but disable JSON-RPC API service.
• Update configuration to use the external database server.
• Consider adding more Test Agent services.
• If global cache is used, configure Redis to listen on an external interface. The Redis server can also be moved to a dedicated server.
• Consider moving JSON-RPC API service to a dedicated server. If so, update the configuration to use the external database server.
• If applicable, configure all parts to use external database server and external Redis server.

Queues

Every enqueued test has a queue tag. In the configuration file it is set which queue should be processed by the Test Agent service. Only tests with matching queue value (default 0) will be processed. Queue tag is set by the JSON-RPC API methods start_domain_test and add_batch_job, respectively (default 0 in both cases).

If desirable it is possible to create a batch with another queue value and then let a dedicated Test Agent service, possibly on a dedicated server, process the tests in the batch, while another Test Agent service processes tests from GUI.

It is important to note that if a test is tagged with a queue value that no Test Agent service uses it will never be processed.

In the end, all completed tests will end up in the same database and will be mixed when looking for completed tests for the same domain name (get_test_history).

Appendix: Add more JSON-RPC API services

The JSON-RPC API service listens by default on 127.0.0.1 on port 5000. That is governed by the start script for the JSON-RPC API service which is /etc/systemd/system/zm-rpcapi.service (Rocky Linux), /etc/init.d/zm-rpcapi (Ubuntu and Debian) or /usr/local/etc/rc.d/zm_rpcapi (FreeBSD). Create a copy so that the additional service (daemon) has a new name, new PID file, new log file and listens to a new port. Also see the Backend installation instructions.

Start the new daemon and now a second JSON-RPC API service is running.

To be useful, the second JSON-RPC API service should probably have a different configuration file too. The configuration file is found as /etc/zonemaster/backend_config.ini (Linux) or as /usr/local/etc/zonemaster/backend_config.ini (FreeBSD). The database settings must not be changed, or else the two JSON-RPC API services will not be part of the same Zonemaster Backend. Examples of settings that could be different between the two JSON-RPC API services are:

• enable_add_api_user
• Available profiles

Restart the JSON-RPC API services to use the updated configuration files.

API

Table of contents

• Purpose
• Protocol
  • Deviations from JSON-RPC 2.0
  • Notes on the JSON-RPC 2.0 implementation
• Request handling
• Error reporting
• Privilege levels
• Data types
  • API key
  • Batch id
  • Client id
  • Client version
  • Domain name
  • DS info
  • IP address
  • Language tag
  • Name server
  • Non-negative integer
  • Priority
  • Profile name
  • Progress percentage
  • Queue
  • Severity level
  • Test id
  • Test result
  • Timestamp
  • Username
• API methods
  • API method: version_info
  • API method: profile_names
  • API method: get_language_tags
  • API method: get_host_by_name
  • API method: get_data_from_parent_zone
  • API method: start_domain_test
  • API method: test_progress
  • API method: get_test_results
  • API method: get_test_history
    • Undelegated and delegated
  • API method: add_api_user
  • API method: add_batch_job
  • API method: get_batch_job_result
  • API method: get_test_params
• Experimental API methods

Purpose

This document describes the JSON-RPC API provided by the Zonemaster RPC API daemon. This API provides means to check the health of domains and to fetch domain health reports. Health checks are called tests in Zonemaster lingo.

Protocol

This API is implemented using JSON-RPC 2.0.

JSON-RPC request objects are accepted in the body of HTTP POST requests to any path. The HTTP request must contain the header Content-Type: application/json.

All JSON-RPC request and response objects have the keys "jsonrpc", "id" and "method". For details on these, refer to the JSON-RPC 2.0 specification.

Deviations from JSON-RPC 2.0

• The "jsonrpc" property is not checked.
• The error code -32603 is used for invalid arguments, as opposed to the dedicated error code -32602.
• When standard error codes are used, the accompanying messages are not the standard ones.

Notes on the JSON-RPC 2.0 implementation

• Extra top-level properties in request objects are allowed but ignored.
• No extra properties are allowed in the "params" object.
• Error messages from the API should be considered sensitive as they sometimes leak details about the internals of the application and the system.
• The error code -32601 is used when the "method" property is missing, rather than the perhaps expected error code -32600.

Request handling

When a method expects a string argument but receives an array or an object, the value may be interpreted as something like "ARRAY(0x1a2d1d0)" or "HASH(0x1a2d2c8)".

When a method expects a boolean argument, any kind of value is accepted. A number of values are interpreted as false: false, null, "", "0" and any number equal to zero. Everything else is interpreted as true.

When a method expects an integer arguments, numbers encoded in strings are also accepted and used transparently, and numbers with fractions are rounded to the nearest integer.

For details on when a test are performed after it's been requested, see the architecture documentation.

Error reporting

If the request object is invalid JSON, an error with code -32700 is reported.

If no method is specified or an invalid method is specified, an error with code -32601 is reported.

If no params object is specified when it is required, or the params object for the specified method is invalid, an error with code -32602 is reported. For more information on the validation error data format see Validation error data.

All error states that occur after the RPC method has been identified are reported as internal errors with code -32603.

Privilege levels

This API provides three classes of methods:

• Unrestricted methods are available to anyone with access to the API.
• Authenticated methods have parameters for username and api key credentials.
• Administrative methods require that the connection to the API is opened from localhost (127.0.0.1 or ::1).

Data types

This sections describes a number of data types used in this API. Each data type is based on a JSON data type, but additionally imposes its own restrictions.

API key

Basic data type: string

A string of alphanumerics, hyphens (-) and underscores (_), of at least 1 and at most 512 characters. I.e. a string matching /^[a-zA-Z0-9-_]{1,512}$/.

Represents the password of an authenticated account (see Privilege levels)

Batch id

Basic data type: number

A strictly positive integer.

The unique id of a batch.

Client id

Basic data type: string

A string of alphanumerics, hyphens, underscores, pluses (+), tildes (~), full stops (.), colons (:) and spaces ( ), of at least 1 and at most 50 characters. I.e. a string matching /^[a-zA-Z0-9-+~_.: ]{1,50}$/.

Represents the name of the client. Used for monitoring which client (GUI) uses the API.

Client version

Basic data type: string

A string of alphanumerics, hyphens, pluses, tildes, underscores, full stops, colons and spaces, of at least 1 and at most 50 characters. I.e. a string matching /^[a-zA-Z0-9-+~_.: ]{1,50}$/.

Represents the version of the client. Used for monitoring which client (GUI) uses the API.

Domain name

Basic data type: string

1. If the string is a single character, that character must be ..

2. The length of the string must not be greater than 254 characters.

3. When the string is split at . characters (after IDNA conversion, if needed), each component part must be at most 63 characters long.

Note: Currently there are no restrictions on what characters that are allowed.

DS info

Basic data type: object

DS for Delegation Signer references a DNSKEY record in the delegated zone.

Properties:

• "digest": A string, required. Either 40, 64 or 96 hexadecimal characters (case-insensitive).
• "algorithm": An non negative integer, required.
• "digtype": An non negative integer, required.
• "keytag": An non negative integer, required.

IP address

Basic data type: string

This parameter is a string that is either

• a valid IPv4 address in dot-decimal notation ;
• a valid IPv6 address in recommended text format for IPv6 addresses.

Language tag

Basic data type: string

A string matching /^[a-z]{2}$/.

The set of valid language tags is further constrained by the LANGUAGE.locale property. A language tag needs to match the language code of a locale tag in LANGUAGE.locale.

Design

The language tag values are intended to be ISO 639-1 two-character language codes.

Out-of-the box support

A default installation will accept the following language tags:

Name server

Basic data type: object

Properties:

• "ns": A domain name, required.
• "ip": An IP address (IPv4 or IPv6), optional. (default: unset)

Non-negative integer

Basic data type: number (integer)

A non-negative integer is either zero or strictly positive.

Priority

Basic data type: number (integer)

This parameter is any integer that will be used by The Zonemaster Test Agents to sort the test requests from highest to lowest priority. This parameter will typically be used in a setup where a GUI will send requests to the RPC API and would like to get response as soon as possible while at the same time using the idle time for background batch testing. The drawback of this setup will be that the GUI will have to wait for at least one background processing slot to become free (would be a few seconds in a typical installation with up to 30 parallel zonemaster processes allowed)

Profile name

Basic data type: string

This parameter is a case-insensitive string validated with the case-insensitive regex /^[a-z0-9]$|^[a-z0-9][a-z0-9_-]{0,30}[a-z0-9]$/i which must be predefined in the configuration file as specified in the Configuration document profile sections.

The name of a profile.

Progress percentage

Basic data type: number (integer)

An integer ranging from 0 (not started) to 100 (finished).

Queue

Basic data type: number (integer)

This parameter allows an optional separation of testing in the same database. The default value for the queue is 0. It is closely related to the ZONEMASTER.lock_on_queue parameter of the backend_config.ini file. The typical use case for this parameter would be a setup with several separate Test Agents running on separate physical or virtual machines each one dedicated to a specific task, for example queue 0 for frontend tests and queue 1 dedicated to batch testing.

Severity level

Basic data type: string

One of the strings (in order from least to most severe):

• "INFO"
• "NOTICE"
• "WARNING"
• "ERROR"
• "CRITICAL"

Severity levels in Zonemaster are defined in the Severity Level Definitions document. The following severity levels are not available through the RPCAPI (in order from least to most severe):

• DEBUG3
• DEBUG2
• DEBUG

Test id

Basic data type: string

A string of exactly 16 lower-case hex-digits matching /^[0-9a-f]{16}$/.

Each test has a unique test id.

Test result

Basic data type: object

The object has four keys, "module", "message", "level" and "testcase".

• "module": a string. The test module that produced the result.
• "message": a string. A human-readable message describing that particular result.
• "level": a severity level. The severity of the message.
• "testcase": a string. The Test Case Identifier of the Test Case that produced the result.

Sometimes additional keys are present.

• "ns": a domain name. The name server used by the test module. This key is added when the module name is "NAMESERVER".

Timestamp

Basic data type: string

A string representing a date and time using the following ISO 8601 format: "YYYY-MM-DDThh:mm:ssZ". Example: "2017-12-18T07:56:17Z"

Username

Basic data type: string

A string of alphanumerics, dashes, full stops and at-signs, of at least 1 and at most 50 characters. I.e. a string matching /^[a-zA-Z0-9-.@]{1,50}$/.

Represents the name of an authenticated account (see Privilege levels)

Validation error data

Basic data type: array

The items of the array are objects with two keys, "path" and "message":

• "path": a string. A JSON Pointer to an element in the request's param object. E.g.: "/nameservers/0/ip".
• "message": a string. The error message associated with the element referenced by "path".

API methods

API method: version_info

Returns the version of the Zonemaster-LDNS, Zonemaster-Engine and Zonemaster-Backend software combination.

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "version_info"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "zonemaster_ldns": "1.0.1",
    "zonemaster_backend": "1.0.7",
    "zonemaster_engine": "v1.0.14"
  }
}

"result"

An object with the following properties:

• "zonemaster_ldns": A string. The version number of the running Zonemaster LDNS.
• "zonemaster_backend": A string. The version number of the running Zonemaster Backend.
• "zonemaster_engine": A string. The version number of the Zonemaster Engine used by the RPC API daemon.

"error"

TODO: List all possible error codes and describe what they mean enough for clients to know how react to them.

API method: profile_names

Returns the names of the public subset of the available profiles.

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "profile_names"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "default",
    "another-profile"
  ]
}

"result"

An array of Profile names in lower case. "default" is always included.

API method: get_language_tags

Returns the set of valid language tags.

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_language_tags"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "da",
    "en",
    "es",
    "fi",
    "fr",
    "nb",
    "sv"
  ]
}

"result"

An array of language tags. It is never empty.

"error"

TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. Or prevent RPCAPI from starting with errors in the configuration file and make it not to reread the configuration file while running.

API method: get_host_by_name

Looks up the A and AAAA records for a hostname (domain name) on the public Internet.

Example request:

Valid syntax:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "get_host_by_name",
  "params": {"hostname": "zonemaster.net"}
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": [
    {
      "zonemaster.net": "192.134.4.83"
    },
    {
      "zonemaster.net": "2001:67c:2218:3::1:83"
    }
  ]
}

"params"

An object with the property:

• "hostname": A domain name, required. The hostname whose IP addresses are to be resolved.

"result"

A list of one or two objects representing IP addresses (if 2 one is for IPv4 the other for IPv6). The objects each have a single key and value. The key is the domain name given as input. The value is an IP address for the name, or the value 0.0.0.0 if the lookup returned no A or AAAA records.

TODO: If the name resolves to two or more IPv4 address, how is that represented?

"error"

• If any parameter is invalid an error code of -32602 is returned. The data property contains an array of all errors, see Validation error data.

  Example of error response:

{
  "jsonrpc": "2.0",
  "id": 1624630143271,
  "error": {
    "message": "Invalid method parameter(s).",
    "code": "-32602",
    "data": [
      {
        "path": "/hostname",
        "message": "Missing property"
      }
    ]
  }
}

API method: get_data_from_parent_zone

Returns all the NS/IP and DS/DNSKEY/ALGORITHM pairs of the domain from the parent zone.

Example request: Valid syntax:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "get_data_from_parent_zone",
  "params": {"domain": "zonemaster.net"}
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "ns_list": [
      {
        "ns": "ns.nic.se",
        "ip": "2001:67c:124c:100a::45"
      },
      {
        "ns": "ns.nic.se",
        "ip": "91.226.36.45"
      },
      ...
    ],
    "ds_list": [
      {
        "algorithm": 5,
        "digtype": 2,
        "keytag": 54636,
        "digest": "cb496a0dcc2dff88c6445b9aafae2c6b46037d6d144e43def9e68ab429c01ac6"
      },
      {
        "keytag": 54636,
        "digest": "fd15b55e0d8ee2b5a8d510ab2b0a95e68a78bd4a",
        "algorithm": 5,
        "digtype": 1
      }
    ]
  }
}

Note: The above example response was abbreviated for brevity to only include the first two elements in each list. Omitted elements are denoted by a ... symbol.

"params"

An object with the properties:

• "domain": A domain name, required. The domain whose DNS records are requested.
• "language": A language tag, optional, used for validation error messages translation, if not provided messages will be untranslated (in English).

"result"

An object with the following properties:

• "ns_list": A list of name server objects representing the nameservers of the given domain name.
• "ds_list": A list of DS info objects representing delegation signer (DS record data) of the given domain name.

"error"

• If any parameter is invalid an error code of -32602 is returned. The data property contains an array of all errors, see Validation error data.

  Example of error response:

{
  "jsonrpc": "2.0",
  "id": 1624630143271,
  "error": {
    "data": [
      {
        "message": "The domain name character(s) are not supported",
        "path": "/domain"
      }
    ],
    "code": "-32602",
    "message": "Invalid method parameter(s)."
  }
}

API method: start_domain_test

Enqueues a new test and returns the test id of the test.

Example request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "start_domain_test",
  "params": {
    "client_id": "Zonemaster Dancer Frontend",
    "domain": "zonemaster.net",
    "profile": "default",
    "client_version": "1.0.1",
    "nameservers": [
      {
        "ip": "2001:67c:124c:2007::45",
        "ns": "ns3.nic.se"
      },
      {
        "ip": "192.93.0.4",
        "ns": "ns2.nic.fr"
      }
    ],
    "ds_info": [],
    "ipv6": true,
    "ipv4": true
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": "c45a3f8256c4a155"
}

"params"

An object with the following properties:

• "domain": A domain name, required. The zone to test.
• "ipv6": A boolean, optional. (default: net.ipv4 profile value). Used to enable or disable testing over IPv4 transport protocol.
• "ipv4": A boolean, optional. (default: net.ipv6 profile value). Used to enable or disable testing over IPv6 transport protocol.
• "nameservers": A list of name server objects, optional. (default: []). Used to perform un-delegated test.
• "ds_info": A list of DS info objects, optional. (default: []). Used to perform un-delegated test.
• "profile": A profile name, optional. (default: "default"). Run the tests using the given profile.
• "client_id": A client id, optional. (default: unset). Used to monitor which client uses the API.
• "client_version": A client version, optional. (default: unset). Used to monitor which client use the API
• "priority": A priority, optional. (default: 10)
• "queue": A queue, optional. (default: 0)
• "language": A language tag, optional, used for validation error messages translation, if not provided messages will be untranslated.

"result"

A test id.

If a test has been requested with the same parameters (as listed below) not more than "reuse time" ago, then a new request will not trigger a new test. Instead the test id of the previous test will be returned. The default value of "reuse time" is 600 seconds, and can be set by the ZONEMASTER.age_reuse_previous_test key in the configuration file.

The parameters that are compared when to determine if two requests are to be considered to be the same are domain, ipv6, ipv4, nameservers, ds_info and profile.

"error"

• If any parameter is invalid an error code of -32602 is returned. The data property contains an array of all errors, see Validation error data.

• If the given profile is not among the available profiles, a user error is returned, see profile name section.

Example of error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": "-32602",
    "data": [
      {
        "message": "Expected integer - got string.",
        "path": "/ds_info/0/algorithm"
      },
      {
        "message": "Missing property.",
        "path": "/ds_info/0/digest"
      },
      {
        "path": "/profile",
        "message": "Unknown profile"
      },
      {
        "path": "/domain",
        "message": "The domain name character(s) are not supported"
      },
      {
        "path": "/nameservers/0/ip",
        "message": "Invalid IP address"
      }
    ],
    "message": "Invalid method parameter(s)."
  }
}

API method: test_progress

Reports on the progress of a test.

Example request:

Valid syntax:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "test_progress",
  "params": {"test_id": "c45a3f8256c4a155"}
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": 100
}

"params"

An object with the property:

"test_id": A test id, required. The test to report on.

"result"

A progress percentage.

"error"

TODO: List all possible error codes and describe what they mean enough for clients to know how react to them.

API method: get_test_results

Return all test result objects of a test, with messages in the requested language as selected by the language tag.

Example request:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "get_test_results",
  "params": {
    "id": "c45a3f8256c4a155",
    "language": "en"
  }
}

The id parameter must match the result in the response to a start_domain_test call, and that test must have been completed.

Example response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "created_at": "2016-11-15T11:53:13Z",
    "hash_id": "c45a3f8256c4a155",
    "params": {
      "ds_info": [],
      "client_version": "1.0.1",
      "domain": "zonemaster.net",
      "profile": "default",
      "ipv6": true,
      "nameservers": [
        {
          "ns": "ns3.nic.se",
          "ip": "2001:67c:124c:2007::45"
        },
        {
          "ip": "192.93.0.4",
          "ns": "ns2.nic.fr"
        }
      ],
      "ipv4": true,
      "client_id": "Zonemaster Dancer Frontend"
    },
    "testcase_descriptions": {
      "ZONE08": "MX is not an alias",
      "SYNTAX05": "Misuse of '@' character in the SOA RNAME field",
      ...
    },
    "results": [
      {
        "module": "SYSTEM",
        "message": "Using version v1.0.14 of the Zonemaster engine.\n",
        "level": "INFO"
      },
      {
        "message": "Configuration was read from DEFAULT CONFIGURATION\n",
        "level": "INFO",
        "module": "SYSTEM"
      },
      ...
    ]
  }
}

Note: The above example response was abbreviated for brevity to only include the first two elements in each list. Omitted elements are denoted by a ... symbol.

"params"

An object with the following properties:

• "id": A test id, required.
• "language": A language tag, required.

"result"

An object with the following properties:

• "created_at": A timestamp. The time in UTC at which the test was created.
• "hash_id": A test id. The test in question.
• "params": See below.
• "results": A list of test result objects.
• "testcase_descriptions": A map with the Test Case Identifiers as keys and the translated Test Case Description of the corresponding Test Cases as values.

If the test was created by start_domain_test then "params" is a normalized version "params" object sent to start_domain_test when the test was created.

If the test was created with add_batch_job then "params" is a normalized version of an object created from the following parts:

• The keys from the"test_params" object sent to add_batch_job when the test was created as part of a batch.
• The "domain" key holding the specific domain name for this test result from the "domains" object included in the call to add_batch_job.

TODO: Change name in the API of "hash_id" to "test_id"

"error"

TODO: List all possible error codes and describe what they mean enough for clients to know how react to them.

API method: get_test_params

Return a normalized params objects of a test.

Example request:

Valid syntax:

{
    "jsonrpc": "2.0",
    "id": 143014426992009,
    "method": "get_test_params",
    "params": {"test_id": "6814584dc820354a"}
}

Example response:

{
    "jsonrpc": "2.0",
    "id": 143014426992009,
    "result": {
         "domain": "zonemaster.net",
         "profile": "default",
         "client_id": "Zonemaster Dancer Frontend",
         "nameservers": [
            {
                "ns": "ns3.nic.se",
                "ip": "2001:67c:124c:2007::45"
            },
            {
                "ip": "192.93.0.4",
                "ns": "ns2.nic.fr"
            }
         ],
         "ipv4": true,
         "ipv6": true,
         "client_version": "1.0.1",
         "ds_info": []
    }
}

"params"

An object with the property:

• "test_id": A test id, required.

"result"

The "params" object sent to start_domain_test or add_batch_job when the test was started.

"error"

TODO: List all possible error codes and describe what they mean enough for clients to know how react to them.

API method: get_test_history

Returns a list of completed tests for a domain.

Example request:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "get_test_history",
  "params": {
    "offset": 0,
    "limit": 200,
    "filter": "all",
    "frontend_params": {
      "domain": "zonemaster.net"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": [
    {
      "id": "c45a3f8256c4a155",
      "creation_time": "2016-11-15 11:53:13.965982",
      "created_at": "2016-11-15T11:53:13Z",
      "undelegated": true,
      "overall_result": "error"
    },
    {
      "id": "32dd4bc0582b6bf9",
      "undelegated": false,
      "creation_time": "2016-11-14 08:46:41.532047",
      "created_at": "2016-11-14T08:46:41Z",
      "overall_result": "error"
    },
    ...
  ]
}

Note: The above example response was abbreviated for brevity to only include the first two elements in each list. Omitted elements are denoted by a ... symbol.

Undelegated and delegated

A test is considered to be "delegated" below if the test was started, by start_domain_test or add_batch_job without specifying neither "nameserver" nor "ds_info". Else it is considered to be "undelegated".

"params"

An object with the following properties:

• "offset": A non-negative integer, optional. (default: 0). Position of the first returned element from the database returned list.
• "limit": A non-negative integer, optional. (default: 200). Number of element returned from the offset element.
• "filter": A string, one of "all", "delegated" and "undelegated", optional. (default: "all")
• "frontend_params": An object, required.

The value of "frontend_params" is an object with the following properties:

• "domain": A domain name, required.

"result"

An object with the following properties:

• "id" A test id.
• "created_at": A timestamp. The time in UTC at which the test was created.
• "overall_result": A string. It reflects the most severe problem level among the test results for the test. It has one of the following values:
  • "ok", if there are only messages with severity level "INFO" or "NOTICE".
  • "warning", if there is at least one message with severity level "WARNING", but none with "ERROR" or "CRITICAL".
  • "error", if there is at least one message with severity level "ERROR", but none with "CRITICAL".
  • "critical", if there is at least one message with severity level "CRITICAL".
• "undelegated": true if the test is undelegated, false otherwise.

"error"

TODO: List all possible error codes and describe what they mean enough for clients to know how react to them.

API method: add_api_user

In order to use the add_batch_job method a username and its api key must be added by this method.

This method is not available if RPCAPI.enable_add_api_user is disabled (disabled by default). This method is not available unless the connection to RPCAPI is over localhost (administrative method).

Example request:

{
  "jsonrpc": "2.0",
  "id": 4711,
  "method": "add_api_user",
  "params": {
    "username": "citron",
    "api_key": "fromage"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 4711,
  "result": 1
}

"params"

An object with the following properties:

• "username": A username, required. The username to be added.
• "api_key": An api key, required. The api key for the username to be added.

"result"

An integer. The value is equal to 1 if the registration is a success, or 0 if it failed.

"error"

TODO: List all possible error codes and describe what they mean enough for clients to know how react to them.

Trying to add a already existing user:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "data": {
      "username": "citron"
    },
    "message": "User already exists",
    "code": -32603
  }
}

Omitting params:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": "-32602",
    "message": "Invalid method parameter(s).",
    "data": [
      {
        "message": "Expected string - got null.",
        "path": "/api_key"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "data": [
      {
        "path": "/username",
        "message": "Expected string - got null."
      }
    ],
    "message": "Invalid method parameter(s).",
    "code": "-32602"
  }
}

Trying to add a user over non-localhost:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "data": {
      "remote_ip": "10.0.0.1"
    },
    "message": "Call to \"add_api_user\" method not permitted from a remote IP"
  }
}

Trying to add a user when the method is disabled:

{
  "error": {
    "code": -32601,
    "message": "Procedure 'add_api_user' not found"
  }
}

API method: add_batch_job

Add a new batch test composed by a set of domain name and a params object. All the domains will be tested using identical parameters.

This method is not available if RPCAPI.enable_add_batch_job is disabled (enabled by default).

A username and its api key can be added with the add_api_user method.

Tests enqueued using this method are assigned a priority of 5.

In previous versions of Zonemaster-Backend a new batch could not be created by the same username if that username had created a batch that was not yet finished. That restriction has been removed in version 2023.2.

Example request:

{
  "jsonrpc": "2.0",
  "id": 147559211348450,
  "method": "add_batch_job",
  "params" : {
    "api_key": "fromage",
    "username": "citron",
    "test_params": {},
    "domains": [
      "zonemaster.net",
      "domain1.se",
      "domain2.fr"
    ]
  }
}

Example response:

{
    "jsonrpc": "2.0",
    "id": 147559211348450,
    "result": 8
}

"params"

An object with the following properties:

• "username": A username, required. The name of the account of an authorized user.
• "api_key": An api key, required. The api_key associated with the username.
• "domains": A list of domain names, required. The domains to be tested.
• "test_params": As described below, optional. (default: {})

The value of "test_params" is an object with the following properties:

• "client_id": A client id, optional. (default: unset)
• "profile": A profile name, optional (default: "default"). Run the tests using the given profile.
• "client_version": A client version, optional. (default: unset)
• "nameservers": A list of name server objects, optional. (default: [])
• "ds_info": A list of DS info objects, optional. (default: [])
• "ipv4": A boolean, optional. (default: net.ipv4 profile value).
• "ipv6": A boolean, optional. (default: net.ipv6 profile value).
• "priority": A priority, optional. (default: 5)
• "queue": A queue, optional. (default: 0)

"result"

A batch id.

"error"

If the given profile is not among the available profiles, a user error is returned, see the profile name section.

Trying to add a batch when wrong username or api key is used:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "message": "User not authorized to use batch mode",
    "code": -32603,
    "data": {
      "username": "citron"
    }
  }
}

Trying to add a batch with an empty list of domains:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "data": [
      {
        "message": "Not enough items: 0/1.",
        "path": "/domains"
      }
    ],
    "message": "Invalid method parameter(s).",
    "code": "-32602"
  }
}

Trying to add a batch when the method has been disabled.

{
  "error": {
    "message": "Procedure 'add_batch_job' not found",
    "code": -32601
  }
}

API method: get_batch_job_result

Return all test id objects of a batch test, with the number of finished test.

Example request:

Valid syntax:

{
    "jsonrpc": "2.0",
    "id": 147559211994909,
    "method": "batch_status",
    "params": {
        "batch_id": "8"
    }
}

Example response:

{
   "jsonrpc": "2.0",
   "id": 147559211994909,
   "result": {
      "nb_finished": 5,
      "finished_test_ids": [
         "43b408794155324b",
         "be9cbb44fff0b2a8",
         "62f487731116fd87",
         "692f8ffc32d647ca",
         "6441a83fcee8d28d"
      ],
      "nb_running": 195
   }
}

"params"

An object with the property:

• "batch_id": A batch id, required.

"result"

An object with the following properties:

• "nb_finished": a non-negative integer. The number of finished tests.
• "nb_running": a non-negative integer. The number of running tests.
• "finished_test_ids": a list of test ids. The set of finished tests in this batch.

"error"

If the batch_id is undefined the following error is returned:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "data": {
      "batch_id": "10"
    },
    "message": "Unknown batch",
    "code": -32603
  }
}

Experimental API methods

There are also some experimental API methods documented only by name:

• system_versions
• conf_profiles
• conf_languages
• lookup_address_records
• lookup_delegation_data
• job_create
• job_status
• job_results
• job_params
• domain_history
• user_create
• batch_create
• batch_status

Telemetry

Metrics

If enabled in the Metrics section in the configuration file, Statsd compatible metrics are available to use:

Usage

Testing the metrics feature can be as easy as running a listening UDP server like

ns -lup 8125

This should be enough to see the metrics emitted by Zonemaster.

More complex setups are required for the metrics to be used in alerts and dashboards. StatsD metrics can be integrated to a number of metrics backend like Prometheus (using the StatsD exporter), InfluxDB (using Telegraf and the StatsD plugin), Graphite (integration guide) and others.

StatsD Exporter (Prometheus)

1. Download the binary (tar file) corresponding to your environment https://github.com/prometheus/statsd_exporter/releases
2. Untar the file
3. cd into the statsd_exporter directory
4. Create a statsd_mapping.yml file with content as below

   mappings:
   - match: zonemaster.rpcapi.requests.*.*
     name: zonemaster_rpcapi_requests_total
     labels:
       method: $1
       status: $2
   - match: zonemaster.testagent.tests_duration_seconds
     observer_type: histogram
     buckets: [ 1, 2.5, 5, 10, 15, 30, 45, 60, 75, 90, 105, 120, 150, 180]
     name: zonemaster_testagent_tests_duration_seconds
   - match: zonemaster.testagent.cleanup_duration_seconds
     observer_type: histogram
     buckets: [ 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]
     name: zonemaster_testagent_cleanup_duration_seconds
   - match: zonemaster.testagent.fetchtests_duration_seconds
     observer_type: histogram
     buckets: [ 0.001, 0.0025, 0.005, 0.0075, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2, 3, 5, 10]
     name: zonemaster_testagent_fetchtests_duration_seconds
   

5. Run it like

   ./statsd_exporter --statsd.mapping-config=./statsd_mapping.yml --statsd.listen-udp=:8125 --statsd.listen-tcp=:8125
   

6. Run the following to see Zonemaster metrics:

   curl localhost:9102/metrics | grep zonemaster
   

Using the GUI

• The GUI API

API

The Zonemaster GUI provides an API to access specific resource and perform specific tasks.

A path is added to the Zonemaster GUI base URL, e.g. https://zonemaster.net/.

The supported paths are the following:

• <lang>/run-test: the default path, access the input form.
• <lang>/domain_check: same as run-test, but deprecated.
• <lang>/run-test/<domain>: populate the input form with <domain>, which is expected to be a name of a DNS zone, and launch the test. Currently undelegated tests cannot be performed via the API.
• <lang>/result/<test-id>: access the result page with results for the test with <test-id>.
• <lang>/test/<test-id>: same as <lang>/result/<test-id>, but deprecated.
• <lang>/faq: access the FAQ.

The GUI will rewrite <lang>/domain_check to <lang>/run-test before the page is displayed. Note that <lang>/domain_check/<domain> is not rewritten and hence is an invalid path.

The GUI will rewrite <lang>/test/<test-id> to <lang>/result/<test-id> before the result is displayed.

The GUI will redirect from <path> to <lang>/<path> automatically using the user browser language, if supported and configured by the installation. Else it uses the default language defined in the reverse proxy configuration.

Specifications

• Test Cases: contains the specifications of the Test Cases that the Zonemaster implementation is based on.
• Test types: contains the specification of Test Types, currently only for undelegated tests.
• Test zones: contains the specifications of Test Zones for the verification of Test Case implementation.

Test Types

This directory contains Test Type specifications, currently only specification for undelegated tests.

• undelegated-test.md

Undelegated tests

Objective

The purpose of an undelegated test is to test a possible future delegation before it is put in production. Hence, while testing an undelegated test, extra information (such as name servers, IP addresses) must be provided as input, and Zonemaster should run the test cases with the provided information.

Specification

An undelegated test should mimic the a delegated test. The information for the test must be provided when starting the test.

An undelegated test can be run on a already delegated domain, but then Zonemaster must disregard the specific information for that domain found in public DNS.

Information that is part of the delegation must be provided with the initiation of the test. That following information is used for the undelegated test:

• Domain (zone) to be tested. Mandatory information.

• NS records. No NS records may be looked up before the test starts, the complete RR set must be provided. Mandatory information.

• Glue records. The IP addresses of the name server names that belong to the delegated zone or below must be provided. They must not be looked up before the test starts. If not provided or only partly provided, the information will be treated as an incomplete delegation.

• DS records. If no DS records are provided, then it is assumed that there are no DS records for the zone. They must not be looked up.

• Name server addresses. Addresses of name server names that belong to the delegated zone is covered under "glue records" above. Addresses of other name servers may be provided, of else they are looked up. If at least one address (IPv4 or IPv6) is provided for a name server, then no further lookup shall be done for that name during the test (neither IPv4 nor IPv6).

The complete set of "NS records", the "Glue records" and the "DS records" is considered to be equivalent to what must be provided by the delegating zone, and replaces that, if the delegation exists. If the delegation does not exists, the provided set works as if the delegation existed.

The Name server addresses provided, if any, are considered to replace the real IP addresses for those name server names.

Test scenarios for verification of test case implementation

Table of contents

• Objective
• Test scenarios
• Test environment
• Naming conventions
  • Test zone names
  • Data outside the test zones
• Undelegated data
• Terminology

Objective

The purpose of the structure found here is to define test zones to be able to test the correctness of the implementation of the Zonemaster test cases. The main use case is to be the basis for the unit tests in the Zonemaster implementation. The second use case is to verify work in progress, e.g. implementation of new or updated test cases or updated test case implementation where the test case has not changed.

There can be other use cases, but only these two use cases are covered here and in the test zone specifications.

Test scenarios

The goal of the test scenarios is to cover all reasonable contexts where different message tags are outputted when a test case is run on test zones. The message tags are defined in the test case specifications found via "test cases" and the scenarios are defined in the test case specific specifications for test data found via the test-zones directory.

In the test zone specifications the scenarios are defined in two parts:

• What messages from test case that are expected to be outputted and what messages are expected not to be outputted when a test zone setup according to the scenario is tested by the test case.
• Specification of the zone setup for the scenario.

One special aspect is the test scenario name. Since the name is to be part of the test zone name there are some requirements on it:

• Under a specific test case there must not be two scenarios with the same name. Two closely related scenarios can, in their names, be separated with a relevant suffix.
• The length of the scenario name must not exceed 32 characters to give room for additional parts and still make sure it can fit into a DNS label.
• The character set of the name is limited to those of a host name, i.e. A-Z0-9- where A-Z will be downcased to a-z in the domain name.
• The scenario name must not start or end with -.

Test environment

The tests against the test zones are assumed to be run in a closed environment with a private DNS tree to achieve full access to any zone. Configuration data and instructions to set this up are available in the test-zone-data directory in this repository.

Naming conventions

In this document, domain names are given without trailing dot, except for the root zone (or node) given as a dot ..

The non-existing .xa TLD and its tree is used to host the target test zones, i.e. the zone name that will be given as Child Zone to the test case. All test zones are to be created under .xa except for a few cases elaborated below.

Unless specified in the test zone specification, DNS records that can be stored within the zone should also be stored there:

• MX records should point at the relative name mail and that name should be added to the zone.
• Name server names (NS record RDATA) should be in-bailiwick. "Prefixes" to be used are ns1, ns2, ns3 etc.

Test zone names

The normal test zone name is built from the following parts:

• .xa, the non-existing TLD used here.
• The test case identifier in lower case, e.g. zone09.
• The test scenario name in lower case, e.g. no-response-mx-query.

In the normal case, the test zone name is <scenario name>.<test case name>.xa, e.g. no-response-mx-query.zone09.xa. The normal case should be used as long as it is possible.

There are some exceptions to the name of the test zone that are identified here:

1. If the test zone is the root, then the name is ..
2. If the test zone is a TLD zone, then the name is <scenario name>-<test case name>. Note that hyphen "-" is used between the parts to create one label. E.g. no-mx-tld-zone09. In practice such a TLD can never be in conflict with real TLDs in the public DNS tree, especially since TLD names are not permitted to contain neither dash "-" nor digits.
3. If the test zone must be in the ARPA tree, then the name is <scenario name>.<test case name>.arpa, e.g. no-mx-arpa.zone09.arpa. In practice such a name will never be in conflict with names in the public DNS tree since there no such names under public .arpa.
4. If a scenario requires that the parent zone has different settings compared to other scenarios for the same test case, then the test zone name is child.<scenario name>.<test case name>.xa, e.g. child.no-response-mx-query.zone09.xa, where no-response-mx-query.zone09.xa, instead of zone09.xa, is the parent zone of the test zone.
5. If a scenario requires that the grandparent zone has different settings compared to other scenarios for the same test case, then the test zone name is child.parent.<scenario name>.<test case name>.xa, e.g. child.parent.no-response-mx-query.zone09.xa, where no-response-mx-query.zone09.xa, instead of zone09.xa, is the grandparent zone of the test zone.

Data outside the test zones

If a scenario requires that a certain name is outside its own zone, it should be stored within the .xb TLD (also a non-existing TLD) using the same name structure as under .xa, i.e. names for a scenario should be stored under <scenario name>.<test case name>.xb, e.g. no-mx-arpa.zone09.xb. If required test zones can be created in the same way under .xc and .xd.

What was stated above on data outside its own zone does not apply to reverse data since that must be stored in the in-addr.arpa or ip6.arpa tree, and the owner names of such data must follow the reverse data standards. There is no requirements for creating separate zones for in-addr.arpa or ip6.arpa or below.

Undelegated data

Some test scenarios require that an undelegated test be carried out on it. In that case, the scenario specification will contain a small "undelegated data" structure with one line per name server. The format is one of the following

• NAME-SERVER-NAME
• NAME-SERVER-NAME/IPv4
• NAME-SERVER-NAME/IPv6 where "NAME-SERVER-NAME" is the actual name of the name server, e.g. ns1a.del-non-distinct-und.delegation02.xa, and "IPv4" and "IPv6", respectively, are literal strings indicating that in the test zone configuration an IP address of that type should be used. If there is no "/IPv4" or "/IPv6" then the name server is given without IP address.

In the undelegated structure for a specific scenario the name server name can be repeated multiple times with different IP addresses. If it appears without IP address specification it should only appear once.

Here is an example of an undelegated data section from a scenario specification:

  * Undelegated data:
    * ns1a.del-non-distinct-und.delegation02.xa/IPv4
    * ns1a.del-non-distinct-und.delegation02.xa/IPv6
    * ns1b.del-non-distinct-und.delegation02.xa/IPv4
    * ns1b.del-non-distinct-und.delegation02.xa/IPv6

Terminology

• "Glue Record" - The term is used as defined in RFC 8499, section 7, pages 24-25.

• "In-Bailiwick" - The term is used as defined in RFC 8499, section 7, pages 24-25. In this document it is limited to the meaning "in domain" in the RFC.

• "Out-Of-Bailiwick" - The terms means, in this document, what is not "In-Bailiwick, in domain". RFC 8499, section 7, pages 24-25.

Specification of test zones for Basic-TP

Test zone specifications are available for:

• Basic01
• Basic02 not yet available
• Basic03 not yet available

Specification of test zones for Basic01

Table of contents

• Background
• Test Case
• Test scenarios
• Test zone names
• Test scenarios and message tags
• Zone setup for test scenarios

Background

See the test zone README file.

Test Case

This document specifies defined test zones for test case Basic01.

Test scenarios

The purpose of the test scenarios is to cover all reasonable contexts where different message tags are outputted when Basic01 is run on a test zone. The message tags are defined in the test case (Basic01) and the scenarios are defined below.

The test scenarios are structured as stated in the test zone README file.

Test zone names

The test zone for each test scenario in this document is a subdomain (or lower zone) delegated from the base name (basic01.xa) and that subdomain having the same name as the scenario. The names of those zones are given in section "Zone setup for test scenarios" below.

All tags

The test case can output any of these message tags, but not necessarily in any combination.

• B01_CHILD_FOUND
• B01_CHILD_IS_ALIAS
• B01_INCONSISTENT_ALIAS
• B01_INCONSISTENT_DELEGATION
• B01_NO_CHILD
• B01_PARENT_DISREGARDED
• B01_PARENT_FOUND
• B01_PARENT_NOT_FOUND
• B01_PARENT_UNDETERMINED
• B01_ROOT_HAS_NO_PARENT
• B01_SERVER_ZONE_ERROR

Test scenarios and message tags

If a message tag is not listed for the scenario, its presence or non-presence is irrelevant to the test scenario and must be ignored.

• (1) All tags except for those specified as "Forbidden message tags" (no instances for these test scenarios)
• (2) All tags except for those specified as "Mandatory message tags"

Zone setup for test scenarios

Assumptions for the scenario specifications unless otherwise specified for the specific scenario:

• The child zone is child.parent.SCENARIO.basic01.xa.
  • It is delegated to two name servers, ns1-delegated-child.basic01.xa and ns2-delegated-child.basic01.xa.
    • The name server names have A and AAAA records to avoid non-relevant error messages.
    • There is no zone file or zone data for the child zone.
  • If there is an undelegated "version" of the child zone, it is referred to ns3-undelegated-child.basic01.xa and ns4-undelegated-child.basic01.xa.
    • The name server names have A and AAAA records to avoid non-relevant error messages.
    • There is no zone file or zone data for the undelegated "version".
• The parent zone is parent.SCENARIO.basic01.xa.
  • It is served by two in-bailiwick NS (ns1 and ns2).
  • ns1 and ns2 have the same zone content.
  • ns1 and ns2 have both IPv4 and IPv6 glue.
  • The records matching glue in the zone are complete.
  • The delegation from the grand parent has the same NS with complete glue.
• The grandparent zone is SCENARIO.basic01.xa.
  • It is served by two in-bailiwick NS (ns1 and ns2).
  • ns1 and ns2 have the same zone content.
  • ns1 and ns2 have both IPv4 and IPv6 glue.
  • The records matching glue in the zone are complete.
  • The delegation from the SCENARIO zone has the same NS with complete glue.
• Responds with a A record for the zone on query for A.
• Responds with a AAAA record for the zone on query for AAAA.
• All responses are authoritative with RCODE Name "NoError"
• EDNS, version 0, is included in all responses on queries with EDNS.
• EDNS is not included in responses on queries without EDNS.
• Standard test zone root is used.
• In all cases, delegation and zone are consistent.
  • Same NS.
  • Any required glue matches address records in zone.
  • No extra address records for the NS names.

GOOD-1

A "happy path". Everything is fine.

• Zone: child.parent.good-1.basic01.xa

GOOD-MIXED-1

One grandparent server also serves parent zone.

• Zone: child.parent.good-mixed-1.basic01.xa
  • Parent zone parent.good-mixed-1.basic01.xa is served by ns1, ns2 and on ns4.good-mixed-1.basic01.xa.
  • Grandparent zone good-mixed-1.basic01.xa is served on ns1 and ns4.

GOOD-MIXED-2

One parent server also hosts the child zone.

• Zone: child.parent.good-mixed-2.basic01.xa
  • Child zone is served by ns1, ns2 and ns4.parent.good-mixed-2.basic01.xa.
  • Child zone exists.
  • There is a zone file for the child zone, and that is loaded on the child zone name servers.
  • Parent zone parent.good-mixed-2.basic01.xa is served by ns1 and ns4.

GOOD-PARENT-HOST-1

The child is hosted on parent servers only.

• Zone: child.parent.good-parent-host-1.basic01.xa
  • Child zone is served by ns1.parent.good-parent-host-1.basic01.xa and ns2.parent.good-parent-host-1.basic01.xa.
  • There is a zone file for the child zone.

GOOD-GRANDPARENT-HOST-1

The child is hosted on grandparent servers only.

• Zone: child.parent.good-grandparent-host-1.basic01.xa
  • Child zone is served by ns1.good-grandparent-host-1.basic01.xa and ns2.good-grandparent-host-1.basic01.xa.
  • There is a zone file for the child zone.

GOOD-UNDEL-1

The child zone is delegated, but there is also an undelegated version which is the one tested.

• Zone: child.parent.good-undel-1.basic01.xa
  • Child zone is delegated, but there is also an undelegated version.
  • There are no zone files for child (delegated or undelegated).
  • Undelegated data:
    • ns3-undelegated-child.basic01.xa
    • ns4-undelegated-child.basic01.xa

GOOD-MIXED-UNDEL-1

The child zone is delegated, but there is also an undelegated version which is the one tested. One grandparent server, in the delegated tree, also serves parent zone.

• Zone: child.parent.good-mixed-undel-1.basic01.xa
  • Parent zone parent.good-mixed-undel-1.basic01.xa is served by ns1, ns2 and on ns4.good-mixed-undel-1.basic01.xa.
  • Grandparent zone good-mixed-undel-1.basic01.xa is served on ns1 and ns4.
  • Child zone is delegated, but there is also an undelegated version.
  • No child zone exists.
  • Undelegated data:
    • ns3-undelegated-child.basic01.xa
    • ns4-undelegated-child.basic01.xa

GOOD-MIXED-UNDEL-2

The child zone is delegated, but there is also an undelegated version. One parent server also serves the delegated child zone.

• Zone: child.parent.good-mixed-undel-2.basic01.xa
  • Child zone is served by ns1, ns2 and ns6.parent.good-mixed-undel-2.basic01.xa.
  • Child zone exists.
  • Parent zone parent.good-mixed-undel-2.basic01.xa is served by ns1 and ns6.
  • Child zone is delegated, but there is also an undelegated version, but no zone for the undelegated version.
  • Undelegated data:
    • ns3-undelegated-child.basic01.xa
    • ns4-undelegated-child.basic01.xa

NO-DEL-UNDEL-1

The child zone is not delegated, but there is an undelegated version.

• Zone: child.parent.no-del-undel-1.basic01.xa
  • Undelegated data:
    • ns3-undelegated-child.basic01.xa
    • ns4-undelegated-child.basic01.xa

NO-DEL-MIXED-UNDEL-1

The child zone is not delegated, but there is an undelegated version that is tested. One grandparent server also serves the parent zone.

• Zone: child.parent.no-del-mixed-undel-1.basic01.xa
  • Parent zone parent.no-del-mixed-undel-1.basic01.xa is served by ns1, ns2 and on ns4.no-del-mixed-undel-1.basic01.xa.
  • Grandparent zone no-del-mixed-undel-1.basic01.xa is served on ns1 and ns4.
  • Child zone is not delegated, but there is an undelegated version, but no zone file.
  • Undelegated data:
    • ns3-undelegated-child.basic01.xa
    • ns4-undelegated-child.basic01.xa

NO-DEL-MIXED-UNDEL-2

The child zone is not delegated, but there is an undelegated version that is tested. One grandparent server also serves the parent zone. There are extra empty nodes between the zone cuts.

• Zone: child.w.x.parent.y.z.no-del-mixed-undel-2.basic01.xa
  • Parent zone parent.y.z.no-del-mixed-undel-2.basic01.xa is served by ns1, ns2 and on ns4.no-del-mixed-undel-2.basic01.xa.
  • Grandparent zone no-del-mixed-undel-2.basic01.xa is served on ns1 and ns4.
  • There are no zone cuts at w, x, y and z.
  • Child zone is not delegated, but there is also an undelegated version, but no zone file.
  • Undelegated data:
    • ns3-undelegated-child.basic01.xa
    • ns4-undelegated-child.basic01.xa

NO-CHILD-1

The child zone is not delegated. Parent zone returns NXDOMAIN.

• Zone: child.parent.no-child-1.basic01.xa
  • Child zone does not exist and is not served by any NS.

NO-CHILD-2

The child zone is not delegated. Parent zone returns NODATA.

• Zone: child.parent.no-child-2.basic01.xa
  • Child zone does not exist and is not served by any NS.
  • The name child.parent.no-child-2.basic01.xa exists as a TXT record.

NO-CHLD-PAR-UNDETER-1

The child zone is not delegated. One grandparent NS lacks delegation of parent and return NXDOMAIN of child. The parent zone lacks delegation of child.

• Zone: child.parent.no-chld-par-undeter-1.basic01.xa
  • Child zone does not exist is not served by any NS.
  • Grandparent ns1 lacks delegation of parent.
  • Grandparent ns2 has delegation of parent (to both parent NS).
  • Parent zone lacks delegation of child.

CHLD-FOUND-PAR-UNDET-1

The child zone is delegated from one grandparent NS and from the parent zone.

• Zone: child.parent.chld-found-par-undet-1.basic01.xa
  • Grandparent ns1 has delegation of child but lacks delegation of parent.
  • Grandparent ns2 has delegation of parent (to both parent NS).
  • Parent zone has delegation of child.

CHLD-FOUND-INCONSIST-1

The child is delegated from one parent NS. The other responds with NXDOMAIN.

• Zone: child.parent.chld-found-inconsist-1.basic01.xa
  • Parent ns1 has normal delegation of child to two child NS, ns1 and ns2.
  • Parent ns2 lacks delegation of child (NXDOMAIN).

CHLD-FOUND-INCONSIST-2

The child is delegated from one parent NS. On the other there is an CNAME response.

• Zone: child.parent.chld-found-inconsist-2.basic01.xa
  • Parent ns1 has normal delegation of child to two child NS, ns1 and ns2.
  • Parent ns2 lacks delegation of child, and has a CNAME on that name, pointing at no-child.parent.chld-found-inconsist-2.basic01.xa, which has two address records (A and AAAA) with the IP addresses of child ns2.

CHLD-FOUND-INCONSIST-3

The child is delegated from one parent NS. On the other there is a CNAME to another name, and that other name is delegated.

• Zone: child.parent.chld-found-inconsist-3.basic01.xa
  • Parent ns1 has normal delegation of child to two child NS, ns1 and ns2.
  • Parent ns2 lacks delegation of child, and has a CNAME on the name, pointing at sister.parent.chld-found-inconsist-3.basic01.xa, which is delegated to ns1-delegated-child.basic01.xa and ns2-delegated-child.basic01.xa.
  • Zone sister does not exist.

CHLD-FOUND-INCONSIST-4

The child is delegated from one parent NS. On the other there is a DNAME to another name.

• Zone: child.parent.chld-found-inconsist-4.basic01.xa
  • Parent ns1 has normal delegation of child to two child NS, ns1 and ns2.
  • Parent ns2 has a DNAME on child pointing at sister.parent.chld-found-inconsist-4.basic01.xa which is delegated to ns1-delegated-child.basic01.xa and ns2-delegated-child.basic01.xa.
  • Zone sister does not exist.

CHLD-FOUND-INCONSIST-5

The child is delegated from one parent NS. On the other there is a NODATA response.

• Zone: child.parent.chld-found-inconsist-5.basic01.xa
  • Parent ns1 has normal delegation of child to two child NS, ns1 and ns2.
  • Parent ns2 lacks delegation of child, instead child has two address records (A and AAAA) with the IP addresses of child ns2.

CHLD-FOUND-INCONSIST-6

The child is delegated from one parent NS, which is also NS for the child. On the other there is an NXDOMAIN response.

• Zone: child.parent.chld-found-inconsist-6.basic01.xa
  • Parent ns1 has normal delegation of child to the two child NS.
  • Parent ns2 lacks delegation of child (NXDOMAIN).
  • Child shares ns1.parent.chld-found-inconsist-6.basic01.xa with parent.
  • Child also uses child ns2.
  • Child exists with a zone.

CHLD-FOUND-INCONSIST-7

The child is delegated from one parent NS, which is also NS for the child. On the other there is a CNAME response.

• Zone: child.parent.chld-found-inconsist-7.basic01.xa
  • Parent ns1 has normal delegation of child to two child NS, ns1 and ns2.
  • Parent ns2 lacks delegation of child, and has a CNAME on that name, pointing at no-child.parent.chld-found-inconsist-7.basic01.xa, which has two address records (A and AAAA) with the IP addresses of child ns2.
  • Child shares ns1.parent.chld-found-inconsist-7.basic01.xa with parent.
  • Child also uses ns2.
  • Child exists with a zone.

CHLD-FOUND-INCONSIST-8

The child is delegated from one parent NS, which is also NS for the child. On the other there is a CNAME to another name, and that other name is delegated.

• Zone: child.parent.chld-found-inconsist-8.basic01.xa
  • Parent ns1 has normal delegation of child to two child NS, ns1 and ns2.
  • Parent ns2 lacks delegation of child, and has a CNAME on the name, pointing at sister.parent.chld-found-inconsist-8.basic01.xa, which is ns1-delegated-child.basic01.xa and ns2-delegated-child.basic01.xa.
  • Zone sister does not exist.
  • Child shares ns1.parent.chld-found-inconsist-8.basic01.xa with parent.
  • Child also uses ns2.
  • Child exists with a zone.

CHLD-FOUND-INCONSIST-9

The child is delegated from one parent NS, which is also NS for the child. On the other there is a DNAME to another name.

• Zone: child.parent.chld-found-inconsist-9.basic01.xa
  • Parent ns1 has normal delegation of child to two child NS, ns1 and ns2.
  • Parent ns2 has a DNAME on child pointing at sister.parent.chld-found-inconsist-9.basic01.xa which is delegated to ns1-delegated-child.basic01.xa and ns2-delegated-child.basic01.xa.
  • Zone sister does not exist.
  • Child shares ns1.parent.chld-found-inconsist-9.basic01.xa with parent.
  • Child also uses ns2.
  • Child exists with a zone.

CHLD-FOUND-INCONSIST-10

The child is delegated from one parent NS, which is also NS for the child. On the other there is a NODATA response.

• Zone: child.parent.chld-found-inconsist-10.basic01.xa
  • Parent ns1 has normal delegation of child to two child NS, ns1 and ns2.
  • Parent ns2 lacks delegation of child, instead child has two address records (A and AAAA) with the IP addresses of child ns2.
  • Child shares ns1.parent.chld-found-inconsist-10.basic01.xa with parent.
  • Child also uses ns2.
  • Child exists with a zone.

NO-DEL-UNDEL-NO-PAR-1

The child is not delegated, but there is undelegated data to test. Both grandparent NS return SERVFAIL.

• Zone: child.parent.no-del-undel-no-par-1.basic01.xa
  • Grandparent ns1 and ns2 both return SERVFAIL.
  • No need of parent zone.
  • Child zone is not delegated, but there is an undelegated version.
  • Undelgated data:
    • ns3-undelegated-child.basic01.xa
    • ns4-undelegated-child.basic01.xa

NO-DEL-UNDEL-PAR-UND-1

The child is not delegated, but there is an undelegated data to test. One grandparent NS lacks delegation of parent and return NXDOMAIN of child. The parent zone lacks delegation of child.

• Zone: child.parent.no-del-undel-par-und-1.basic01.xa
  • Child zone does not exist is not served by any NS.
  • Grandparent ns1 lacks delegation of parent.
  • Grandparent ns2 has delegation of parent (to both parent NS).
  • Parent zone lacks delegation of child.
  • Child zone is not delegated, but there is an undelegated version.
  • Undelegated data:
    • ns3-undelegated-child.basic01.xa
    • ns4-undelegated-child.basic01.xa

NO-CHLD-NO-PAR-1

The child is not delegated. Both grandparent NS return SERVFAIL.

• Zone: child.parent.no-chld-no-par-1.basic01.xa
  • Grandparent ns1 and ns2 both return SERVFAIL.
  • No need of parent zone.
  • Child zone is not delegated, and there is no undelegated data.
  • No need of child zone.

CHILD-ALIAS-1

The child zone does not exist, instead there is a DNAME in the parent zone.

• Zone: child.parent.child-alias-1.basic01.xa
  • Parent has a DNAME on child pointing at sister.parent.child-alias-1.basic01.xa which is delegated to ns1-delegated-child.basic01.xa and ns2-delegated-child.basic01.xa.
  • Zone sister does not exist.

CHILD-ALIAS-2

The child zone does not exist, instead there is a DNAME in the parent zone, however, different DNAME targets in the two parents.

• Zone: child.parent.child-alias-2.basic01.xa
  • On ns1 parent has a DNAME on child pointing at sister.parent.child-alias-2.basic01.xa which is delegated to ns1-delegated-child.basic01.xa and ns2-delegated-child.basic01.xa.
  • Zone sister does not exist.
  • On ns2 parent has a DNAME on child pointing at brother.parent.child-alias-2.basic01.xa which is delegated to ns1-delegated-child.basic01.xa and ns2-delegated-child.basic01.xa.
  • Zone brother does not exist.

ZONE-ERR-GRANDPARENT-1

Grandparent ns2 responds with AA bit unset on queries for grandparent zone.

• Zone: child.parent.zone-err-grandparent-1.basic01.xa
  • Normal response on grandparent ns1.
  • Grandparent ns2 responds with AA bit unset on queries for the grandparent zone.

ZONE-ERR-GRANDPARENT-2

Grandparent ns2 responds with NODATA on NS query for grandparent zone.

• Zone: child.parent.zone-err-grandparent-2.basic01.xa
  • Normal response on grandparent ns1.
  • Grandparent ns2 responds with NODATA on NS query for the grandparent zone.

ZONE-ERR-GRANDPARENT-3

Grandparent ns2 responds with wrong owner name on NS on query for grandparent zone NS.

• Zone: child.parent.zone-err-grandparent-3.basic01.xa
  • Normal response on grandparent ns1.
  • Grandparent ns2 responds with other owner name on NS query for zone-err-grandparent-3.basic01.xa:
    • Owner name oncle.zone-err-grandparent-3.basic01.xa instead.

ROOT-ZONE

Test on the standard root zone.

• Zone: .
  • No special zone files are to be created.

Specification of test zones for Consistency-TP

Test zone specifications are available for:

• CONSISTENCY05
• CONSISTENCY06

Specification of test zones for CONSISTENCY05

Table of contents

• Background
• Test Case
• Test scenarios
• Test zone names
• Test scenarios and message tags
• Zone setup for test scenarios

Background

See the test zone README file.

Test Case

This document specifies defined test zones for test case CONSISTENCY05.

Test scenarios

The purpose of the test scenarios is to cover all reasonable contexts where different message tags are outputted when CONSISTENCY05 is run on a test zone. The message tags are defined in the test case (CONSISTENCY05) and the scenarios are defined below.

The test scenarios are structured as stated in the test zone README file.

Test zone names

The test zone for each test scenario in this document is a subdomain delegated from the base name (consistency05.xa) and that subdomain having the same name as the scenario. The names of those zones are given in section "Zone setup for test scenarios" below.

Test scenarios and message tags

If a message tag is not listed for the scenario, its presence or non-presence is irrelevant to the test scenario and must be ignored.

Zone setup for test scenarios

Assumptions for the scenario specifications unless otherwise specified for the specific scenario:

• For each scenario zone there are two name servers configured.
  • Both NS (ns1 and ns2) are equal in delegation and in zone.
  • Both NS are in-bailiwick
  • Both NS have both IPv4 and IPv6 addresses
  • All required glue are present in the delegation.
  • All glue exactly matches the authoritative address records in correct zone (not more and not less records).
  • All NS IP addresses respond with identical zone content.
• Responds with a A record for the zone on query for A.
• Responds with a AAAA record for the zone on query for AAAA.
• All responses are authoritative with RCODE Name "NoError"
• EDNS, version 0, is included in all responses on queries with EDNS.
• EDNS is not included in responses on queries without EDNS.
• In undelegated data, IPv4 and IPv6, respectively, are placeholders for the actual IP addresses used for the scenario. They are to be found where the data is specified.
  • If no placeholder is given with the name server name, then no IP address is given and might be looked up.
  • The format for undelegated data follow the format used for zonemaster-cli (after --ns).

ADDRESSES-MATCH-1

The "happy path". Everything is fine.

• Zone: addresses-match-1.consistency05.xa

ADDRESSES-MATCH-2

Also the "happy path". Out-of-bailiwick NS this time. And no glue.

• Zone: addresses-match-2.consistency05.xa
  • Both ns1 and ns2 are out-of-bailiwick under the xb tree.
  • ns1 is "ns1.addresses-match-2.consistency05.xb"
  • ns2 is "ns2.addresses-match-2.consistency05.xb"
  • Delegation is without glue.
  • The zone has no address records for the NS names
  • The "addresses-match-2.consistency05.xb" zone has a full set of the address records for ns1 and ns2.

ADDRESSES-MATCH-3

One NS does not give AA answer, but else fine.

• Zone: addresses-match-3.consistency05.xa
  • ns1 responds with AA flag unset.

ADDRESSES-MATCH-4

One NS does give SERVFAIL response, but else fine.

• Zone: addresses-match-4.consistency05.xa
  • ns1 responds with RCODE Name "ServFail".

ADDRESSES-MATCH-5

One NS does not respond, but else fine.

• Zone: addresses-match-5.consistency05.xa
  • ns1 gives no response at all.

ADDRESSES-MATCH-6

Also "happy path". Out-of-bailiwick NS, but with glue.

• Zone: child.addresses-match-6.consistency05.xa
  • Both ns1 and ns2 are out-of-bailiwick
  • ns1 is "ns1.sibbling.addresses-match-6.consistency05.xa"
  • ns2 is "ns2.sibbling.addresses-match-6.consistency05.xa"
  • Delegation is with glue.
  • The test zone ("child") has no address records for the NS names, but the "sibbling" zone has full set of address records.

ADDRESSES-MATCH-7

Also "happy path". NS in subdomain.

• Zone: addresses-match-7.consistency05.xa
  • ns1 is "ns1.subdomain.addresses-match-7.consistency05.xa."
  • ns2 is "ns2.subdomain.addresses-match-7.consistency05.xa."
  • Delegation is with glue.
  • "subdomain.addresses-match-7.consistency05.xa" is delegated to the same ns1 and ns2.
  • ns1 and ns2 are defined with address records in the "subdomain" zone.

ADDR-MATCH-DEL-UNDEL-1

Also the "happy path". But there is an undelegated zone to be tested.

• Zone: addr-match-del-undel-1.consistency05.xa
  • Delegated zone on ns1 and ns2.
  • Undelegated zone on ns3 and ns4.
  • Delegated zone has neither ns1, ns2, ns3 nor ns4 as address records.
  • Undelegated zone has neither ns1 nor ns2 as an address record, but it has both ns3 and ns4 as address records.
  • Undelgated data:
    • ns3.addr-match-del-undel-1.consistency05.xa/IPv4
    • ns3.addr-match-del-undel-1.consistency05.xa/IPv6
    • ns4.addr-match-del-undel-1.consistency05.xa/IPv4
    • ns4.addr-match-del-undel-1.consistency05.xa/IPv6

ADDR-MATCH-DEL-UNDEL-2

Also the "happy path". But there is an undelegated zone to be tested, and its NS are out-of-bailiwick.

• Zone: addr-match-del-undel-2.consistency05.xa
  • Delegated zone on ns1 and ns2.
  • Undelegated zone on "ns3.addr-match-del-undel-2.consistency05.xb" and "ns4.addr-match-del-undel-2.consistency05.xb".
  • Delegated and undelegated zone, respectively, do not have neither ns1 nor ns2 as an address record.
  • Undelegated data:
    • ns3.addr-match-del-undel-2.consistency05.xb
    • ns4.addr-match-del-undel-2.consistency05.xb

ADDR-MATCH-NO-DEL-UNDEL-1

Also the "happy path". No delegation but there is an undelegated zone to be tested.

• Zone: addr-match-no-del-undel-1.consistency05.xa
  • No delegated zone.
  • Undelegated zone on ns1 and ns2.
  • Undelegated data:
    • ns1.addr-match-no-del-undel-1.consistency05.xa/IPv4
    • ns1.addr-match-no-del-undel-1.consistency05.xa/IPv6
    • ns2.addr-match-no-del-undel-1.consistency05.xa/IPv4
    • ns2.addr-match-no-del-undel-1.consistency05.xa/IPv6

ADDR-MATCH-NO-DEL-UNDEL-2

Also the "happy path". No delegation but there is an undelegated zone to be tested. NS are out-of-bailiwick.

• Zone: addr-match-no-del-undel-2.consistency05.xa
  • No delegated zone.
  • Undelegated zone on "ns3.addr-match-no-del-undel-2.consistency05.xb" and "ns4.addr-match-no-del-undel-2.consistency05.xb".
  • Undelegated data:
    • ns3.addr-match-no-del-undel-2.consistency05.xb
    • ns4.addr-match-no-del-undel-2.consistency05.xb

CHILD-ZONE-LAME-1

Lame. No NS responds.

• Zone: child-zone-lame-1.consistency05.xa
  • ns1 and ns2 do not respond.

CHILD-ZONE-LAME-2

Lame. One NS non-AA and one NS SERVFAIL.

• Zone: child-zone-lame-2.consistency05.xa
  • ns1 responses with AA bit unset.
  • ns2 responds with RCODE Name "ServFail".

IB-ADDR-MISMATCH-1

For one NS (in-bailiwick), the addresses in the glue do not match those in the authoritative data from the zone.

• Zone: ib-addr-mismatch-1.consistency05.xa
  • ns2 is defined in the zone, but with different addresses (IPv4 and IPv6), i.e. not the same as in glue.
  • Both ns2 servers (IP address sets from glue and child, respectively) must give identical DNS responses.

IB-ADDR-MISMATCH-2

For one NS (in-bailiwick), address records exist in the glue, but not in the authoritative data for the zone.

• Zone: ib-addr-mismatch-2.consistency05.xa
  • ns2 is not defined in the zone, i.e. there are no address records for ns2 (IPv4 or IPv6) in the zone.

IB-ADDR-MISMATCH-3

For ns2 (in-bailiwick), there is no NS for ns2 and the glue does not match any address records in the zone. Furthermore, ns2 does not respond.

• Zone: ib-addr-mismatch-3.consistency05.xa
  • There is no NS record with ns2 in RDATA.
  • ns2 is not defined in the zone, i.e. there are no address records for ns2 (IPv4 or IPv6) in the zone.
  • ns2 does not respond (but it is in the delegation)

IB-ADDR-MISMATCH-4

Both NS are in-bailiwick and exist with correct glue in the delegation, but there are no address records in the zone matching the glue records.

• Zone: ib-addr-mismatch-4.consistency05.xa
  • Neither ns1 nor ns2 are defined in the zone as address records.
  • The correct NS records are in the zone.

EXTRA-ADDRESS-CHILD

Child zone has one extra address record on the NS name.

• Zone: extra-address-child.consistency05.xa
  • The zone has address records for ns2 that match glue, but in addition the zone has extra A and AAAA records for ns2.
  • Both ns2 servers (both sets of IP addresses from child) must give identical DNS responses.

OOB-ADDR-MISMATCH

For one NS (out-of-bailiwick, but with glue) glue does not match AA address response.

• Zone: child.oob-addr-mismatch.consistency05.xa
  • Both ns1 and ns2 are out-of-bailiwick
  • ns1 is "ns1.sibbling.oob-addr-mismatch.consistency05.xa"
  • ns2 is "ns2.sibbling.oob-addr-mismatch.consistency05.xa"
  • Delegation is with glue.
  • The test zone ("child") has no address records for the NS names.
  • The "sibling" zone has full set of address records
  • ns1 in the "sibling" zone matches the addresses of glue.
  • ns2 in the "sibling" zone does not match the addresses of glue.
  • All IP addresses of ns1 and ns2 must serve identical versions of the zone.

Specification of test zones for CONSISTENCY06

Table of contents

• Background
• Test Case
• Test scenarios
• Test zone names
• Test scenarios and message tags
• Zone setup for test scenarios

Background

See the test zone README file.

Test Case

This document specifies defined test zones for test case CONSISTENCY06.

Test scenarios

The purpose of the test scenarios is to cover all reasonable contexts where different message tags are outputted when CONSISTENCY06 is run on a test zone. The message tags are defined in the test case (CONSISTENCY06) and the scenarios are defined below.

The test scenarios are structured as stated in the test zone README file.

Test zone names

The test zone for each test scenario in this document is a subdomain delegated from the base name (consistency06.xa) and that subdomain having the same name as the scenario. The names of those zones are given in section "Zone setup for test scenarios" below.

Test scenarios and message tags

If a message tag is not listed for the scenario, its presence or non-presence is irrelevant to the test scenario and must be ignored.

Zone setup for test scenarios

Assumptions for the scenario specifications unless otherwise specified for the specific scenario:

• For each scenario zone there are two name servers configured.
  • Both NS (ns1 and ns2) are equal in delegation and in zone.
  • Both NS are in-bailiwick
  • Both NS have both IPv4 and IPv6 addresses
  • All required glue are present in the delegation.
  • All NS IP addresses respond with identical zone content.
• All queries for SOA are responded with a SOA record in an authoritative answer.
• ns1 and ns2 respond with identical SOA records.
• All responses, to zone content, are authoritative with RCODE Name "NoError"
• EDNS, version 0, is included in all responses on queries with EDNS.
• EDNS is not included in responses on queries without EDNS.
• In undelegated data, IPv4 and IPv6, respectively, are placeholders for the actual IP addresses used for the scenario. They are to be found where the data is specified.
  • If no placeholder is given with the name server name, then no IP address is given and might be looked up.
  • The format for undelegated data follow the format used for zonemaster-cli (after --ns).

ONE-SOA-MNAME-1

The "happy path". Everything is fine.

• Zone: one-soa-mname-1.consistency06.xa.

ONE-SOA-MNAME-2

Not so "happy path". One name server does not respond.

• Zone: one-soa-mname-2.consistency06.xa.
  • ns1 gives no response at all.

ONE-SOA-MNAME-3

Not so "happy path". One name server responds without SOA

• Zone: one-soa-mname-3.consistency06.xa.
  • ns1 responds, but with no SOA record in the answer section (maybe answering but not having the zone).

ONE-SOA-MNAME-4

Not so "happy path". One name server does not respond. That ns is also missing in the zone.

• Zone: one-soa-mname-4.consistency06.xa.
  • ns2 gives no response at all.
  • ns2 is missing in the zone (but available in the delegation)

MULTIPLE-SOA-MNAMES-1

Different SOA MNAME on the servers

• Zone: multiple-soa-mnames-1.consistency06.xa.
  • MNAME in SOA on ns1 equal to ns1
  • MNAME in SOA on ns2 equal to ns2

MULTIPLE-SOA-MNAMES-2

Different SOA MNAME on two servers and a third not responding server

• Zone: multiple-soa-mnames-2.consistency06.xa.
  • MNAME in SOA on ns1 equal to ns1
  • MNAME in SOA on ns2 equal to ns2
  • Also delegated to ns3, for which there is no response.

MULT-SOA-MNAMES-NO-DEL-UNDEL-1

Zone not delegated, but there is an undelegated version. Different SOA MNAME on the servers.

• Zone: mult-soa-mnames-no-del-undel-1.consistency06.xa.
  • MNAME in SOA on ns1 equal to ns1
  • MNAME in SOA on ns2 equal to ns2
  • Undelegated data:
    • ns1.mult-soa-mnames-no-del-undel-1.consistency06.xa/IPv4
    • ns1.mult-soa-mnames-no-del-undel-1.consistency06.xa/IPv6
    • ns2.mult-soa-mnames-no-del-undel-1.consistency06.xa/IPv4
    • ns2.mult-soa-mnames-no-del-undel-1.consistency06.xa/IPv6

MULT-SOA-MNAMES-NO-DEL-UNDEL-2

Zone not delegated, but there is an undelegated version. Different SOA MNAME on the servers. NS are out-of-bailiwick.

• Zone: mult-soa-mnames-no-del-undel-2.consistency06.xa.
  • NS are out-of-bailiwick, "ns3.mult-soa-mnames-no-del-undel-2.consistency06.xb" and "ns4.mult-soa-mnames-no-del-undel-2.consistency06.xb".
  • MNAME in SOA on ns1 equal to ns1
  • MNAME in SOA on ns2 equal to ns2
  • Undelegated data:
    • ns3.mult-soa-mnames-no-del-undel-2.consistency06.xb
    • ns3.mult-soa-mnames-no-del-undel-2.consistency06.xb

NO-RESPONSE

No name server responds.

• Zone: no-response.consistency06.xa.
  • ns1 gives no response at all.
  • ns2 gives no response at all.

Specification of test scenarios for DNSSEC-TP

Test scenario specifications are available for:

• DNSSEC03
• DNSSEC10
• DNSSEC16

Specification of test zones for DNSSEC03

Table of contents

• Background
• Test Case
• Test scenarios
• Test zone names
• Test scenarios and message tags
• Zone setup for test scenarios
• Terminology

Background

See the test zone README file.

Test Case

This document specifies defined test zones for test case DNSSEC03.

Test scenarios

The purpose of the test scenarios is to cover all reasonable contexts where different message tags are outputted when DNSSEC03 is run on a test zone. The message tags are defined in the test case (DNSSEC03) and the scenarios are defined below.

The test scenarios are structured as stated in the test zone README file.

Test zone names

The test zone for each test scenario in this document is a subdomain delegated from the base name (dnssec03.xa) and that subdomain having the same name as the scenario except where the test domain must be the root zone, a TLD or a domain under .arpa. The names of those zones are given in section "Zone setup for test scenarios" below.

Test scenarios and message tags

If a message tag is not listed for the scenario, its presence or non-presence is irrelevant to the test scenario and must be ignored.

Zone setup for test scenarios

Assumptions for the scenario specifications, unless stated otherwise for the specific scenario:

1. Each zone is hosted by two NS, ns1 and ns2.
2. Both ns have equal hosting.
3. NS in delegation is equal to NS in zone.
4. All responses are authoritative.
5. RRSIG in responses are disregarded.
6. The actual owner name of the NSEC3 record will not be verified.
7. The record type list of the NSEC3 record will not be verified.
8. The zone is to respond with one SOA record with the zone name as owner name on SOA query.
9. The zone is to respond with one DNSKEY record with the zone name as owner name on DNSKEY query.
10. The zone is to respond with one NSEC3 record with a hash owner name in authority section on NSEC query (note, NSEC not NSEC3). NODATA response.
11. The NSEC3 record is to have the following settings:

• Hash algo = 1
• Flags = 0
• Iteration = 0
• Salt = "-" (no salt)

NO-DNSSEC-SUPPORT

No DNSSEC support in the zone.

• Zone: "no-dnssec-support.dnssec03.xa."
  • No DNSKEY in query for DNSKEY (9).

NO-NSEC3

No NSEC3 support in the zone.

• Zone: "no-nsec3.dnssec03.xa."
  • No NSEC3 in query for NSEC (10).

GOOD-VALUES

Happy path

• Zone: "good-values.dnssec03.xa."

ERR-MULT-NSEC3

Strange response with two NSEC3 records.

• Zone: "err-mult-nsec3.dnssec03.xa."
  • Two NSEC3 records, with different hash owner name are to be included in the response. RDATA can be identical. (10)

BAD-VALUES

The NSEC3 record has values no permitted by RFC 9276, see the specification of test case DNSSEC03.

• Zone: "bad-values.dnssec03.xa."
  • The following values in NSEC3 (11):
    • Hash algo = 2
    • Flags = 1
    • Iteration = 1
    • Salt = "8104"

INCONSISTENT-VALUES

The NSEC3 records returned from the two NS are not equal.

• Zone: "inconsistent-values.dnssec03.xa."
  • Both NS give the same owner name of the NSEC3 record, but ns1 gives standard values, whereas ns2 responds with an NSEC3 record with the following values: (2, 11)
    • Hash algo = 2
    • Flags = 1
    • Iteration = 1
    • Salt = "8104"

NSEC3-OPT-OUT-ENABLED-TLD

On a TLD, opt-out just gives an INFO message.

• Zone: "nsec3-opt-out-enabled-tld-dnssec03." (TLD)
  • NSEC3 record with the following value: (11)
    • Flags = 1

SERVER-NO-DNSSEC-SUPPORT

One NS of two does not support DNSSEC (no DNSKEY)

• Zone: "server-no-dnssec-support.dnssec03.xa"
  • ns2 does not return any DNSKEY record on DNSKEY query (2, 9)

SERVER-NO-NSEC3

One NS of two does not have NSEC3

• Zone: "server-no-nsec3.dnssec03.xa"
  • ns2 does not return any NSEC3 record on NSEC query (2, 10)

UNASSIGNED-FLAG-USED

Unassigned flag used.

• Zone: "unassigned-flag-used.dnssec03.xa"
  • NSEC3 record with the following value: (11)
    • Flags = 2

ERROR-RESPONSE-NSEC-QUERY

Error in response from one NS on NSEC query.

• Zone: "error-response-nsec-query.dnssec03.xa"
• Normal response on DNSKEY query from ns1.
• RCODE name SERVFAIL on NSEC query from ns1.
• Normal responses from ns2.

NO-RESPONSE-NSEC-QUERY

No response from one NS on NSEC query.

• Zone: "no-response-nsec-query.dnssec03.xa"
• Normal responses from ns1.
• Normal response on DNSKEY query from ns2.
• No response on NSEC query from ns2.

ERROR-NSEC-QUERY

No response and error in response on NSEC query, respectively, from two NS.

• Zone: "error-nsec-query.dnssec03.xa"
• Normal response on DNSKEY query from ns1 and ns2.
• RCODE name SERVFAIL on NSEC query from ns1.
• No response on NSEC query from ns2.

Specification of Test Scenarios for DNSSEC10

Table of contents

• Background
• Test Case
• Test scenarios
• Test zone names
• All message tags
• Test scenarios and message tags
• Test scenarios and setup of test zones

Background

See the test scenario README file.

Test Case

This document specifies defined test scenarios for test case DNSSEC10.

Test scenarios

The purpose of the test scenarios is to cover all reasonable contexts where different message tags are outputted when DNSSEC10 is run on a test zone. The message tags are defined in the test case (DNSSEC10) and the scenarios are defined below.

The test scenarios are structured as stated in the test scenario README file.

Test zone names

The test zone or zones for each test scenario in this document is a subdomain (or lower zone) delegated from the base name (dnssec10.xa) and that subdomain having the same name as the scenario. The names of those zones are given in section "Test scenarios and setup of test zones" below.

All message tags

The test case can output any of these message tags, but not necessarily in any combination. See DNSSEC10 for the specification of the tags.

• DS10_ALGO_NOT_SUPPORTED_BY_ZM
• DS10_ERR_MULT_NSEC
• DS10_ERR_MULT_NSEC3
• DS10_ERR_MULT_NSEC3PARAM
• DS10_EXPECTED_NSEC_NSEC3_MISSING
• DS10_HAS_NSEC
• DS10_HAS_NSEC3
• DS10_INCONSISTENT_NSEC
• DS10_INCONSISTENT_NSEC3
• DS10_INCONSISTENT_NSEC_NSEC3
• DS10_MIXED_NSEC_NSEC3
• DS10_NSEC3PARAM_GIVES_ERR_ANSWER
• DS10_NSEC3PARAM_MISMATCHES_APEX
• DS10_NSEC3PARAM_QUERY_RESPONSE_ERR
• DS10_NSEC3_ERR_TYPE_LIST
• DS10_NSEC3_MISMATCHES_APEX
• DS10_NSEC3_MISSING_SIGNATURE
• DS10_NSEC3_NODATA_MISSING_SOA
• DS10_NSEC3_NODATA_WRONG_SOA
• DS10_NSEC3_NO_VERIFIED_SIGNATURE
• DS10_NSEC3_RRSIG_EXPIRED
• DS10_NSEC3_RRSIG_NOT_YET_VALID
• DS10_NSEC3_RRSIG_NO_DNSKEY
• DS10_NSEC3_RRSIG_VERIFY_ERROR
• DS10_NSEC_ERR_TYPE_LIST
• DS10_NSEC_GIVES_ERR_ANSWER
• DS10_NSEC_MISMATCHES_APEX
• DS10_NSEC_MISSING_SIGNATURE
• DS10_NSEC_NODATA_MISSING_SOA
• DS10_NSEC_NODATA_WRONG_SOA
• DS10_NSEC_NO_VERIFIED_SIGNATURE
• DS10_NSEC_QUERY_RESPONSE_ERR
• DS10_NSEC_RRSIG_EXPIRED
• DS10_NSEC_RRSIG_NOT_YET_VALID
• DS10_NSEC_RRSIG_NO_DNSKEY
• DS10_NSEC_RRSIG_VERIFY_ERROR
• DS10_SERVER_NO_DNSSEC
• DS10_ZONE_NO_DNSSEC

Test scenarios and message tags

If a message tag is not listed for the scenario, its presence or non-presence is irrelevant to the test scenario and must be ignored.

• (1) All tags except for those specified as "Forbidden message tags" (no instances for these test scenarios)
• (2) All tags except for those specified as "Mandatory message tags"

Test scenarios and setup of test zones

Default zone configuration

Unless otherwise specified in the specific scenario specification, the test zone or zones for the scenario will follow the default setup as stated below. The child zone is the zone to be tested for the scenario.

• The child zone is SCENARIO.dnssec10.xa.
  • It is delegated to two name servers, ns1.SCENARIO.dnssec10.xa and ns2.SCENARIO.dnssec10.xa.
    • The name server names have A and AAAA records to avoid non-relevant error messages.
    • The delegation of the child zone is complete with glue records.
  • There is a zone file for the child zone.
  • All child zone servers give the same response.
  • The responses are either with NSEC record (NSEC zone) or NSEC3 record (NSEC3 zone), not mixed.
• The parent zone is dnssec10.xa.
  • It is served by two in-bailiwick NS (ns1 and ns2).
  • ns1 and ns2 have the same zone content.
  • ns1 and ns2 have both IPv4 and IPv6 glue.
  • The records matching glue in the zone are complete.
• If the child zone is an NSEC zone:
  • Responds with an NSEC response on the NSEC3PARAM query.
  • Responds with an NSEC record in answer section on the NSEC query.
• If the child zone is an NSEC3 zone:
  • Responds with an NSEC3 response on the NSEC query.
  • Responds with an NSEC3PARAM record in answer section on the NSEC3PARAM query.
• All responses will have the AA bit set.
• All responses will have the RCODE Name "NoError".

GOOD-NSEC-1

An NSEC zone and a "happy path". Everything is fine.

• Zone: good-nsec-1.dnssec10.xa

GOOD-NSEC3-1

An NSEC3 zone and a "happy path". Everything is fine.

• Zone: good-nsec3-1.dnssec10.xa

ALGO-NOT-SUPP-BY-ZM-1

An NSEC zone. Unknown algorithm of a DNSKEY.

• Zone: algo-not-supp-by-zm-1.dnssec10.xa
  • There is an extra RRSIG for the NSEC record (as the response to the NSEC3PARAM query).
    • That RRSIG has been created by algorithm 255, which is an unsupported private algorithm.
    • A matching DNSKEY (algorithm 255) is available.
    • For this test scenario a fake signature and a fake public key are used.
  • The extra DNSKEY is in the DNSKEY RRset which is resigned by the valid KSK.

ALGO-NOT-SUPP-BY-ZM-2

An NSEC3 zone. Unknown algorithm of a DNSKEY.

• Zone: algo-not-supp-by-zm-2.dnssec10.xa
  • There is an extra RRSIG for the NSEC3 record (as the response to the NSEC query).
    • That RRSIG has been created by algorithm 255, which is an unsupported private algorithm.
    • A matching DNSKEY (algorithm 255) is available.
  • For this test scenario a fake signature and a fake public key are used.
  • The extra DNSKEY is in the DNSKEY RRset which is resigned by the valid KSK.

ERR-MULT-NSEC-1

An NSEC zone. An extra NSEC record is returned on the NSEC3PARAM query.

• Zone: err-mult-nsec-1.dnssec10.xa
  • An extra NSEC record is returned in the response to the NSEC3PARAM query.
    • The extra NSEC record has the same owner name, but different value in "Next Domain Name" field.
  • RRSIG is recalculated.

ERR-MULT-NSEC-2

An NSEC zone. An extra NSEC record is returned on the NSEC query.

• Zone: err-mult-nsec-2.dnssec10.xa
  • An extra NSEC record is returned in the response to the NSEC query.
    • The extra NSEC record has the same owner name, but different value in "Type List" field.
  • RRSIG is recalculated.

ERR-MULT-NSEC3-1

An NSEC3 zone. An extra NSEC3 record is returned.

• Zone: err-mult-nsec3-1.dnssec10.xa
  • An extra NSEC3 record is returned in the response to the NSEC query.
    • The extra NSEC3 record has the same hash owner name, but different value in "Next Hashed Owner Name" field.
  • The NSEC3 RRset has been signed with a valid RRSIG.

ERR-MULT-NSEC3PARAM-1

An NSEC3 zone. An extra NSEC3PARAM record is returned.

• Zone: err-mult-nsec3param-1.dnssec10.xa
  • An extra NSEC3PARAM record is returned in the response to the NSEC query.
    • The extra NSEC3PARAM record has the same owner name, but different number of iterations.
  • The NSEC3PARAM RRset has been signed with a valid RRSIG.

EXP-NSEC-NSEC3-MISS-1

A zone without NSEC and NSEC3. There is no NSEC or NSEC3 function.

• Zone: exp-nsec-nsec3-miss-1.dnssec10.xa
  • The NSEC query gives a NODATA response with no NSEC or NSEC3 record.
  • The NSEC3PARAM query gives a NODATA response with no NSEC or NSEC3 record.

INCONSISTENT-NSEC-1

An NSEC zone. Some errors in NSEC handling.

• Zone: inconsistent-nsec-1.dnssec10.xa
  • ns1 includes no NSEC record in the NODATA response on the NSEC3PARAM query.
  • ns2 includes no NSEC record in the NODATA response on the NSEC query.

INCONSISTENT-NSEC3-1

An NSEC3 zone. Some errors in NSEC3 handling.

• Zone: inconsistent-nsec3-1.dnssec10.xa
  • ns1 includes no NSEC3 record in the NODATA response on the NSEC query.
  • ns2 includes no NSEC3PARAM or NSEC3 record in the NODATA response on the NSEC3PARAM query.

INCONSIST-NSEC-NSEC3-1

Mixing beteen NSEC and NSEC3.

• Zone: inconsist-nsec-nsec3-1.dnssec10.xa
  • ns1 holds an NSEC version of the zone.
  • ns2 holds an NSEC3 version of the zone.

INCONSIST-NSEC-NSEC3-2

NSEC on one server and NSEC3 on the other plus errors in NSEC and NSEC3 handling.

• Zone: inconsist-nsec-nsec3-2.dnssec10.xa
  • ns1 holds an NSEC version of the zone.
    • It responds with a NODATA respond without NSEC record on the NSEC3PARAM query.
    • It does respond with an NSEC record to the NSEC query.
  • ns2 holds an NSEC3 version of the zone.
    • It responds with a NODATA respond without NSEC3 record on the NSEC query.
    • It does respond with an NSEC3PARAM record to the NSEC3PARAM query.

MIXED-NSEC-NSEC3-1

Servers gives both NSEC and NSEC3

• Zone: mixed-nsec-nsec3-1.dnssec10.xa
  • The zone gives an NSEC record in response to NSEC query.
  • The zone gives an NSEC3PARAM record in response to the NSEC3PARAM query.

MIXED-NSEC-NSEC3-2

Servers gives both NSEC and NSEC3

• Zone: mixed-nsec-nsec3-2.dnssec10.xa
  • The zone gives a NODATA response with NSEC3 record in response to NSEC query.
  • The zone gives a NODATA response with NSEC record in response to the NSEC3PARAM query.

NSEC3PARAM-GIVES-ERR-ANSWER-1

An NSEC3 zone. Error in response to NSEC3PARAM query.

• Zone: nsec3param-gives-err-answer-1.dnssec10.xa
  • The zone gives a TXT record, but no NSEC3PARAM record, in response to the NSEC3PARAM query.

NSEC3PARAM-GIVES-ERR-ANSWER-2

An NSEC3 zone. Error in response to NSEC3PARAM query on ns1. No NSEC or NSEC3 on ns2.

• Zone: nsec3param-gives-err-answer-1.dnssec10.xa
  • On ns1, the zone gives a TXT record, but no NSEC3PARAM record, in response to the NSEC3PARAM query.
  • On ns2, the zone gives NODATA responses without NSEC or NSEC3 record for both the NSEC3PARAM query and the NSEC query.

NSEC3PARAM-MISMATCHES-APEX-1

An NSEC3 zone. The owner name of the NSEC3PARAM record is erroneous.

• Zone: nsec3param-mismatches-apex-1.dnssec10.xa
  • The owner name of the NSEC3PARAM record in response to the NSEC3PARAM query is erroneous and does not match apex.
    • The owner name is sub.nsec3param-mismatches-apex-1.dnssec10.xa instead of expected nsec3param-mismatches-apex-1.dnssec10.xa.

NSEC3PARAM-Q-RESPONSE-ERR-1

An NSEC3 zone. Error in response to NSEC3PARAM query.

• Zone: nsec3param-q-response-err-1.dnssec10.xa
  • No DNS response on the NSEC3PARAM query.

NSEC3PARAM-Q-RESPONSE-ERR-2

An NSEC3 zone. Error in response to NSEC3PARAM query.

• Zone: nsec3param-q-response-err-2.dnssec10.xa
  • The response on the NSEC3PARAM query has the RCODE Name "REFUSED".

NSEC3PARAM-Q-RESPONSE-ERR-3

An NSEC3 zone. Error in response to NSEC3PARAM query on ns1. No NSEC or NSEC3 on ns2.

• Zone: nsec3param-q-response-err-3.dnssec10.xa
  • The response from ns1 on the NSEC3PARAM query has the AA flag unset.
  • On ns2, the zone gives NODATA responses without NSEC or NSEC3 record for both the NSEC3PARAM query and the NSEC query.

NSEC3-ERR-TYPE-LIST-1

An NSEC3 zone. The type list of the NSEC3 record is erroneous.

• Zone: nsec3-err-type-list-1.dnssec10.xa
  • The type list of the NSEC3 record includes NSEC.

NSEC3-ERR-TYPE-LIST-2

An NSEC3 zone. The type list of the NSEC3 record is erroneous.

• Zone: nsec3-err-type-list-2.dnssec10.xa
  • The type list of the NSEC3 record misses RRSIG.

NSEC3-MISMATCHES-APEX-1

An NSEC3 zone. The hash owner name of the NSEC3 record is erroneous.

• Zone: nsec3-mismatches-apex-1.dnssec10.xa
  • The hash owner name of the NSEC3 record in response to the NSEC query is erroneous and does not match apex.

NSEC3-MISSING-SIGNATURE-1

An NSEC3 zone. The RRSIG is missing

• Zone: nsec3-missing-signature-1.dnssec10.xa
  • There is no RRSIG for the NSEC3 record in the response with NSEC3 record.

NSEC3-NODATA-MISSING-SOA-1

An NSEC3 zone. The SOA record is missing in the NODATA response.

• Zone: nsec3-nodata-missing-soa-1.dnssec10.xa
  • In the NODATA response to the NSEC query the SOA record is missing.

NSEC3-NODATA-WRONG-SOA-1

An NSEC3 zone. In the NODATA response the SOA record has the wrong owner name.

• Zone: nsec3-nodata-wrong-soa-1.dnssec10.xa
  • The owner name of the SOA record in the NODATA response to the NSEC query is sub.nsec3-nodata-wrong-soa-1.dnssec10.xa instead of expected nsec3-nodata-wrong-soa-1.dnssec10.xa.

NSEC3-NO-VERIFIED-SIGNATURE-1

An NSEC3 zone. The RRSIG for the NSEC3 record cannot be verified.

• Zone: nsec3-no-verified-signature-1.dnssec10.xa
  • The RRSIG record for the NSEC3 record in the NODATA response to the NSEC query cannot be verified.
    • There is no matching DNSKEY for the RRSIG for the NSEC3 record.

NSEC3-NO-VERIFIED-SIGNATURE-2

An NSEC3 zone. The RRSIG for the NSEC3 record cannot be verified.

• Zone: nsec3-no-verified-signature-2.dnssec10.xa
  • The RRSIG record for the NSEC3 record in the NODATA response to the NSEC query cannot be verified.
    • The RRSIG has expired, i.e. the current date-time is beyond the last valid date-time.

NSEC3-NO-VERIFIED-SIGNATURE-3

An NSEC3 zone. The RRSIG for the NSEC3 record cannot be verified.

• Zone: nsec3-no-verified-signature-3.dnssec10.xa
  • The RRSIG record for the NSEC3 record in the NODATA response to the NSEC query cannot be verified.
    • The RRSIG it not yet valid, i.e. the current date-time is before the first valid date-time.

NSEC3-NO-VERIFIED-SIGNATURE-4

An NSEC3 zone. The RRSIG for the NSEC3 record cannot be verified.

• Zone: nsec3-no-verified-signature-4.dnssec10.xa
  • The RRSIG record for the NSEC3 record in the NODATA response to the NSEC query cannot be verified.
    • The RRSIG signature does not match the NSEC record and appointed DNSKEY.

NSEC-ERR-TYPE-LIST-1

An NSEC zone. The type list of the NSEC record is erroneous.

• Zone: nsec-err-type-list-1.dnssec10.xa
  • The type list of the NSEC record includes NSEC3PARAM.

NSEC-ERR-TYPE-LIST-2

An NSEC zone. The type list of the NSEC record is erroneous.

• Zone: nsec-err-type-list-2.dnssec10.xa
  • The type list of the NSEC record misses RRSIG.

NSEC-GIVES-ERR-ANSWER-1

An NSEC zone. Error in response to NSEC query.

• Zone: nsec-gives-err-answer-1.dnssec10.xa
  • The zone gives a TXT record, but no NSEC record, in response to the NSEC query.

NSEC-GIVES-ERR-ANSWER-2

An NSEC zone. Error in response to NSEC query on ns1. No NSEC or NSEC3 on ns2.

• Zone: nsec-gives-err-answer-2.dnssec10.xa
  • On ns1, the zone gives a TXT record, but no NSEC record, in response to the NSEC query.
  • On ns2, the zone gives NODATA responses without NSEC or NSEC3 record for both the NSEC3PARAM query and the NSEC query.

NSEC-MISMATCHES-APEX-1

An NSEC zone. The owner name of the NSEC record is errouneous.

• Zone: nsec-mismatches-apex-1.dnssec10.xa
  • The owner name of the NSEC record in response to the NSEC3PARAM query is errouneous and does not match apex.
    • The owner name is sub.nsec-mismatches-apex-1.dnssec10.xa instead of expected nsec-mismatches-apex-1.dnssec10.xa.

NSEC-MISMATCHES-APEX-2

An NSEC zone. The owner name of the NSEC record is errouneous.

• Zone: nsec-mismatches-apex-2.dnssec10.xa
  • The owner name of the NSEC record in response to the NSEC query is errouneous and does not match apex.
    • The owner name is sub.nsec-mismatches-apex-2.dnssec10.xa instead of expected nsec-mismatches-apex-2.dnssec10.xa.

NSEC-MISSING-SIGNATURE-1

An NSEC zone. The RRSIG is missing.

• Zone: nsec-missing-signature-1.dnssec10.xa
  • There is no RRSIG for the NSEC record in the response with NSEC record on the NSEC3PARAM query.

NSEC-NODATA-MISSING-SOA-1

An NSEC zone. The SOA record is missing in the NODATA response.

• Zone: nsec-nodata-missing-soa-1.dnssec10.xa
  • In the NODATA response to the NSEC3PARAM query the SOA record is missing.

NSEC-NODATA-WRONG-SOA-1

An NSEC zone. In the NODATA response the SOA record has the wrong owner name.

• Zone: nsec-nodata-wrong-soa-1.dnssec10.xa
  • The owner name of the SOA record in the NODATA response to the NSEC3PARAM query is sub.nsec-nodata-wrong-soa-1.dnssec10.xa instead of expected nsec-nodata-wrong-soa-1.dnssec10.xa.

NSEC-NO-VERIFIED-SIGNATURE-1

An NSEC zone. The RRSIG for the NSEC record cannot be verified.

• Zone: nsec-no-verified-signature-1.dnssec10.xa
  • The RRSIG record for the NSEC record in the NODATA response to the NSEC3PARAM query cannot be verified.
    • There is no matching DNSKEY for the RRSIG for that NSEC record.

NSEC-NO-VERIFIED-SIGNATURE-2

An NSEC zone. The RRSIG for the NSEC record cannot be verified.

• Zone: nsec-no-verified-signature-2.dnssec10.xa
  • The RRSIG record for the NSEC record in the NODATA response to the NSEC3PARAM query cannot be verified.
    • The RRSIG has expired, i.e. the current date-time is beyond the last valid date-time.

NSEC-NO-VERIFIED-SIGNATURE-3

An NSEC zone. The RRSIG for the NSEC record cannot be verified.

• Zone: nsec-no-verified-signature-3.dnssec10.xa
  • The RRSIG record for the NSEC record in the NODATA response to the NSEC3PARAM query cannot be verified.
    • The RRSIG it not yet valid, i.e. the current date-time is before the first valid date-time.

NSEC-NO-VERIFIED-SIGNATURE-4

An NSEC zone. The RRSIG for the NSEC record cannot be verified.

• Zone: nsec-no-verified-signature-4.dnssec10.xa
  • The RRSIG record for the NSEC record in the NODATA response to the NSEC3PARAM query cannot be verified.
    • The RRSIG signature does not match the RRSIG record and appointed DNSKEY.

NSEC-QUERY-RESPONSE-ERR-1

An NSEC zone. Error in response to NSEC query.

• Zone: nsec-query-response-err-1.dnssec10.xa
  • No DNS response on the NSEC query.

NSEC-QUERY-RESPONSE-ERR-2

An NSEC zone. Error in response to NSEC query.

• Zone: nsec-query-response-err-2.dnssec10.xa
  • The response on the NSEC query has the RCODE Name "REFUSED".

NSEC-QUERY-RESPONSE-ERR-3

An NSEC zone. Error in response to NSEC query on ns1. No NSEC or NSEC3 in responses from ns2.

• Zone: nsec-query-response-err-3.dnssec10.xa
  • The response from ns1 on the NSEC query has the AA flag unset.
  • On ns2, the zone gives NODATA responses without NSEC or NSEC3 record for both the NSEC3PARAM query and the NSEC query.

SERVER-NO-DNSSEC-1

An NSEC zone. No DNSKEY in response from ns1. Normal response from ns2.

• Zone: server-no-dnssec-1.dnssec10.xa
  • The answer section in response from ns1 on the DNSKEY query is empty. Unsigned NODATA response without NSEC or NSEC3.
  • The NSEC and NSEC3PARAM queries are irrelevant, but they also give a Unsigned NODATA response without NSEC or NSEC3 on ns1.

SERVER-NO-DNSSEC-2

An NSEC3 zone. No DNSKEY in response from ns1. Normal response from ns2.

• Zone: server-no-dnssec-2.dnssec10.xa
  • The answer section in response from ns1 on the DNSKEY query is empty. Unsigned NODATA response without NSEC or NSEC3.
  • The NSEC and NSEC3PARAM queries are irrelevant, but they also give a Unsigned NODATA response without NSEC or NSEC3 on ns1.

ZONE-NO-DNSSEC-1

No DNSKEY in response.

• Zone: zone-no-dnssec-1.dnssec10.xa
  • The answer section in response on the DNSKEY query is empty. Unsigned NODATA response without NSEC or NSEC3.
  • The NSEC and NSEC3PARAM queries are irrelevant, but they also give a Unsigned NODATA response without NSEC or NSEC3.

Specification of test zones for DNSSEC16

Table of contents

• Background
• Test Case
• Test scenarios
• Test zone names
• Test scenarios and message tags
• Zone setup for test scenarios
• Terminology

Background

See the test zone README file.

Test Case

This document specifies defined test zones for test case DNSSEC16.

Test scenarios

The purpose of the test scenarios is to cover all reasonable contexts where different message tags are outputted when DNSSEC16 is run on a test zone. The message tags are defined in the test case (DNSSEC16) and the scenarios are defined below.

The test scenarios are structured as stated in the test zone README file.

Test zone names

The test zone for each test scenario in this document is a subdomain delegated from the base name (dnssec16.xa) and that subdomain having the same name as the scenario except where the test domain must be the root zone, a TLD or a domain under .arpa. The names of those zones are given in section "Zone setup for test scenarios" below.

Test scenarios and message tags

If a message tag is not listed for the scenario, its presence or non-presence is irrelevant to the test scenario and must be ignored.

Zone setup for test scenarios

Assumptions for the scenario specifications:

• Only CDS or DNSKEY records in apex are considered.
• Unless stated otherwise, all name servers respond authoritatively with RCODE Name "NoError" on all queries.
• Unless stated otherwise, all name servers respond authoritatively with (or without) CDS records on CDS queries and DNSKEY records on DNSKEY queries, respectively.
• Unless stated otherwise, all RRSIGs are present where expected and are valid.
• Each zone is served by two nameservers and both respond consistently.
• No DS record is published at parent zone (dnssec16.xa).

CDS-INVALID-RRSIG

• Zone: "cds-invalid-rrsig.dnssec16.xa."
  • The zone has a Well Formed DNSKEY Record (key 1).
  • The zone has one Well Formed CDS Record, that matches key 1, but the RRSIG of the CDS RRset has expired.

CDS-MATCHES-NO-DNSKEY

• Zone: "cds-matches-no-dnskey.dnssec16.xa."
  • The zone has one Well Formed DNSKEY Record (key 1).
  • The zone has one Well Formed CDS Record that matches key 1.
  • The zone has a second Well Formed CDS Record that matches no key by key tag.

CDS-MATCHES-NON-SEP-DNSKEY

• Zone: "cds-matches-non-sep-dnskey.dnssec16.xa."
  • The zone has a Well Formed DNSKEY Record, but flag bit 15 is unset (key 1).
  • The zone has one Well Formed CDS Record that matches key 1.

CDS-MATCHES-NON-ZONE-DNSKEY

• Zone: "cds-matches-non-zone-dnskey.dnssec16.xa."
  • The zone has one Well Formed DNSKEY Record (key 1).
  • The zone has a second Well Formed DNSKEY Record, but flag bit 7 is unset and the key has not signed the DNSKEY RRset (key 2).
  • The zone has one Well Formed CDS Record and matches key 1 (CDS 1).
  • The zone has a second Well Formed CDS Record, matching key 2, but the key has not signed the CDS RRset.

CDS-NOT-SIGNED-BY-CDS

• Zone: "cds-not-signed-by-cds.dnssec16.xa."
  • The zone has two Well Formed DNSKEY Record (key 1 and 2).
  • The zone has one Well Formed CDS Record that matches key 1.
  • The zone has a second Well Formed CDS Record that matches key 2, but its DNSKEY has not signed the CDS RRset.

CDS-SIGNED-BY-UNKNOWN-DNSKEY

• Zone: "cds-signed-by-unknown-dnskey.dnssec16.xa."
  • The zone has a Well Formed DNSKEY Record (key 1).
  • The zone has one Well Formed CDS Record, and it matches key 1.
  • The CDS RRset has an additional RRSIG that matches no DNSKEY by key tag.

CDS-UNSIGNED

• Zone: "cds-unsigned.dnssec16.xa."
  • The zone has a Well Formed DNSKEY Record (key 1).
  • The zone has one Well Formed CDS Record, and it matches key 1, but the CDS RRset is not signed.

CDS-WITHOUT-DNSKEY

• Zone: "cds-without-dnskey.dnssec16.xa."
  • The zone has no DNSKEY.
  • The zone has one Well Formed CDS Record that matches no DNSKEY.

DELETE-CDS

• Zone: "delete-cds.dnssec16.xa."
  • The zone has a Well Formed DNSKEY Record.
  • The zone has one CDS RR that is a Delete CDS.

DNSKEY-NOT-SIGNED-BY-CDS

• Zone: "dnskey-not-signed-by-cds.dnssec16.xa."
  • The zone has a Well Formed DNSKEY Record (key 1), but the key has not signed the DNSKEY RRset.
  • The zone has one Well Formed CDS Record, and it matches key 1.

MIXED-DELETE-CDS

• Zone: "mixed-delete-cds.dnssec16.xa."
  • The zone has a Well Formed DNSKEY Record (key 1).
  • The zone has one Well Formed CDS Record, and it matches key 1.
  • The zone has a second CDS RR that is a Delete CDS.

NO-CDS

• Zone: "no-cds.dnssec16.xa."
  • The name servers give no CDS RRset on CDS query (NODATA).

NOT-AA

• Zone: "not-aa.dnssec16.xa."
  • The name servers give non-AA response on CDS queries.

VALID-CDS

• Zone: "valid-cds.dnssec16.xa."
  • The zone has a Well Formed DNSKEY Record (key 1).
  • The zone has one Well Formed CDS Record, and it matches key 1.

Terminology

• "Well Formed DNSKEY Record" - The term is used, in this document, for a DNSKEY record that meets the following requirements:

  • It is a DNSKEY record in apex.
  • It uses algorithm 10 (RSA/SHA-512) with a 2048-bit key length, see DNSSEC05 and DNSSEC14.
  • Flag bit 7 (zone key) and bit 15 (SEP) are set.
  • The DNSKEY RRset has been signed by the key and the RRSIG is valid.

• "Well Formed CDS Record" - The term is used, in this document, for a CDS record that meets the following requirements:

  • It is a CDS record in apex.
  • It uses hash digest 2 (SHA-256), see DNSSEC01.
  • Its digest is a digest of a Well Formed DNSKEY Record.
  • The CDS RRset has been signed by the its DNSKEY and the RRSIG is valid.

Specification of test scenarios for Delegation-TP

Test scenario specifications are available for:

• Delegation01
• Delegation02
• Delegation03

Specification of test Scenarios for Delegation01

Table of contents

• Background
• Test Case
• Test scenarios
• Test zone names
• All message tags
• Test scenarios and message tags
• Test zone setup

Background

See the test scenario README file.

Test Case

This document specifies test scenarios for test case Delegation01.

Test scenarios

The purpose of the test scenarios is to cover all reasonable contexts where different message tags are output when Delegation01 is run on a test zone. The message tags are defined in the test case (Delegation01) and the scenarios are defined below.

The test scenarios are structured as stated in the test scenario README file.

Test zone names

The test zone for each test scenario in this document is a subdomain delegated from the base name (delegation01.xa) and that subdomain having the same name as the scenario. The names of those zones are given in section Test zone setup below.

All message tags

The test case can output any of these message tags, but not necessarily in any combination. See Delegation01 for the specification of the tags.

• ENOUGH_IPV4_NS_CHILD
• ENOUGH_IPV4_NS_DEL
• ENOUGH_IPV6_NS_CHILD
• ENOUGH_IPV6_NS_DEL
• ENOUGH_NS_CHILD
• ENOUGH_NS_DEL
• NOT_ENOUGH_IPV4_NS_CHILD
• NOT_ENOUGH_IPV4_NS_DEL
• NOT_ENOUGH_IPV6_NS_CHILD
• NOT_ENOUGH_IPV6_NS_DEL
• NOT_ENOUGH_NS_CHILD
• NOT_ENOUGH_NS_DEL
• NO_IPV4_NS_CHILD
• NO_IPV4_NS_DEL
• NO_IPV6_NS_CHILD
• NO_IPV6_NS_DEL

Test scenarios and message tags

If a message tag is not listed for the scenario, its presence or non-presence is irrelevant to the test scenario and must be ignored.

1) All tags except for those specified as "Forbidden message tags" (no instances for these test scenarios)

2) All tags except for those specified as "Mandatory message tags"

Test zone setup

Assumptions for the scenario specifications unless otherwise specified for the specific scenario:

• For each scenario zone there are two name servers configured.
  • Both name servers (ns1 and ns2) are equal in delegation and in zone.
  • Both name servers are in-bailiwick.
  • Both name servers have both IPv4 and IPv6 addresses.
  • All required glue records are present in the delegation.
  • All glue exactly match the authoritative address records in correct zone (not more and not less records).
  • All name server IP addresses respond with identical zone content.

ENOUGH-1

This is the main happy path.

• Zone: enough-1.delegation01.xa

ENOUGH-2

This is also a happy path. Out-of-bailiwick.

• Zone: enough-2.delegation01.xa
  • Both ns1 and ns2 are out-of-bailiwick.
    • ns1 is "ns1.enough-2.delegation01.xb"
    • ns2 is "ns2.enough-2.delegation01.xb"
  • Delegation is without glue.
  • The test zone ("child") has no address records for the name server names.
  • The "delegation01.xb" zone has the full set of address records.

ENOUGH-3

This is also a happy path. Also out-of-bailiwick, but with sibling glue.

• Zone: enough-3.delegation01.xa
  • Both ns1 and ns2 are out-of-bailiwick
    • ns1 is "ns1.enough-3.sibling.delegation01.xa"
    • ns2 is "ns2.enough-3.sibling.delegation01.xa"
  • Delegation is with glue.
  • The child zone has no address records for the name server names.
  • The two name servers are defined directly in the parent zone with full set of address records.

ENOUGH-DEL-NOT-CHILD

Only one name server in child zone.

• Zone: enough-del-not-child.delegation01.xa
  • The child zone defines only one name server, ns1.
  • Delegation is complete.

ENOUGH-CHILD-NOT-DEL

Only one name server in delegation.

• Zone: enough-child-not-del.delegation01.xa
  • The delegation has only one name server, for ns1.
  • The child has two name servers with full set of address records.

IPV6-AND-DEL-OK-NO-IPV4-CHILD

No IPv4 in zone.

• Zone: ipv6-and-del-ok-no-ipv4-child.delegation01.xa
  • No A records for ns1 and ns2 in zone.
  • Delegation is complete.

IPV4-AND-DEL-OK-NO-IPV6-CHILD

No IPv6 in zone.

• Zone: ipv4-and-del-ok-no-ipv6-child.delegation01.xa
  • No AAAA records for ns1 and ns2 in zone.
  • Delegation is complete.

NO-IPV4-1

No IPv4 in delegation or zone.

• Zone: no-ipv4-1.delegation01.xa
  • No A glue for ns1 and ns2.
  • No A records in zone for ns1 and ns2.

NO-IPV4-2

No IPv4 in delegation or zone. Out-of-bailiwick name servers and no glue.

• Zone: no-ipv4-2.delegation01.xa
  • Both ns1 and ns2 are out-of-bailiwick under the xb tree.
    • ns1 is "ns1.no-ipv4-2.delegation01.xb"
    • ns2 is "ns2.no-ipv4-2.delegation01.xb"
  • Delegation is without glue.
  • The test zone ("child") has no address records for the name server names
  • The "delegation01.xb" zone has full set of address records for this.
    • AAAA only, not A

NO-IPV4-3

No IPv4 in delegation or zone. Out-of-bailiwick name servers, but with sibling glue.

• Zone: no-ipv4-3.delegation01.xa
  • Both ns1 and ns2 are out-of-bailiwick
    • ns1 is "ns1.no-ipv4-3.sibling.delegation01.xa"
    • ns2 is "ns2.no-ipv4-3.sibling.delegation01.xa"
  • Delegation is with glue.
  • The child zone has no address records for the name server names
  • The sibling names have full sets of address records.
    • AAAA only, not A.

NO-IPV6-1

No IPv6 in delegation or zone.

• Zone: no-ipv6-1.delegation01.xa
  • No AAAA glue for ns1 and ns2.
  • No AAAA records in zone for ns1 and ns2.

NO-IPV6-2

No IPv6 in delegation or zone. Out-of-bailiwick name servers and no glue.

• Zone: no-ipv6-2.delegation01.xa
  • Both ns1 and ns2 are out-of-bailiwick under the xb tree.
    • ns1 is "ns1.no-ipv6-2.delegation01.xb"
    • ns2 is "ns2.no-ipv6-2.delegation01.xb"
  • Delegation is without glue.
  • The test zone ("child") has no address records for the name servers names
  • The "delegation01.xb" zone has full set of address records for this.
    • A only, not AAAA

NO-IPV6-3

No IPv6 in delegation or zone. Out-of-bailiwick name servers, but with sibling glue.

• Zone: no-ipv6-3.delegation01.xa
  • Both ns1 and ns2 are out-of-bailiwick
    • ns1 is "ns1.no-ipv6-3.sibling.delegation01.xa"
    • ns2 is "ns2.no-ipv6-3.sibling.delegation01.xa"
  • Delegation is with glue.
  • The child zone has no address records for the name server names
  • The sibling names has full set of address records.
    • A only, not AAAA.

MISMATCH-DELEGATION-CHILD-1

Missing glue, only IPv4 on ns1 and only IPv6 on ns2.

• Zone: mismatch-delegation-child-1.delegation01.xa
  • Only IPv4 glue on ns1.
  • Only IPv6 glue on ns2.
  • Full set in zone.

MISMATCH-DELEGATION-CHILD-2

The zone has only IPv4 on ns1 and only IPv6 on ns2.

• Zone: mismatch-delegation-child-2.delegation01.xa
  • Only IPv4 on ns1 in zone.
  • Only IPv6 on ns2 in zone.
  • Full set in delegation.

Specification of test Scenarios for Delegation02

Table of contents

• Background
• Test Case
• Test scenarios
• Test zone names
• All message tags
• Test scenarios and message tags
• Test zone setup

Background

See the test scenario README file.

Test Case

This document specifies test scenarios for test case Delegation02.

Test scenarios

The purpose of the test scenarios is to cover all reasonable contexts where different message tags are output when Delegation02 is run on a test zone. The message tags are defined in the test case (Delegation02) and the scenarios are defined below.

The test scenarios are structured as stated in the test scenario README file.

Test zone names

The test zone for each test scenario in this document is a subdomain delegated from the base name (delegation02.xa) and that subdomain having the same name as the scenario. The names of those zones are given in section Test zone setup below.

All message tags

The test case can output any of these message tags, but not necessarily in any combination. See Delegation02 for the specification of the tags.

• DEL_DISTINCT_NS_IP
• CHILD_DISTINCT_NS_IP
• DEL_NS_SAME_IP
• CHILD_NS_SAME_IP

Test scenarios and message tags

If a message tag is not listed for the scenario, its presence or non-presence is irrelevant to the test scenario and must be ignored.

1) All tags except for those specified as "Forbidden message tags" (no instances for these test scenarios)

2) All tags except for those specified as "Mandatory message tags"

Test zone setup

Assumptions for the scenario specifications unless otherwise specified for the specific scenario:

• For each scenario zone there are two name servers configured.
  • Both name servers (ns1 and ns2) are equal in delegation and in zone.
  • Both name servers are in-bailiwick.
  • Both name servers have both IPv4 and IPv6 addresses.
  • All addresses are distinct.
  • All required glue are present in the delegation.
  • All glue exactly matches the authoritative address records in correct zone (not more and not less records).
  • All name server IP addresses respond with identical zone content.

ALL-DISTINCT-1

This is the happy path.

• Zone: all-distinct-1.delegation02.xa

ALL-DISTINCT-2

This is also a happy path. Out-of-bailiwick.

• Zone: all-distinct-2.delegation02.xa
  • Both ns1 and ns2 are out-of-bailiwick under the xb tree.
    • ns1 is "ns1.all-distinct-2.delegation02.xb"
    • ns2 is "ns2.all-distinct-2.delegation02.xb"
  • Delegation is without glue.
  • The test zone has no address records for the name server names.
  • The "delegation02.xb" zone has full set of address records for this scenario.

ALL-DISTINCT-3

This is also a happy path. Also out-of-bailiwick, but with sibling glue.

• Zone: all-distinct-3.delegation02.xa
  • Both ns1 and ns2 are out-of-bailiwick
    • ns1 is "ns1.all-distinct-3.sibling.delegation02.xa"
    • ns2 is "ns2.all-distinct-3.sibling.delegation02.xa"
  • Delegation is with glue.
  • The test zone ("child") has no address records for the name server names.
  • The "delegation02.xa" zone has full set of address records for this scenario.

DEL-NON-DISTINCT

The glue records use the same IP addresses.

• Zone: del-non-distinct.delegation02.xa
  • The name servers are ns1a and ns1b
    • ns1a and ns1b in the delegation (glue) have the same IPv4 and IPv6 addresses, respectively.
    • ns1a and ns1b have distinct addresses in the zone (IPv4 and IPv6, respectively).

DEL-NON-DISTINCT-UND

The glue records use the same IP addresses. The zone is undelegated.

• Zone: del-non-distinct-und.delegation02.xa
  • The zone is undelegated.
  • name servers are ns1a and ns1b
    • ns1a and ns1b in the delegation (glue) have the same IPv4 and IPv6 addresses, respectively.
    • ns1a and ns1b have distinct addresses in the zone (IPv4 and IPv6, respectively).
  • Undelegated data:
    • ns1a.del-non-distinct-und.delegation02.xa/IPv4
    • ns1a.del-non-distinct-und.delegation02.xa/IPv6
    • ns1b.del-non-distinct-und.delegation02.xa/IPv4
    • ns1b.del-non-distinct-und.delegation02.xa/IPv6

CHILD-NON-DISTINCT

The address records in the zone use the same IP addresses.

• Zone: child-non-distinct.delegation02.xa
  • name servers are ns1a and ns1b
    • ns1a and ns1b in the delegation (glue) have distinct addresses (IPv4 and IPv6, respectively).
    • ns1a and ns1b have the same addresses in the zone, IPv4 and IPv6, respectively.

CHILD-NON-DISTINCT-UND

The address records in the zone use the same IP addresses.

• Zone: child-non-distinct-und.delegation02.xa
  • The zone is undelegated.
  • name servers are ns1a and ns1b
    • ns1a and ns1b in the delegation (glue) have distinct addresses (IPv4 and IPv6, respectively).
    • ns1a and ns1b have the same addresses in the zone, IPv4 and IPv6, respectively.
  • Undelegated data:
    • ns1a.child-non-distinct-und.delegation02.xa/IPv4
    • ns1a.child-non-distinct-und.delegation02.xa/IPv6
    • ns1b.child-non-distinct-und.delegation02.xa/IPv4
    • ns1b.child-non-distinct-und.delegation02.xa/IPv6

NON-DISTINCT-1

The address records in both delegation and zone use the same IP addresses.

• Zone: non-distinct-1.delegation02.xa
  • name servers are ns1a, ns1b and ns2
    • ns1a and ns1b in the delegation (glue) have the same IPv4 and IPv6 addresses, respectively.
    • ns1a and ns1b have the same addresses in the zone, IPv4 and IPv6, respectively.
    • ns2 has a distinct address both in delegation and in zone.

NON-DISTINCT-2

The name servers in both delegation and zone refer to the same IP addresses. The names are out-of-bailiwick.

• Zone: non-distinct-2.delegation02.xa
  • name servers are ns1a, ns1b and ns2, and are out-of-bailiwick under the xb tree.
    • ns1a is "ns1a.non-distinct-2.delegation02.xb"
    • ns1b is "ns1a.non-distinct-2.delegation02.xb"
    • ns2 is "ns2.non-distinct-2.delegation02.xb"
  • Delegation is without glue.
  • ns1a and ns1b have the same addresses, IPv4 and IPv6, respectively.
  • ns2 has distinct addresses (IPv4 and IPv6).
  • The test zone has no address records for the name server names.
  • The "delegation02.xb" zone has full set of address records for this scenario.

NON-DISTINCT-3

The name servers in both delegation and zone refer to the same IP addresses. The names are out-of-bailiwick, but with sibling glue.

• Zone: non-distinct-3.delegation02.xa
  • name servers are ns1a, ns1b and ns2, and are out-of-bailiwick.
    • ns1a is "ns1a.non-distinct-3.sibling.delegation02.xa"
    • ns1b is "ns1a.non-distinct-3.sibling.delegation02.xa"
    • ns2 is "ns2.non-distinct-3.sibling.delegation02.xa"
  • Delegation has sibling glue.
  • ns1a and ns1b have the same addresses, IPv4 and IPv6, respectively.
  • ns2 has distinct addresses (IPv4 and IPv6).
  • The test zone has no address records for the name server names.
  • The "delegation02.xa" zone has full set of address records for this scenario.

Specification of test Scenarios for Delegation03

Table of contents

• Background
• Test Case
• Test scenarios
• Test zone names
• All message tags
• Test scenarios and message tags
• Test zone setup

Background

See the test scenario README file.

Test Case

This document specifies test scenarios for test case Delegation03.

Test scenarios

The purpose of the test scenarios is to cover all reasonable contexts where different message tags are output when Delegation03 is run on a test zone. The message tags are defined in the test case (Delegation03) and the scenarios are defined below.

The test scenarios are structured as stated in the test scenario README file.

Test zone names

The test zone for each test scenario in this document is a subdomain delegated from the base name (delegation03.xa) and that subdomain having the same name as the scenario. The names of those zones are given in section Test zone setup below.

All message tags

The test case can output any of these message tags, but not necessarily in any combination. See Delegation03 for the specification of the tags.

• REFERRAL_SIZE_OK
• REFERRAL_SIZE_TOO_LARGE

Test scenarios and message tags

If a message tag is not listed for the scenario, its presence or non-presence is irrelevant to the test scenario and must be ignored.

1) All tags except for those specified as "Forbidden message tags" (no instances for these test scenarios)

2) All tags except for those specified as "Mandatory message tags"

Test zone setup

Assumptions for the scenario specifications unless otherwise specified for the specific scenario:

• For each scenario zone there are two name server configured.
  • Both name servers are in-bailiwick.
  • Both name servers have both IPv4 and IPv6 addresses.
  • All addresses are distinct.
  • All required glue are present in the delegation.
  • There is no actual zone or zone file, only a delegation.
    • For these scenarios only the delegation is needed.

REFERRAL-SIZE-OK-1

This is the happy path.

• Zone: referral-size-ok-1.delegation03.xa.

REFERRAL-SIZE-OK-2

Referral is large, but not too large. The name servers are in-bailiwick.

• Zone: referral-size-ok-2.delegation03.xa.
  • ns1 is "ns1.ipv4-large-but-not-too-large.referral-size-ok-2.delegation03.xa".
  • ns1 is "ns1.ipv6-large-but-not-too-large.referral-size-ok-2.delegation03.xa".
  • ns2 is "ns2.ipv4-large-but-not-too-large.referral-size-ok-2.delegation03.xa".
  • ns2 is "ns2.ipv6-large-but-not-too-large.referral-size-ok-2.delegation03.xa".

REFERRAL-SIZE-TOO-LARGE-1

Referral is too large and name servers are in-bailiwick.

• Zone: referral-size-too-large-1.delegation03.xa
  • Name server names are relative to the zone name:
    • ns1 is "ns1.1abcdefghijklmnopqrstuv.1defghijkl"
    • ns2 is "ns2.2abcdefghijklmnopqrstuv.2defghijkl"
    • ns3 is "ns3.2abcdefghijklmnopqrstuv.3defghijkl"
    • ns4 is "ns4.2abcdefghijklmnopqrstuv.4defghijkl"
    • ns5 is "ns5.2abcdefghijklmnopqrstuv.5defghijkl"

REFERRAL-SIZE-TOO-LARGE-2

Referral is too large and name servers are out-of-bailiwick with no glue.

• Zone: referral-size-too-large-2.delegation03.xa
  • The zone is delegated to ns1, ns2, ns3 and ns4.
    • ns1 is "ns1.1abcdefghijklmnopqrstuvwxyz.1abcdefghijklmnopqrstuvwxy.1abcdefghijklmnopqrstuvw.referral-size-too-large-2.delegation03.xb"
    • ns2 is "ns2.2abcdefghijklmnopqrstuvwxyz.2abcdefghijklmnopqrstuvwxy.2abcdefghijklmnopqrstuvw.referral-size-too-large-2.delegation03.xb"
    • ns3 is "ns3.3abcdefghijklmnopqrstuvwxyz.3abcdefghijklmnopqrstuvwxy.3abcdefghijklmnopqrstuvw.referral-size-too-large-2.delegation03.xb"
    • ns4 is "ns4.4abcdefghijklmnopqrstuvwxyz.4abcdefghijklmnopqrstuvwxy.4abcdefghijklmnopqrstuvw.referral-size-too-large-2.delegation03.xb"
  • Delegation is without glue.
  • The test zone has no address records for the name server names.
  • The "delegation03.xb" zone has full set of address records (IPv4 and IPv6).

Specification of test zones for Nameserver-TP

Test zone specifications are available for:

• NAMESERVER11
• NAMESERVER15

Specification of test zones for NAMESERVER11

Table of contents

• Background
• Test Case
• Test scenarios
• Test zone names
• Test scenarios and message tags
• Zone setup for test scenarios

Background

See the test zone README file.

Test Case

This document specifies defined test zones for test case NAMESERVER11.

Test scenarios

The purpose of the test scenarios is to cover all reasonable contexts where different message tags are outputted when NAMESERVER11 is run on a test zone. The message tags are defined in the test case (NAMESERVER11) and the scenarios are defined below.

The test scenarios are structured as stated in the test zone README file.

Test zone names

The test zone for each test scenario in this document is a subdomain delegated from the base name (nameserver11.xa) and that subdomain having the same name as the scenario. The names of those zones are given in section "Zone setup for test scenarios" below.

Test scenarios and message tags

If a message tag is not listed for the scenario, its presence or non-presence is irrelevant to the test scenario and must be ignored.