CloudHost/zonemaster.es
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add full Zonemaster stack with Docker and Spanish UI

Browse Source 
- Clone all 5 Zonemaster component repos (LDNS, Engine, CLI, Backend, GUI)
- Dockerfile.backend: 8-stage multi-stage build LDNS→Engine→CLI→Backend
- Dockerfile.gui: Astro static build served via nginx
- docker-compose.yml: backend (internal) + frontend (port 5353)
- nginx.conf: root redirects to /es/, /api/ proxied to backend
- zonemaster-gui/config.ts: defaultLanguage set to 'es' (Spanish)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Malin
2026-04-21 08:19:24 +02:00
commit 8d4eaa1489
1567 changed files with 204155 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
zonemaster/docs/README-for-doc.zonemaster.net.md Normal file
View File

@@ -0,0 +1,53 @@
<!-- This document replaces public/README.md on doc.zonemaster.net -->
# Public documentation
# ![Zonemaster][Zonemaster-logo]
<!-- The text below has been taken from the Introduction section in main README and
should be kept in sync with the source. -->
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 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 [The Swedish Internet Foundation].
A public instance is running on [zonemaster.net].
<!-- The text below has been copied from public/README.md and should be kept in
sync with the source -->
The public documentation is divided into the following main categories:
* [Release information](RELEASE.md) gives release information of latest release.
* [Installation](installation/README.md) contains documents that explain how to
install the different components of Zonemaster.
* [Upgrading](upgrading/README.md) contains documents that explain how to upgrade
a Zonemaster installation.
* [Configuration](configuration/README.md) contains documents that explain how a
Zonemaster installation can be configured.
* [Using](using/README.md) contains user guides to the different components of
Zonemaster.
* [Specifications](specifications/README.md) contains specifications of the
Zonemaster test cases, test types and test zones.
* [Development](development/README.md) contains information for developers both
in and outside the Zonemaster project.
* [License](LICENSE.md) gives the license information for Zonemaster.
[AFNIC]: https://www.afnic.fr/en/
[The Swedish Internet Foundation]: https://internetstiftelsen.se/en/
[Zonemaster.net]: https://zonemaster.net
<!-- Location on doc.zonemaster.net: -->
[Zonemaster-logo]: ../zonemaster_logo_2021_color.png

19
zonemaster/docs/README.md Normal file
View File

@@ -0,0 +1,19 @@
# Documentation
In this repository, most documentation of Zonemaster is found.
* [public] - In the public documentation you will find installation instructions,
user guides for each Zonemaster component and other documentation.
* [internal] - In the internal tree you can find documentation regarding the
design and requirements of the Zonemaster implementation.
* [Contact and Mailing lists] - Information on forum and mailing lists for
Zonemaster.
The [public] documentation can be built using [mdbook]. See
[public/README][public] for details.
[Contact and Mailing lists]: contact-and-mailing-lists.md
[Internal]: ./internal
[mdbook]: https://rust-lang.github.io/mdBook/
[Public]: ./public/README.md

82
zonemaster/docs/contact-and-mailing-lists.md Normal file
View File

@@ -0,0 +1,82 @@
# Contact and Mailing lists
An [open discussion forum] can be found at Github. You are welcome to ask your
question there or join the mailing list and ask it there.
## Mailing lists
The Zonemaster project offer two public mailing lists with
different goals:
* zonemaster-announce
* zonemaster-users
### zonemaster-announce
The goal of `zonemaster-announce` is to provide a low-volume
mailing list for announcements from the Zonemaster project. Mainly
it is used to announce that a new Zonemaster release has been
published, but also to report on severe security problems.
The members of the list are not able to post any messages to the
list. This is for one-way communication only.
To sign-up on the list, go to
https://lists.iis.se/postorius/lists/zonemaster-announce.lists.iis.se/
### zonemaster-users
The goal of `zonemaster-users` is to provide a forum for discussions
between and questions from Zonemaster users. The users in this sense
are mainly those that have installed some part of the code. That
could either be for evaluation on a small virtual server or a
full-fledged installation of all parts for public use or anything
in between.
The members of the Zonemaster working group are also on list and can
reply to questions and participate in discussions.
The members of the list can post messages to the list, but those
must of course be relevant and respectful.
To sign-up on the list, go to
https://lists.iis.se/postorius/lists/zonemaster-users.lists.iis.se/
## Questions on problems with a domain name
If you have problem with your domain name, we can unfortunately not
help you solving the issue. Zonemaster can hopefully point out what
is wrong, but to have that issue resolved, you have to turn to
your DNS operator.
If Zonemaster does not report when there is a DNS error, or if
Zonemaster falsely reports an error, then we are very interested
to hear from you.
## Contacting the Zonemaster project
The best way to contact the Zonemaster project, besides using the
mailing list, is to create an issue in the GitHub issue tracker
for the Zonemaster repositories. That could be pure questions, but also
bug reports or suggestions for improvements.
* [Issues in Zonemaster::LDNS]
* [Issues in Zonemaster::Engine]
* [Issues in Zonemaster::CLI]
* [Issues in Zonemaster::Backend]
* [Issues in zonemaster::GUI]
If you cannot determine which repository to create the issue in, please
select the main Zonemaster repository (i.e.
[general issues in Zonemaster][Issues in Zonemaster]).
If you cannot use any of the methods above, due to the subject matter, please
send an e-mail to zonemaster@zonemaster.net.
[Issues in Zonemaster::Backend]: https://github.com/zonemaster/zonemaster-backend/issues
[Issues in Zonemaster::CLI]: https://github.com/zonemaster/zonemaster-cli/issues
[Issues in Zonemaster::Engine]: https://github.com/zonemaster/zonemaster-engine/issues
[Issues in Zonemaster::LDNS]: https://github.com/zonemaster/zonemaster-ldns/issues
[Issues in Zonemaster]: https://github.com/zonemaster/zonemaster/issues
[Issues in zonemaster::GUI]: https://github.com/zonemaster/zonemaster-gui/issues
[Open discussion forum]: https://github.com/orgs/zonemaster/discussions

73
zonemaster/docs/internal/design/Architecture Notes.md Normal file
View File

@@ -0,0 +1,73 @@
# Testing Library
This is the central part of the whole system, that actually performs DNS tests and evaluates the results.
Conceptually, the library is divided into three layers: objects that model the underlying DNS reality we're looking at, objects that look at the DNS information, perform tests on it and evaluate the results, and finally structural objects needed for the first two layers to work.
A certain amount of global state is kept (in order to make sure the zone and nameserver object caches are complete). If more than one test is run in the same process, it may or may not be desirable to clear the cache between tests.
## Design Goals
Our experience with earlier designs of tools for testing and verification of DNS leads us to consider the following attributes important in such a system.
1. Accuracy
The results reported by a testing tool must accurately reflect the reality the tool sees. This may at times make reported results difficult to interpret, and it is tempting to have the system do automated interpretation. It is useful to have a layer that helps a non-technical users understand what is being reported, but such a layer must be a high level and it must be possible for an expert user to get an unfiltered view of the results. For the results to be consistently accurate, it is also important that the tests be well defined and the software well tested.
2. Repeatability
To the largest extent possible, immediately successive probes of the same target should give the same results. Perfect repeatability cannot be achieved since the reality of the Internet is complex and changes constantly, but no randomness or unpredictability should be added by the testing tool itself.
3. Traceability
It must be possible to tell exactly what sequence of DNS responses led to a certain result being reported by the tool. The ingenuity of humans is endless, and there will always be excentric, unusual and/or faulty configurations and servers out there that we haven't seen before. When we encounter a new thing for the first time, it should be possible to examine it in detail.
Notably *not* on this list is performance. It is of course important that tests be executed as quickly as possible, but speed must not come at the cost of any of the listed characteristics. Experience also tells us that DNS testing software spends the vast majority of its time waiting for responses from nameservers, and that thus the most useful thing we can do to speed tests up is to reduce the number of questions we send to the absolute minimum. Which, conveniently enough, usually also helps make the results accurate, repeatable and traceable.
## DNS-Modeling Layer
This layer has two main types of objects.
### Zone Object
A zone is identified by its name. In a running program, there is always at most one object for every zone. A zone object contains, among other things, pointers to its parent zone, its authoritative nameservers (as listed by those nameservers themselves), the nameserves listed for it in the parent zone, and the glue address records the parent zone holds for it.
### Nameserver Object
A nameserver is identified by its name and IP address, and like for zone objects there will only be one object for each such pair. All DNS queries made by the program go through a nameserver object, and the object will cache the response to every unique query, in order to minimize the number of queries sent in total (this caching may be made by IP address alone).
## Testing Layer
This layer holds the main entry point to the testing system, where as the most basic case one can enter a domain name and run all available tests. There is a single top-level object for every complete set of tests run, holding information such as the times when the test was started and ended, as well as the results of all performed subtests.
The function of the top-level testing object is:
1. To create the zone object for the zone to be tested.
2. To perform basic tests on the zone to determine if it is possible to perform more complex tests (basically checking that the zone exists and has nameservers).
3. Load all available test modules.
4. Run requested tests in the loaded modules (by default, all tests in all modules).
5. Provide a way for tests in one loaded module to execute tests in other modules if they're available.
The tests themselves are, as indicated above, implemented as plugin modules. The modules must provide some specified methods, providing metadata about their function as well as the ability to have tests executed and their results returned.
## Structural Layer
### DNS Recursor Object
We have our own recursor in order to be able to observe and manipulate the recursion process. The main thing we want to be able to do is to see which domain delegates directly to the zone being tested, and to be able to perform tests on domains which are not yet published into the global DNS tree (undelegated tests).
### Log Entry Object
Object used to record atomic pieces of information from tests.
### Logger Object
Object used to collect Log Entry Objects from a test run, assign severity levels to single Log Entry Objects and translate them into human-readable text in various languages.
### Configuration Object
Read configuration from suitable sources and make it available to the rest of the system.
### Information Object
An object through which a user can read meta-information about the system. This should include (but not necessarily be limited to) information on which tests are available, which messages can be emitted, which translations are available and the message-to-severity mapping policy in effect.

66
zonemaster/docs/internal/design/Implementation Guidelines.md Normal file
View File

@@ -0,0 +1,66 @@
# Guidelines to implementing tests with Zonemaster
Zonemaster is a Perl framework meant to aid the implementation of DNS tests. The design of the framework is based primarily on IIS's experiences with the DNSCheck tool and the top-level-domain Pre-Delegation Testing platform. This document aims to present the rationales for the various design decisions in Zonemaster.
## Goals of the system as a whole
All design decisions are intended to contribute toward one or more of a number of overall goals. These are, in rough order of descending importance:
1. Correctness
First and foremost, the results produced by tests must be _correct_. By correct here we mean that they accurately implement the specification for a given test, and that they can be verified to do so by a competent observer.
2. Predictability
Given an identical view of the outside world, the test must always give the exact same result. There must be nothing random or arbitrary in the implementation (or the specification).
3. Transparency
We should be able to tell after the fact why a test produced the result it did. It is acceptable for this to require re-running a test with settings that record more detailed (and thus voluminous) information, but in the extreme case it should be possible to go back and look at the details of every single incoming DNS packet in order to figure out why something strange happened.
4. Modifiability
We should be able to modify the test's view of the outside world. The must common use for this is to test zones that have not yet been delegated from their intended parents.
## Looking at Zonemaster with the goals in mind
In the Zonemaster framework, tests are implemented in plugin modules. These modules must have a method called `all`, which takes a _zone object_ as its single argument. This object represents the entire outside world for the tests. Test code must never communicate with the outside world (like for example nameservers) except via the methods in the zone object.
### The zone object is the world
By forcing all communication to pass through a single chokepoint, we serve all of the goals listed above. For example, the `query_one` method makes sure to always send queries to the same child-side server (the first one in lexicographic order by stringified name). The query methods also have the ability to transparently store incoming packets for future inspection, and it will have the ability to answer queries with pre-loaded information instead of sending them out into the world (which makes it vastly easier to write unit tests for the testing code). And by having all this functionality hidden away in another object, the test code itself can be written in a more straightforward way, which in turn makes it easier to determine if it is correct.
### Zonemaster packet and record objects have helpers
The less code there is, the easier it is to determine if it actually does what it should. When writing DNS tests, there are certain actions that come up often. In order to reduce the amount of code implementing the tests themselves, we extract such actions into helper methods in the objects representing DNS packets and (possibly in the future) resource records.
The intention is that as often occurring patterns are found, they will be extracted out into surrounding objects. As a rule of thumb, I'd suggest that once a certain structure has been needed in three or more places, extracting it out should be considered.
## Implementation guidelines
### Returning information from tests, the theory
There are basically two levels at which a user is interested in the result of a test: only the plain results, or the results plus intermediate and debugging information created during the testing process. They way this separation is intended to work in Zonemaster is by a test implementation creating log entry objects for all information that might be interesting, but only return a list of the ones representing actual test results to the caller. The other ones will be kept track of by the framework, and a user can ask to get them if and when they so desire. So a user who is only interested in the results will run the test(s) and get the results as a list of log entry objects as the return value. A user who has more complex needs can ask the framework to also get the rest of the log entries.
### Test Policy
It is recommended, although not required, that each test case be implemented as its own method. What _is_ required is that a test module check with the global configuration that a certain test case should be executed before it does so.
### Code formatting
The top level of the Zonemaster git repository contains `.perltidyrc`, a config file for [Perl::Tidy]. Please use it before you push, make a pull request or otherwise send code outside of your own repository.
### Code style
The top level of the Zonemaster git repository also contains `.perlcriticrc`, a config file for [Perl::Critic]. Strive to make your code free from warnings on at least levels 4 and 5 before you send it out into the world.
### Exposing test metadata
### Returning information from tests, the practice
(to be continued)
[Perl::Critic]: https://metacpan.org/pod/Perl::Critic
[Perl::Tidy]: https://metacpan.org/pod/Perl::Tidy

52
zonemaster/docs/internal/design/Profiles.md Normal file
View File

@@ -0,0 +1,52 @@
# Profiles
## Overview
Profiles is a configuration format and feature of Zonemaster Engine.
Each of Zonemaster CLI, Backend and GUI allow users and administrators to configure Zonemaster Engine with different profiles.
This document provides a high-level view of how profiles are applied across the different Zonemaster components.
For details on how profiles integrate with a given component, refer to the respective component documentations.
Links to the relevant sections are provided below.
## Background
The Zonemaster requirements and specification documents speak of user-configurable profiles and policies
for Zonemaster Engine and CLI.
In release v2018.2 all of the configurable features "config", "filter", "policy" and "profile" from the
requirements and specifications were integrated into a single data structure, also called "profile".
## Profiles in Zonemaster Engine
Zonemaster Engine has an effective profile that guides how it performs its tests and analyzes their results.
It comes with a sensible default profile while allowing applications to override the default behavior.
This is described in greater detail in the [Zonemaster::Engine::Profile] documentation.
## Profiles in Zonemaster Backend
Zonemaster Backend allows its administrators to configure available profiles for its users to choose from.
Configuration is described in greater detail in the [Zonemaster Backend configuration] documentation.
The [Zonemaster Backend RPC-API] documentation lists methods that accept profile name arguments.
## Profiles in Zonemaster CLI
Zonemaster CLI allows users to specify the path to a profile to be used when starting a test.
If no profile is specified, the Zonemaster Engine default profile is used.
## Profiles in Zonemaster GUI
Zonemaster GUI allows the user select profile from a set of choices.
The available profile choices are configured in a JSON file that maps profile name strings to description strings.
-------
[Zonemaster Backend RPC-API]: ../../public/using/backend/rpcapi-reference.md
[Zonemaster Backend configuration]: ../../public/configuration/backend.md#public-profiles-and-private-profiles-sections
[Zonemaster::Engine::Profile]: https://metacpan.org/pod/Zonemaster::Engine::Profile

28
zonemaster/docs/internal/design/README.md Normal file
View File

@@ -0,0 +1,28 @@
# README
## Overview
This directory contains documentation relating to the architecture of the
Zonemaster components and how they interact to achieve the desired result.
## Contents
* [Architecture Notes.md]
TBD
* [Implementation Guidelines.md]
TBD
* [Profiles.md]
Profiles is a configuration format and feature of Zonemaster Engine.
Each of Zonemaster CLI, Backend and GUI allow users and administrators to configure Zonemaster Engine with different profiles.
* [Versions and Releases.md]
TBD
[Architecture Notes.md]: Architecture%20Notes.md
[Implementation Guidelines.md]: Implementation%20Guidelines.md
[Profiles.md]: Profiles.md
[Versions and Releases.md]: Versions%20and%20Releases.md

120
zonemaster/docs/internal/design/Versions and Releases.md Normal file
View File

@@ -0,0 +1,120 @@
# Versions and Releases
## Introduction
This document is intended to specify the semantics of the versions numbers used for the Zonemaster Product and its
components. There are two different version schema, one for the Zonemaster Product, and one for its components.
The main Zonemaster Repository ([Zonemaster]) stores the specifications
and documentation for the Zonemaster Product. There is no direct code for Zonemaster in that repository. The Zonemaster
components are part of the Zonemaster Product, but stored in separate repositories
([Zonemaster-LDNS], [Zonemaster-Engine], [Zonemaster-CLI], [Zonemaster-Backend] and [Zonemaster-GUI].
This document also discusses how the Zonemaster project intend to do new releases.
## Version Number Syntax for Zonemaster product
Published version numbers of the Zonemaster Product (stored in the main repository, i.e. [Zonemaster]) are in format
_vYYYY.I.i_, where
* "v" is the literal character,
* "YYYY" is the year of the creation of the release in four digits,
* "." is the literal dot, and
* "I" and "i" are integer counters starting with 1.
* "I" or "i" (not both) is incremented for each release unless "YYYY" is incremented.
* If "YYYY" is incremented, then "I" is reset to 1 and "i" is omitted.
* If "I" is incremented, then ".i" omitted, e.g. from _v2016.1.2_ to _v2016.2_.
* If "i" is incremented, then "I" remains the same as the previous version, e.g. from _v2016.1.1_ to _v2016.1.2_.
* "I" can be incremented even if there is no ".i", e.g. from _v2016.3_ to _v2016.4_.
The product version is normally incremented with the "i" only, e.g. from _v2016.3_ to _v2016.3.1_, when no component has
been updated on major or minor version. If any component has been updated on major or minor version, then the "YYYY" or
"I" must be updated in the product version.
### Versioning principle
A specific version of the Zonemaster Product includes, besides specifications and other documents, a specific
version of each of the Zonemaster components. The specifications and other documents are stored in the main
repository, and the version is defined in Git by a tag on the last commit. The included versions of the components is
defined by the [Changes][Zonemaster-Changes] file.
## Version Number Syntax for Zonemaster components
Published version numbers of each Zonemaster component is in the common x.y.z triplet form. The x part is referred to
as the _major version_, the y part as the _minor version_ and the z part as the _patch version_.
### Versioning principle
Zonemaster follow the ideas of [Semantic Versioning]. This is how it is stated (version 2.0.0):
>Given a version number MAJOR.MINOR.PATCH, increment the:
>1. MAJOR version when you make incompatible API changes,
>2. MINOR version when you add functionality in a backwards-compatible manner, and
>3. PATCH version when you make backwards-compatible bug fixes.
### Major version
Changes in this number indicate changes in the outward-facing interface, and it means that users of
the interface probably have to do changes to their code, or changes of the usage.
### Minor Version
Changes in the minor version number indicate that there are functional changes that is fully backward compatible.
If the user wants to utilize the new features and functions, calls to Zonemaster might have to be changed.
Interface changes are permitted, as long as they
are of such a nature that they do not affect current users. That is, the interface after a minor version upgrade should be
a strict superset of the interface as it was before.
### Patch Version
Changes in the patch version number indicate internal changes in the library, that need not be visible to an external user
in any way other than the reported test results being more correct or previous bug does not show up.
### Development Versions
Interim versions for development use (that is, intended for developers working on the versioned component itself rather
than developers using the component) are created directly from the "develop" branch of the Git repositories, and are
not published on [CPAN] ([Zonemaster-GUI] is never published at [CPAN]).
## Publication of releases
Major, minor and patch releases of the Zonemaster Components, including the mail repository, are published in the GitHub
repositories by merging the code to the "master" branch in Git and by creating a release note in GitHub. In the normal
case the Perl based components are also published at [CPAN]. The rest of the Zonemaster Product
([Zonemaster-GUI], specifications and documentation) is only available in the "master" branch in each repository.
All components have clear installation instructions for installing the latest version.
## Release Handling
### Development Releases
Issued as needed.
### Patch Versions
The goal is that it should be easy to do patch releases, in order to encourage fixing problems quickly. All unit tests
must pass, and all changes must be properly documented. Besides that, enough testing should be completed before a new
version is released. Automated tests that cover the corrected code should be included.
### Minor Versions
These should be done with more care. Not only must all unit tests pass and everything be documented, but release
candidates should be produced and known major users of the component should be encouraged to test the release
candidates.
### Major version
When this happens, it must be clearly documented and all parts of Zonemaster must work together. Automated tests for new
functionality must be created before release, and integration testing between components must be performed.
[CPAN]: https://www.cpan.org/
[Semantic Versioning]: https://semver.org/
[Zonemaster-Backend]: https://github.com/zonemaster/zonemaster-backend
[Zonemaster-CLI]: https://github.com/zonemaster/zonemaster-cli
[Zonemaster-Changes]: https://github.com/zonemaster/zonemaster/blob/master/Changes
[Zonemaster-Engine]: https://github.com/zonemaster/zonemaster-engine
[Zonemaster-GUI package file]:https://github.com/zonemaster/zonemaster-gui/blob/master/package.json
[Zonemaster-GUI]: https://github.com/zonemaster/zonemaster-gui
[Zonemaster-LDNS]: https://github.com/zonemaster/zonemaster-ldns
[Zonemaster]: https://github.com/zonemaster/zonemaster

75
zonemaster/docs/internal/distrib-testing/Debian-build-environment.md Normal file
View File

@@ -0,0 +1,75 @@
# Debian Build Environment
## Table of contents
* [Introduction](#introduction)
* [Preparation](#preparation)
* [Installation for package building](#installation-for-package-building)
* [Translation work](#translation-work)
* [Installation for mdBook](#installation-for-mdbook)
## Introduction
These are instructions for creating a build environment for Zonemaster
components based on Perl. This is not meant as instructions for installing
Zonemaster itself.
This instruction is for creating it on Debian. See other files for other OSs.
## Preparation
1. Make a clean installation of latest version of Debian.
2. Update the package database.
```sh
sudo apt-get update
```
## Installation for package building
1. Install dependencies and tools:
```sh
sudo apt-get install git cpanminus gettext autoconf automake build-essential libdevel-checklib-perl libextutils-pkgconfig-perl libmime-base32-perl libmodule-install-xsutil-perl libtest-differences-perl libtest-exception-perl libssl-dev libidn2-dev libtool
```
2. Clone 'develop' branch from all Zonemaster repositories except GUI:
```sh
git clone -b develop https://github.com/zonemaster/zonemaster.git
for d in ldns engine cli backend; do git clone -b develop https://github.com/zonemaster/zonemaster-$d.git; done
```
## Translation work
Install for translation (handling PO files), only needed if PO files are to be
handled.
* Follow "Software preparation" in [Instructions for translators] for
Debian (usually use the version in develop branch).
## Installation for mdBook
> Note that building with Cargo below can be time consuming.
Needed for release process:
```
sudo apt install rustc
```
```
cargo install mdbook-linkcheck
```
Needed to build the mdBook (not part of release process):
```
sudo apt install rustc
```
```
cargo install mdbook mdbook-linkcheck
```
[Instructions for translators]: ../maintenance/Instructions-for-translators.md#software-preparation

113
zonemaster/docs/internal/distrib-testing/FreeBSD-build-environment.md Normal file
View File

@@ -0,0 +1,113 @@
# FreeBSD Build Environment
## Table of contents
* [Introduction](#introduction)
* [Preparation](#preparation)
* [Installation for package building](#installation-for-package-building)
* [Translation work](#translation-work)
* [Installation for mdBook](#installation-for-mdbook)
## Introduction
These are instructions for creating a build environment for Zonemaster
components based on Perl. This is not meant as instructions for installing
Zonemaster itself.
This instruction is for creating it on FreeBSD. See other files for other OSs.
## Preparation
1. Do a clean installation of latest version of FreeBSD
2. Become root:
```sh
su -l
```
3. Update to latest patch level
```sh
freebsd-update fetch install
```
4. Reboot into latest patch level and then continue as root on next step
```sh
shutdown -r now
```
5. Create a new user (optional)
Make sure to add `wheel` as an additional group for the user.
```sh
adduser
```
6. Update list of package repositories:
Create the file `/usr/local/etc/pkg/repos/FreeBSD.conf` with the
following content, unless it is already updated:
```sh
FreeBSD: {
url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
}
```
7. Check or activate the package system:
Run the following command, and accept the installation of the `pkg` package
if suggested.
```sh
pkg info -E pkg
```
8. Update local package repository:
```sh
pkg update -f
```
## Installation for package building
1. Install dependencies and tools:
```sh
pkg install gmake gettext-tools git-lite p5-Locale-PO p5-App-cpanminus p5-ExtUtils-PkgConfig p5-MIME-Base32 p5-Module-Install libtool autoconf automake p5-Devel-CheckLib p5-Module-Install-XSUtil p5-Test-Exception libidn libidn2
```
2. Clone 'develop' branch from all Zonemaster repositories except GUI:
```sh
git clone -b develop https://github.com/zonemaster/zonemaster.git
for d in ldns engine cli backend; do git clone -b develop https://github.com/zonemaster/zonemaster-$d.git; done
```
## Translation work
Install for translation (handling PO files), only needed if PO files are to be
handled.
* Follow "Software preparation" in [Instructions for translators] for
FreeBSD (usually use the version in develop branch).
## Installation for mdBook
Needed for release process:
```
pkg install mdbook-linkcheck
```
Needed to build the mdBook (not part of release process):
```
pkg install mdbook mdbook-linkcheck
```
[Instructions for translators]: ../maintenance/Instructions-for-translators.md#software-preparation

87
zonemaster/docs/internal/distrib-testing/README.md Normal file
View File

@@ -0,0 +1,87 @@
# Build Environment Preparation
## Overview
The build environment is used for several purposes, but the purpose
is not for the actual installation of Zonemaster. For the installation
the normal installation instructions for users should be used. In most
cases, if you create a build environment you usually do not install
Zonemaster on that.
* When testing the installation instructions for users you should avoid
to do that from a build environment.
* For the use cases below, your should in most cases make sure that
you use the develop branch.
* You should probably read this file
[from the develop branch][BuildEnvironmentPreparation], not master
branch to get the latest changes.
## Use cases
1. Creating Perl tarballs for testing 1).
2. Creating Perl tarballs for uploading to CPAN as part of a Zonemaster
release 1).
3. Creating Zonemaster-GUI zip distribution for testing.
4. Creating Zonemaster-GUI zip distribution for release.
5. Translation work (PO file updates).
6. Updating documents in Zonemaster/Zonemaster by scripts in
[utils README] as part of release.
7. Check for broken, internal links in mdBook as part of release.
8. Development work.
There could be more use cases.
1\) Zonemaster-LDNS, Zonemaster-Engine, Zonemaster-CLI and Zonemaster-Backend.
### Building Perl CPAN packages
To create a Perl tarball (use cases 1 and 2) you need a specific environment.
Once you have set up your build environment follow the building instructions as
described in [Create Test Distribution] document of the release process.
Build environments:
* [Debian build environment]
* [FreeBSD build environment]
* [Ubuntu build environment]
* Rocky-Linux environment (TBD)
### GUI zip distribution
For use cases 3 and 4, install [Ubuntu Node.js environment].
### Translation work
For use case 5 (which applies for Zonemaster-Engine and
Zonemaster-CLI) install one of the environments listed for
use case 1 and 2 and then follow the Zonemaster-Engine
[instructions for translators].
### Updating documents
For use case 6, install one of the environments listed
for use cases 1 and 2, and then follow the
[installation instructions] for Zonemaster-Engine. Make sure
that you install from develop branch.
### Check for broken, internal links in mdBook
For use case 7, install according to the build environment
instructions (see above).
### Development work
For use case 8, install an environment as for use cases
1 or 3. Additional installation might be needed.
<!-- Zonemaster links point on purpose on the develop branch. -->
[BuildEnvironmentPreparation]: https://github.com/zonemaster/zonemaster/blob/develop/docs/internal/distrib-testing/README.md
[Debian build environment]: Debian-build-environment.md
[FreeBSD build environment]: FreeBSD-build-environment.md
[Ubuntu build environment]: Ubuntu-build-environment.md
[Ubuntu Node.js environment]: Ubuntu-Node.js-build-environment.md
[Create Test Distribution]: ../maintenance/ReleaseProcess-create-test-distribution.md
[Installation instructions]: https://github.com/zonemaster/zonemaster/blob/develop/docs/public/installation/zonemaster-engine.md
[instructions for translators]: https://github.com/zonemaster/zonemaster/blob/develop/docs/internal/maintenance/Instructions-for-translators.md
[utils README]: ../../../utils/README.md

42
zonemaster/docs/internal/distrib-testing/Ubuntu-Node.js-build-environment.md Normal file
View File

@@ -0,0 +1,42 @@
# Ubuntu Node.js Build Environment
The build process takes over 1GB of RAM. A machine with at least 2GB of RAM is recommended to build Zonemaster-GUI.
The requirements to build the Zonemaster-GUI distribution zip file are Node.js
and npm. Below are instructions to create such a build environment on Ubuntu.
Node.js and npm are available from the [Node.js] official website. The required
Node.js version is 18. The process has been tested on Ubuntu 22.04, which we use
here.
1. Make a clean installation of Ubuntu 22.04.
2. Update the package database and install curl
```sh
sudo apt-get update && sudo apt-get install curl
```
3. Install Node.js by using [NVM], a node version manager.
```sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
```
4. After installation, log out and log in again to handle [known issue], or just:
```sh
source ~/.bashrc
```
5. Install the supported Node.js version
```sh
nvm install 24
```
6. Switch to the previously installed version
```sh
nvm use 24
```
[known issue]: https://github.com/nvm-sh/nvm#troubleshooting-on-linux
[Node.js]: https://nodejs.org/en
[NVM]: https://github.com/nvm-sh/nvm

118
zonemaster/docs/internal/distrib-testing/Ubuntu-build-environment.md Normal file
View File

@@ -0,0 +1,118 @@
# Ubuntu Build Environment
## Table of contents
* [Introduction](#introduction)
* [Preparation](#preparation)
* [Installation for package building](#installation-for-package-building)
* [Install Docker](#install-docker)
* [Translation work](#translation-work)
* [Generate documents in Zonemaster/Zonemaster](#generate-documents-in-zonemasterzonemaster)
* [Installation for mdBook](#installation-for-mdbook)
## Introduction
These are instructions for creating a build environment for Zonemaster components
based on Perl. This is not meant as instructions for installing Zonemaster
itself. You should normally use the version of these instructions found in the
develop branch.
This instruction is for creating it on Ubuntu. See other files for other OSs.
This description targets to create a system that can be used for the following
needs for testing and releasing Zonemaster:
1. Git work on the Zonemaster repositories.
2. Creating distributing packages for testing or uploading to CPAN.
3. Creating Docker imaging for testing or uploading to Docker Hub.
4. Updating PO files (translation).
5. Generating the files listed in the [utils README].
## Preparation
1. Make a clean installation of [Ubuntu] 22.04.
2. Update the package database.
```sh
sudo apt-get update
```
## Installation for package building
1. Install dependencies and tools:
```sh
sudo apt-get install git cpanminus gettext autoconf automake build-essential libdevel-checklib-perl libextutils-pkgconfig-perl libmime-base32-perl libmodule-install-xsutil-perl libssl-dev libtest-exception-perl libidn2-dev libtool
```
2. Clone 'develop' branch from all Zonemaster repositories except GUI:
```sh
git clone -b develop https://github.com/zonemaster/zonemaster.git
for d in ldns engine cli backend; do git clone -b develop https://github.com/zonemaster/zonemaster-$d.git; done
```
## Install Docker
This step is only needed if Docker images are to be built.
The Docker version installed by the command below is the version found in the
Ubuntu package repository. If a newer version is needed, follow the
instructions on the [Install Docker Engine on Ubuntu] page instead.
```sh
sudo apt-get install docker.io
```
Add yourself to the Docker group.
```sh
sudo usermod -aG docker $LOGNAME
```
## Translation work
Install for translation (handling PO files), only needed if PO files are to be
handled.
* Follow "Software preparation" in [Instructions for translators] for
Ubuntu (usually use the version in develop branch).
## Generate documents in Zonemaster/Zonemaster
Only needed if the files listed in [utils README] are to be generated (updated).
* Follow the [Installation instructions] for Zonemaster-Engine for Ubuntu.
* Only install the dependencies from binary packages and CPAN (if any).
* Do not install neither Zonemaster::LDNS nor Zonemaster::Engine at this stage.
## Installation for mdBook
> Note that building with Cargo below can be time consuming.
Needed for release process:
```
sudo apt install rustc
```
```
cargo install mdbook-linkcheck
```
Needed to build the mdBook (not part of release process):
```
sudo apt install rustc
```
```
cargo install mdbook mdbook-linkcheck
```
[Install Docker Engine on Ubuntu]: https://docs.docker.com/engine/install/ubuntu/
[Installation instructions]: ../../public/installation/zonemaster-engine.md
[Instructions for translators]: ../maintenance/Instructions-for-translators.md#software-preparation
[Ubuntu]: https://ubuntu.com/
[Utils README]: ../../../utils/README.md

35
zonemaster/docs/internal/functional-tests/Behavior-TP/behavior01.md Normal file
View File

@@ -0,0 +1,35 @@
## BEHAVIOR01: NXDOMAIN returned in response in the event of querying a domain name that does not exist
### Test case identifier
**BEHAVIOR01:** Name Error RCODE returned in response in the event of
querying a domain name that does not exist
### Objective
This test is to verify whether the engine responds with a RCODE NXDOMAIN when
querying a domain name that does not exist.
### Inputs
The domain to be tested. The domain should not be already delegated in the DNS.
### Ordered description of steps to be taken to execute the test case
1. Zonemaster CLI is used to verify an invalid domain
2. If the query don’t receive an RCODE NXDOMAIN, the test returns FAIL
### Results
Verifying the invalid domain with zonemaster CLI does provide conclusive errors as you
could see from the appendix
### Appendix
```
zonemaster-cli afnics.fr
Seconds Level Message
======= ========= =======
1.17 CRITICAL Nameserver for zone fr responded with NXDOMAIN to query for
glue.
1.17 CRITICAL Not enough data about afnics.fr was found to be able to run
tests.
```

39
zonemaster/docs/internal/functional-tests/Behavior-TP/behavior02.md Normal file
View File

@@ -0,0 +1,39 @@
## BEHAVIOR02: NODATA returned in response in the event of querying a domain name that exists but no relevant answers in the answer section
### Test case identifier
**BEHAVIOR02:** NODATA returned in response in the event of querying a
domain name that exist but no relevant answers in the answer section
### Objective
Section 1 of [RFC 2308](https://datatracker.ietf.org/doc/html/rfc2308) mentions that
"NODATA" is a pseudo RCODE. "NODATA" indicates that there are RRs for the requested
domain name, but none of them match the record type queried.
"NODATA" is indicated by an answer with RCODE set to "NOERROR" (defined in RFC
[RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035)) and no relevant answers in the
answer section.
This test is to verify whether the engine responds with NODATA when
querying a domain name that exists, but the queried record type does not exist.
### Inputs
The domain to be tested. The domain should be already delegated in the DNS, but
should not contain delegation RRs or the queried RRs
### Results
Verifying a domain such as "gouv.fr" which does not have delegation RRs results
in expected results as you can see from the appendix.
### Appendix
```
zonemaster-cli gouv.fr
Seconds Level Message
======= ========= =======
1.16 CRITICAL Nameservers for "fr" provided no NS records for tested zone.
RCODE given was NOERROR.
1.16 CRITICAL Not enough data about gouv.fr was found to be able to run
tests.
```

44
zonemaster/docs/internal/functional-tests/Behavior-TP/behavior03.md Normal file
View File

@@ -0,0 +1,44 @@
## BEHAVIOR03: The behavior of the engine when IPv6 or IPv4 is disabled
### Test case identifier
**BEHAVIOR03:** The behavior of the engine when IPv6 or IPv4 is disabled
### Objective
This test is to verify whether appropriate results are displayed when
querying a domain name from the CLI with IPv6 or IPv4 disabled.
### Inputs
The domain to be tested.
### Ordered description of steps to be taken to execute the test case
1. A valid domain is verified with corresponding options "--no-ipv6" or "--no-ipv4" using Zonemaster CLI
2. If the query don’t receive a CRITICAL or ERROR notice, the test returns PASS
### Results
Verifying a valid zone with either IPv4 or IPV6 disabled using the zonemaster
CLI does provide expected results without false positive or false negative as
seen in the appendix.
### Appendix
```
zonemaster-cli --no-ipv6 afnic.fr
Seconds Level Message
======= ========= =======
2.30 NOTICE IPv6 is disabled, not sending "NS" query to
ns1.nic.fr/2001:660:3003:2::4:1.
2.30 NOTICE IPv6 is disabled, not sending "NS" query to
ns2.nic.fr/2001:660:3005:1::1:2.
2.31 NOTICE IPv6 is disabled, not sending "NS" query to
ns3.nic.fr/2001:660:3006:1::1:1.
7.65 NOTICE SOA 'mname' nameserver (dnsmaster.nic.fr) is not listed in
"parent" NS records for tested zone (ns1.nic.fr;ns2.nic.fr;ns3.nic.fr).
7.65 NOTICE SOA 'refresh' value (7200) is less than the recommended one
(14400).
7.65 NOTICE SOA 'retry' value (1800) is less than the recommended one
(3600).
```

21
zonemaster/docs/internal/functional-tests/Behavior-TP/behavior04.md Normal file
View File

@@ -0,0 +1,21 @@
## BEHAVIOR04: Able to test a particular profile from the CLI using an option which selects a particular test profile
### Test case identifier
**BEHAVIOR04:** Able to test a particular profile from the CLI using an option
which selects a particular test profile
### Objective
Zonecheck CLI has an option '-P' which allows to select a particular profile to
test. For example, "zonecheck -P Afnic iis.se" tests the zone with the tests
defined in afnic.profile
(https://github.com/mat813/ZoneCheck/blob/master/etc/zonecheck/afnic.profile).
### Results
The Zonemaster-CLI has integrated this functionality even though
as of not we do not have different profiles to test.

41
zonemaster/docs/internal/functional-tests/Behavior-TP/behavior05.md Normal file
View File

@@ -0,0 +1,41 @@
## BEHAVIOR05: Capable of running the test when the delegation parameters are specified
### Test case identifier
**BEHAVIOR05:** Capable of running the test when the delegation parameters are specified
### Objective
This test is to verify whether the engine is capable of running an undelegated
test
### Inputs
The domain to be tested with NS and IP addresses. It could be either a delegated
or un delegated domain
### Ordered description of steps to be taken to execute the test case
1. A valid domain is verified using Zonemaster CLI with appropriate options as
seen in the appendix
2. If the query don’t receive a CRITICAL or ERROR notice, the test returns PASS
### Results
As viewed in the appendix, the engine is capable of testing un delegated
domains.
### Appendix
```
zonemaster-cli iis.se --ns i.ns.se/194.146.106.22 --ns
i.ns.se/2001:67c:1010:5::53 --ns ns.nic.se/212.247.7.228 --ns
ns.nic.se/2a00:801:f0:53::53 --ns ns3.nic.se/212.247.8.152 --ns
ns3.nic.se/2a00:801:f0:211::152 IISIIS
Seconds Level Message
======= ========= =======
6.20 WARNING Nameserver ns3.nic.se has an IP address (212.247.8.152)
without PTR configured.
10.45 NOTICE 192.36.144.107 returned no DS records for iis.se.
11.51 NOTICE SOA 'refresh' value (10800) is less than the recommended one
(14400).
```

43
zonemaster/docs/internal/functional-tests/Behavior-TP/behavior06.md Normal file
View File

@@ -0,0 +1,43 @@
## BEHAVIOR06: Timestamps display
### Test case identifier
**BEHAVIOR06:** Timestamps display
### Objective
This test is to verify whether the engine displays timestamps on the test being
run
### Inputs
The domain to be tested.
### Ordered description of steps to be taken to execute the test case
1. A valid domain is verified using Zonemaster CLI with appropriate options as
see in the appendix
2. If the query don’t show timestamp in the results, the test returns FAIL
### Results
### Appendix
```
zonemaster-cli --time afnic.fr
Seconds Level Message
======= ========= =======
17.89 NOTICE SOA 'mname' nameserver (dnsmaster.nic.fr) is not listed in
"parent" NS records for tested zone (ns1.nic.fr;ns2.nic.fr;ns3.nic.fr).
17.90 NOTICE SOA 'refresh' value (7200) is less than the recommended one
(14400).
17.90 NOTICE SOA 'retry' value (1800) is less than the recommended one
(3600).
sandoche@eryx:~$ zonemaster-cli afnic.fr
Seconds Level Message
======= ========= =======
8.16 NOTICE SOA 'mname' nameserver (dnsmaster.nic.fr) is not listed in
"parent" NS records for tested zone (ns1.nic.fr;ns2.nic.fr;ns3.nic.fr).
8.16 NOTICE SOA 'refresh' value (7200) is less than the recommended one
(14400).
8.17 NOTICE SOA 'retry' value (1800) is less than the recommended one
(3600).
```

33
zonemaster/docs/internal/functional-tests/Behavior-TP/behavior07.md Normal file
View File

@@ -0,0 +1,33 @@
## BEHAVIOR07: IDN Verification
### Test case identifier
**BEHAVIOR07:** IDN Verification
### Objective
The objective of this test is to verify the engine verifies IDN domains
### Inputs
The IDN domain to be tested.
### Ordered description of steps to be taken to execute the test case
1. A standard query for an IDN domain is made using the zonemaster CLI
2. If the output from the CLI does not verify the IDN domain as in the case of
normal domain names, then the test fails
### Results
As seen in the appendix, the engine is capable of verifying IDN domains
### Appendix
```
zonemaster-cli café.fr
Seconds Level Message
======= ========= =======
25.67 WARNING All nameservers are in the same AS (16509).
25.67 WARNING All nameservers IPv4 addresses are in the same AS (16509).
25.70 NOTICE 192.5.4.2 returned no DS records for xn--caf-dma.fr.

182
zonemaster/docs/internal/functional-tests/Behavior-TP/behavior08.md Normal file
View File

@@ -0,0 +1,182 @@
## BEHAVIOR08: Display of verbose information
### Test case identifier
**BEHAVIOR08:** Display of verbose information
### Objective
The objective of this test is to verify whether it is possible to obtain
different levels of information for a zone that is being tested
### Inputs
The domain to be tested.
### Ordered description of steps to be taken to execute the test case
1. A valid domain is verified using Zonemaster CLI with appropriate options as
seen in the appendix. The options --level (CRITICAL, ERROR, WARNING, NOTICE, INFO,
DEBUG, DEBUG2 or DEBUG3) provides different levels of information for the zone being tested
2. If the query doesn't have results with level to the verbose option then the
test return FAIL.
### Results
The engine passes the test as can be verified from the appendix
### Appendix
```
zonemaster-cli --level CRITICAL iis.se
Seconds Level Message
======= ========= =======
Looks OK.
```
```
zonemaster-cli --level INFO iis.se
Seconds Level Message
======= ========= =======
1.86 INFO Nameserver for zone se replies when trying to fetch glue.
1.86 INFO Nameserver for zone se listed these nameservers as glue:
i.ns.se.,ns.nic.se.,ns3.nic.se..
2.34 INFO IPv4 is enabled, can send "NS" query to
i.ns.se/194.146.106.22.
2.35 INFO Nameserver i.ns.se/194.146.106.22 listed these servers as
glue: i.ns.se.,ns.nic.se.,ns3.nic.se..
2.35 INFO IPv6 is enabled, can send "NS" query to
i.ns.se/2001:67c:1010:5::53.
2.37 INFO Nameserver i.ns.se/2001:67c:1010:5::53 listed these servers as
glue: i.ns.se.,ns.nic.se.,ns3.nic.se..
2.37 INFO IPv4 is enabled, can send "NS" query to
ns.nic.se/212.247.7.228.
2.42 INFO Nameserver ns.nic.se/212.247.7.228 listed these servers as
glue: i.ns.se.,ns.nic.se.,ns3.nic.se..
2.42 INFO IPv6 is enabled, can send "NS" query to
ns.nic.se/2a00:801:f0:53::53.
2.46 INFO Nameserver ns.nic.se/2a00:801:f0:53::53 listed these servers
as glue: i.ns.se.,ns.nic.se.,ns3.nic.se..
2.46 INFO IPv4 is enabled, can send "NS" query to
ns3.nic.se/212.247.8.152.
2.50 INFO Nameserver ns3.nic.se/212.247.8.152 listed these servers as
glue: i.ns.se.,ns.nic.se.,ns3.nic.se..
2.50 INFO IPv6 is enabled, can send "NS" query to
ns3.nic.se/2a00:801:f0:211::152.
2.54 INFO Nameserver ns3.nic.se/2a00:801:f0:211::152 listed these
servers as glue: i.ns.se.,ns.nic.se.,ns3.nic.se..
2.54 INFO Functional nameserver found. "A" query for www.iis.se test
aborted.
2.75 INFO All Nameserver addresses are in the routable public addressing
space.
6.84 WARNING Nameserver ns3.nic.se has an IP address (212.247.8.152)
without PTR configured.
8.78 INFO None of the 3 nameserver(s) with IPv6 addresses is part of a
bogon prefix.
8.78 INFO Nameserver i.ns.se/194.146.106.22 accessible over UDP on port
53.
8.81 INFO Nameserver i.ns.se/2001:67c:1010:5::53 accessible over UDP on
port 53.
8.85 INFO Nameserver ns.nic.se/212.247.7.228 accessible over UDP on port
53.
8.89 INFO Nameserver ns.nic.se/2a00:801:f0:53::53 accessible over UDP on
port 53.
8.93 INFO Nameserver ns3.nic.se/212.247.8.152 accessible over UDP on
port 53.
8.93 INFO Nameserver ns3.nic.se/2a00:801:f0:211::152 accessible over UDP
on port 53.
8.94 INFO Nameserver i.ns.se/194.146.106.22 accessible over TCP on port
53.
8.98 INFO Nameserver i.ns.se/2001:67c:1010:5::53 accessible over TCP on
port 53.
9.06 INFO Nameserver ns.nic.se/212.247.7.228 accessible over TCP on port
53.
9.15 INFO Nameserver ns.nic.se/2a00:801:f0:53::53 accessible over TCP on
port 53.
9.23 INFO Nameserver ns3.nic.se/212.247.8.152 accessible over TCP on
port 53.
9.31 INFO Nameserver ns3.nic.se/2a00:801:f0:211::152 accessible over TCP
on port 53.
11.06 INFO Domain's authoritative nameservers do not belong to the same
AS.
11.06 INFO A single SOA serial number was seen (1415096701).
11.06 INFO A single SOA rname value was seen (hostmaster.iis.se.)
11.07 INFO A single SOA time parameter set was seen
(REFRESH=10800,RETRY=3600,EXPIRE=1814400,MINIMUM=14400).
11.08 INFO A unique NS set was seen (i.ns.se.,ns.nic.se.,ns3.nic.se.).
11.12 INFO Found DS records with tags 18937.
11.13 INFO There are both DS and DNSKEY records with key tags 18937.
11.13 INFO DS record with keytag 18937 matches the DNSKEY with the same
tag.
11.13 INFO At least one DS record with a matching DNSKEY record was
found.
11.14 INFO The DNSKEY with tag 18937 uses algorithm number 5/(RSA/SHA1),
which is OK.
11.14 INFO The DNSKEY with tag 52823 uses algorithm number 5/(RSA/SHA1),
which is OK.
11.34 INFO The zone has NSEC records.
11.34 INFO Parent lists enough nameservers
(i.ns.se;ns.nic.se;ns3.nic.se). Lower limit set to 2.
11.34 INFO Child lists enough nameservers (i.ns.se;ns.nic.se;ns3.nic.se).
Lower limit set to 2.
11.35 INFO Parent and child list enough nameservers
(i.ns.se;ns.nic.se;ns3.nic.se). Lower limit set to 2.
11.35 INFO All the IP addresses used by the nameservers are unique
11.35 INFO The smallest possible legal referral packet is smaller than
513 octets (it is 357).
11.36 INFO All the nameservers are authoritative.
11.38 INFO No nameserver point to CNAME alias.
11.38 INFO All the nameservers have SOA record.
11.39 INFO All of the nameserver names are listed both at parent and
child.
11.39 INFO The module Example was disabled by the policy.
11.58 INFO None of the following nameservers is a recursor :
i.ns.se,ns.nic.se,ns3.nic.se.
11.78 INFO The following nameservers support EDNS0 :
ns.nic.se/212.247.7.228,i.ns.se/2001:67c:1010:5::53,ns3.nic.se/212.247.8.152,ns.nic.se/2a00:801:f0:53::53,ns3.nic.se/2a00:801:f0:211::152,i.ns.se/194.146.106.22.
11.78 INFO AXFR not available on nameserver i.ns.se/194.146.106.22.
11.82 INFO AXFR not available on nameserver i.ns.se/2001:67c:1010:5::53.
11.89 INFO AXFR not available on nameserver ns.nic.se/212.247.7.228.
11.97 INFO AXFR not available on nameserver ns.nic.se/2a00:801:f0:53::53.
12.05 INFO AXFR not available on nameserver ns3.nic.se/212.247.8.152.
12.13 INFO AXFR not available on nameserver
ns3.nic.se/2a00:801:f0:211::152.
12.14 INFO All nameservers reply with same IP used to query them.
12.33 INFO The following nameservers answer AAAA queries without problems
:
ns.nic.se/2a00:801:f0:53::53,ns3.nic.se/212.247.8.152,i.ns.se/2001:67c:1010:5::53,ns.nic.se/212.247.7.228,i.ns.se/194.146.106.22,ns3.nic.se/2a00:801:f0:211::152.
12.33 INFO All nameservers succeeded to resolve to an IP address.
12.34 INFO No illegal characters in the domain name (iis.se).
12.34 INFO Both ends of all labels of the domain name (iis.se) have no
hyphens.
12.34 INFO Domain name (iis.se) has no label with a double hyphen ('--')
in position 3 and 4 (with a prefix which is not 'xn--').
12.34 INFO Nameserver (i.ns.se) syntax is valid.
12.34 INFO Nameserver (ns.nic.se) syntax is valid.
12.34 INFO Nameserver (ns3.nic.se) syntax is valid.
12.34 INFO There is no misused '@' character in the SOA RNAME field
(hostmaster.iis.se.).
12.35 INFO The SOA RNAME field (hostmaster@iis.se) is compliant with
RFC2822.
12.35 INFO SOA MNAME (ns.nic.se) syntax is valid.
12.35 INFO Domain name MX (mx1.iis.se) syntax is valid.
12.35 INFO Domain name MX (mx2.iis.se) syntax is valid.
12.42 INFO SOA 'mname' nameserver (ns.nic.se) is authoritative for
'iis.se' zone.
12.42 NOTICE SOA 'refresh' value (10800) is less than the recommended one
(14400).
12.42 INFO SOA 'refresh' value (10800) is higher than the SOA 'retry'
value (3600).
12.43 INFO SOA 'expire' value (1814400) is higher than the minimum
recommended value (604800) and lower than 'refresh' value.
12.43 INFO SOA 'minimum' value (14400) is between the recommended ones
(300/86400).
12.46 INFO SOA 'mname' value (ns.nic.se) refers to a NS which is not an
alias (CNAME).
12.48 INFO SOA 'mname' value (ns.nic.se) refers to a NS which is not an
alias (CNAME).
12.49 INFO Target (MX=mx2.iis.se/MX=mx1.iis.se) found to deliver e-mail
for the domain name.
```

54
zonemaster/docs/internal/functional-tests/Behavior-TP/behavior09.md Normal file
View File

@@ -0,0 +1,54 @@
## BEHAVIOR09: Appropriate error code when the zone is misconfigured
### Test case identifier
**BEHAVIOR09:** Appropriate error code when the zone is misconfigured
### Objective
The objective of this test is to verify that the engine catches the zone
mis-configurations appropriately
### Inputs
The broken domain to be tested.
### Ordered description of steps to be taken to execute the test case
1. A standard query for the domain is made using the zonemaster CLI
2. If the output from the CLI does not catch the expected errors, then the test
returns FAIL
### Results
Even though exhaustive tests are not run, for the tests being run the engine
seems to capture the errors.
### Appendix
```
zonemaster-cli broken.dnssec.ee
Seconds Level Message
======= ========= =======
6.12 WARNING All nameservers are in the same AS (51349).
6.12 WARNING All nameservers IPv4 addresses are in the same AS (51349).
6.23 ERROR DS record with keytag 57307 does not match the DNSKEY with the
same tag.
6.24 ERROR No DS record with a matching DNSKEY record was found.
6.34 ERROR RRSIG with keytag 57307 and covering type(s) DNSKEY has
already expired (expiration is: 1393471638).
6.34 ERROR RRSIG with keytag 48381 and covering type(s) SOA has already
expired (expiration is: 1393882163).
6.41 ERROR Signature for DNSKEY with tag 57307 failed to verify with
error 'Bogus DNSSEC signature'.
6.41 ERROR The apex DNSKEY RRset was not correctly signed.
6.41 ERROR Trying to verify SOA RRset with signature 48381 gave error
'Bogus DNSSEC signature'.
6.41 ERROR No RRSIG correctly signed the SOA RRset.
6.47 ERROR Trying to verify NSEC3 RRset with RRSIG 48381 gave error
'Bogus DNSSEC signature'.
7.33 NOTICE SOA 'refresh' value (10800) is less than the recommended one
(14400).
```

39
zonemaster/docs/internal/functional-tests/Configuration-TP/configuration01.md Normal file
View File

@@ -0,0 +1,39 @@
## CONFIGURATION01: The data for a canonical name and its aliases cannot be different
### Test case identifier
**CONFIGURATION01:** The data for a canonical name and its aliases cannot be
different
### Objective
Section 3.6.2 of [RFC 1034](https://datatracker.ietf.org/doc/html/rfc1034)
mentions that if a CNAME RR is present at a node, no other data should be
present; this ensures that the data for a canonical name and its aliases cannot
be different. This rule also insures that a cached CNAME can be used without
checking with an authoritative server for other RR types.
The objective of this test is to verify whether the engine conforms to the
specification described above.
### Inputs
The domain to be tested.
### Ordered description of steps to be taken to execute the test case
1. Configure a live zone, wherein the CNAME record coexist with any other data
```
configuration02-z1.zft-root.rd.nic.fr.
```
2. A standard query for the domain is made
3. If the query don’t receive Error response, the test returns with FAIL
### Results
Current DNS softwares does not allow a zone to be loaded wherein a CNAME coexist
with other RR. The only way to emulate this behavior is to use an old DNS
software version or write our own implementation. It has been decided that such
efforts are not necessary at this stage and hence this test is not run.

111
zonemaster/docs/internal/functional-tests/Configuration-TP/configuration02.md Normal file
View File

@@ -0,0 +1,111 @@
## CONFIGURATION02: Cyclic Zone Dependency
different
### Test case identifier
**CONFIGURATION02:** Cyclic Zone Dependency
### Objective
A cyclic zone dependency happens when two or more zones DNS service depends on
each other in a circular way. This scenario is possible due to configuration
errors in either or both of the zones; however in some cases it is also possible
when none of the involved zones has any noticeable configuration error. Thus the
combination of two or more correctly configured zones may also result in cyclic
zone dependency.
The objective here is to verify whether the engine identifies such a dependency.
### Inputs
The domain to be tested.
### Ordered description of steps to be taken to execute the test case
1. Configure live zone(s) with cyclic dependencies
```
configuration02-z1.zft-root.rd.nic.fr.
```
2. A standard query for the domain is made
3. If the query don’t receive Error response, the test returns with FAIL
### Results
Verifying the zone with zonemaster CLI does not provide any conclusive errors as
you could see from the appendix
### Appendix
```
zonemaster-cli configuration02-z1.zft-root.rd.nic.fr.
Seconds Level Message
======= ========= =======
113.63 NOTICE Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 did not respond to NS
query.
113.64 NOTICE Nameserver
ns2.configuration02-z2.zft-root.rd.nic.fr/46.105.116.200 did not respond to NS
query.
119.90 NOTICE Nameserver dns1.configuration02-z1.zft-root.rd.nic.fr has an
IP address (178.33.232.188) with mismatched PTR result
(ns324830.ip-178-33-232.eu.).
119.90 NOTICE Nameserver dns2.configuration02-z1.zft-root.rd.nic.fr has an
IP address (46.105.116.200) with mismatched PTR result
(ns334987.ip-46-105-116.eu.).
119.90 ERROR Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 not accessible over
UDP on port 53.
119.94 ERROR Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 not accessible over
TCP on port 53.
120.45 WARNING All nameservers are in the same AS (16276).
120.45 WARNING All nameservers IPv4 addresses are in the same AS (16276).
120.46 WARNING Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.46 WARNING Nameserver
ns2.configuration02-z2.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.46 WARNING Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.46 WARNING Nameserver
ns2.configuration02-z2.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.46 WARNING Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.46 WARNING Nameserver
ns2.configuration02-z2.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.46 WARNING Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.46 WARNING Nameserver
ns2.configuration02-z2.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.47 WARNING Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.47 WARNING Nameserver
ns2.configuration02-z2.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.47 WARNING Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.47 WARNING Nameserver
ns2.configuration02-z2.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.47 WARNING Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.47 WARNING Nameserver
ns2.configuration02-z2.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.47 WARNING Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.47 WARNING Nameserver
ns2.configuration02-z2.zft-root.rd.nic.fr/46.105.116.200 did not respond.
120.48 NOTICE 176.31.226.223 returned no DS records for
configuration02-z1.zft-root.rd.nic.fr.
120.49 NOTICE IP 178.33.232.188 refers to multiple nameservers
(dns1.configuration02-z1.zft-root.rd.nic.fr;ns1.configuration02-z2.zft-root.rd.nic.fr).
120.49 NOTICE IP 46.105.116.200 refers to multiple nameservers
(dns2.configuration02-z1.zft-root.rd.nic.fr;ns2.configuration02-z2.zft-root.rd.nic.fr).
120.52 WARNING Nameserver dns2.configuration02-z1.zft-root.rd.nic.fr response
is not authoritative on UDP port 53.
120.53 WARNING Nameserver dns2.configuration02-z1.zft-root.rd.nic.fr response
is not authoritative on TCP port 53.
120.53 WARNING Nameserver ns2.configuration02-z2.zft-root.rd.nic.fr response
is not authoritative on UDP port 53.
120.53 WARNING Nameserver ns2.configuration02-z2.zft-root.rd.nic.fr response
is not authoritative on TCP port 53.
150.68 NOTICE Nameserver
dns2.configuration02-z1.zft-root.rd.nic.fr/46.105.116.200 dropped AAAA query.
150.68 NOTICE Nameserver
ns2.configuration02-z2.zft-root.rd.nic.fr/46.105.116.200 dropped AAAA query.

59
zonemaster/docs/internal/functional-tests/Configuration-TP/configuration03.md Normal file
View File

@@ -0,0 +1,59 @@
## CONFIGURATION03: Lame Delegation
### Test case identifier
**CONFIGURATION03:** Lame delegation
### Objective
Lame delegation errors happen when a name server that is registered in the DNS
system as authoritative for a zone does not provide authoritative answers for
the zone.
### Inputs
The domain to be tested.
### Inputs
The domain to be tested.
### Ordered description of steps to be taken to execute the test case
1. Configure live zone(s) with lame delegation
```
zft-sandoche.rd.nic.fr
```
2. A standard query for the domain is made
3. If the query don’t receive Error response, the test returns with FAIL
### Results
Verifying the zone with zonemaster CLI does provide conclusive errors as
you could see from the appendix
### Appendix
```
zonemaster-cli zft-sandoche.rd.nic.fr
Seconds Level Message
======= ========= =======
10.18 NOTICE Nameserver ns2.rd.nic.fr has an IP address (192.134.4.81) with
mismatched PTR result (lea.rd.nic.fr.).
10.18 NOTICE Nameserver ns2.rd.nic.fr has an IP address
(2001:67c:2218:3::1:7) with mismatched PTR result (dalila.rd.nic.fr.).
12.12 WARNING All nameservers IPv6 addresses are in the same AS (2485).
12.15 NOTICE 192.134.4.81 returned no DS records for
zft-sandoche.rd.nic.fr.
12.16 WARNING Nameserver ns2.rd.nic.fr response is not authoritative on UDP
port 53.
12.16 WARNING Nameserver ns2.rd.nic.fr response is not authoritative on TCP
port 53.
12.17 ERROR A SOA query NOERROR response from ns2.rd.nic.fr was received
empty.
12.91 NOTICE SOA 'refresh' value (3600) is less than the recommended one
(14400).
12.92 NOTICE SOA 'retry' value (1800) is less than the recommended one
(3600).
13.56 NOTICE No target (MX, A or AAAA record) to deliver e-mail for the
domain name.

59
zonemaster/docs/internal/functional-tests/Configuration-TP/configuration04.md Normal file
View File

@@ -0,0 +1,59 @@
## CONFIGURATION04: Delegation Inconsistency - Name Server Records
### Test case identifier
**CONFIGURATION04:** Delegation Inconsistency - Name Server Records
### Objective
When a parent zone 'P' delegates part of its namespace to a child 'C', P stores
the list of NS records for the authoritative servers of zone 'C'. This list of
NS records are kept both at the parent 'P' and the child zone 'C'.
Delegation inconsistency occurs when changes at the 'C' are not reflected to the NS RRs
at 'P'.
### Inputs
The domain to be tested.
### Ordered description of steps to be taken to execute the test case
1. Configure a live zone with inconsistency in name server records between parent
and child.
```
configuration04-1.zft-root.rd.nic.fr
```
2. The engine should return FAIL at least once for the configuration defined. If it
returns PASS for all the tests then the engine does not capture delegation
inconsistency in name server records.
### Results
Verifying the zone with zonemaster CLI does provide conclusive errors as
you could see from the appendix
### Appendix
Seconds |Level |Message
:--------|:---------|-----------------------------------------------------------------------------------------------
20.36 |ERROR |Nameserver ns2.rd.nic.fr/192.134.4.81 did not return NS records. RCODE was NOERROR|
20.36 |ERROR |Nameserver ns2.rd.nic.fr/2001:67c:2218:3::1:7 did not return NS records. RCODE was NOERROR|
30.39 |NOTICE |Nameserver ns334987.ip-46-105-116.eu/46.105.116.200 did not respond to NS query |
31.23 |ERROR |Nameserver ns334987.ip-46-105-116.eu/46.105.116.200 not accessible over UDP on port 53|
31.28 |ERROR |Nameserver ns334987.ip-46-105-116.eu/46.105.116.200 not accessible over TCP on port 53|
32.37 |WARNING |All nameservers IPv6 addresses are in the same AS (2485)|
32.38 |WARNING |Nameserver ns334987.ip-46-105-116.eu/46.105.116.200 did not respond|
32.38 |WARNING |Nameserver ns334987.ip-46-105-116.eu/46.105.116.200 did not respond|
32.38 |WARNING |Nameserver ns334987.ip-46-105-116.eu/46.105.116.200 did not respond|
32.38 |WARNING |Nameserver ns334987.ip-46-105-116.eu/46.105.116.200 did not respond|
32.39 |NOTICE |176.31.226.223 returned no DS records for configuration04-1.zft-root.rd.nic.fr|
32.40 |WARNING |Nameserver ns2.rd.nic.fr response is not authoritative on UDP port 53|
32.40 |WARNING |Nameserver ns2.rd.nic.fr response is not authoritative on TCP port 53|
32.40 |WARNING |Nameserver ns334987.ip-46-105-116.eu response is not authoritative on UDP port 53|
32.40 |WARNING |Nameserver ns334987.ip-46-105-116.eu response is not authoritative on TCP port 53|
32.40 |ERROR |A SOA query NOERROR response from ns2.rd.nic.fr was received empty|
32.40 |ERROR |Parent has nameserver(s) not listed at the child (ns2.rd.nic.fr;ns324830.ip-178-33-232.eu;ns334987.ip-46-105-116.eu)|
32.40 |ERROR |None of the nameservers listed at the parent are listed at the child|
62.52 |NOTICE |Nameserver ns334987.ip-46-105-116.eu/46.105.116.200 dropped AAAA query|

17
zonemaster/docs/internal/functional-tests/Restriction-TP/restriction01.md Normal file
View File

@@ -0,0 +1,17 @@
## RESTRICTION01: Label length
### Test case identifier
**RESTRICTION01:** Label length
### Objective
In DNS, domain names are expressed in terms of a sequence of labels. Section
2.3.1 of [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035) mentions that the
label must be 63 characters or less.
The objective for this test is verify whether the engine conforms to the
specification described in the previous paragraph.
### Results
Since it is not possible to fit in more than 63 octets in a DNS label
, it is impossible to run this test.

17
zonemaster/docs/internal/functional-tests/Restriction-TP/restriction02.md Normal file
View File

@@ -0,0 +1,17 @@
## RESTRICTION02: Domain name length
### Test case identifier
**RESTRICTION02:** Domain name length
### Objective
Section 3.1 of [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035) mentions that the
the total length of a domain name (i.e., label octets and label length octets)
is restricted to 255 octets or less.
The objective for this test is verify whether the engine conforms to the
specification described in the previous paragraph
### Results
Since it is not possible to fit in more than 255 octets in a DNS
packet, this test is not run.

24
zonemaster/docs/internal/functional-tests/Restriction-TP/restriction03.md Normal file
View File

@@ -0,0 +1,24 @@
## RESTRICTION03: Character set restriction for label
### Test case identifier
**RESTRICTION03:** Character set restriction for label
### Objective
Even though section 11 of [RFC 2181](https://datatracker.ietf.org/doc/html/rfc2181) mentions
that any binary string could be part of a label, many of the registries will
not permit special symbols in the label. This is an habit pursued by the
registries based on section 2.1 of the [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123),
i.e. following the LDH (Letters, Digits and Hyphen) format. Even for the
IDNs [RFC 5892](https://datatracker.ietf.org/doc/html/rfc5892) limits to the LDH
format.
The objective for this test is verify whether the engine identifies the
domain names which is not in the LDH format.
### Result
The engine does not capture the restriction for LDH and the explanation is
provided here : https://github.com/zonemaster/zonemaster/issues/153

97
zonemaster/docs/internal/maintenance/ChangeManagement.md Normal file
View File

@@ -0,0 +1,97 @@
# Zonemaster - Change management
## Scope
This document outlines how the any changes to the software during the
technical maintenance period will be classified and the process to implement
these changes.
## Input for change
Change requests can come from anywhere such as the users mailinglist, the
steering committee or the development team. The change requests could be
classified into two broad categories:
1. Minor change
2. Major change
## Minor change
The nature of minor change requests are explained in the following
subsection:
### Bug Fixing
Any bug fixes, the team or any user discovers should be published in the
GitHub issue tracker.
Not all issues in the tracker are bugs, and not all reported bugs are
software bugs, but can be protocol errors in DNS, or user or documentation
errors.
Bug fixes are included in minor releases. See the [version numbering policy]
document for documentation on version numbers for releases.
### Minor Changes
Minor changes are new features, changes or deprecated functionality that
do not break backwards compatibility, neither force any user to change or
update their environment that currently runs the software.
Minor changes are included in minor releases. See the [version numbering policy]
document for documentation on version numbers for releases.
## Major changes
Any change and specification that requires changes in the software
architecture, an API change or new major features could be classified
under the category "Major change".
Major changes are included in major releases. See the [version numbering policy]
document for documentation on version numbers for releases.
## Process to implement the change
Change requests can come from anywhere such as the users mailinglist, the
steering committee or the development team.
### Minor changes
A "bug fix" or "minor change" should be added as an issue in GitHub. Then
the person corresponding is assigned by the release manager or the person
who has created the issue. The assigned person should then close the
ticket within a specified time as mentioned in the "Key Performance
Indicator" (or) update the bug with the time duration on when the bug/minor improvement could be solved (or) comments the reason for not able to solve
the bug/minor improvement.
### Major changes
Any new development for Zonemaster must follow the strict process where
there are formal requirements, specifications for implementing the
requirements and then any design and architecture fulfilling the
specifications, and finally the implementation and quality assurance.
When all this is performed successfully the software package is released
using the release process.
#### Decision on discarding or including changes
Whatever be the type of change request, it should go through the "Issues
tracker" in the GitHub project. All requests should be promptly responded
to, even if the decision to acknowledge the request is postponed (or)
not taken into consideration.
Requirements should then be ranked in importance depending on a number of
factors such as complexity, amount of work, risk, architectural changes,
relevance to the product and so on.
The decision to include the requirement for the release during the
maintenance period will be taken by the development team in consultation
with the steering committee.
New requirements that are acknowledged (by the development team and the
steering committee) make it to the roadmap and planned for specification
and implementation. They are also added to the current set of requirements.
[version numbering policy]: ../design/Versions%20and%20Releases.md

1
zonemaster/docs/internal/maintenance/Instructions-for-translators.md Normal file
View File

@@ -0,0 +1 @@
Moved to [Translating Engine, CLI and Backend](../../public/translation/Translating-Engine-CLI-Backend.md)

93
zonemaster/docs/internal/maintenance/IssueLabels.md Normal file
View File

@@ -0,0 +1,93 @@
# Labels for Issues and Pull Requests
## Label categories
The table below defines the labels to be used when classifying issues and pull requests.
Each label is assigned to one of these categories:
* Area
* Priority
* Release category
* Status
* Type
* Versioning
# Usage
A label from *Area* and *Type* should be attached to an issue or pull request,
when applicable.
One label from *Priority* could be attached to an issue, or else the issue is
considered to have normal priority. Similarly, the same could be done for a pull
request.
A label from *Status* can be used if applicable.
A PR should always have exactly one label from *Versioning* except in the
[Zonemaster/Zonemaster] repository where they do not apply.
A PR should have one or more labels from *Release category*. `RC-None` must not
be combined with any other *Release category* label.
## Labels
Category | Label | Color | Used in repository | Scope | Description
-----------------|--------------------|---------|--------------------|-------|---------------------------------------------------------
Area | A-Documentation | green | all | Both | Area: Documentation only.
Area | A-TestCase | green | main or Engine | Both | Area: Test case specification or implementation of test case.
Area | A-Translation | green | all | Both | Area: Documentation of, implementation of or actual translation of text.
Priority | P-High | red | all | Both | Priority: Issue to be solved before others.
Release category | RC-BreakingChanges | magenta | all | PR | Release category: Breaking changes.
Release category | RC-Deprecations | magenta | all | PR | Release category: Deprecations.
Release category | RC-Features | magenta | all | PR | Release category: Features.
Release category | RC-Fixes | magenta | all | PR | Release category: Fixes.
Release category | RC-None | magenta | all | PR | Release category: Not to be included in Changes file.
Status | S-ReleaseTested | yellow | all | PR | Status: The PR has been successfully tested in release testing.
Status | S-PRforIssue | yellow | all | Issue | Status: There is a PR that is meant to resolve the issue.
Type | T-Bug | red | all | Both | Type: Bug in software or error in test case specification.
Type | T-Feature | blue | all | Issue | Type: New feature in software or test case specification.
Type | T-Question | blue | all | Issue | Type: External question.
Type | T-TrackingIssue | blue | all | Issue | Type: Tracks other issues, PRs or other changes.
Versioning | V-Major | pink | all but main | Both | Versioning: The change gives an update of major in version.
Versioning | V-Minor | pink | all but main | Both | Versioning: The change gives an update of minor in version.
Versioning | V-Patch | pink | all but main | Both | Versioning: The change gives an update of patch in version.
### Color
In the table above, the following terms for "Color" are defined:
Term | Color code
---------|---------------------------------------------
blue | #0CCFF2
green | #55D700
pink | #FFC0CB
red | #EE0701
yellow | #FFCE2E
magenta | #D4C5F9
### Used in repository
In the table above, the following terms for "Used in repository" are defined:
Term | Definition or meaning
---------|---------------------------------------------
all | Stands for the [Zonemaster/Zonemaster], [Zonemaster-LDNS], [Zonemaster-Engine], [Zonemaster-CLI], [Zonemaster-Backend] and [Zonemaster-GUI] repositories
main | Stands for the [Zonemaster/Zonemaster] repository
Engine | Stands for the [Zonemaster-Engine] repository
### Scope
In the table above, the following terms for "Scope" are defined:
Term | Definition or meaning
------|---------------------------------------------------
PR | The label is meant for Pull Request only
Issue | The label is meant for Issue only
Both | The label is meant for both Pull Request and Issue
[Zonemaster/Zonemaster]: https://github.com/zonemaster/zonemaster
[Zonemaster-LDNS]: https://github.com/zonemaster/zonemaster-ldns
[Zonemaster-Engine]: https://github.com/zonemaster/zonemaster-engine
[Zonemaster-CLI]: https://github.com/zonemaster/zonemaster-cli
[Zonemaster-Backend]: https://github.com/zonemaster/zonemaster-backend
[Zonemaster-GUI]: https://github.com/zonemaster/zonemaster-gui

364
zonemaster/docs/internal/maintenance/ReleaseProcess-create-docker-image.md Normal file
View File

@@ -0,0 +1,364 @@
Release Process - Create Docker Image
=====================================
## Table of contents
* [1. Overview](#1-overview)
* [2. Prerequisite](#2-prerequisite)
* [3. Create Docker images](#3-create-docker-images)
* [4. Upload images to Docker Hub](#4-upload-images-to-docker-hub)
* [5. Image sanity checks][sanity checks]
* [6. Handy Docker commands][Handy Docker commands]
## 1. Overview
This document covers two stages in the release processes:
1. Creating Docker images for testing.
2. Creating Docker image for publishing on Docker Hub
Presently only Zonemaster-CLI is published, and therefore only Zonemaster-LDNS,
Zonemaster-Engine and Zonemaster-CLI are covered here.
## 2. Prerequisite
### Environment
The steps in this documents are assumed to be executed on a computer installed
as an [Ubuntu Build Environment] computer. It could work on another OS as long
as the same support is available.
All commands in this instruction are assumed to be executed from the one and the
same directory. If you run `cd`, then you have to run `cd` back to the start
directory.
The Docker environment is assumed to be clean. Consider running the following
commands to clean up before proceeding (see section "[Handy Docker commands]"):
```sh
[ "$(docker ps -a -q)" != '' ] && docker rm -f $(docker ps -a -q)
```
```sh
[ "$(docker image ls -q)" != '' ] && docker image prune -a
```
### Enable IPv6 support
Docker has no IPv6 support by default. On Linux it can be enabled. Do that unless
already done, or else zonemaster-cli will report errors when trying to access
servers on IPv6.
Create or update `/etc/docker/daemon.json`. This is a minimal file that enables
IPv6 support:
```json
{
"ipv6": true,
"fixed-cidr-v6": "2001:db8:1::/64"
}
```
Restart the docker daemon:
```sh
sudo systemctl restart docker
```
## 3. Create Docker images
### Clone the repositories
```sh
git clone https://github.com/zonemaster/zonemaster-ldns
git clone https://github.com/zonemaster/zonemaster-engine
git clone https://github.com/zonemaster/zonemaster-cli
git clone https://github.com/zonemaster/zonemaster-backend
```
### Check out right branch depending on the use case
* Check out `develop` branch when creating an image for release testing:
```sh
git -C zonemaster-ldns checkout origin/develop
git -C zonemaster-engine checkout origin/develop
git -C zonemaster-cli checkout origin/develop
git -C zonemaster-backend checkout origin/develop
```
* Check out `master` branch when creating an image for Docker Hub at release, or
when creating an image based on release version:
```sh
git -C zonemaster-ldns checkout origin/master
git -C zonemaster-engine checkout origin/master
git -C zonemaster-cli checkout origin/master
git -C zonemaster-backend checkout origin/master
```
### Make sure repositories are clean and create `Makefile` in all repositories
```sh
(cd zonemaster-ldns; git submodule deinit -f ldns; git clean -dfx; git reset --hard; perl Makefile.PL)
```
```sh
(cd zonemaster-engine; git clean -dfx; git reset --hard; perl Makefile.PL)
```
```sh
(cd zonemaster-cli; git clean -dfx; git reset --hard; perl Makefile.PL)
```
```sh
(cd zonemaster-backend; git clean -dfx; git reset --hard; perl Makefile.PL)
```
### Create images
Create an image for each repository. That image will be tagged "local". The
images must be created in order since there is a dependency on the previous
image in each step.
```sh
make -C zonemaster-ldns all dist docker-build
```
```sh
make -C zonemaster-engine all dist docker-build
```
```sh
make -C zonemaster-cli all dist docker-build
```
```sh
make -C zonemaster-backend all dist docker-build
```
### Determine version of Zonemaster-CLI image
> The description in this section must be followed if the image is to be uploaded
> to Docker Hub below. If not, this section can be skipped, modified or followed
> depending on needs.
The version of Zonemaster-CLI has the format "v0.0.0" and it is the normal
version of the Docker image too. If needed a "dash version" is used on the Docker
images, and that has the format "v0.0.0-N" where "v0.0.0" is the same version as
Zonemaster-CLI, and "N" is a positive integer starting with "1".
First determine what the version should be. Compare the version of
Zonemaster-Cli just built with the highest version of the image uploaded to
Docker Hub. There are three valid possibilities:
1. The version on Docker Hub has lower version than the local version. If so
set the tags of the image with the simple steps below ignoring "dash
versions".
*Example: version on Docker Hub is v6.0.0 or v6.0.0-1, local version is v6.0.1,
new image will have version v6.0.1.*
2. The version on Docker Hub has the same version as the local version. Set the
version on the new Docker image to be "v0.0.0-1" where "v0.0.0" is equal to
the local version.
*Example: version on Docker Hub is v6.0.1, local version is v6.0.1, new image
will have version v6.0.1-1.*
3. The version on Docker Hub is a "dash version" where the "v0.0.0" part is the
same as the local version. Set the version of the new Docker image to be
"v0.0.0-N" where "v0.0.0" is equal to the local version and "N" is the
integer incremented by 1 compared to the version on Docker Hub.
*Example: version on Docker Hub is v6.0.1-1, local version is v6.0.1, new image
will have version v6.0.1-2.*
### Determine version of Zonemaster-Backend image
The version of Zonemaster-Backend follows the same rules as Zonemaster-CLI.
### Tag the Zonemaster-CLI image
For the Zonemaster-CLI image, add a version tag and a tag "latest".
* Add version tag:
```sh
make -C zonemaster-cli docker-tag-version
```
* Add tag "latest":
```sh
make -C zonemaster-cli docker-tag-latest
```
* If "dash version" is to be used, set tag with that version and remove tag with
plain version where "v0.0.0" should be the local version and "v0.0.0-N" should be
the "dash version" determined above:
```
cd zonemaster-cli
docker tag zonemaster/cli:local zonemaster/cli:v0.0.0-N
docker rmi zonemaster/cli:v0.0.0
```
All the created images can now be listed. Also consider doing [sanity checks] to
verify that all images work. Images without tag are temporary images without
further use. List images:
```sh
docker images
```
### Tag the Zonemaster-Backend image
For the Zonemaster-Backend image, add a version tag and a tag "latest".
* Add version tag:
```sh
make -C zonemaster-backend docker-tag-version
```
* Add tag "latest":
```sh
make -C zonemaster-backend docker-tag-latest
```
* If "dash version" is to be used, set tag with that version and remove tag with
plain version where "v0.0.0" should be the local version and "v0.0.0-N" should be
the "dash version" determined above:
```
cd zonemaster-backend
docker tag zonemaster/backend:local zonemaster/backend:v0.0.0-N
docker rmi zonemaster/backend:v0.0.0
```
All the created images can now be listed. Also consider doing [sanity checks] to
verify that all images work. Images without tag are temporary images without
further use. List images:
```sh
docker images
```
## 4. Upload images to Docker Hub
To upload an image to the Zonemaster Docker Hub organization you have to have
a Docker Hub account and the authorization to upload images.
```sh
docker login
```
The same image is pushed twice with different tags. Verify in the listing
above that they have the same ID.
* Push latest.
```sh
docker push zonemaster/cli:latest
docker push zonemaster/backend:latest
```
* Set correct version (see listing above) and push image with version tag. If
"dash version" is used, use "v0.0.0-N" set to correct version instead.
```sh
docker push zonemaster/cli:v0.0.0
docker push zonemaster/backend:v0.0.0
```
## 5. Image sanity checks
Zonemaster-LDNS:
```sh
docker run --rm zonemaster/ldns:local perl -MZonemaster::LDNS -E 'say Zonemaster::LDNS->new("9.9.9.9")->query("zonemaster.net")->string'
```
Zonemaster-Engine:
```sh
docker run --rm zonemaster/engine:local perl -MZonemaster::Engine -E 'say join "\n", Zonemaster::Engine->test_module("BASIC", "zonemaster.net")'
```
Zonemaster-CLI:
```sh
docker run --rm zonemaster/cli:local zonemaster.net
```
Zonemaster-Backend:
Start the backend in the background:
```sh
docker run --rm -p 5000:5000 --name zm -d zonemaster/backend:local full
```
Run `docker ps -a`. The container named `zm` should be running.
Run a test through the backend:
```sh
docker run -ti --rm --net host zonemaster/backend:local zmtest zonemaster.net
```
The output should be a JSON object containing, among other things,
a list of message tags in JSON format.
Test the correct operation of the `zmb` tool by running a test:
```sh
docker run -ti --rm --net host zonemaster/backend:local zmb start_domain_test --domain zonemaster.net
docker run -ti --rm --net host zonemaster/backend:local zmb get_test_results --test-id be98f37d3b137ce0 --lang en
```
The output should be a JSON object, similar to the previous one.
Finally, stop the backend:
```sh
docker stop zm
```
And run `docker ps -a` to ensure that the backend is no longer running.
## 6. Handy Docker commands
List all containers, including stopped containers.
```sh
docker ps -a
```
List all images
```sh
docker images
```
Remove container identified as "ID"
```sh
docker rm ID
```
Remove image identified as "ID"
```sh
docker rmi ID
```
Remove all containers
```sh
docker rm -f $(docker ps -a -q)
```
Remove all images
```sh
docker image prune -a
```
Save an image to a tar file
```sh
docker save -o docker-zonemaster-cli.tar zonemaster/engine
```
Load an image from a tar file
```sh
docker load -i docker-zonemaster-cli.tar
```
[Ubuntu Build Environment]: ../distrib-testing/Ubuntu-build-environment.md
[Sanity checks]: #5-image-sanity-checks
[Handy Docker commands]: #6-handy-docker-commands

168
zonemaster/docs/internal/maintenance/ReleaseProcess-create-test-distribution.md Normal file
View File

@@ -0,0 +1,168 @@
Release process - Create Test Distribution
==========================================
## Table of contents
* [1. Overview](#1-overview)
* [2. Prepare a build environment](#2-prepare-a-build-environment)
* [3. Create a clean environment](#3-create-a-clean-environment)
* [4. Generate Makefile, META.yml and others](#4-generate-makefile-metayml-and-others)
* [5. Verify that MANIFEST is up to date and that tarball can be built](#5-verify-that-manifest-is-up-to-date-and-that-tarball-can-be-built)
* [6. Produce distribution tarballs](#6-produce-distribution-tarballs)
* [7. Produce distribution zip file](#7-produce-distribution-zip-file)
* [8. Produce Docker image](#8-produce-docker-image)
* [9. Verify that Zonemaster works when installed](#9-verify-that-zonemaster-works-when-installed)
* [10. Restart testing](#10-restart-testing)
## 1. Overview
The purpose of this part is to create the test distributions that can be
used in QA testing for a release. It can also be used to create test
distributions to verify a pull request.
> **Note:** *Normally, the develop branch version of this document should be used.*
## 2. Prepare a build environment
Set up build system to be used for the test distribution creation. See
[Build Environment Preparation] for how to set it up.
## 3. Create a clean environment
Make sure that you have checked out the correct git branch, normally
the `develop` branch and that your clone is up-to-date.
```
git fetch --all
git branch
```
For Zonemaster-LDNS only - empty the submodule area (LDNS):
```
git submodule deinit -f ldns
```
Make sure your working directory is clean.
```
git status --ignored
```
To clean (throw away untracked changes or files):
```
git clean -dfx
git reset --hard
```
You should usually work in the *develop branch*, and that should be up-to-date
with the remote *develop branch*. Your working branch:
```
git branch -av | grep "^*"
```
All branches called "develop":
```
git branch -av --list "*develop"
```
## 4. Generate Makefile, META.yml and others
> This section is not relevant for Zonemaster-GUI.
* For Zonemaster-LDNS:
```
perl Makefile.PL --no-ed25519
```
* For all components except Zonemaster-LDNS:
```
perl Makefile.PL
```
> **Note: You can ignore the following warnings:**
> * Missing META.yml (created by the very same command).
> * Zonemaster-LDNS: Missing ldns source files (fetched by the very same command).
> * Zonemaster-Engine and Zonemaster-CLI: Missing .mo files (created in a later step).
> * Missing prerequisite (only needed on target system), e.g.:
> * "Warning: prerequisite JSON::XS 0 not found."
## 5. Verify that MANIFEST is up to date and that tarball can be built
> This section is not relevant for Zonemaster-GUI.
Build generated files (if any) and verify that a distribution tarball can be
successfully built for each component that is to be updated in this release.
```
make all
```
For all components, make sure that all files are covered by MANIFEST and/or
MANIFEST.SKIP, i.e. no missing or extra files:
```
make distcheck
```
## 6. Produce distribution tarballs
> This section is not relevant for Zonemaster-GUI.
```
make dist
```
## 7. Produce distribution zip file
> This section is relevant for Zonemaster-GUI only.
For this you need a [build environment for Node.js], on which you create
the zip file.
Clone the Zonemaster-GUI git repository:
1. `git clone -b develop https://github.com/zonemaster/zonemaster-gui.git`
2. `cd zonemaster-gui`
If you already have the repository:
1. `cd zonemaster-gui`
2. `git fetch --all`
3. `git checkout origin/develop`
Build the distribution zip file:
1. `npm install`
2. `npm run build`
3. `npm run release`
> If you get building errors, repeat the `nvm` commands in
> [build environment for Node.js] first.
>
> Usually you can ignore warnings and security fixes, and usually you
> do not run any `npm audit fix`. Check for open issues in Zonemaster-GUI
> and ask the others in the work group.
The distribution zip file is in the root level of the zonemaster-gui folder.
Its name is `zonemaster_web_gui_v0.0.0.zip` with correct version.
## 8. Produce Docker image
Follow the instructions in [Create Docker Image] to build CLI Docker image for
testing.
## 9. Verify that Zonemaster works when installed
Verify that Zonemaster works when installed according to the documented
installation procedures
Using the *preliminary distribution tarballs* produced in step 6 above, the
*preliminary distribution zip file* produced in step 7 above and the Docker
image produced in step 8, follow the procedures in [SystemTesting].
## 10. Restart testing
If the system testing fails in a way that requires updated distribution
tarballs, zip file or Docker image:
1. Get the changes merged.
2. Consider whether the actions taken in steps 2–8 above need amendment.
3. Resume this document from step 9 above.
[Build Environment Preparation]: ../distrib-testing/README.md
[Build environment for Node.js]: ../distrib-testing/Ubuntu-Node.js-build-environment.md
[Create Docker Image]: ReleaseProcess-create-docker-image.md
[NVM]: https://github.com/nvm-sh/nvm
[Node.js]: https://nodejs.org/en/
[SystemTesting]: SystemTesting.md

190
zonemaster/docs/internal/maintenance/ReleaseProcess-deb-packages.md Normal file
View File

@@ -0,0 +1,190 @@
Release Process - Create .deb packages
======================================
## Overview
The purpose of this process is to create and publish .deb packages for
Zonemaster components, currently only Zonemaster-CLI, Zonemaster-Engine and
Zonemaster-LDNS are covered.
The process to build the packages is split in two steps. In the first step "nightly
packages" are updated. In the second step packages are promoted to "stable packages".
## 1. Update the nightly packages specification
Nightly packages are based on the develop branch of Zonemaster git repositories.
The sources for nightly packages are kept in the branch `<distribution>-nightly`
of the [Packages sources] repository. Where `<distribution>` corresponds to the
name of the Debian or Ubuntu version the branch is building packages for.
As Ubuntu packages are based on the Debian ones, this will most likely be a
Debian version name.
For each package:
1. If dependencies have changed, update the `Build-Depends` and `Depends`
section of the `debian/control` file for each required package to add
and/or remove any dependencies that have changed.
2. If there are new files (such as executables), update `debian/*.manpages` and
`debian/*.install` accordingly. This step is not required for new Perl
modules, but will be for new scripts.
## 2. Promote the nightly build to stable
When a new Zonemaster release of the relevant component has been
[published on GitHub], and when the nightly package is working fine (the build
is successful, it can be installed and is usable, all of that should have been
already checked during the release testing if the package specification has not
changed since), promote it to stable. The only difference between a nightly
packages and its promoted version is the upstream tarball. While the nightly
packages use the develop branch as upstream, the stable ones use a specific
tag.
1. Locally merge the `<distribution>-nightly` branch into `<distribution>` of
the [Packages sources] repository. The `.gitlab-ci.yml` and `pkg.sh` files
should not be merged.
For instance the following commands could be used to merge
`bullseye-nightly` into `bullseye`:
```
git checkout bullseye
git merge --no-commit bullseye-nightly
git reset HEAD -- .gitlab-ci.yml */pkg.sh
git checkout -- .gitlab-ci.yml */pkg.sh
git commit
```
2. Update the upstream ref in `pkg.sh` with the tag of the corresponding release
for each package.
3. Update the `changelog` for each package, by adding a new entry. The first line
should contain the package version in format
`<project version>-<package version>`.
For example: `zonemaster-cli (3.1.0-3)` is the partial entry for
Zonemaster-CLI version `3.1.0`, the package version is `3`. Package version
is incremented when the package sources are updated but the upstream version
(i.e. Zonemaster component version) remains the same.
4. Push the modifications to the packages sources repository. Then the packages
are automatically built and deployed to package.zonemaster.net.
> Note: It is fairly important to perform all of those steps in "one push"
> as the continuous deployment pipeline will start building the new packages
> on the push event.
## Test the packages
To test the newly created packages you can configure Zonemaster packages
repository using:
```sh
curl -LSsf https://package.zonemaster.net/setup.sh | sudo sh
```
To configure the nightly repository use instead:
```sh
curl -LSsf https://package.zonemaster.net/setup.sh | sudo nightly=yes sh
```
The packages can then be installed using apt, e.g.:
```sh
sudo apt install zonemaster-cli
```
## Add support for a new OS version
Edit the `.gitlab-ci.yml` file to add three new jobs for the new OS version.
The name of the job is in the format `{step}:{os}:{version codename}`, where
step is one of `build`, `publish` and `test`. The jobs must extend a parent job
named `.{step}`. The build and publish steps must also define the following
variables:
* `OS`: OS name as it is in the `/etc/os-release`;
* `DISTRIBUTION`: Version codename as defined by `VERSION_CODENAME` in
`/etc/os-release`, optionally suffixed by `-nightly`.
The container image used for building should be the same version as the targeted
distribution.
Example for Ubuntu 22.04, codename "Jammy" the following is added to the CI
file.
```yml
build:ubuntu:jammy:
extends: .build
image: ubuntu:jammy
variables:
# For nightly
#DISTRIBUTION: jammy-nightly
# For stable
DISTRIBUTION: jammy
OS: ubuntu
publish:ubuntu:jammy:
extends: .publish
image: ubuntu:jammy
variables:
# For nightly
#DISTRIBUTION: jammy-nightly
# For stable
DISTRIBUTION: jammy
OS: ubuntu
needs:
- build:ubuntu:jammy
test:ubuntu:jammy:
extends: .test
image: ubuntu:jammy
# Only in nightly branches
#variables:
# nightly: 'yes'
needs:
- publish:ubuntu:jammy
```
When publishing packages for a different Debian version, it may be prefered to
create a separate set of branches. In this case the new CI jobs replace the olds
ones in the CI file.
## Appendices
### Repositories location
* [Packages sources]: hold the sources for all Zonemaster packages.
Each package is split in two, one for the libraries and executable and an
other one for the documentation. The documentation packages are marked as
"Recommends" and will be installed by default alongside their corresponding
package.
* [Common GitLab pipeline]: common ci/cd jobs for all branches in the packages
source repository.
* [`package.zonemaster.net` content]: setup script and public verification key
### Publication pipeline overview
The continuous deployment pipeline performs 3 tasks:
1. `build`: build the packages using the `build.sh` script in the packages
sources repository.
2. `publish`: update the [aptly] repository and publish the new packages.
3. `test`: perform a smoke test by installing the latest package and running the
CLI.
### Further resources
* [Aptly documentation](https://www.aptly.info/doc/overview/)
* [Debian maintainer guide](https://www.debian.org/doc/manuals/maint-guide/)
* [Third party repository in Debian](https://wiki.debian.org/DebianRepository/UseThirdParty)
[aptly]: https://www.aptly.info
[Packages sources]: https://gitlab.rd.nic.fr/zonemaster/packages/debian
[Common GitLab pipeline]: https://gitlab.rd.nic.fr/zonemaster/ci/-/blob/main/deb-packaging.yml
[`package.zonemaster.net` content]: https://gitlab.rd.nic.fr/zonemaster/packages/www/
[published on GitHub]: ReleaseProcess-release.md#17-tag-the-release-with-git

107
zonemaster/docs/internal/maintenance/ReleaseProcess-preparation.md Normal file
View File

@@ -0,0 +1,107 @@
Release process - Preparation
=============================
The steps in this document should be processed early in the release
process, definitely before acceptance testing starts, but also before
development has been completed.
## 1. Update prerequisites
Make sure the [declaration of prerequisites] is up to date with regard to
[SupportCriteria].
## 2. Update [CI] configuration
Make sure the Travis configuration for each repo, in the `develop` branch
is up to date with the [supported Perl versions].
* zonemaster-ldns - [.travis.yml][ldns.travis]
* zonemaster-engine - [.github/workflows/ci.yml][engine.github-actions]
* zonemaster-cli - [.travis.yml][cli.travis]
* zonemaster-backend - [.travis.yml][backend.travis]
> Zonemaster-GUI uses no Perl and Zonemaster/Zonemaster uses no Travis.
## 3. Verify that META.yml will have all the correct data
> This section is not relevant for Zonemaster-GUI or Zonemaster/Zonemaster.
META.yml is created by Makefile.PL so if META.yml is not correct, then
Makefile.PL must be updated.
1. Make a clean clone for each repository
```
git clean -dfx
git reset --hard
```
2. Check out the `develop` branch. Check out the right commit
of the submodule (LDNS) if Zonemaster-LDNS.
```
git checkout origin/develop
git submodule update # Zonemaster-LDNS only
```
3. Run
```
perl Makefile.PL --no-ed25519 # zonemaster-ldns only
perl Makefile.PL # other repositories
```
4. Verify that META.yml contains all the paths in the table in [Appendix META]
below and that the value at each path matches the listed requirement.
## 4. Verify that MANIFEST and MANIFEST.SKIP are up to date
> This section is not relevant for Zonemaster-GUI or Zonemaster/Zonemaster.
MANIFEST must, directly or indirectly, list all files that should be installed.
MANIFEST.SKIP must list all file that should not be installed, and what is
counted are all files available when `make dist` is run.
## 5. Check for deprecated features
Check all documentation in all repositories for deprecated features that are
planned to be removed in the upcoming release.
If anything was found and there is no PR to remove it, then create an issue
labelled `P-High` that something must be done before the release unless there is
already an issue.
Removed feature will probably require that the major version is increased
(breaking change). See "[Versions and Releases]".
## Appendix META
Requirements for generated META.yml file.
Property | Requirement
---------------------|----------------------------------------------------------------------
abstract | component tag line
author | current maintainer and original author
license | [license string]
name | name of the component
recommends | all modules that aren't strictly required but still used if available
requires | all required modules
requires.perl | minimum perl version
resources.bugtracker | link to the bug tracker
resources.license | link to the license text
resources.repository | link to the repository
version | version number of the new release
[CI]: https://github.com/travis-ci/travis-ci
[declaration of prerequisites]: ../../public/installation/prerequisites.md
[license string]: https://metacpan.org/pod/CPAN::Meta::Spec#license
[SupportCriteria]: SupportCriteria.md
[ldns.travis]: https://github.com/zonemaster/zonemaster-ldns/blob/develop/.travis.yml
[engine.github-actions]: https://github.com/zonemaster/zonemaster-engine/blob/develop/.github/workflows/ci.yml
[cli.travis]: https://github.com/zonemaster/zonemaster-cli/blob/develop/.travis.yml
[backend.travis]: https://github.com/zonemaster/zonemaster-backend/blob/develop/.travis.yml
[supported Perl versions]: ../../public/installation/prerequisites.md#supported-perl-versions
[Appendix META]: #appendix-meta
[Versions and Releases]: ../design/Versions%20and%20Releases.md

530
zonemaster/docs/internal/maintenance/ReleaseProcess-release.md Normal file
View File

@@ -0,0 +1,530 @@
Release process - Release
=========================
## Table of contents
* [1. Overview](#1-overview)
* [2. Applicable components](#2-applicable-components)
* [3. Updates to repositories](#3-updates-to-repositories)
* [4. Determine the new version number](#4-determine-the-new-version-number)
* [5. Update the Changes files]
* [6. Set version number for Perl modules](#6-set-version-number-for-perl-modules)
* [7. Set version number for GUI](#7-set-version-number-for-gui)
* [8. Update Makefile.PL with required version](#8-update-makefilepl-with-required-version)
* [9. Create a clean Git working area of *develop branch*](#9-create-a-clean-git-working-area-of-develop-branch)
* [10. Produce distribution tarballs](#10-produce-distribution-tarballs)
* [11. Produce distribution zip file](#11-produce-distribution-zip-file)
* [12. Update Zonemaster repository main _README.md_](#12-update-zonemaster-repository-main-readmemd)
* [13. Generate documents and check public documents](#13-generate-documents-and-check-public-documents)
* [14. Upload to CPAN](#14-upload-to-cpan)
* [15. Merge develop branch into master](#15-merge-develop-branch-into-master)
* [16. Create Docker images and upload image to Docker Hub](#16-create-docker-images-and-upload-image-to-docker-hub)
* [17. Tag the release with git](#17-tag-the-release-with-git)
* [18. Announce the release](#18-announce-the-release)
* [19. Merge master into develop](#19-merge-master-into-develop)
* [20. Clean-up on discussion forum](#20-clean-up-on-discussion-forum)
* [21. Clean-up on GitHub related to the release](#21-clean-up-on-github-related-to-the-release)
* [Appendix A on version number in Makefile.PL](#appendix-a-on-version-number-in-makefilepl)
* [Appendix B on reverting commits](#appendix-b-on-reverting-commits)
## 1. Overview
The steps in this document executes the actual release. They assume that
development, the preparation steps and the QA testing have been concluded.
To run the steps below a build system is needed. See
[Build Environment Preparation] for how to set it up.
> **Note:** *Normally, the develop branch version of this document should be used.*
[(Top)](#table-of-contents)
## 2. Applicable components
Every applicable step below should be run for each component. If there are no
changes in a component (no release) it should be skipped. The main component
(Zonemaster/Zonemaster) can never be skipped and should always be released.
The components should be released in the following order:
* zonemaster-ldns
* zonemaster-engine
* zonemaster-cli
* zonemaster-backend
* zonemaster-gui
* Zonemaster/Zonemaster
[(Top)](#table-of-contents)
## 3. Updates to repositories
All updates to *develop branch* and *master branch* should go via pull
requests following the usual process. That is just assumed here.
[(Top)](#table-of-contents)
## 4. Determine the new version number
The version number of the new release should be chosen according to
[Versions and Releases] document.
Each component listed above should have its version number. The Zonemaster
Product (Zonemaster/Zonemaster) version number also refer to the version
of the other components.
[(Top)](#table-of-contents)
## 5. Update the Changes files
Any changes since the last release must be documented in the Changes files.
Refer to any GitHub issues or pull requests related to the change by the
issue number or pull request number or both.
The updates to the *Changes* file are done to the *develop branch*.
* zonemaster-ldns - [Changes LDNS]
* zonemaster-engine - [Changes Engine]
* zonemaster-cli - [Changes CLI]
* zonemaster-backend - [Changes Backend]
* zonemaster-gui - [Changes GUI]
* Zonemaster/Zonemaster
- First update [Changes Zonemaster]
- Then update the [RELEASE.md] page (use content of *Changes* file, only
latest release) to match the upcoming [Github release page].
[(Top)](#table-of-contents)
## 6. Set version number for Perl modules
> This step does not apply to Zonemaster/Zonemaster and Zonemaster-GUI
The version numbers is to be set in these Perl modules in the *develop branch*:
* zonemaster-ldns - [LDNS.pm]
* zonemaster-engine - [Engine.pm]
* zonemaster-cli - [CLI.pm]
* zonemaster-backend - [Backend.pm]
[(Top)](#table-of-contents)
## 7. Set version number for GUI
> This step applies to Zonemaster-GUI only
Update the following files in the *develop branch* of **Zonemaster-GUI**:
* [package.json][package.json GUI]
- In the top of the file, the version is given after "version".
- The file `package-lock.json` is ignored
Update the following file in the *develop branch* of **Zonemaster/Zonemaster**:
* [public/installation/zonemaster-gui.md][Installation.md GUI]
- The version is both part of the filename (zip file) and part of the download
path (a directory). Both are repeated several times, once per OS.
> The update of the installation document can preferably be done in the same
> pull request as the update of the `Changes` file for Zonemaster/Zonemaster
[(Top)](#table-of-contents)
## 8. Update Makefile.PL with required version
> This section is relevant for Zonemaster-Engine, Zonemaster-CLI and
> Zonemaster-Backend.
If needed, update Makefile.PL in the *develop branch*. See [Appendix A] for
how the version number should be specified in `Makefile.PL`.
Usually let Zonemaster-Engine, Zonemaster-CLI and Zonemaster-Backend,
respectively, require the version of other the Zonemaster components
(see below) included in this release, because that is what has been tested.
If a component will not be updated by this release, then it can continue to
require the previous version unless it must be change to resolve some issue,
and then the version of the requiring component must also be updated.
In **[Zonemaster-Engine Makefile.PL]** set the lowest version of Zonemaster-LDNS
that Zonemaster-Engine requires. E.g.
```
requires 'Zonemaster::LDNS' => 2.001;
```
In **[Zonemaster-CLI Makefile.PL]** and **[Zonemaster-Backend Makefile.PL]**,
set the minimum required versions of Zonemaster-LDNS and Zonemaster-Engine.
E.g.
```
requires 'Zonemaster::Engine' => 4.000;
requires 'Zonemaster::LDNS' => 2.001;
```
[(Top)](#table-of-contents)
## 9. Create a clean Git working area of *develop branch*
Make sure that you have checked out the `develop` branch and that your clone is
up-to-date.
```
git fetch --all
git branch
```
Empty the submodule area (LDNS). Zonemaster-LDNS only.
```
git submodule deinit -f ldns
```
Make sure your working directory is clean.
```
git status --ignored
```
Or clean it.
```
git clean -dfx
git reset --hard
```
[(Top)](#table-of-contents)
## 10. Produce distribution tarballs
> This section is not relevant for Zonemaster-GUI or Zonemaster/Zonemaster
See [Release process - Create Test Distribution], sections 4-6 for more details
and what warnings that could be ignored.
```
perl Makefile.PL --no-ed25519 # For Zonemaster-LDNS:
```
```
perl Makefile.PL # For other components
```
```
make all # For all
make distcheck
make dist
```
[(Top)](#table-of-contents)
## 11. Produce distribution zip file
> This section is relevant for Zonemaster-GUI only.
For this you need a [build environment for Node.js], on which you create
the zip file. See [Release process - Create Test Distribution], sections 7
for more details
Build the distribution zip file:
```
npm install
npm run build
npm run release
```
> If you get building errors, repeat the `nvm` commands in
> [build environment for Node.js] first.
>
> You can ignore warnings and security fixes at this stage, and do not run
> any `npm audit fix`.
The distribution zip file is in the root level of the zonemaster-gui folder.
Its name is `zonemaster_web_gui_v0.0.0.zip` with correct version.
[(Top)](#table-of-contents)
## 12. Update Zonemaster repository main _README.md_
> This section is relevant for Zonemaster/Zonemaster only.
If needed, update the following section of the Zonemaster repository main
[README.md][Zonemaster main README] file in *develop branch*:
* Notable bugs and issues
[(Top)](#table-of-contents)
## 13. Generate documents and check public documents
> The two sub-sections here are relevant for Zonemaster/Zonemaster only.
### 13.1. Generate documents
If no files in neither Zonemaster/Zonemaster nor Zonemaster-Engine have been
updated this section can be skipped.
1. On a computer install Zonemaster-LDNS and Zonemaster-Engine using the
distribution packages created for this release.
2. Clone Zonemaster/Zonemaster and check out the *develop branch*. The
working area should be clean (`git status --ignore`).
3. Go to the [utils][utils Zonemaster] directory and create the files as
documented in the [README.pm][Zonemaster utils README] file in that
directory.
4. If any of the created files has been updated (`git status`) then it
should be added to the *develop branch* via a pull request.
5. No reviewer or approval is required for this change.
### 13.2 Check public documents
> The step above, 13.1, should be completed (merged to develop branch) before
> this step is run to avoid double errors.
Prior to this step `mdbook-linkcheck` must be installed (see
[Build environment preparation]). Run from the Zonemaster/Zonemaster
repository (develop branch checked out):
```
mdbook-linkcheck -s docs/public/
```
1. If any error is reported, correct the file or files.
2. Add changes to the *develop branch* via a pull request.
3. No reviewer or approval is required for this change.
4. Repeat the command after merging the changes to verify that the found errors
have been resolved.
[(Top)](#table-of-contents)
## 14. Upload to CPAN
> This section is not relevant for Zonemaster-GUI or Zonemaster/Zonemaster.
For each component that is to be updated in this release, publish the
distribution tarball created following this document on CPAN.
Currently we use the organizational account [ZNMSTR] on [PAUSE] for doing
this.
[(Top)](#table-of-contents)
## 15. Merge develop branch into master
> For the steps in this section, it is assumed that the git "remote"
> which is called "origin" points at "zonemaster/zonemaster.git",
> "zonemaster/zonemaster-ldns.git" etc. This is default when making a
> git clone. Use `git remote -v` to verify that.
Make sure you're up to date and your working directory is completely clean:
git fetch origin
git status --ignored
> **Note:** To throw away any and all changes to tracked and untracked files you
> can run `git clean -dfx ; git reset --hard`.
Verify if there are commits on `master` since last release:
TAG=$( git tag --list --sort=-creatordate | head -n 1 )
# count the number of commits in master since last release and
# if the count is not 0, look for commits belonging to master and develop
[ $(git rev-list --count $TAG..master) -ne 0 ] && cat <( git rev-list $TAG^2..develop ) <( git rev-list $TAG..master ) | sort | uniq -d
If commits are returned by this previous command, some additional work is
needed. See [Appendix B] for that.
Finally once `master` branch is ready, create a pull request from `develop`
into `master` and merge it. No reviewer or approval is required for this
update.
[(Top)](#table-of-contents)
## 16. Create Docker images and upload image to Docker Hub
1. Follow the instructions in [Create Docker Image] to build a Docker images.
2. Upload the Zonemaster-CLI image to [Docker Hub] for Zonemaster using the
instructions in [Create Docker Image].
[(Top)](#table-of-contents)
## 17. Tag the release with git
For each repository, go to "releases" in GitHub and select "draft a new release".
Use the version number as tag and create a new release description. Use the
section of Changes file for the relevant release and make links of everything
that can have meaningful links, especially make links to issues and PRs.
For Zonemaster-GUI, add the *distribution zip file* as attached file to the
release description in GitHub.
Always release the Zonemaster Product (Zonemaster/Zonemaster) as the last step.
The releases pages:
* [Zonemaster-LDNS Releases]
* [Zonemaster-Engine Releases]
* [Zonemaster-CLI Releases]
* [Zonemaster-Backend Releases]
* [Zonemaster-GUI Releases]
* [Zonemaster Product Releases] - use the [RELEASE.md] created in
[step 5][5. Update the Changes files].
[(Top)](#table-of-contents)
## 18. Announce the release
1. Send emails to the mailing lists `zonemaster-users` and `zonemaster-announce`
(the same email content will usually work fine). Always refer to the
[Github release page], but the URL with the version.
2. Forward the `zonemaster-users` email to the mailing list `zonemaster-group`.
3. Create an announcement on the [Zonemaster discussion forum] on GitHub.
1. Choose "New discussion"
2. Select "Announcements"
3. Use Zonemaster version as title
4. Use the body of the [Github release page] for the version as the body of
the announcement.
[(Top)](#table-of-contents)
## 19. Merge master into develop
Create a pull request from `master` on github back into `develop` and merge
it. No review or approval is required for this update.
[(Top)](#table-of-contents)
## 20. Clean-up on discussion forum
On the [Zonemaster discussion forum] on GitHub, close the announcement of the
previous version. Also close discussions that are not relevant to keep open,
i.e. resolved issues and other questions that have been answered and some time
has passed with no further follow-up questions.
[(Top)](#table-of-contents)
## 21. Clean-up on Github related to the release
For each repository:
* Zonemaster/Zonemaster
* zonemaster-ldns
* zonemaster-engine
* zonemaster-cli
* zonemaster-backend
* zonemaster-gui
Do the following steps related to the release:
1. Check the issues with the release as milestone.
1. Close if completed or irrelevant.
2. Else move to a new milestone.
2. Verify that the milestone of the release is 100% complete.
1. Close if completed.
2. Else make it complete and then close it.
3. Verify that there are milestones for at least two of the next standard releases.
1. If not, create the appropriate vYYYY.x milestones (e.g v2025.1)
2. Also, if no due date has been chosen, set YYYY-06-15 for the .1 release and
YYYY-12-15 for the .2 release.
[(Top)](#table-of-contents)
## Appendix A on version number in Makefile.PL
As described above, `Makefile.PL` of Zonemaster-CLI and Zonemaster-Backend,
respectively, must be specified with the lowest supported version of
Zonemaster::LDNS and Zonemaster::Engine, respectively. Zonemaster-Engine
must have that of Zonemaster::LDNS.
The versions of Zonemaster::LDNS and Zonemaster::Engine are defined in the
format `vX.Y.Z` and it is important how this is written in `Makefile.PL`.
For lowest risk of error follow the following steps:
1. Expand the version number with leading zeros on second ("Y") and third
("Z") level. Remove the leading `v` and the second and third dots.
E.g. `v2.1.2` = `2.001002`.
2. Decide if the third level can be skipped, e.g. `v2.1.2` > `2.001`.
3. Please note that if the version in `Makefile.PL` is set to `2.1` then
the interpretation is that the "v" version is `v2.100.0` or greater.
When specifying the version of Zonemaster::LDNS and Zonemaster::Engine in
`Makefile.PL` always use the expanded format, e.g. `2.001002` or `2.001`
depending on the need.
For other libraries, other formats may be correct. If the version of the
library only has two levels ("X.Y") then other rules apply. Also note
that the version in Zonemaster::Backend is specified as `X.Y.Z` without
the "v", which may affect the version comparison.
[(Top)](#table-of-contents)
## Appendix B on reverting commits
When merging `develop` into `master` a merge conflict could occur. This is due
to the fact that some commits belongs to both branches. Usually this is the
result of a merge request in `master` branch instead of `develop` during
development. Once this happens, the faulty merge is reverted on `master` and
merged into `develop`. Depending on the steps chosen, this could lead to having
the same commit in both branches.
To avoid merge conflict, it is necessary to revert the revert commits on
`master` (yes revert of the revert) before merging `develop` into `master`.
### How would the release officer find the commit to revert?
Usually a revert commit contains a predefined subject (or title) looking like:
`Revert "subject of the reverted commit"`.
One can looks for commits with this string using a command like:
TAG=$( git tag --list --sort=-creatordate | head -n 1 )
for c in $(cat <( git rev-list $TAG^2..develop ) <( git rev-list $TAG..master ) | sort | uniq -d); \
do git log --oneline --grep="Revert \"$(git show -s --pretty=%s $c)\"" $c~..master ^$TAG ; \
done
Or look for them visually with:
git log --oneline --graph $TAG..master
Once found, either revert each commits (`git revert <commit> ...`) or the merge
commit.
### How would the release officer know the parent number to revert?
In case one reverts the merge commit, since it was merged into master, the
parent number is `1`.
git revert -m 1 <merge commit>
[(Top)](#table-of-contents)
<!-- Zonemaster links point on purpose on the develop branch. -->
[5. Update the Changes files]: #5-update-the-changes-files
[Appendix A]: #appendix-a-on-version-number-in-makefilepl
[Appendix B]: #appendix-b-on-reverting-commits
[Backend.pm]: https://github.com/zonemaster/zonemaster-backend/blob/develop/lib/Zonemaster/Backend.pm
[Build environment preparation]: ../distrib-testing/README.md
[Build environment for Node.js]: ../distrib-testing/Ubuntu-Node.js-build-environment.md
[CI]: https://github.com/travis-ci/travis-ci
[CLI.pm]: https://github.com/zonemaster/zonemaster-cli/blob/develop/lib/Zonemaster/CLI.pm
[CPAN]: https://www.cpan.org/
[Changes Backend]: https://github.com/zonemaster/zonemaster-backend/blob/develop/Changes
[Changes CLI]: https://github.com/zonemaster/zonemaster-cli/blob/develop/Changes
[Changes Engine]: https://github.com/zonemaster/zonemaster-engine/blob/develop/Changes
[Changes GUI]: https://github.com/zonemaster/zonemaster-gui/blob/develop/Changes
[Changes LDNS]: https://github.com/zonemaster/zonemaster-ldns/blob/develop/Changes
[Changes Zonemaster]: https://github.com/zonemaster/zonemaster-gui/blob/develop/Changes
[Create Docker Image]: ReleaseProcess-create-docker-image.md
[Docker Hub]: https://hub.docker.com/u/zonemaster
[Engine.pm]: https://github.com/zonemaster/zonemaster-engine/blob/develop/lib/Zonemaster/Engine.pm
[Github release page]: https://github.com/zonemaster/zonemaster/releases/latest
[Installation.md GUI]: ../../public/installation/zonemaster-gui.md
[LDNS.pm]: https://github.com/zonemaster/zonemaster-ldns/blob/develop/lib/Zonemaster/LDNS.pm
[PAUSE]: https://pause.perl.org/pause/query
[Package.json GUI]: https://github.com/zonemaster/zonemaster-gui/blob/develop/package.json
[RELEASE.md]: ../../public/RELEASE.md
[Release process - Create Test Distribution]: ReleaseProcess-create-test-distribution.md
[Utils Zonemaster]: ../../../utils/
[Version.ts GUI]: https://github.com/zonemaster/zonemaster-gui/blob/develop/src/environments/version.ts
[Versions and releases]: ../design/Versions%20and%20Releases.md
[ZNMSTR]: https://metacpan.org/author/ZNMSTR
[Zonemaster Product Releases]: https://github.com/zonemaster/zonemaster/releases
[Zonemaster main README]: ../../../README.md
[Zonemaster utils README]: ../../../utils/README.md
[Zonemaster-Backend Makefile.PL]: https://github.com/zonemaster/zonemaster-backend/blob/develop/Makefile.PL
[Zonemaster-Backend Releases]: https://github.com/zonemaster/zonemaster-backend/releases
[Zonemaster-CLI Makefile.PL]: https://github.com/zonemaster/zonemaster-cli/blob/develop/Makefile.PL
[Zonemaster-CLI Releases]: https://github.com/zonemaster/zonemaster-cli/releases
[Zonemaster discussion forum]: https://github.com/orgs/zonemaster/discussions
[Zonemaster-Engine Makefile.PL]: https://github.com/zonemaster/zonemaster-engine/blob/develop/Makefile.PL
[Zonemaster-Engine Releases]: https://github.com/zonemaster/zonemaster-engine/releases
[Zonemaster-GUI Releases]: https://github.com/zonemaster/zonemaster-gui/releases
[Zonemaster-LDNS Releases]: https://github.com/zonemaster/zonemaster-ldns/releases

19
zonemaster/docs/internal/maintenance/ReleaseProcess-test-planning.md Normal file
View File

@@ -0,0 +1,19 @@
Release process - Test Planning
===============================
The purpose of test planning is to raise the quality by making the release
testing more structured, getting better coverage and finding more bugs.
This gives us greater faith in our releases.
## Release testing start up-meeting
1. Compile a list of all pull requests that should be tested.
2. For each test item, discuss how it could and should be tested.
Make sure there is a heading titled "How to test this PR" in the pull request
description.
Add it if needed.
Add/update notes under this heading to reflect the conclusions made.
3. Discuss prioritization of the test items and who should test what.
Note down all the conclusions.

36
zonemaster/docs/internal/maintenance/ReleaseProcess.md Normal file
View File

@@ -0,0 +1,36 @@
Release process
===============
This process has been split into different parts which are described in their
own documents.
## 1. [Preparation]
The steps in this subprocess should be processed early in the release
process, definitely before acceptance testing starts, but also before
development has been completed.
## 2. [Test planning]
This phase should be performed after the end of development but before
acceptance testing starts.
## 3. [Create test distributions]
The purpose of this part is to create the test distributions that can be
used in QA testing for a release. It can also be used to create test
distributions to verify a pull request.
## 4. [Release]
The steps in this part executes the actual release. They assume that
development, the preparation steps and the QA testing have been concluded.
[Create test distributions]: ReleaseProcess-create-test-distribution.md
[Preparation]: ReleaseProcess-preparation.md
[Release]: ReleaseProcess-release.md
[Test planning]: ReleaseProcess-test-planning.md

29
zonemaster/docs/internal/maintenance/StyleGuide.md Normal file
View File

@@ -0,0 +1,29 @@
# Style Guide
## Scope
The following style guide applies to document text and certain file names
specified below.
## Guidelines
* Zonemaster is always written as **Zonemaster**, never shortened (e.g. "ZM") or
uncapitalized (e.g. "zonemaster").
* Case-insensitive regexes are always written out with the ignore-case flag
(e.g. `/[a-z]/i`).
* For variable names in test case specifications each word is capitalized (e.g.
"Domain Part"). If a word is an abbreviation, it is usually written with all
capitals, e.g. "DNS".
* When writing Markdown documents, use lower case fragments when referring to
internal headings' anchors, i.e. use `#objective` not `#Objective` to create
a link to the "Objective" section.
* When linking to other documents and including the URL in the rendered text,
put angle brackets around the URL, i.e. use the [CommonMark autolink] syntax.
I.e. write as `<https://example.com/>` not just as `https://example.com/`.
If the angle brackets are not included the URL is still rendered as a link on
GitHub (per [GFM autolink] syntax), but other tools may not recognize it as a
link.
[CommonMark autolink]: https://spec.commonmark.org/0.30/#autolinks
[GFM autolink]: https://github.github.com/gfm/#autolinks-extension-

156
zonemaster/docs/internal/maintenance/SupportCriteria.md Normal file
View File

@@ -0,0 +1,156 @@
Support criteria
================
This document hosts a set of guiding principles for selecting configuration
parameter items to support.
## General
It is legitimate to avoid supporting items that are otherwise perfectly eligible
for support, just for the sake of limiting the total number of configuration
tuples.
## Architectures
Zonemaster is actively tested on the amd64/x86_64 processor architecture. No
testing is currently done on ARM architecture.
## Operating systems
Zonemaster is actively tested on the following operating systems:
* Debian
* FreeBSD
* Rocky Linux
* Ubuntu
CentOS is no longer supported and has been replaced by Rocky Linux.
## Operating system versions
### List of versions is set
The criteria below are used at the time of release of Zonemaster to determine what versions
that are supported for the version of Zonemaster to be released. That list of versions is
fixed for the lifetime of the Zonemaster version.
### Criteria
The following criteria are used to determine which version of the operating
system that is supported:
* Minor version/point release/patch level should not be specified.
* Operating system versions without long term support form their
vendor should not be supported.
* Operating system versions that have reached their end-of-life (or end of
general support) should not be supported.
* Operating system versions that are expected to reach their end-of-life (or
end of general support) within the lifetime of the Zonemaster version should
not be supported.
* Operating system versions that do not provide the prerequisites for
Zonemaster should not be supported.
### Operating system specific guidelines
* Debian:
* Only the current "stable" release is supported.
* Current "stable" is listed on
<https://wiki.debian.org/DebianReleases#Current_Releases.2FRepositories>.
* FreeBSD:
* One major branch is supported. The selected major branch is supported for
its lifetime, and then replaced by the newest major branch. The replacement
is done when EOL will be reached within the expected lifetime of the
Zonemaster release.
* For the selected major release, only the newest point release is tested.
* The active major branches are found on <https://www.freebsd.org/security/>
(scroll down to "Supported FreeBSD releases").
* Rocky Linux:
* All major versions that have not reached EOL are supported.
* If the EOL of a major version is within the expected lifetime of the
Zonemaster release then that major version is not supported.
* Only the newest point release is tested.
* Active releases are listed on <https://rockylinux.org/download> and
<https://en.wikipedia.org/wiki/Rocky_Linux#Releases>.
* Ubuntu:
* All LTS versions that have not reached the "End of Standard Support" are
supported.
* If the "End of Standard Support" for an LTS version is within the expected
lifetime of the Zonemaster release then that LTS version is not supported.
* For each LTS version, only the newest point release is tested.
* LTS releases are listed on <https://wiki.ubuntu.com/Releases>.
## Database engines
Zonemaster provides database integrations for these database engines:
* MariaDB (MySQL)
* PostgreSQL
* SQLite (included in Zonemaster-Backend dependency)
## Database engine versions
The database engine versions that are provided by the respective supported
operating system version should be supported.
Database engine versions that lack required features cannot be supported.
* Database engine versions provided by each version of Debian are listed here:
* <https://packages.debian.org/search?searchon=names&keywords=mariadb-server>
* <https://packages.debian.org/search?searchon=names&keywords=postgresql>
* Database engine versions provided FreeBSD are listed here:
* <https://ports.freebsd.org/cgi/ports.cgi?query=mysql&stype=name&sektion=databases>
and look for "mysql??-server-*" (FreeBSD does not support MariaDB in a
default Backend installation).
* <https://ports.freebsd.org/cgi/ports.cgi?stype=name&sektion=databases&query=postgresql>
* Database engine versions provided by each version of Rocky Linux are listed here: TBP
* Database engine versions provided by each version of Ubuntu are listed here:
* <https://packages.ubuntu.com/search?suite=default&section=all&arch=any&searchon=names&keywords=mariadb-server>
* <https://packages.ubuntu.com/search?suite=default&section=all&arch=any&searchon=names&keywords=postgresql>
## Translation locales
Can we say something about how the current triple of locales was chosen? How
about including new languages?
## System locales
A base line locale should be included.
Locales that expose classes of bugs should be included.
## Perl versions
The Perl versions that are provided by the respective supported operating system
version should be supported.
The point release should not be specified.
* Perl versions provided by each version of Debian are listed here:
* <https://packages.debian.org/search?searchon=names&keywords=perl>
* Perl versions provided FreeBSD are listed here:
* <https://ports.freebsd.org/cgi/ports.cgi?stype=name&sektion=lang&query=perl>
* Perl versions provided by each version of Rocky Linux are listed here: TBP
* Perl versions provided by each version of Ubuntu are listed here:
* <https://packages.ubuntu.com/search?suite=default&section=all&arch=any&searchon=names&keywords=perl>
## Nice-to-have resources
* [Debian point releases](https://wiki.debian.org/DebianReleases/PointReleases)
* [Ubuntu patch levels](https://wiki.ubuntu.com/Releases)

197
zonemaster/docs/internal/maintenance/SystemTesting.md Normal file
View File

@@ -0,0 +1,197 @@
System testing
==============
Before a new version of Zonemaster can be released it must pass three levels of
system testing: Installation Testing, Smoke Testing and Acceptance Testing.
Each test level is described in a separate section below. A separate section is
reserved for the concept of Configurations, which is used by other sections.
## 1. Configurations
The purpose of configurations is to provide different contexts for the tests to
run in.
A configuration is a tuple of the following parameters:
* architecture (e.g. x86_64)
* operating system version (e.g. Ubuntu 14.04)
* database engine version (e.g. PostgreSQL 9.3)
* system locale (e.g. en_US.UTF-8)
* Perl version (e.g. 5.20)
The set of possible values for the following configuration parameters (except
for system locale) are declared in the README.md of the top-level zonemaster
repository.
The set of possible values for the system locale configuration parameter is:
* C
* en_US.UTF-8
Regarding minimum hardware requirements, the following defaults should be chosen:
* CPU: 2 cores
* RAM: 2GB
* Storage: 20GB
## 2. Installation testing
This test level validates that all components of Zonemaster can be installed
according to their respective installation instructions.
### Configurations
The set of configurations must include at least:
* One configuration for each supported architecture.
* One configuration for each supported operating system version.
* One configuration for each supported database engine version.
### Procedure
1. Make sure you have the correct preliminary distribution tarball for each
component. See [Create Test Distribution].
2. For each configuration:
1. Prepare a machine
1. Allocate a machine with the architecture specified by the configuration.
2. Follow the preparation document for the operating system specified by the configuration.
* [Debian-Preparation]
* [FreeBSD-Preparation]
* [Ubuntu-Preparation]
* Rocky-Linux-Preparation (TBD)
2. Install Zonemaster LDNS
1. Install dependencies according to the [LDNS installation] instructions.
2. Install the preliminary distribution tarball for zonemaster-ldns.
```sh
sudo cpanm Zonemaster-LDNS-${LDNS_VERSION}.tar.gz
```
3. Follow the [post-installation sanity check][LDNS sanity check] section of the installation guide to the letter.
3. Install Zonemaster Engine
1. Install dependencies according to the [Engine installation] instructions.
2. Install the preliminary distribution tarball for zonemaster-engine.
```sh
sudo cpanm Zonemaster-Engine-${ENGINE_VERSION}.tar.gz
```
3. Follow the [post-installation sanity check][Engine sanity check] section of the installation guide to the letter.
4. Install Zonemaster Backend
1. Install dependencies according to the [Backend installation] instructions.
2. Install the preliminary distribution tarball for zonemaster-backend.
```sh
sudo cpanm Zonemaster-Backend-${BACKEND_VERSION}.tar.gz
```
3. Follow the configuration section of the [Backend installation] instructions to the letter.
4. Follow the startup section of the [Backend installation] instructions to the letter.
5. Follow the [smoke test] section of the installation guide to the letter.
5. Install Zonemaster GUI
1. Follow the prerequisites section of the [GUI installation] instructions to the letter.
2. Follow the installation section of the [GUI installation] instructions to the letter.
3. Follow the configuration section of the [GUI installation] instructions to the letter.
4. Follow the startup section of the [GUI installation] instructions to the letter.
5. Follow the [post-installation sanity check][GUI sanity check] section of the installation guide to the letter.
6. Install Zonemaster CLI
1. Follow the prerequisites section of the [CLI installation] installation to the letter.
2. Install the preliminary distribution tarball for zonemaster-backend.
```sh
sudo cpanm Zonemaster-CLI-${CLI_VERSION}.tar.gz
```
3. Follow the [post-installation sanity check][CLI sanity check] section of the installation guide to the letter.
## 3. Smoke testing
This test level validates that fundamental use cases:
* work independent of specific configurations
* weren't broken by new changes
### Configurations
... To be specified.
### Procedure
For each configuration:
1. Prepare an installation
2. Smoke test of Zonemaster CLI
1. Test a working domain (e.g. `afnic.fr`)
2. Test working IDN (e.g. `президент.рф`)
3. Test a broken domain (e.g. `error.com`)
4. Working domains not signed with DNSSEC (e.g. `google.com`)
5. Working domains signed with DNSSEC (e.g. `iis.se`)
6. Broken DNSSEC domains (e.g. `broken.dnssec.ee`)
3. Smoke test of Zonemaster GUI
1. Test progress bar
2. Test presentation of results
3. Test export
4. Test history
## 4. Acceptance testing
This test level validates that each change since last release:
* works independent of specific configurations
* weren't broken by other new changes
### Configurations
... To be specified.
### Procedure
1. Prepare an installation
2. Acceptance testing through Zonemaster CLI
Test each new entry in the Changes files of *Zonemaster CLI* and *Zonemaster Engine*.
4. Acceptance testing through Zonemaster Backend
Test each new entry in the Changes file of *Zonemaster Backend*.
4. Acceptance testing through Zonemaster GUI
Test each new entry in the Changes file of *Zonemaster GUI*.
[Backend installation]: ../../public/installation/zonemaster-backend.md
[CLI installation]: ../../public/installation/zonemaster-cli.md
[CLI sanity check]: ../../public/installation/zonemaster-cli.md#post-installation-sanity-check
[Create Test Distribution]: ../maintenance/ReleaseProcess-create-test-distribution.md
[Debian-Preparation]: ../distrib-testing/Debian-build-environment.md
[Engine installation]: ../../public/installation/zonemaster-engine.md
[Engine sanity check]: ../../public/installation/zonemaster-engine.md#post-installation-sanity-check
[FreeBSD-Preparation]: ../distrib-testing/FreeBSD-build-environment.md
[GUI installation]: ../../public/installation/zonemaster-gui.md
[GUI sanity check]: ../../public/installation/zonemaster-gui.md#post-installation-sanity-check
[LDNS installation]: ../../public/installation/zonemaster-ldns.md#recommended-installation
[LDNS sanity check]: ../../public/installation/zonemaster-ldns.md#post-installation-sanity-check
[Requirements for IDN support]: https://github.com/zonemaster/zonemaster-ldns/blob/master/README.md#idn
[Smoke test]: ../../public/installation/zonemaster-backend.md#61-smoke-test
[Ubuntu-Preparation]: ../distrib-testing/Ubuntu-build-environment.md

55
zonemaster/docs/internal/requirements/CLI-Combined-Requirements.md Normal file
View File

@@ -0,0 +1,55 @@
*This is the merged requirements from the respective CLI's of
ZoneCheck and DNSCheck.*
**Usability:**
- [1.1] The output from the CLI MUST provide timestamps for each log line,
with an option to remove or add the timestamps in the output.
- [1.2] The output from the CLI MUST be able to provide information about
what test level and test case generated a certain log entry with an
option to remove or add the information in the output.
- [1.3] The CLI MUST be able to report the version used to run the test.
Optional to report any version of each individual test case.
- [1.4] The CLI MUST be able to stop testing and return at a command line
configurable error level (not only CRITICAL)
- [1.5] The CLI MUST be able to run a test over IPv4 or IPv6-only with a
provided flag (read: disable protocol at runtime).
**Input:**
- [2.1] The CLI MUST be able to output a help text, either explicitly or
if user input does not validate.
- [2.2] The CLI SHOULD have a filter parameter to be able to hide log
messages below a certain error level.
- [2.3] The CLI MUST be able to run with a user-provided configuration
(what to test). A default SHOULD be used if none is provided.
- [2.4] The CLI MUST be able to run with a user-provided policy
(error levels). A default SHOULD be used if none is provided.
- [2.5] The CLI MUST be able to run with a user-provided locale (language).
A default SHOULD be used if none is provided.
- [2.6] The user MUST be able to specify name servers and corresponding
IP-addresses as input for undelegated test purposes.
- [2.8] The user MUST be able to specify DS-data as input to be able to
test DNSSEC fully even for undelegated domains.
- [2.9] The user MUST specify no more than one domain to test.
- [2.10] The CLI MUST be able to simply report its version and exit with
a provided flag.
- [2.11] The CLI MUST be able to test all available test cases within one
group, it MAY also work per unique test case (--test=zone or --test=zone03).
**Output:**
- [3.1] The CLI MUST be able to provide an output log that is machine
parseable and this MAY be disabled or enabled with a provided parameter.
- [3.2] The CLI MUST be able to provide output that is human readable and
this SHOULD be the default mode although the default MAY be configurable.
- [3.3] The output from the CLI MUST have several levels of verbosity for
DNS debugging purposes, for example additional messages and module
version reports at a low level up to raw DNS packets and dependency
modules' versions at higher levels.
- [3.4] The CLI MUST have a flag to list all available tests and a brief
text on what these tests do. The CLI MAY also have more detailed
information about each test reachable elsewhere from the CLI.
**Optional (or for future uses):**
- [4.1] Boost policy error level WARNING to ERROR with provided flag.
- [4.2] Possible to activate tool debugging code.
- [4.3] Possibility for the CLI to limit output (filter) by type of errors
or ignore specific hosts.

23
zonemaster/docs/internal/requirements/DNSCheck-Batch-Requirements.txt Normal file
View File

@@ -0,0 +1,23 @@
Requirements for batch functionality (taken from DNSCheck 1.*'s) for the Zonemaster project. This is the functional requirements from the current DNSCheck.
Today we have several users of batch functionality, for example:
1. The Web interface uses the batch functionality to queue tests and to display history of test results.
2. The automatic support emails going out to IIS's Registrars to test and track domains as they change.
3. To generate DNS delegation quality statistics.
A batch function could be called a user of the Zonemaster test framework with the ultimate goal of easily accessing stored test results in an efficient way for statistics or reporting purposes.
One type of batch user: https://github.com/dotse/dnscheck/tree/master/webui
Another type of batch user: https://github.com/dotse/dnscheck/blob/master/engine/apps/dnscheck-dispatcher
Functions:
[1.1] A batch function MUST support grouping of test results, thus traceable and unique flagged runs for as few as one but as many as millions of zones (Current DNSCheck terminology: SOURCE).
[1.2] The batch function MUST make sure that every single test result has a unique identifier, and the result must be retrievable using the unique identifier, timestamp or test domain (Current DNSCheck terminology: UNIQUE_ID).
[1.3] A batch function MUST be able to keep complete history per test run that is linked to what source generated the test as per [1.1] (Current DNSCheck terminology: HISTORY).
[1.4] A batch function MUST be able to prioritize test runs based on an extendable (0..n) priority number (not "high/low" or similar) (Current DNSCheck terminology: QUEUE).
[1.5] The batch function MUST be able to store complete test results of up to several million tests and make these efficiently retrievable (within seconds) based on the domain as keyword for listing previous test runs.
[1.6] The batch function MUST log when a test was started, when it ended, the complete test result, what source generated the result and at what priority (TRACEABILITY).
[1.7] The batch function MUST support a queue system, running tests based on the level of priority as per [1.4].
[1.9] The batch function MUST support a configurable maximum number of concurrent domain tests it starts and maintains until completed, also based on priority as per [1.4].
[ future IIS special re-delegation test ]
[1.8] The batch function MUST be able to use information (if available) of previously used name servers for any domain being tested (HISTORY #2).

23
zonemaster/docs/internal/requirements/DNSCheck-CLI-Requirements.txt Normal file
View File

@@ -0,0 +1,23 @@
Requirements for CLI functionality (taken from DNSCheck 1.*'s) for the Zonemaster project. This is the functional requirements from the current DNSCheck.
Current code: https://github.com/dotse/dnscheck/blob/master/engine/apps/dnscheck
Usability:
[1.1] The output from the CLI MUST provide timestamps for each log line, with an option to remove or add the timestamps in the output.
[1.2] The output from the CLI MUST be able to provide information about what test level and test case generated a certain log entry with an option to remove or add the information in the output.
[1.3] The CLI MUST be able to report the version used to run the test. Optional to report any version of each individual test case.
Input:
[2.1] The CLI MUST be able to output a help text, either explicitly or if user input does not validate.
[2.2] The CLI SHOULD have a filter parameter to be able to hide log messages below a certain error level.
[2.3] The CLI MUST be able to run with a user-provided configuration. A default SHOULD be used if none is provided.
[2.4] The CLI MUST be able to run with a user-provided policy. A default SHOULD be used if none is provided.
[2.5] The CLI MUST be able to run with a user-provided locale (language). A default SHOULD be used if none is provided.
[2.6] The user MUST be able to specify name servers and corresponding IP-addresses as input for undelegated test purposes.
[2.8] The user MUST be able to specify DS-data as input to be able to test DNSSEC fully even for undelegated domains.
[2.9] The user MUST specify no more than one domain to test.
Output:
[3.1] The CLI MUST be able to provide an output log that is machine parseable and this MAY be disabled or enabled with a provided parameter.
[3.2] The CLI MUST be able to provide output that is human readable and this SHOULD be the default mode although the default MAY be configurable.
[3.3] The output from the CLI MUST have several levels of verbosity for DNS debugging purposes, for example additional messages and module version reports at a low level up to raw DNS packets and dependency modules' versions at higher levels.

35
zonemaster/docs/internal/requirements/DNSCheck-GUI-Requirements.txt Normal file
View File

@@ -0,0 +1,35 @@
Requirements for GUI functionality (taken from DNSCheck 1.*'s) for the Zonemaster project. This is the functional requirements from the current DNSCheck.
Link to example: http://dnscheck.iis.se
Link to code: https://github.com/dotse/dnscheck/tree/master/webui
Language:
[1.1] The GUI MUST support multiple languages in a standardized and reasonably easy-to-understand way (especially to make it easy to add more languages in the future).
[1.2] The GUI MUST have a way of identifying preference of connected users' language and this SHOULD be implemented on the client side (for example using language preference settings from connecting browser).
[1.3] The GUI MUST have a easily configurable default language as a fallback from req [1.2].
[1.4] The GUI MUST support IDN 2.0 domains as input.
[1.5] The GUI MUST have an easy-to-understand way to change the language from the first page.
[1.6] When a user has chosen a language the index, faq and results from the database MUST be in the chosen language UNLESS specific messages are missing where in such a case the default language COULD be used for these, or all, messages.
Usability:
[2.1] The GUI MUST have more than one possible view towards the users and the default SHOULD be the most simple one.
[2.2] The GUI MUST have a view containing the "undelegated"-functionality, this view SHOULD be perfectly clear on what this means (for example a small warning that notifies the user when presenting undelegated-results).
[2.3] The simple view SHOULD highlight found errors and warnings for the test being run.
[2.4] The simple view SHOULD give the user the possibility to see more information about encountered errors from within the simple view, if he/she so chooses.
[2.5] The GUI MUST be able to give a simple, summarized verdict on the domain being tested (for example; green/yellow/red).
[2.6] The GUI MUST provide a list with previous runs for the given domain and these SHOULD be kept separate between normal and "undelegated" testruns.
[2.7] The list from [2.6] MUST contain working links to the previous tests and these MAY be the same links as created in [4.2].
Security:
[3.1] The GUI MUST have a chroot-similar design where its config, outside of reach of the web root itself, is read only once at startup.
[3.2] The GUI MUST have all sensitive information in the protected configuration file from [3.1] but MAY have options elsewhere if deemed necessary.
[3.3] The GUI SHOULD have an easy-to-read source code that is well documented and commented.
Functionality:
[4.1] The GUI MUST have the same functionality over IPv6 as is given over IPv4 and SHOULD inform the user from what address they are connecting.
[4.2] The GUI MUST create unique links for every test generated through its interface and these links SHOULD be easy to find for the user.
[4.3] The GUI SHOULD allow links to tests that were generated from other sources than the GUI itself but MAY not allow all available sources to be accessed.

39
zonemaster/docs/internal/requirements/DefineTests.md Normal file
View File

@@ -0,0 +1,39 @@
Can we Discard these existing Test Cases
========================================
* serial number of the form YYYYMMDDnn
* Reasons for not discarding : The recommended syntax is YYYYMMDDnn (YYYY=year, MM=month, DD=day, nn=revision number. This would not overflow until the year 4294. (RFC 1912 [page 3])
* Reasons for discarding : Even though some BIND versions allow you to use a decimal in a serial
number, don't. A decimal serial number is converted to an unsigned 32-bit integer internally anyway. The formula for a n.m serial number is n*10^(3+int(0.9+log10(m))) + m which translates to
something rather unexpected. For example it's routinely possible with a decimal serial number (perhaps automatically generated by SCCS) to be incremented such that it is numerically larger, but after the above conversion yield a serial number which is LOWER than before. Decimal serial numbers have been officially deprecated in recent BIND versions. (RFC 1912 [page 3])
* Delegated domain is not an openrelay
* Reasons for discarding : Not required for testing DNS
* Domain of the hostmaster email is not an openrelay
* Reasons for discarding : Not required for testing DNS
* Can deliver email to 'postmaster'
* Reasons for discarding : This test conforms to the requirements in RFC 1123 [Page 52] "A host that supports a receiver-SMTP MUST support the reserved mailbox "Postmaster"". The RFC is setting up the
requirements for Internet hosts. But this test requirements is not really the responsibility of DNS. D
o we need this ?
* Can deliver email to hostmaster
* Reasons for not discarding : It is imperative that this address get to one or more real persons, because it is often used for everything from reporting bad DNS data to reporting security incidents (RFC 1912 [page 3])
* Domain able to receive email (delivery using MX, A, AAAA)
* Reasons for discarding : Not required for testing DNS
* Test if mail delivery possible
* Reasons for discarding : Not required for testing DNS
Defining the Test Cases
=======================
* ICMP answer
* root servers list present
* root servers list identical to ICANN
* root servers addresses identical to ICANN
* coherence between NS and ANY records
* coherence between SOA and ANY records
* coherence between MX and ANY records

53
zonemaster/docs/internal/requirements/Engine-Functional-Test-Requirements.md Normal file
View File

@@ -0,0 +1,53 @@
Engine - Functional Test requirements
======================================
Objective
----------
The purpose of Zonemaster tool is to test the quality of a DNS delegation.
The tool comprises of three different functional blocks:
1. Test engine – which comprises of necessary source code to run test
implementations and report results
2. Web GUI – will enable users to provide input (such as a domain name
with different options) and call the test engine and read results from a web
browser
3. CLI – will enable users to provide input (such as a domain name with
different options) and call the test engine and read results from a text
console
The objective of this document is to run functional tests for the two
functional blocks – Test engine and GUI. As of now CLI is not within the
scope of this document.
Scope
------
The test specification (which is part of the test engine) implemented has already
gone/going through the process of unit testing. Unit testing is done to
confirm that a unitary code (such as a single test case source code)
component provides the correct output for a given input.
Functional tests are intended to verify whether the code (written as part of
the test engine) accurately detects the DNS problem's it is meant to detect
with neither false positive nor false negative.
|Req| Test requirement |Explanation|Status|
|:--|:-------------------------------------------|-----------|------|
|FR01|A DNS query with a label that exceeds the maximum length - 63 characters|[RESTRICTION01](../functional-tests/Restriction-TP/restriction01.md)|Cannot test|
|FR02|A FQDN that exceeds the maximum length - 255 octets|[RESTRICTION02](../functional-tests/Restriction-TP/restriction02.md)|Cannot test|
|FR03|A host name label with other than letters, digits and '-'character|[RESTRICTION03](../functional-tests/Restriction-TP/restriction03.md)|Not Verified|
|FR04|CNAME RRs collision (If a CNAME RR is present at a node, no other data should be present; (3.6.2) - RFC 1034)|[CONFIGURATION01](../functional-tests/Configuration-TP/configuration01.md)|Did not test|
|FR05|Zone cyclic dependency|[CONFIGURATION02](../functional-tests/Configuration-TP/configuration02.md)|Results inconclusive|
|FR06|Lame delegation |[CONFIGURATION03](../functional-tests/Configuration-TP/configuration03.md)|OK|
|FR07|Delegation Inconsistency|[CONFIGURATION04](../functional-tests/Configuration-TP/configuration04.md)|OK|
|FR08|Test whether the tool correctly treats the name error with "NXDOMAIN" in response|[BEHAVIOR01](../functional-tests/Behavior-TP/behavior01.md)|OK|
|FR09|Test whether the tool correctly treats when "no such data exist" with "NODATA" in response|[BEHAVIOR02](../functional-tests/Behavior-TP/behavior02.md)|OK|
|FR10|Appropriate results when certain protocols are disabled (e.g.IPv6)|[BEHAVIOR03](../functional-tests/Behavior-TP/behavior03.md)|OK|
|FR11|Test whether the tool run only appropriate tests when the default test profile is modified|[BEHAVIOR04](../functional-tests/Behavior-TP/behavior04.md)|KO|
|FR12|Capable of running the test when the delegation parameters are specified|[BEHAVIOR05](../functional-tests/Behavior-TP/behavior05.md)|OK|
|FR13|Able to test non delegated domain|[BEHAVIOR05](../functional-tests/Behavior-TP/behavior05.md)|OK|
|FR14|Check whether timestamps are being displayed|[BEHAVIOR06](../functional-tests/Behavior-TP/behavior06.md)|OK|
|FR15|IDN verification|[BEHAVIOR07](../functional-tests/Behavior-TP/behavior07.md)|OK|
|FR16|Displays verbose information when it is launched with appropriate flags|[BEHAVIOR08](../functional-tests/Behavior-TP/behavior08.md)|OK|
|FR17|Triggers appropriate error code when the zone is misconfigured|[BEHAVIOR09](../functional-tests/Behavior-TP/behavior09.md)|OK|

18
zonemaster/docs/internal/requirements/ExistingZCFeatures.md Normal file
View File

@@ -0,0 +1,18 @@
# ZoneCheck Features
* Powerful XML based configuration file (allowing changes in test severity,
order, zone of application, ...)
* Does not depend on policies
* Fine grained test selection (by test, by categories, by zones)
* Full IPv6 support (connectivity and AAAA records)
* Supports several input/output interfaces such as CLI, CGI, GUI, inetd
* Dedicated mode for use inside shell scripts
* Batch mode available (ideal when dealing with several domains)
* Use of stylesheets for easy integration and javascript for enhancement only
* Generates reports either by severity or by hosts
* I18N and L10N support (available: French, English)
* Multi-threaded application in order to cut down checking time
* Extensible: new tests, new interfaces, new reports, ...
* Exception and cache mechanisms to simplify test writing
* Open source

40
zonemaster/docs/internal/requirements/ExistingZCFeaturesGUI.md Normal file
View File

@@ -0,0 +1,40 @@
Existing ZC GUI Features
========================
ZoneCheck GUI Features which could be included in "Zonemaster"
Link to example : http://www.zonecheck.fr/demo/
Language:
---------
1. Multiple language support (French and English) is available based on the
browser language settings of the user
2. Easy to add more languages other than English and French
3. Configuration settings available to select the language of the result of
the test other than that of the default page
Usability:
----------
1. Possible to test only with domain name as input
2. Possible to test undelegated domains
3. Possible to select the output format (html/text) of the test report
4. Possible to test with different test profiles
5. Has a progress bar which allows the client to have an idea that the tests
are being conducted even if there is a delay
6. Possible to select the type of the report generated
7. Possible to stop the tests on the event of a fatal error
8. Possible to have a detailed report which shows the test done, condition
for passing the test and the results of the test with details from the zone
that is being tested
9. Possible to limit testing the zone based on the needs of the user (such
as IPv4 only, TCP only etc..)
10. Provides a brief description of the test when it is performed
Functionality:
---------------
1. Possible to add new output formats easily
2. Possible to include different profile tests easily
3. Possible to add extra test easily

43
zonemaster/docs/internal/requirements/FunctionalRequirements.md Normal file
View File

@@ -0,0 +1,43 @@
Existing Functionalities
=========================
| *Input* | *Explanation* |
|:-------------------------------------------|:--------------------------------------------|
|Able to disable testing certain protocols at run time|no IPv4, IPv6, UDP, TCP etc.|
|Able to modify the test profile |Able to modify the test profile easily without modifying the code. Such as possibility to specify what tests to be run (or) not to run|
|Able to specify delegation parameters | For example to test a hypothetical zone delegation from its parent zone|
|Able to have certain defaults in initial config file to minimize configuration time for new users| |
|Possibility to use non default configuration file for specific runs| |
|Able to test non delegated domain| |
|Multiple input interfaces | Should be able to be used by normal users, DNS professionals and by an API |
| *Output* | *Explanation* |
|:-------------------------------------------|:--------------------------------------------|
|Different output format for the results | For example; HTML, XML etc. |
|Multiple output results | Comprehensible for normal user as well as DNS professionals |
|Possibility to output only a summary of results | |
|Multiple language support |Such as English, French and Swedish |
|Different Levels of verbosity | Not only on/off with decent debugging possibility |
|Sort output by errors or hosts | |
|Output a list of the tests we can run | |
|Error results clarity | Return Codes |
| Others | Explanation |
|:-------------------------------------------|:--------------------------------------------|
|Modular | * Functionality of the tool could be enhanced by adding more modules preforming additional tests
| | * Reuse of functions from one module to another
| | * Each module could have a list of dependencies on other modules. A module should be able to process the results of other modules.|
|Able to Cache the results | Helps in reducing resource consumption, thus improving performance|
|Timestamp on the test being run | As done by dnsCheck now |
|Modules should be able to report tests as they are being run | As done by dnsCheck using the "--raw"-flag|
|Separate running of tests, evaluation of results and preparing reports | |
|Ability to store results in a database | |
|Performance - optimization of network as well as system resources when compared to dnscheck and ZoneCheck | |
|Maintaining Bug report | |
|Web User Interface | |
|DNS Packet Serialization | |
| DNSSEC tests | |
|Statistics on network performance, RTT: min, max, stddev, avg, per protocol and #queries sent per name server||

69
zonemaster/docs/internal/requirements/GUI-Combined-Requirements.txt Normal file
View File

@@ -0,0 +1,69 @@
This is the merged requirements from the respective GUI's of ZoneCheck and
DNSCheck.
Language:
[1.1] The GUI MUST support multiple languages in a standardized and reasonably
easy-to-understand way (especially to make it easy to add more languages in the
future). [1.2] The GUI MUST have a way of identifying preference of connected
users' language and this SHOULD be implemented on the client side (for example
using language preference settings from connecting browser).
[1.3] The GUI MUST have a easily configurable default language as a fallback
from req [1.2].
[1.4] The GUI MUST support IDN 2.0 domains as input.
[1.5] The GUI MUST have an easy-to-understand way to change the language from
the first page.
[1.6] When a user has chosen a language the index, faq and results MUST be in
the chosen language UNLESS specific messages are missing where in such a case
the default language COULD be used for these, or all, messages.
Usability:
[2.1] The GUI MUST have more than one possible view towards the users and the
default SHOULD be the most simple one.
[2.2] The GUI MUST have a view containing the "undelegated"-functionality, this
view SHOULD be perfectly clear on what this means (for example a small warning
that notifies the user when presenting undelegated-results). [2.3] The simple
view SHOULD highlight found errors and warnings for the test being run.
[2.4] The simple view SHOULD give the user the possibility to see more
information about encountered errors from within the simple view, if he/she so
chooses. [2.5] The GUI MUST be able to give a simple, summarized verdict on the
domain being tested (for example; green/yellow/red).
[2.6] The GUI MUST provide a list with previous runs for the given domain and
these SHOULD be kept separate between normal and "undelegated" testruns.
[2.7] The list from [2.6] MUST contain working links to the previous tests and
these MAY be the same links as created in [4.2].
[2.8] The GUI MUST be able to run on delegated zones with the zone itself
exclusively as input (name servers as input is optional)
[2.9] The GUI MUST be able to run on undelegated zones with the zone and at
least one name server as input. [2.10] The GUI MUST be able to support HTML/TXT
as output and SHOULD be designed with further output formats in mind.
[2.11] The GUI MUST be able to run with different test profiles (meaning: what
tests are being run at all).
[2.12] The GUI MUST be able to show a progress bar with a rough estimate of
total test progress and it SHOULD also tell the user what specific test is
currently running.
[2.13] The GUI MUST be able to stop a test on a fatal error if the user has
given the GUI input to do so.
Security:
[3.1] The GUI MUST have a chroot-similar design where its config, outside of
reach of the web root itself, is read only once at startup.
[3.2] The GUI MUST have all sensitive information in the protected
configuration file from [3.1] but MAY have options elsewhere if deemed
necessary. [3.3] The GUI SHOULD have an easy-to-read source code that is well
documented and commented.
Functionality:
[4.1] The GUI MUST have the same functionality over IPv6 as is given over IPv4.
[4.2] The GUI MUST create unique links for every test generated through its
interface and these links SHOULD be easy to find for the user.
[4.3] The GUI SHOULD allow links to tests that were generated from other
sources than the GUI itself but MAY not allow all available sources to be
accessed.
[4.4] The GUI MUST be designed so that it is easy to add new tests easily.
[4.5] The GUI MUST be able to take DS record(s) as input to test DNSSEC
properly on undelegated domains.
[4.6] The GUI SHOULD report to the user what IP-address he/she is connecting
from.
[4.7] The GUI MUST report what version of the engine was used to generate the
result(s) displayed.

44
zonemaster/docs/internal/requirements/GUI-Functional-Test-Requirements.md Normal file
View File

@@ -0,0 +1,44 @@
GUI - Functional Test requirements
======================================
Objective
----------
The objective of this document is to run functional tests for the Web GUI.
Scope
------
The scope of the testing will limited to the functional testing (End-to-End testing) of the GUI.
Security and Performance testing are not included.
[![Build Status](https://travis-ci.org/zonemaster/zonemaster-gui.svg?branch=master)](https://app.travis-ci.com/github/zonemaster/zonemaster-gui)
|Req| Test requirement |How Verified|
|:--|:-------------------------------------------|------------|
|FR01|A Home button that sends the user to the default simple view |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR01.e2e-spec.ts)|
|FR02|All menus should be clickable in latest version of different browsers such as Firefox, IE, Chrome, Safari etc. |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR02.e2e-spec.ts)|
|FR03|All appropriate fields should be writable |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR03.e2e-spec.ts)|
|FR04|Valid title for the Web interface|[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR04.e2e-spec.ts)|
|FR05|Supports Swedish language|[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR05.e2e-spec.ts)|
|FR06|Supports French language|[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR06.e2e-spec.ts)|
|FR07|Supports English language |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR07.e2e-spec.ts)|
|FR08|Presence of a default fallback language - English |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR08.e2e-spec.ts)
|FR09|Once a language is chosen, all other links should open in that respective language |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR09.e2e-spec.ts)
|FR10|On launching the URL opens with a default simple view | [Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR10.e2e-spec.ts)|
|FR11|The simple view should look the same in latest version of different browsers such as Firefox, Internet Explorer, Chrome, Safari etc. | [Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR05.e2e-spec.ts) |
|FR12|The simple view should support an advanced view expanding when the checkbox is enabled|[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR12.e2e-spec.ts)|
|FR13|The advanced view should support the possibility of enabling or disabling IPv4 or IPv6 |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR13.e2e-spec.ts)|
|FR14|The advanced view should support the possibility of choosing a profile from multiple profiles|[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR14.e2e-spec.ts)|
|FR15|The advanced view should look the same in latest version of different browsers such as Firefox, Internet Explorer, Chrome, Safari etc. |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR15.e2e-spec.ts)|
|FR16|The advanced view should have a text describing what undelegated means? |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR16.e2e-spec.ts)|
|FR17|Able to specify delegation parameters |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR17.e2e-spec.ts)|
|FR18|The GUI should be able to run tests by just providing the domain name |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR18.e2e-spec.ts)|
|FR19|The GUI should be able to run the test with at least one name server as input |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR19.e2e-spec.ts)|
|FR20|The user must be able to submit one or more DS record(s) for use with DNSSEC |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR20.e2e-spec.ts)|
|FR21|Able to provide a summarized result of the test being run (possibility in different colours for error, warning, success etc.) |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR21.e2e-spec.ts)|
|FR22|Provide the possibility to see more information about encountered errors within the simple view |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR22.e2e-spec.ts)|
|FR23|Provide a list of previous runs for the domain and should be paginated |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR23.e2e-spec.ts)|
|FR24|The list of previous runs should contain links to the previous tests |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR24.e2e-spec.ts)|
|FR25|Should be able to export the result in multiple formats (HTML, CSV, JSON, TEXT) |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR26.e2e-spec.ts)|
|FR26|Should be able to show a progress bar with a rough estimate of the total test progress |[Script](https://github.com/zonemaster/zonemaster-gui/blob/master/e2e/FR26.e2e-spec.ts)|

10
zonemaster/docs/internal/requirements/README.md Normal file
View File

@@ -0,0 +1,10 @@
Requirements (internal)
=======================
## Purpose of this directory
This contents of this directory includes different files which were used by the
AFNIC and IIS team internally for the ZM project. Any of the contents of this
directory will not be useful for any type of users of the Zonemaster software,
other than the Afnic and IIS team.

46
zonemaster/docs/internal/templates/specifications/tests/MessageTagSpecification.md Normal file
View File

@@ -0,0 +1,46 @@
# Message Tag Specification
Message tags outputted by the test cases, and defined in the test case
specifications, must conform to the following specifications.
The message tag must match the regex `/^[A-Z][A-Z0-9_][A-Z]$/`. Lower case
letters are not allowed.
The tag can be broken into three parts, in order:
* Test case specific prefix
* Delimiter "_"
* Tag string
## Test case specific prefix
The message tag prefix is an abbreviation of the test case identifier created by
a 1-2 letter abbreviation of the test level name and the two-digit suffix of the
test case ID. For specification of the test case ID see
[Test Case Identifier Specification].
The test level abbreviation is always as follows:
Test level name | Example Test case ID | Abbreviation| Prefix | Example message tag
:----------------|:-----------------------|:------------|:--------|:-------------------
Address | Address01 | A | A01 | A01_NO_RESPONSE
Basic | Basic04 | B | B04 | B04_NO_DATA
Connectivity | Connectivity03 | CN | CN03 | CN03_HAS_DATA
Consistency | Consistency01 | CS | CS01 | CS01_SAME_VALUE
DNSSEC | DNSSEC15 | DS | DS15 | DS15_NO_KEY
Delegation | Delegation05 | DG | DG05 | DG05_NO_GLUE
Nameserver | Nameserver08 | N | N08 | N08_TOO_FEW_NS
Syntax | Syntax06 | S | S06 | S06_WRONG_FORMAT
Zone | Zone07 | Z | Z07 | Z07_SOA_RESTRY
## Delimiter
The delimiter between the prefix and the tag string is "_". See the examples in
the table above.
## Tag string
The tag string should be a short string that gives information about the message.
[Test Case Identifier Specification]: TestCaseIdentifierSpecification.md

330
zonemaster/docs/internal/templates/specifications/tests/Template01.md Normal file
View File

@@ -0,0 +1,330 @@
> > Limit all lines to 80 characters with the possible exception of tables
> > such as the one in the summary section.
# TEMPLATE01: This is a test specification template
> > Replace "TEMPLATE01" with test case ID (in uppercase). Replace the text
> > with a short description
## Test case identifier
**TEMPLATE01**
> > Replace with correct test case ID as specified in the
> > [Test Case Identifier Specification].
## Table of contents
> > If the specification contains extra sections, or if some section is not
> > included, update the list. In the normal case, keep the following sections.
* [Objective](#objective)
* [Scope](#scope)
* [Inputs](#inputs)
* [Summary](#summary)
* [Test procedure](#test-procedure)
* [Outcome(s)](#outcomes)
* [Special procedural requirements](#special-procedural-requirements)
* [Intercase dependencies](#intercase-dependencies)
* [Terminology](#terminology)
## Objective
> > Write a description of what this test case tests, i.e. the details that are
> > considered to be right and wrong. Include references to RFCs and other
> > documents.
> >
> > Do not include full links here (in the source). Put them at the end of the
> > specification document instead, as in this template.
> >
> > Do have deep links, but keep the display text short if possible. E.g.:
...described in [RFC 4035][RFC 4035#section-3.1.3], section 3.1.3, ...
## Scope
> > If this test case assumes, but not depends on, another test case then specify
> > it. Dependency would mean that the test case is affected by the other test
> > case, or even cannot be run if the other has not been run. Assuming that
> > another test case has been run is just to make it possible to ignore certain
> > errors. E.g.:
It is assumed that *Child Zone* is also tested and reported by [Connectivity01].
This test case will just ignore non-responsive name servers or name servers not
giving a correct DNS response for an authoritative name server.
## Inputs
> > Input data to the test case. Always include the Child zone, but it can also
> > be other data units, such as current time, if that is relevant.
> >
> > The input data name is put in quote marks '""', then a hyphen '-' as a
> > separator, and finally a description.
* "Child Zone" - The domain name to be tested.
## Summary
> > First we can have bullets, if applicable, that state notable things about
> > the execution or the messages. E.g.
* If no CDS record is found, the test case will terminate early
with no message tag outputted.
* If a CDS record is of "delete" type, then it can by definition not
match or point at any DNSKEY record.
> > Here is a table of all message tags referred to in the steps. The table has
> > the following columns:
> > 1. The message tag outputted in the test procedure below.
> > 2. The default severity level.
> > 3. The arguments (if any) to be included in the message ID. Argument name
> > must be selected from the defined names (see link below).
> > 4. Message ID to be outputted by the implementation with any arguments
> > included (see example below).
> >
> > Always use the same table set-up, but with the correct tags. Keep the table
> > sorted by message tag. Here is an example:
Message Tag | Level | Arguments | Message ID for message tag
:-----------------------------|:--------|:---------------------|:--------------------------------------------
T01_ALGO_NOT_SUPPORTED_BY_ZM | NOTICE | algo_descr, algo_num | The algorithm used, {algo_descr} ({also_num}) is not supported by the Zonemaster implementation.
T01_BROKEN_DNSSEC | ERROR | ns_ip_list | Replies do not follow the standard. Returned from name servers "{ns_ip_list}".
T01_HAS_NSEC | INFO | | The *Child Zone* uses NSEC.
T01_HAS_NSEC3 | INFO | | The *Child Zone* uses NSEC3.
T01_INCONSISTENT_DNSSEC | ERROR | keytag | The keytag "{keytag}" of the zone is inconsistent with respect to DNSSEC.
The value in the Level column is the default severity level of the message. The
severity level can be changed in the [Zonemaster-Engine profile]. Also see the
[Severity Level Definitions] document.
The argument names in the Arguments column lists the arguments used in the
message. The argument names are defined in the [argument list].
> > The message tags should be formed following the [Message Tag Specification].
> >
> > The default severity level is selected from the [Severity Level Definitions].
## Test procedure
> > This section contains the detailed steps to execute the test case. The steps
> > should be as explicit as possible to avoid that different implementations or
> > executions make different interpretations or assumptions.
> >
> > If the test procedure uses DNS queries (most test cases do), then add the
> > following paragraph (types of DNS queries that do no apply for the test case
> > can be removed):
In this section and unless otherwise specified below, the terms "[DNS Query]",
"[EDNS Query]" and "[DNSSEC Query]" follow the specification for DNS queries
as specified in [DNS Query and Response Defaults]. The handling of the DNS
responses on the DNS queries follow, unless otherwise specified below, what is
specified for [DNS Response], [EDNS Response], and [DNSSEC Response],
respectively, in the same specification.
> > How the term "[DNSSEC Query]" is used can be seen in the next example below.
> >
> > The steps should be written in such a way that it is reasonably possible to
> > use them to execute the test case manually using tools such as [`dig`][dig].
> > It can be assumed that the reader of the text has good understanding of DNS.
> >
> > The steps should state what messages (message tags) to be outputted when.
> > Only messages with default severity level DEBUG or higher can be included.
> >
> > All messages with level INFO or higher must be included. I.e. the
> > implementation should not include messages with default level INFO or higher
> > unless included in the specification.
> >
> > Messages DEBUG or lower can be added in the implementation as needed without
> > being included in the specification.
> >
> > Also include statement on what other information to be accompanied
> > with the message (included as parameter to the message tag). Example of such
> > information is IP addresses to name servers.
> >
> > When referring to the data defined in **Inputs** then use the name in
> > *italic*, e.g.:
2. Create a [DNSSEC Query] with query type DNSKEY and query name *Child Zone*
("DNSKEY Query").
> > If data sets are created, then defined them in quote marks. E.g.:
4. Create three empty sets, "NSEC-Zone", "NSEC3-Zone", and
"No-DNSSEC-Zone".
> > When used (referred to) in the steps, make the name italic. E.g.:
6. Add the name server IP to the *NSEC-Zone* set (*NSEC3-Zone*
set).
> > When a message is outputted in the steps, it is done by outputting
> > the message tag, "T01_HAS_NSEC3" in the example below. Make the tag as a link
> > name in italic. What the link name points at is to be defined at the bottom
> > of the document. E.g.:
8. If the NSEC (NSEC3) records do not "cover" the
*Nonexistent Query Name*, then output *[T01_HAS_NSEC3]*
> > When referring to RCODE, such as "NoError", use the term [RCODE Name]
> > with a link to the IANA page. Also use the name forms on that page.
## Outcome(s)
> > First we have standard text that should normally be the same in all
> > test case specifications.
The outcome of this Test Case is "fail" if there is at least one message
with the severity level *[ERROR]* or *[CRITICAL]*.
The outcome of this Test Case is "warning" if there is at least one message
with the severity level *[WARNING]*, but no message with severity level
*ERROR* or *CRITICAL*.
In other cases, no message or only messages with severity level
*[INFO]* or *[NOTICE]*, the outcome of this Test Case is "pass".
> > Then there could be statements about data being outputted from the test case
> > for use as input data for other test cases.
## Special procedural requirements
> > First we have standard text that should normally be the same in all
> > test case specifications.
If either IPv4 or IPv6 transport is disabled, skip sending queries over that
transport protocol. A message will be outputted reporting that the transport
protocol has been skipped.
> > Then there could be some other limitations or specialties of how or when
> > this test case is run. E.g.:
The test case is only performed if some DNSKEY record is found in the
*Child Zone*.
> > This is a standard limitation for all test cases:
The *Child Zone* must be a valid name meeting
"[Requirements and normalization of domain names in input]".
## Intercase dependencies
> > Either the following text if there is no formal dependencies on other test
> > cases...
None.
> > ...or specification on the outcome that this test case depend on, e.g.:
Example of formal dependency to be added.
> > Also see the text under **Objective** about test cases that are assumed to be
> > run, but that this test case does not depend on. I.e. not dependencies in a
> > formal sense.
## Terminology
> > If there is no terminology to be explained, then this section should contain
> > the following text:
No special terminology for this test case.
> > Following are examples of terminology that are candidates to be included
> > in the section.
* "DNS Lookup" - The term is used when a recursive lookup is used, though
any changes to the DNS tree introduced by an [undelegated test] must be
respected.
* "in-bailiwick" - The term is used as defined in [RFC 8499][RFC 8499#page-25],
section 7, page 25. In this document, the term "in-bailiwick" is limited to the
meaning "in-domain" in [RFC 8499][RFC 8499#page-25].
* "glue records" - The term is defined in [RFC 8499][RFC 8499#page-24], section 7,
page 24.
* "out-of-bailiwick" - The term is used in this document to mean what is not
"in-bailiwick" (see definition above).
* "send" (to an IP address) - The term is used when a DNS query is sent to
a specific name server.
* "using Method" - The term is used when data is fetched using the defined
[Method][Methods].
> > ----
> > The links listed below are not visible when rendered by GitHub. In the
> > specification the different parts below should be combined into one link
> > collection and sorted. Always start the link label (the left side) with an
> > upper case letter (if it starts with a letter). The reference can from the
> > text is case independent.
> >
> > All link names are listed below to the left with the link target to the
> > right. They are only visible when viewing the source of this document.
> >
> > All message tags are linked to section **Summary**
[T01_ALGO_NOT_SUPPORTED_BY_ZM]: #summary
[T01_HAS_NSEC]: #summary
[T01_HAS_NSEC3]: #summary
[T01_INCONSISTENT_DNSSEC]: #summary
> > All links in the template are absolute except for links within this template
> > or to other documents in the template tree. All absolute links to documents
> > in the zonemaster/zonemaster directory are to the develop branch. In the
> > test case specification all links should be relative if the link target is
> > in the zonemaster/zonemaster repository.
> >
> > A few relative links in this template:
[Message Tag Specification]: MessageTagSpecification.md
[Test Case Identifier Specification]: TestCaseIdentifierSpecification.md
> > Absolute links to be converted to relative links in the test case
> > specification. Here grouped to be easier to copy, but sort them
> > them always in the specification.
> > Links to pages on Zonemaster/Zonemaster:
[Severity Level Definitions]: ../../../../public/specifications/tests/SeverityLevelDefinitions.md
[DEBUG]: ../../../../public/specifications/tests/SeverityLevelDefinitions.md#notice
[INFO]: ../../../../public/specifications/tests/SeverityLevelDefinitions.md#info
[NOTICE]: ../../../../public/specifications/tests/SeverityLevelDefinitions.md#notice
[WARNING]: ../../../../public/specifications/tests/SeverityLevelDefinitions.md#warning
[ERROR]: ../../../../public/specifications/tests/SeverityLevelDefinitions.md#error
[CRITICAL]: ../../../../public/specifications/tests/SeverityLevelDefinitions.md#critical
[Connectivity01]: ../../../../public/specifications/tests/Connectivity-TP/connectivity01.md
[Argument list]: ../../../../public/specifications/tests/ArgumentsForTestCaseMessages.md
[DNS Query and Response Defaults]: ../../../../public/specifications/tests/DNSQueryAndResponseDefaults.md
[DNS Query]: ../../../../public/specifications/tests/DNSQueryAndResponseDefaults.md#default-setting-in-dns-query
[DNS Response]: ../../../../public/specifications/tests/DNSQueryAndResponseDefaults.md#default-handling-of-a-dns-response
[DNSSEC Query]: ../../../../public/specifications/tests/DNSQueryAndResponseDefaults.md#default-setting-in-dnssec-query
[DNSSEC Response]: ../../../../public/specifications/tests/DNSQueryAndResponseDefaults.md#default-handling-of-a-dnssec-response
[EDNS Query]: ../../../../public/specifications/tests/DNSQueryAndResponseDefaults.md#default-setting-in-edns-query
[EDNS Response]: ../../../../public/specifications/tests/DNSQueryAndResponseDefaults.md#default-handling-of-an-edns-response
[Methods]: ../../../../public/specifications/tests/Methods.md
[MethodsV2]: ../../../../public/specifications/tests/MethodsV2.md
[Undelegated test]: ../../../../public/specifications/test-types/undelegated-test.md
[Requirements and normalization of domain names in input]: ../../../../public/specifications/tests/RequirementsAndNormalizationOfDomainNames.md
[Zonemaster-Engine profile]: ../../../../public/configuration/profiles.md
> > External links:
[Dig]: https://en.wikipedia.org/wiki/Dig_(command)
[RCODE Name]: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
[RFC 4035#section-3.1.3]: https://datatracker.ietf.org/doc/html/rfc4035#section-3.1.3
[RFC 8499#page-25]: https://datatracker.ietf.org/doc/html/rfc8499#page-25
[RFC 8499#page-24]: https://datatracker.ietf.org/doc/html/rfc8499#page-24
> > Keep all links sorted, and make a straight column of the link targets in
> > the test case specification.

36
zonemaster/docs/internal/templates/specifications/tests/TestCaseIdentifierSpecification.md Normal file
View File

@@ -0,0 +1,36 @@
# Test Case Identifier Specification
All test cases belong to one specific test level and their names are based on
that test level’s name. The following test levels are defined and available:
* Address
* Basic
* Connectivity
* Consistency
* DNSSEC
* Delegation
* Nameserver
* Syntax
* Zone
The test level name is not case-sensitive, but the forms defined above
must be used when referring to the test levels, i.e. only the first letter
uppercase, expect for acronyms for which all uppercase is used.
For example "Address" and neither "ADDRESS" nor "address".
The test case identifier in the test case specification (both in the main
headline and in the "Test case identifier" section) uses the test level name,
as defined above, and has the format: `{Test level name} + {Index}`
When referencing to a test case, for readability, the letter case defined
above must be used for the test level name.
The `{Index}` is a two-digit suffix 01-99, and should be selected so that the
test case identifier is unique. Normally the first free index is selected.
Example of test case identifiers:
* Address03
* Basic04
* DNSSEC15
* Zone06

9
zonemaster/docs/internal/test-requirements/README.md Normal file
View File

@@ -0,0 +1,9 @@
![Zonemaster](/docs/images/zonemaster_logo_2021_color.png)
==========
### Purpose of this directory
[TestRequirements.md](TestRequirements.md) provides a list of the tests performed when the
Zonemaster engine validates a domain.

34
zonemaster/docs/internal/test-requirements/TestRequirements-table-specification.txt Normal file
View File

@@ -0,0 +1,34 @@
This document specifies the format of the table in document
[TestRequirements.md] in the same directory. It is only relevant
for anyone updating the table.
The table in [TestRequirements.md] is also a database that
should be parsable by script, and must therefore be kept in the
specified format.
The table, in the source code, must remain in Markdown format.
In the raw Markdown code, the table must be preceded by an HTML
comment line (with nothing in between) containing "START-TABLE".
And directly after the table there must be an HTML comment
containing "END-TABLE".
The table must have four fields. There must be no "|" at the start
or end of the lines in the table.
Field one is the requirement ID which must have the form
"Rxxxxx" where x is a digit 0-9. The ID should sorted and must be
unique.
Field two must be the requirement specification.
Field three must be the requirement reference one or more
Markdown links, i.e. something like "[xxxx]". The field may
be empty.
Field four must be one or more Markdown links to test cases.
The field may be empty.
The first line must be the table header and the second line
the delimiter between header and table body. Both lines will be
ignored by the parser.

235
zonemaster/docs/internal/test-requirements/TestRequirements.md Normal file
View File

@@ -0,0 +1,235 @@
# Test requirements
## Overview
Zonemaster is implemented as a number of test cases. Behind the test cases are
requirements on a DNS zone and its name servers. The requirements are derived
from the DNS protocol specifications and best practices. Each test case is
meant to verify one or a few of the requirements.
## Requirements
In the table below, all requirements behind the Zonemaster test cases are
listed. For each requirement there is a link to a reference and a link to
the specification of the Zonemaster test case that verifies that
requirement. In the defined specifications more details are found.
Note that there is one defined specification that is generic enough not to be
considered a test case: [Normalization].
This is not a static document. As DNS evolves and new issues are pointed
at requirements will be added, removed or modified just as the test cases.
<!-- When updating the table, read TestRequirements-table-specification.txt -->
<!-- START-TABLE -->
Req ID| Requirement specification | Reference | Defined specification
:---- |:-----------------------------------------------------------------------------------|:--------------------|:---------------------
R00100| A name server IP address should be globally routable on Internet. | |[ADDRESS01]
R00200| A name server IP address should be registered in the DNS reverse lookup tree. | |[ADDRESS02]
R00300| A name server IP address reverse lookup entry should be valid. |[RFC1912] |[ADDRESS03]
R00400| The zone name should consists of valid IDN or non-IDN ASCII labels (names). | |[Normalization]
R00500| IDN labels (names) should be valid. |[RFC5890] |[Normalization]
R00600| Non-IDN ASCII labels (names) should be valid. |[RFC1123] [RFC2782] |[Normalization]
R00700| A DNS zone should have a parent zone from which it is delegated. | |[Normalization]
R00800| A DNS zone should have at least one accessible name server that hosts it. | |[Normalization]
R00900| A name server for a zone should respond on a query. | |[CONNECTIVITY01] [CONNECTIVITY02]
R01000| A name server for a zone should respond with SOA record on SOA query. |[RFC2181] |[CONNECTIVITY01] [CONNECTIVITY02] [DELEGATION06]
R01100| A name server for a zone should respond with RCODE NoError on SOA query. | |[CONNECTIVITY01] [CONNECTIVITY02]
R01200| A name server for a zone should respond with AA flag set on SOA query. |[RFC2181] |[CONNECTIVITY01] [CONNECTIVITY02]
R01300| A name server for a zone should respond with NS RRset on NS query. |[RFC2181] |[CONNECTIVITY01] [CONNECTIVITY02]
R01400| A name server for a zone should respond with RCODE NoError on NS query. | |[CONNECTIVITY01] [CONNECTIVITY02]
R01500| A name server for a zone should respond with AA flag set on NS query. |[RFC2181] |[CONNECTIVITY01] [CONNECTIVITY02]
R01600| A name server should respond on port 53 over UDP. |[RFC1035] |[CONNECTIVITY01]
R01700| A name server should respond on port 53 over TCP. |[RFC7766] |[CONNECTIVITY02]
R01800| The name server IP addresses should be announce from different ASNs. |[RFC2182] |[CONNECTIVITY03]
R01900| The name server IP addresses should not be on the same subnet. | |[CONNECTIVITY04]
R02000| All name servers for a zone should respond with the same SOA serial number. |[RFC1034] |[CONSISTENCY01]
R02100| All name servers for a zone should respond with the same SOA RNAME value. |[RFC1034] |[CONSISTENCY02]
R02200| All name servers for a zone should respond with the same SOA REFRESH value. |[RFC1034] |[CONSISTENCY03]
R02300| All name servers for a zone should respond with the same SOA RETRY value. |[RFC1034] |[CONSISTENCY03]
R02400| All name servers for a zone should respond with the same SOA EXPIRE value. |[RFC1034] |[CONSISTENCY03]
R02500| All name servers for a zone should respond with the same SOA MINIMUM value. |[RFC1034] |[CONSISTENCY03]
R02600| All name servers for a zone should respond with the same NS RRset. |[RFC1034] |[CONSISTENCY04]
R02700| The NS RRset in the delegation should be identical to the NS RRset in the zone. |[RFC1034] [IANA] |[CONSISTENCY05] [DELEGATION07]
R02800| All name servers for a zone should respond with the same SOA MNAME value. |[RFC1034] |[CONSISTENCY06]
R02900| The SOA MNAME value should point at the primary master server of the zone. |[RFC1035] |[CONSISTENCY06]
R03000| A zone should be hosted by at least two names servers (on IPv4). |[RFC1034] |[DELEGATION01]
R03100| A zone should be hosted by at least two names servers (on IPv6). | |[DELEGATION01]
R03200| A zone should be hosted on IPv4. |[RFC3901] [RFC4472] |[DELEGATION01]
R03300| Name servers for a zone should have distinct IP addresses. | |[DELEGATION02]
R03400| Referral from parent name servers should fit into 512 octets. |[IANA] |[DELEGATION03]
R03500| The name server for the zone should respond authoritatively for the zone. |[RFC2181] |[DELEGATION04]
R03600| The name server name should not point at a CNAME. |[RFC2181] |[DELEGATION05]
R03700| Signed zone must have DNSKEY. | |
R03800| Only valid DS hash algorithm should be used. |[RFC8624] |[DNSSEC01]
R03900| If child zone is signed then parent zone should have DS record(s). |[RFC4035] |[DNSSEC07]
R04000| DS at parent must match a DNSKEY at child. |[RFC4035] [RFC6840] |[DNSSEC02]
R04100| Parent name server should respond with NoError on DS query. | |[DNSSEC02]
R04200| Parent name server should respond with AA on DS query. | |[DNSSEC02]
R04300| DNSKEY RRset should be signed by DNSKEY from RRset. | |[DNSSEC02]
R04400| DNSKEY(DS) should have SEP flag set. | |[DNSSEC02]
R04500| RRSIG(DNSKEY RRset) should match appointed DNSKEY from DNSKEY RRset. | |[DNSSEC02] [DNSSEC08]
R04600| The number of NSEC3 iterations should be limited. |[RFC5155] |[DNSSEC03]
R04700| RRSIG lifetime should not be too short. |[RFC6781] |[DNSSEC04]
R04800| RRSIG lifetime should not be too long. |[RFC6781] |[DNSSEC04]
R04900| Only valid DNSKEY algorithms should be used. |[RFC8624] |[DNSSEC05]
R05000| Query with DO set should include RRSIG in response for signed zone. |[RFC4035] |[DNSSEC06]
R05100| If the zone is signed, then there should be a DS record in the delegation. |[RFC4035] |[DNSSEC07]
R05200| Name servers should respond with NoError on DNSKEY query. | |[DNSSEC08]
R05300| Name servers should respond with AA on DNSKEY query. | |[DNSSEC08]
R05400| Name servers should respond with *one* DNSKEY RRset. | |[DNSSEC08]
R05500| RRSIG(SOA) should match appointed DNSKEY from DNSKEY RRset. |[RFC4035] |[DNSSEC09]
R05600| NXDOMAIN response should include NSEC/NSEC3 for signed zone. |[RFC4035] [RFC5155] |[DNSSEC10]
R05700| NSEC and NSEC3 should not be mixed in responses. | |[DNSSEC10]
R05800| NSEC/NSEC3 record should be signed by RRSIG. | |[DNSSEC10]
R05900| If parent zone has DS record(s) then child zone must be signed. | |[DNSSEC11]
R06000| It should be possible to verify SOA using DS from parent as trust anchor. | |[DNSSEC12]
R06100| It should be possible to verify NS using DS from parent as trust anchor. | |[DNSSEC12]
R06200| It should be possible to verify DNSKEY using DS as trust anchor. | |[DNSSEC12]
R06300| Every algorithm represented in DNSKEY RRset must be used to sign the entire zone. |[RFC6840] | -
R06400| Every algorithm represented in DNSKEY RRset must be used to sign the SOA RRset. |[RFC6840] |[DNSSEC13]
R06500| Every algorithm represented in DNSKEY RRset must be used to sign the NS RRset. |[RFC6840] |[DNSSEC13]
R06600| Every algorithm represented in DNSKEY RRset must be used to sign the DNSKEY RRset. |[RFC6840] |[DNSSEC13]
R06700| DNSKEY of type RSASHA1 (5) should have a key size of 512 to 4096 bits. |[RFC3110] |[DNSSEC14]
R06800| DNSKEY of type RSASHA1-NSEC3-SHA1 (7) should have a key size of 512 to 4096 bits. |[RFC5155] |[DNSSEC14]
R06900| DNSKEY of type RSASHA256 (8) should have a key size of 512 to 4096 bits. |[RFC5702] |[DNSSEC14]
R07000| DNSKEY of type RSASHA512 (10) should have a key size of 1024 to 4096 bits. |[RFC5702] |[DNSSEC14]
R07100| A name server hosting a zone should not also be a recursive name server. |[RFC5358] [RFC2870] |[NAMESERVER01]
R07200| A name server should support EDNS. | |[NAMESERVER02]
R07300| A name server not supporting EDNS should respond with FORMERR. |[RFC6891] |[NAMESERVER02]
R07400| A name server should not support open zone transfer for its zone or zones. | |[NAMESERVER03]
R07500| A name server should respond with the same source IP as the query was sent to. |[RFC2181] |[NAMESERVER04]
R07600| A name server should handle queries for AAAA correctly. |[RFC4074] |[NAMESERVER05]
R07700| The name of the name server, as given in the NS record, must be resolvable in DNS. |[RFC1035] |[NAMESERVER06]
R07800| A name server should not return a referral to root on queries for zones not hosted. | |[NAMESERVER07]
R07900| A name server should preserve case of query name when creating response. |Ref? |[NAMESERVER08]
R08000| A name server should treat query name without considering character case. |Ref? |[NAMESERVER09]
R08100| A name server should respond with BADVERS on unsupported EDNS version. |[RFC6891] |[NAMESERVER10]
R08200| A name server should completely ignore unsupported EDNS OPTION-CODE. |[RFC6891] |[NAMESERVER11]
R08300| A name server should completely ignore unsupported EDNS flag bit (Z flag bits). |[RFC6891] |[NAMESERVER12]
R08400| A name server with EDNS support should include OPT record in truncated response. |[RFC6891] |[NAMESERVER13]
R08600| The zone (domain) name should only contain legal characters. |[RFC1035] [RFC1123] [RFC2182] [RFC3696] |[SYNTAX01]
R08700| No label of the zone name should start or end with hyphen ("-"). |[RFC1035] [RFC1123] [RFC2182] [RFC3696] |[SYNTAX02]
R08800| No label of the zone name should have "--" in positions 3 and 4 unless it starts with "xn--". |[RFC3696]|[SYNTAX03]
R08900| If the zone name has a label that starts with "xn--" it should be a valid A-label. | |
R09000| If the zone name has an IDN label, its U-label should be valid. | |
R09100| If the zone name has an IDN label, its U-label should not start or end with hyphen ("-"). | |
R09200| If the zone name has an IDN label, its U-label should not have "--" om positions 3 and 4. | |
R09300| If the zone name has an IDN label, its U-label should not have UNASSIGNED or DISALLOWED characters. | |
R09400| If the zone name has an IDN label, any CONTEXTO or CONTEXTJ character in its U-label must follow the rules. | |
R09500| The names of the server names of the zone must be valid hostnames. |[RFC0952] [RFC1123] [RFC2182] [RFC3696] |[SYNTAX04]
R09600| In the SOA RNAME field there should be no "@" character. |[RFC1035] |[SYNTAX05]
R09700| The SOA RNAME field should, after conversion, be a valid email address. |[RFC1035] [RFC1912] [RIPE-203] |[SYNTAX06]
R09800| The SOA MNAME should be a valid hostname. |[RFC0952] [RFC1123] [RFC2182] [RFC3696] |[SYNTAX07]
R09900| The MX record or records of apex, if any, should have valid domain names for the mail target.|[RFC0952] [RFC1123] [RFC2182] [RFC3696] |[SYNTAX08]
R10000| The SOA MNAME field should be a fully qualified master name server of the zone. |[RFC1035] [RIPE-203]|[ZONE01]
R11000| The SOA REFRESH value should be at least 4 hours. |[RFC1912] [RIPE-203]|[ZONE02]
R12000| The SOA RETRY value should be lower than the REFRESH value. |[RFC1912] [RIPE-203]|[ZONE03]
R13000| The SOA RETRY value should be at least 1 hour. |[RFC1912] [RIPE-203]|[ZONE04]
R14000| The SOA EXPIRE value should be at least 2 weeks (1,209,600 sec). |[RFC1912] [RIPE-203]|[ZONE05]
R15000| The SOA MINUMUM value should be at least 300 sec and not more than 86400 sec. |[RFC1912] [RIPE-203]|[ZONE06]
R16000| The SOA MNAME field should not point at a CNAME. | |[ZONE07]
R17000| The mail exchange field in MX records should not point at a CNAME. |[RFC2181] [RFC5321] |[ZONE08]
R18000| Apex of every zone should be a valid mail domain. |[RFC2142] |[ZONE09]
R19000| The should be exactly one SOA record in every zone. |[RFC1035] |[ZONE10]
<!-- END-TABLE -->
<!-- When updating the table, read TestRequirements-table-specification.txt -->
[ADDRESS01]: ../../public/specifications/tests/Address-TP/address01.md
[ADDRESS02]: ../../public/specifications/tests/Address-TP/address02.md
[ADDRESS03]: ../../public/specifications/tests/Address-TP/address03.md
[BASIC01]: ../../public/specifications/tests/Basic-TP/basic01.md
[BASIC02]: ../../public/specifications/tests/Basic-TP/basic02.md
[CONNECTIVITY01]: ../../public/specifications/tests/Connectivity-TP/connectivity01.md
[CONNECTIVITY02]: ../../public/specifications/tests/Connectivity-TP/connectivity02.md
[CONNECTIVITY03]: ../../public/specifications/tests/Connectivity-TP/connectivity03.md
[CONNECTIVITY04]: ../../public/specifications/tests/Connectivity-TP/connectivity04.md
[CONSISTENCY01]: ../../public/specifications/tests/Consistency-TP/consistency01.md
[CONSISTENCY02]: ../../public/specifications/tests/Consistency-TP/consistency02.md
[CONSISTENCY03]: ../../public/specifications/tests/Consistency-TP/consistency03.md
[CONSISTENCY04]: ../../public/specifications/tests/Consistency-TP/consistency04.md
[CONSISTENCY05]: ../../public/specifications/tests/Consistency-TP/consistency05.md
[CONSISTENCY06]: ../../public/specifications/tests/Consistency-TP/consistency06.md
[DELEGATION01]: ../../public/specifications/tests/Delegation-TP/delegation01.md
[DELEGATION02]: ../../public/specifications/tests/Delegation-TP/delegation02.md
[DELEGATION03]: ../../public/specifications/tests/Delegation-TP/delegation03.md
[DELEGATION04]: ../../public/specifications/tests/Delegation-TP/delegation04.md
[DELEGATION05]: ../../public/specifications/tests/Delegation-TP/delegation05.md
[DELEGATION06]: ../../public/specifications/tests/Delegation-TP/delegation06.md
[DELEGATION07]: ../../public/specifications/tests/Delegation-TP/delegation07.md
[DNSSEC01]: ../../public/specifications/tests/DNSSEC-TP/dnssec01.md
[DNSSEC02]: ../../public/specifications/tests/DNSSEC-TP/dnssec02.md
[DNSSEC03]: ../../public/specifications/tests/DNSSEC-TP/dnssec03.md
[DNSSEC04]: ../../public/specifications/tests/DNSSEC-TP/dnssec04.md
[DNSSEC05]: ../../public/specifications/tests/DNSSEC-TP/dnssec05.md
[DNSSEC06]: ../../public/specifications/tests/DNSSEC-TP/dnssec06.md
[DNSSEC07]: ../../public/specifications/tests/DNSSEC-TP/dnssec07.md
[DNSSEC08]: ../../public/specifications/tests/DNSSEC-TP/dnssec08.md
[DNSSEC09]: ../../public/specifications/tests/DNSSEC-TP/dnssec09.md
[DNSSEC10]: ../../public/specifications/tests/DNSSEC-TP/dnssec10.md
[DNSSEC11]: ../../public/specifications/tests/DNSSEC-TP/dnssec11.md
[DNSSEC12]: ../../public/specifications/tests/DNSSEC-TP/dnssec12.md
[DNSSEC13]: ../../public/specifications/tests/DNSSEC-TP/dnssec13.md
[DNSSEC14]: ../../public/specifications/tests/DNSSEC-TP/dnssec14.md
[IANA]: https://www.iana.org/help/nameserver-requirements
[NAMESERVER01]: ../../public/specifications/tests/Nameserver-TP/nameserver01.md
[NAMESERVER02]: ../../public/specifications/tests/Nameserver-TP/nameserver02.md
[NAMESERVER03]: ../../public/specifications/tests/Nameserver-TP/nameserver03.md
[NAMESERVER04]: ../../public/specifications/tests/Nameserver-TP/nameserver04.md
[NAMESERVER05]: ../../public/specifications/tests/Nameserver-TP/nameserver05.md
[NAMESERVER06]: ../../public/specifications/tests/Nameserver-TP/nameserver06.md
[NAMESERVER07]: ../../public/specifications/tests/Nameserver-TP/nameserver07.md
[NAMESERVER08]: ../../public/specifications/tests/Nameserver-TP/nameserver08.md
[NAMESERVER09]: ../../public/specifications/tests/Nameserver-TP/nameserver09.md
[NAMESERVER10]: ../../public/specifications/tests/Nameserver-TP/nameserver10.md
[NAMESERVER11]: ../../public/specifications/tests/Nameserver-TP/nameserver11.md
[NAMESERVER12]: ../../public/specifications/tests/Nameserver-TP/nameserver12.md
[NAMESERVER13]: ../../public/specifications/tests/Nameserver-TP/nameserver13.md
[NAMESERVER14]: ../../public/specifications/tests/Nameserver-TP/nameserver14.md
[Normalization]: ../../public/specifications/tests/RequirementsAndNormalizationOfDomainNames.md
[RFC0952]: https://datatracker.ietf.org/doc/html/rfc952
[RFC1034]: https://datatracker.ietf.org/doc/html/rfc1034
[RFC1035]: https://datatracker.ietf.org/doc/html/rfc1035
[RFC1123]: https://datatracker.ietf.org/doc/html/rfc1123
[RFC1912]: https://datatracker.ietf.org/doc/html/rfc1912
[RFC2142]: https://datatracker.ietf.org/doc/html/rfc2142
[RFC2181]: https://datatracker.ietf.org/doc/html/rfc2181
[RFC2182]: https://datatracker.ietf.org/doc/html/rfc2182
[RFC2782]: https://datatracker.ietf.org/doc/html/rfc2782
[RFC2870]: https://datatracker.ietf.org/doc/html/rfc2870
[RFC3110]: https://datatracker.ietf.org/doc/html/rfc3110
[RFC3696]: https://datatracker.ietf.org/doc/html/rfc3696
[RFC3901]: https://datatracker.ietf.org/doc/html/rfc3901
[RFC4035]: https://datatracker.ietf.org/doc/html/rfc4035
[RFC4074]: https://datatracker.ietf.org/doc/html/rfc4074
[RFC4472]: https://datatracker.ietf.org/doc/html/rfc4472
[RFC5155]: https://datatracker.ietf.org/doc/html/rfc5155
[RFC5321]: https://datatracker.ietf.org/doc/html/rfc5321
[RFC5358]: https://datatracker.ietf.org/doc/html/rfc5358
[RFC5702]: https://datatracker.ietf.org/doc/html/rfc5702
[RFC5890]: https://datatracker.ietf.org/doc/html/rfc5890
[RFC6781]: https://datatracker.ietf.org/doc/html/rfc6781
[RFC6840]: https://datatracker.ietf.org/doc/html/rfc6840
[RFC6891]: https://datatracker.ietf.org/doc/html/rfc6891
[RFC7766]: https://datatracker.ietf.org/doc/html/rfc7766
[RFC8624]: https://datatracker.ietf.org/doc/html/rfc8624
[RIPE-203]: https://www.ripe.net/publications/docs/ripe-203
[SYNTAX01]: ../../public/specifications/tests/Syntax-TP/syntax01.md
[SYNTAX02]: ../../public/specifications/tests/Syntax-TP/syntax02.md
[SYNTAX03]: ../../public/specifications/tests/Syntax-TP/syntax03.md
[SYNTAX04]: ../../public/specifications/tests/Syntax-TP/syntax04.md
[SYNTAX05]: ../../public/specifications/tests/Syntax-TP/syntax05.md
[SYNTAX06]: ../../public/specifications/tests/Syntax-TP/syntax06.md
[SYNTAX07]: ../../public/specifications/tests/Syntax-TP/syntax07.md
[SYNTAX08]: ../../public/specifications/tests/Syntax-TP/syntax08.md
[ZONE01]: ../../public/specifications/tests/Zone-TP/zone01.md
[ZONE02]: ../../public/specifications/tests/Zone-TP/zone02.md
[ZONE03]: ../../public/specifications/tests/Zone-TP/zone03.md
[ZONE04]: ../../public/specifications/tests/Zone-TP/zone04.md
[ZONE05]: ../../public/specifications/tests/Zone-TP/zone05.md
[ZONE06]: ../../public/specifications/tests/Zone-TP/zone06.md
[ZONE07]: ../../public/specifications/tests/Zone-TP/zone07.md
[ZONE08]: ../../public/specifications/tests/Zone-TP/zone08.md
[ZONE09]: ../../public/specifications/tests/Zone-TP/zone09.md
[ZONE10]: ../../public/specifications/tests/Zone-TP/zone10.md

1
zonemaster/docs/public/LICENSE.md Symbolic link
View File

@@ -0,0 +1 @@
../../LICENSE

59
zonemaster/docs/public/README.md Normal file
View File

@@ -0,0 +1,59 @@
# Public documentation
*Click on [SUMMARY](SUMMARY.md) to view a linked tree structure of the public
documentation.*
<!-- A copy of the text below is found in ../README-for-doc.zonemaster.net.md
and if any update is done here, make sure to update there too. -->
The public documentation is divided into the following main categories:
* [Release information](RELEASE.md) gives release information of latest release.
* [Installation](installation/README.md) contains documents that explain how to
install the different components of Zonemaster.
* [Upgrading](upgrading/README.md) contains documents that explain how to upgrade
a Zonemaster installation.
* [Configuration](configuration/README.md) contains documents that explain how a
Zonemaster installation can be configured.
* [Using](using/README.md) contains user guides to the different components of
Zonemaster.
* [Specifications](specifications/README.md) contains specifications of the
Zonemaster test cases, test types and test zones.
* [Development](development/README.md) contains information for developers both
in and outside the Zonemaster project.
* [License](LICENSE.md) gives the license information for Zonemaster.
## Rendering
Renderings of the public documentation are published to [doc.zonemaster.net] for
every release version since v2023.1. It can be built locally using [mdbook], its
[mdbook-linkcheck] plugin.
1. Get a copy of the source tree by cloning the [repository] or downloading an
archive of one of the [releases].
2. Change to the `docs/public` directory and build the book.
```
cd docs/public
mdbook build
```
3. To view the content there are a few options:
* Open the index file if your OS has support for it:
```
open book/index.html
```
* Let mdbook serve it on local computer. Run the following command and open
[localhost:3000] in your browser.
```
mdbook serve
```
* Copy the `book` directory with all files to your computer, go directly to
that directory and open `book/index.html`.
[doc.zonemaster.net]: https://doc.zonemaster.net
[localhost:3000]: http://localhost:3000
[releases]: https://github.com/zonemaster/zonemaster/releases
[repository]: https://github.com/zonemaster/zonemaster
[mdbook]: https://rust-lang.github.io/mdBook/
[mdbook-linkcheck]: https://github.com/Michael-F-Bryan/mdbook-linkcheck

60
zonemaster/docs/public/RELEASE.md Normal file
View File

@@ -0,0 +1,60 @@
# Release v2025.2.1 (2026-03-04)
### \[Release information\]
- Fixes in [Zonemaster-LDNS], [Zonemaster-Engine] and [Zonemaster-GUI].
### \[Breaking changes\]
- None for this release
### \[Deprecations\]
- None for this release
### \[Fixes\]
- Adds documentation on running Zonemaster-Backend through Docker, and update documentation on Zonemaster-GUI translation ([#1464])
### \[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.
Component | Github release notes | Changes file | Updated in this release
---------------------|:----------------------:|----------------------------|:----------------------:
[Zonemaster-LDNS] | [v5.0.2][ldns-tag] | [Changes][ldns-Changes] | Yes
[Zonemaster-Engine] | [v8.1.1][engine-tag] | [Changes][engine-Changes] | Yes
[Zonemaster-CLI] | [v8.0.1][cli-tag] | [Changes][cli-Changes] | No
[Zonemaster-Backend] | [v12.0.0][backend-tag] | [Changes][backend-Changes] | No
[Zonemaster-GUI] | [v5.0.1][gui-tag] | [Changes][gui-Changes] | Yes
For more information on previous versions of the Zonemaster product see the [Changes][zonemaster-Changes] file or the [releases] page on Github. For general information see the [README] file.
The public documentation is also found in a nicer format on the [documentation site]. Zonemaster can be used and tested on the [reference installation].
[README]: https://github.com/zonemaster/zonemaster/blob/master/README.md
[releases]: https://github.com/zonemaster/zonemaster/releases
[documentation site]: https://doc.zonemaster.net/
[reference installation]: https://zonemaster.net/
[ldns-tag]: https://github.com/zonemaster/zonemaster-ldns/releases/tag/v5.0.2
[engine-tag]: https://github.com/zonemaster/zonemaster-engine/releases/tag/v8.1.1
[cli-tag]: https://github.com/zonemaster/zonemaster-cli/releases/tag/v8.0.1
[backend-tag]: https://github.com/zonemaster/zonemaster-backend/releases/tag/v12.0.0
[gui-tag]: https://github.com/zonemaster/zonemaster-gui/releases/tag/v5.0.1
[zonemaster-Changes]: https://github.com/zonemaster/zonemaster/blob/master/Changes
[ldns-Changes]: https://github.com/zonemaster/zonemaster-ldns/blob/master/Changes
[engine-Changes]: https://github.com/zonemaster/zonemaster-engine/blob/master/Changes
[cli-Changes]: https://github.com/zonemaster/zonemaster-cli/blob/master/Changes
[backend-Changes]: https://github.com/zonemaster/zonemaster-backend/blob/master/Changes
[gui-Changes]: https://github.com/zonemaster/zonemaster-gui/blob/master/Changes
[Zonemaster-LDNS]: https://github.com/zonemaster/zonemaster-ldns
[Zonemaster-Engine]: https://github.com/zonemaster/zonemaster-engine
[Zonemaster-CLI]: https://github.com/zonemaster/zonemaster-cli
[Zonemaster-Backend]: https://github.com/zonemaster/zonemaster-backend
[Zonemaster-GUI]: https://github.com/zonemaster/zonemaster-gui
[NOTICE]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/specifications/tests/SeverityLevelDefinitions.md#notice
[WARNING]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/specifications/tests/SeverityLevelDefinitions.md#warning
[#1464]: https://github.com/zonemaster/zonemaster/pull/1464

182
zonemaster/docs/public/SUMMARY.md Normal file
View File

@@ -0,0 +1,182 @@
<!-- This file must match the format described in
https://rust-lang.github.io/mdBook/format/summary.html -->
# Documents in public document tree
- [Overview](README.md)
- [Release information](RELEASE.md)
- [Installation](installation/README.md)
- [Prerequisites](installation/prerequisites.md)
- [Zonemaster-LDNS](installation/zonemaster-ldns.md)
- [Zonemaster-Engine](installation/zonemaster-engine.md)
- [Zonemaster-CLI](installation/zonemaster-cli.md)
- [Zonemaster-Backend](installation/zonemaster-backend.md)
- [Zonemaster-GUI](installation/zonemaster-gui.md)
- [Docker](installation/docker.md)
- [Upgrading](upgrading/README.md)
- [GUI](upgrading/gui.md)
- [Backend](upgrading/backend.md)
- [v1.0.3](upgrading/backend/upgrade_zonemaster_backend_ver_1.0.3.md)
- [v1.1.0](upgrading/backend/upgrade_zonemaster_backend_ver_1.1.0.md)
- [v5.0.0](upgrading/backend/upgrade_zonemaster_backend_ver_5.0.0.md)
- [v5.0.2](upgrading/backend/upgrade_zonemaster_backend_ver_5.0.2.md)
- [v8.0.0](upgrading/backend/upgrade_zonemaster_backend_ver_8.0.0.md)
- [v9.0.0](upgrading/backend/upgrade_zonemaster_backend_ver_9.0.0.md)
- [v11.1.0](upgrading/backend/upgrade_zonemaster_backend_ver_11.1.0.md)
- [v11.2.0](upgrading/backend/upgrade_zonemaster_backend_ver_11.2.0.md)
- [Configuration](configuration/README.md)
- [Profiles](configuration/profiles.md)
- [Global Cache](configuration/global-cache.md)
- [Backend configuration in "backend_config.ini"](configuration/backend.md)
- [Backend environment variables](configuration/backend-environment-variables.md)
- [GUI](configuration/gui/README.md)
- [Building a custom Zonemaster-GUI](configuration/gui/building-custom-gui.md)
- [Run-time configuration using "config.json"](configuration/gui/configuring-using-config-json.md)
- [Simple build-time configuration using "config.ts"](configuration/gui/configuring-using-config-ts.md)
- [Advanced build-time configuration using "tsconfig.json"](configuration/gui/configuring-using-tsconfig-json.md)
- [Configuring using Theming](configuration/gui/configuring-using-theming.md)
- [Using](using/README.md)
- [CLI](using/cli.md)
- [Backend](using/backend/README.md)
- [Using Zonemaster-Backend JSON-RPC API](using/backend/Using-Zonemaster-Backend-JSON-RPC-API.md)
- [Using Zonemaster-Backend for batch testing](using/backend/Using-Zonemaster-Backend-for-batch-testing.md)
- [Using Zonemaster-Backend Docker container](using/backend/Using-Zonemaster-Backend-Docker.md)
- [RPCAPI Reference](using/backend/rpcapi-reference.md)
- [Telemetry](using/backend/telemetry.md)
- [GUI](using/gui/README.md)
- [API](using/gui/api.md)
- [Specifications](specifications/README.md)
- [Test Cases](specifications/tests/README.md)
- [Master Test Plan](specifications/tests/MasterTestPlan.md)
- [Methods](specifications/tests/Methods.md)
- [MethodsV2](specifications/tests/MethodsV2.md)
- [Test Messages](specifications/tests/TestMessages.md)
- [Severity Level Definitions](specifications/tests/SeverityLevelDefinitions.md)
- [DNS Query and Response](specifications/tests/DNSQueryAndResponseDefaults.md)
- [Requirements and Normalization](specifications/tests/RequirementsAndNormalizationOfDomainNames.md)
- [Arguments For Test Case Messages](specifications/tests/ArgumentsForTestCaseMessages.md)
- [Implemented Test Cases](specifications/tests/ImplementedTestCases.md)
- [Address-TP](specifications/tests/Address-TP/README.md)
- [Address01](specifications/tests/Address-TP/address01.md)
- [Address02](specifications/tests/Address-TP/address02.md)
- [Address03](specifications/tests/Address-TP/address03.md)
- [Basic-TP](specifications/tests/Basic-TP/README.md)
- [Basic01](specifications/tests/Basic-TP/basic01.md)
- [Basic02](specifications/tests/Basic-TP/basic02.md)
- [Basic03](specifications/tests/Basic-TP/basic03.md)
- [Connectivity-TP](specifications/tests/Connectivity-TP/README.md)
- [Connectivity01](specifications/tests/Connectivity-TP/connectivity01.md)
- [Connectivity02](specifications/tests/Connectivity-TP/connectivity02.md)
- [Connectivity03](specifications/tests/Connectivity-TP/connectivity03.md)
- [Connectivity04](specifications/tests/Connectivity-TP/connectivity04.md)
- [Consistency-TP](specifications/tests/Consistency-TP/README.md)
- [Consistency01](specifications/tests/Consistency-TP/consistency01.md)
- [Consistency02](specifications/tests/Consistency-TP/consistency02.md)
- [Consistency03](specifications/tests/Consistency-TP/consistency03.md)
- [Consistency04](specifications/tests/Consistency-TP/consistency04.md)
- [Consistency05](specifications/tests/Consistency-TP/consistency05.md)
- [Consistency06](specifications/tests/Consistency-TP/consistency06.md)
- [DNSSEC-TP](specifications/tests/DNSSEC-TP/README.md)
- [DNSSEC01](specifications/tests/DNSSEC-TP/dnssec01.md)
- [DNSSEC02](specifications/tests/DNSSEC-TP/dnssec02.md)
- [DNSSEC03](specifications/tests/DNSSEC-TP/dnssec03.md)
- [DNSSEC04](specifications/tests/DNSSEC-TP/dnssec04.md)
- [DNSSEC05](specifications/tests/DNSSEC-TP/dnssec05.md)
- [DNSSEC06](specifications/tests/DNSSEC-TP/dnssec06.md)
- [DNSSEC07](specifications/tests/DNSSEC-TP/dnssec07.md)
- [DNSSEC08](specifications/tests/DNSSEC-TP/dnssec08.md)
- [DNSSEC09](specifications/tests/DNSSEC-TP/dnssec09.md)
- [DNSSEC10](specifications/tests/DNSSEC-TP/dnssec10.md)
- [DNSSEC11](specifications/tests/DNSSEC-TP/dnssec11.md)
- [DNSSEC12](specifications/tests/DNSSEC-TP/dnssec12.md)
- [DNSSEC13](specifications/tests/DNSSEC-TP/dnssec13.md)
- [DNSSEC14](specifications/tests/DNSSEC-TP/dnssec14.md)
- [DNSSEC15](specifications/tests/DNSSEC-TP/dnssec15.md)
- [DNSSEC16](specifications/tests/DNSSEC-TP/dnssec16.md)
- [DNSSEC17](specifications/tests/DNSSEC-TP/dnssec17.md)
- [DNSSEC18](specifications/tests/DNSSEC-TP/dnssec18.md)
- [Delegation-TP](specifications/tests/Delegation-TP/README.md)
- [Delegation01](specifications/tests/Delegation-TP/delegation01.md)
- [Delegation02](specifications/tests/Delegation-TP/delegation02.md)
- [Delegation03](specifications/tests/Delegation-TP/delegation03.md)
- [Delegation04](specifications/tests/Delegation-TP/delegation04.md)
- [Delegation05](specifications/tests/Delegation-TP/delegation05.md)
- [Delegation06](specifications/tests/Delegation-TP/delegation06.md)
- [Delegation07](specifications/tests/Delegation-TP/delegation07.md)
- [Nameserver-TP](specifications/tests/Nameserver-TP/README.md)
- [Nameserver01](specifications/tests/Nameserver-TP/nameserver01.md)
- [Nameserver02](specifications/tests/Nameserver-TP/nameserver02.md)
- [Nameserver03](specifications/tests/Nameserver-TP/nameserver03.md)
- [Nameserver04](specifications/tests/Nameserver-TP/nameserver04.md)
- [Nameserver05](specifications/tests/Nameserver-TP/nameserver05.md)
- [Nameserver06](specifications/tests/Nameserver-TP/nameserver06.md)
- [Nameserver07](specifications/tests/Nameserver-TP/nameserver07.md)
- [Nameserver08](specifications/tests/Nameserver-TP/nameserver08.md)
- [Nameserver09](specifications/tests/Nameserver-TP/nameserver09.md)
- [Nameserver10](specifications/tests/Nameserver-TP/nameserver10.md)
- [Nameserver11](specifications/tests/Nameserver-TP/nameserver11.md)
- [Nameserver12](specifications/tests/Nameserver-TP/nameserver12.md)
- [Nameserver13](specifications/tests/Nameserver-TP/nameserver13.md)
- [Nameserver15](specifications/tests/Nameserver-TP/nameserver15.md)
- [Syntax-TP](specifications/tests/Syntax-TP/README.md)
- [Syntax01](specifications/tests/Syntax-TP/syntax01.md)
- [Syntax02](specifications/tests/Syntax-TP/syntax02.md)
- [Syntax03](specifications/tests/Syntax-TP/syntax03.md)
- [Syntax04](specifications/tests/Syntax-TP/syntax04.md)
- [Syntax05](specifications/tests/Syntax-TP/syntax05.md)
- [Syntax06](specifications/tests/Syntax-TP/syntax06.md)
- [Syntax07](specifications/tests/Syntax-TP/syntax07.md)
- [Syntax08](specifications/tests/Syntax-TP/syntax08.md)
- [Zone-TP](specifications/tests/Zone-TP/README.md)
- [Zone01](specifications/tests/Zone-TP/zone01.md)
- [Zone02](specifications/tests/Zone-TP/zone02.md)
- [Zone03](specifications/tests/Zone-TP/zone03.md)
- [Zone04](specifications/tests/Zone-TP/zone04.md)
- [Zone05](specifications/tests/Zone-TP/zone05.md)
- [Zone06](specifications/tests/Zone-TP/zone06.md)
- [Zone07](specifications/tests/Zone-TP/zone07.md)
- [Zone08](specifications/tests/Zone-TP/zone08.md)
- [Zone09](specifications/tests/Zone-TP/zone09.md)
- [Zone10](specifications/tests/Zone-TP/zone10.md)
- [Zone11](specifications/tests/Zone-TP/zone11.md)
- [Test Types](specifications/test-types/README.md)
- [Undelegated Test](specifications/test-types/undelegated-test.md)
- [Test Zones](specifications/test-zones/README.md)
- [Engine Perl modules](specifications/test-zones/Engine/README.md)
- [Recursor-PM](specifications/test-zones/Engine/Recursor-PM/README.md)
- [CNAME](specifications/test-zones/Engine/Recursor-PM/CNAME.md)
- [MethodsV2](specifications/test-zones/MethodsV2/README.md)
- [MethodsV2 test scenario specification](specifications/test-zones/MethodsV2/methodsv2.md)
- [Address-TP](specifications/test-zones/Address-TP/README.md)
- [Address01](specifications/test-zones/Address-TP/address01.md)
- [Address03](specifications/test-zones/Address-TP/address03.md)
- [Basic-TP](specifications/test-zones/Basic-TP/README.md)
- [Basic01](specifications/test-zones/Basic-TP/basic01.md)
- [Basic02](specifications/test-zones/Basic-TP/basic02.md)
- [Connectivity-TP](specifications/test-zones/Connectivity-TP/README.md)
- [Connectivity04](specifications/test-zones/Connectivity-TP/connectivity04.md)
- [Consistency-TP](specifications/test-zones/Consistency-TP/README.md)
- [Consistency05](specifications/test-zones/Consistency-TP/consistency05.md)
- [Consistency06](specifications/test-zones/Consistency-TP/consistency06.md)
- [DNSSEC-TP](specifications/test-zones/DNSSEC-TP/README.md)
- [DNSSEC01](specifications/test-zones/DNSSEC-TP/dnssec01.md)
- [DNSSEC03](specifications/test-zones/DNSSEC-TP/dnssec03.md)
- [DNSSEC05](specifications/test-zones/DNSSEC-TP/dnssec05.md)
- [DNSSEC07](specifications/test-zones/DNSSEC-TP/dnssec07.md)
- [DNSSEC10](specifications/test-zones/DNSSEC-TP/dnssec10.md)
- [DNSSEC16](specifications/test-zones/DNSSEC-TP/dnssec16.md)
- [Delegation-TP](specifications/test-zones/Delegation-TP/README.md)
- [Delegation01](specifications/test-zones/Delegation-TP/delegation01.md)
- [Delegation02](specifications/test-zones/Delegation-TP/delegation02.md)
- [Delegation03](specifications/test-zones/Delegation-TP/delegation03.md)
- [Nameserver-TP](specifications/test-zones/Nameserver-TP/README.md)
- [Nameserver11](specifications/test-zones/Nameserver-TP/nameserver11.md)
- [Nameserver15](specifications/test-zones/Nameserver-TP/nameserver15.md)
- [Zone-TP](specifications/test-zones/Zone-TP/README.md)
- [Zone09](specifications/test-zones/Zone-TP/zone09.md)
- [Zone11](specifications/test-zones/Zone-TP/zone11.md)
- [Translation](translation/README.md)
- [Translating Engine, CLI and Backend](translation/Translating-Engine-CLI-Backend.md)
- [Translating GUI](translation/Translating-GUI.md)
- [Development](development/README.md)
- [CLI](development/cli.md)
- [License](LICENSE.md)

23
zonemaster/docs/public/book.toml Normal file
View File

@@ -0,0 +1,23 @@
[book]
authors = [ "Zonemaster Team" ]
description = "Zonemaster documentation"
language = "en"
src = "./"
[build]
create-missing = false
use-default-preprocessors = false
[output.html]
no-section-label = true
[output.html.fold]
enable = true
level = 1
[output.linkcheck]
optional = true
warning-policy= "warn"
follow-web-links = false
traverse-parent-directories = false
exclude = [ 'SUMMARY.md', 'LICENSE.md', 'zonemaster_logo_2021_color.png', 'localhost' ]

17
zonemaster/docs/public/configuration/README.md Normal file
View File

@@ -0,0 +1,17 @@
# Configuration
This section contains information about configuration of the different components
of Zonemaster:
* Setting up or modifying the [profile] in Zonemaster-Engine.
* Enabling the Zonemaster-Engine [global cache] feature.
* Configuring Zonemaster-Backend in the [Backend configuration file].
* Using [environment variables] for Zonemaster-Backend.
* Configuring Zonemaster-GUI in the [GUI configuration section].
[profile]: profiles.md
[global cache]: global-cache.md
[Backend configuration file]: backend.md
[environment variables]: backend-environment-variables.md
[GUI configuration section]: gui/README.md

35
zonemaster/docs/public/configuration/backend-environment-variables.md Normal file
View File

@@ -0,0 +1,35 @@
# 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.

415
zonemaster/docs/public/configuration/backend.md Normal file
View File

@@ -0,0 +1,415 @@
# Configuration
## Table of contents
* [Introduction](#introduction)
* [RPCAPI section](#rpcapi-section)
* [enable_batch_create](#enable_batch_create)
* [enable_user_create](#enable_user_create)
* [enable_add_batch_job](#enable_add_batch_job)
* [enable_add_api_user](#enable_add_api_user)
* [DB section](#db-section)
* [engine](#engine)
* [polling_interval](#polling_interval)
* [MYSQL section](#mysql-section)
* [host](#host)
* [port](#port)
* [user](#user)
* [password](#password)
* [database](#database)
* [POSTGRESQL section](#postgresql-section)
* [host](#host-1)
* [port](#port-1)
* [user](#user-1)
* [password](#password-1)
* [database](#database-1)
* [SQLITE section](#sqlite-section)
* [database_file](#database_file)
* [LANGUAGE section](#language-section)
* [locale](#locale)
* [METRICS section](#metrics-section)
* [statsd_host](#statsd_host)
* [statsd_port](#statsd_port)
* [PUBLIC PROFILES and PRIVATE PROFILES sections](#public-profiles-and-private-profiles-sections)
* [ZONEMASTER section](#zonemaster-section)
* [max_zonemaster_execution_time](#max_zonemaster_execution_time)
* [number_of_processes_for_frontend_testing](#number_of_processes_for_frontend_testing)
* [number_of_processes_for_batch_testing](#number_of_processes_for_batch_testing)
* [lock_on_queue](#lock_on_queue)
* [age_reuse_previous_test](#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][File format].
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][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: `true` or `false` (or `yes` or `no`),
default to `true` (enabled).
**Deprecated:** The `yes`/`no` values are deprecated and will be rejected in
v2026.2.
Use `true`/`false` instead.
### enable_add_api_user
Boolean value to enable the `add_api_user` and `user_create` method of the API.
Accepted values: `true` or `false` (or `yes` or `no`),
default to `false` (disabled).
**Deprecated:** The `yes`/`no` values are deprecated and will be rejected in
v2026.2.
Use `true`/`false` instead.
### enable_batch_create
An experimental alias for [enable_add_batch_job][RPCAPI.enable_add_batch_job].
### enable_user_create
An experimental alias for [enable_add_api_user][RPCAPI.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.
Database Engine | Value
------------------|------
MariaDB | `MySQL`
MySQL | `MySQL`
PostgreSQL | `PostgreSQL`
SQLite | `SQLite`
### 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][MariaDB identifier max lengths].
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][MariaDB identifier max lengths].
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.
Language | Locale tag value | Language code | Locale value used
---------|------------------|---------------|------------------
Danish | da_DK | da | da_DK.UTF-8
English | en_US | en | en_US.UTF-8
Spanish | es_ES | es | es_ES.UTF-8
Finnish | fi_FI | fi | fi_FI.UTF-8
French | fr_FR | fr | fr_FR.UTF-8
Norwegian| nb_NO | nb | nb_NO.UTF-8
Slovenian| sl_SI | sl | sl_SI.UTF-8
Swedish | sv_SE | sv | sv_SE.UTF-8
Setting in the default configuration file:
```
locale = da_DK en_US es_ES fi_FI fr_FR nb_NO sl_SI 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.
[API documentation]: ../using/backend/api.md
[DBD::mysql documentation]: https://metacpan.org/pod/DBD::mysql#host
[Default JSON profile file]: https://github.com/zonemaster/zonemaster-engine/blob/master/share/profile.json
[Environment Variables]: backend-environment-variables.md
[File format]: https://metacpan.org/pod/Config::IniFiles#FILE-FORMAT
[ISO 3166-1 alpha-2]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
[ISO 639-1]: https://en.wikipedia.org/wiki/ISO_639-1
[Installation instructions]: ../installation/zonemaster-backend.md
[Language tag]: ../using/backend/api.md#language-tag
[LDH domain name]: https://datatracker.ietf.org/doc/html/rfc3696#section-2
[MariaDB identifier max lengths]: https://mariadb.com/kb/en/identifier-names/#maximum-length
[MariaDB unquoted identifier]: https://mariadb.com/kb/en/identifier-names/#unquoted
[MYSQL.host]: #host
[MYSQL.port]: #port
[PostgreSQL identifier]: https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS
[Profile JSON files]: profiles.md
[Profile name section]: ../using/backend/rpcapi-reference.md#profile-name
[Profiles]: https://github.com/zonemaster/zonemaster-backend/blob/master/docs/Architecture.md#profile
[RPCAPI.enable_add_api_user]: #enable_add_api_user
[RPCAPI.enable_add_batch_job]: #enable_add_batch_job
[RPCAPI.enable_batch_create]: #enable_batch_create
[RPCAPI.enable_user_create]: #enable_user_create
[SQLITE.database_file]: #database_file
[US ASCII printable characters]: https://en.wikipedia.org/wiki/ASCII#Printable_characters
[Zonemaster-Engine share directory]: https://github.com/zonemaster/zonemaster-engine/tree/master/share
[Zonemaster::Engine::Profile]: https://metacpan.org/pod/Zonemaster::Engine::Profile#PROFILE-PROPERTIES
[Zonemaster Engine default profile]: profiles.md#default-profile

123
zonemaster/docs/public/configuration/global-cache.md Normal file
View File

@@ -0,0 +1,123 @@
# Configuration: Global cache in Zonemaster-Engine
## Table of contents
* [Introduction](#introduction)
* [Prerequisites](#prerequisites)
* [Installation for global cache](#installation-for-global-cache)
* [Create directory for custom profile](#create-directory-for-custom-profile)
* [Enable global cache](#enable-global-cache)
* [Using 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
If there is no `profile.json` in `/etc/zonemaster/` (or `/usr/local/etc/zonemaster/`
for FreeBSD), create it by extracting the default profile using the command in the
[profile documentation].
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][Zonemaster::CLI installation] 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].
[profile documentation]: profiles.md
[Zonemaster::Backend configuration]: backend.md
[Zonemaster::CLI installation]: ../installation/zonemaster-cli.md
[Zonemaster::Engine installation]: ../installation/zonemaster-engine.md

20
zonemaster/docs/public/configuration/gui/README.md Normal file
View File

@@ -0,0 +1,20 @@
# GUI Configuration
This section contains information about configuration of the GUI component.
* [Run-time configuring Zonemaster-GUI using "config.json"] is currently limited
to creating or updating a message banner.
* [Simple build-time configuring Zonemaster-GUI using "config.ts"] lists
basic configuration options of Zonemaster-GUI.
* [Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"] can
change the look-and-feel of Zonemaster-GUI.
* [Configuring Zonemaster-GUI using Theming] gives further instructions for how
to customize Zonemaster-GUI.
* [Build a custom Zonemaster-GUI installation package]
[Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"]: configuring-using-tsconfig-json.md
[Build a custom Zonemaster-GUI installation package]: building-custom-gui.md
[Configuring Zonemaster-GUI using Theming]: configuring-using-theming.md
[Run-time configuring Zonemaster-GUI using "config.json"]: configuring-using-config-json.md
[Simple build-time configuring Zonemaster-GUI using "config.ts"]: configuring-using-config-ts.md

173
zonemaster/docs/public/configuration/gui/building-custom-gui.md Normal file
View File

@@ -0,0 +1,173 @@
# Build a custom Zonemaster-GUI installation package
## Background
If you follow the [Zonemaster-GUI installation instructions] you can install an
official package, and skip the instructions in this document.
However, if you have created a custom [config.ts], done theme settings in
[tsconfig.json] or done some [theme updates] then you must create a custom
installation package for your custom installation. That can be achieved by
following the steps below.
It is also important to state that even though the installation package is
created on Ubuntu 22.04 below, the resulting installation package can be
installed on at least all OSs supported in the
[Zonemaster-GUI installation instructions].
## Prepare build environment
Start by creating a build environment. Here we assume and base it on
[Ubuntu] version 22.04. The instructions will probably work with other versions
of Ubuntu, or with other Linux distributions or other OSs, but then you might
need to adapt some of the commands. Note however that it is important that the
system fully supports [npm].
### Install toolchain
1. Make a clean installation of Ubuntu 22.04.
2. Update the package database and install Curl and Git.
```sh
sudo apt-get update
sudo apt-get install curl git
```
3. Install Node.js by using [NVM], a node version manager.
```sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
```
4. After installation, log out and log in again to handle [known issue], or just:
```sh
source ~/.bashrc
```
5. Install the supported Node.js version
```sh
nvm install 24
```
6. Switch to the previously installed version
```sh
nvm use 24
```
## Check out source code
You need to checkout the source code of Zonemaster-GUI. In the usual case
you will start with the `master` branch latest Zonemaster-GUI release as
shown below.
```sh
git clone -b master https://github.com/zonemaster/zonemaster-gui.git
cd zonemaster-gui
```
If you already have a clone, make sure that you start from an up-to-date `master`
branch.
```sh
git checkout master
git fetch --all
git pull
```
## Add customization
From there, you can start to do your own customization. The simplest case only
requires an update to [config.ts]. See the [GUI Configuration][README] overview
for more details.
You should then save any changed file by doing the following steps (see
[Git tutorial]).
```sh
git checkout -b MY-BRANCH
git add FILE
git commit -m 'What did I do?'
```
## Build installation package
When building you should have a clean repository. Clean means that all temporary
(i.e. non-versioned) files are removed.
1. List all files and changes that will be removed with next step.
```sh
git status --ignored
```
2. Remove all files and changes not included in a Git branch (listed in
previous step).
```sh
git clean -dfx
git reset --hard
```
3. Install [npm] libraries in the repository.
```sh
npm install
```
4. Build the Zonemaster-GUI.
```sh
npm run build
```
5. If building fails, go back to the "[Install toolchain]" section and repeat the
two `nvm` commands and restart building.
6. Build a Zonemaster-GUI installation package (a zip file).
```sh
npm run release
```
If all steps worked well, there will be a zip file in the current repository that
can be used for installation, i.e. by replacing the official installation package
(zip file) with this new zip file in the [Zonemaster-GUI installation instructions].
If the build step above fails, go back to a safe branch and add your updates one
by one, and repeating steps 1-5.
## Testing the Build Locally
To test the static build locally, it must be served from the root path (/). You
can use any static server. Here are two common options, and note that
additional software has to be installed for those:
```sh
python3 -m http.server 8000 --directory ./public
```
```sh
php -S localhost:8000 -t ./public
```
Ensure you're serving the ./public directory (or your build output folder) as
the root for all assets and routing to work correctly.
[Git tutorial]: https://git-scm.com/docs/gittutorial
[Known issue]: https://github.com/nvm-sh/nvm#troubleshooting-on-linux
[NPM]: https://www.npmjs.com/
[NVM]: https://github.com/nvm-sh/nvm
[Node.js]: https://nodejs.org/en
[README]: README.md
[Ubuntu]: https://ubuntu.com/
[Zonemaster-GUI installation instructions]: ../../installation/zonemaster-gui.md
[config.ts]: configuring-using-config-ts.md
[tsconfig.json]: configuring-using-tsconfig-json.md
[theme updates]: configuring-using-theming.md
[Install toolchain]: #install-toolchain

66
zonemaster/docs/public/configuration/gui/configuring-using-config-json.md Normal file
View File

@@ -0,0 +1,66 @@
# Run-time configuring Zonemaster-GUI using "config.json"
The `config.json` configuration file can be used for *run-time* settings of the
Zonemaster-GUI, i.e. no rebuild of the installation package is needed.
Currently, the only supported setting is creating, updating or removing a message
banner. Other types of configuration require a rebuild of the GUI, and are covered
in sibling documents of this document.
## Finding "config.json"
In the source tree the file is found as `static/config.json` relative to the
root of the Git tree.
In a default installation, the file is found as
`/var/www/html/zonemaster-web-gui/dist/config.json`.
## Reloading GUI after update
When the Web browser reloads the GUI, e.g. after running a new test, the
changes are displayed by the GUI.
## Default "config.json" file
The `config.json` file contains configuration that is loaded at runtime.
Currently, it includes settings for displaying banner messages in different
languages:
```json
{
"msgBanner": {
"en": "",
"sv": "",
"da": "",
"es": "",
"fi": "",
"fr": "",
"nb": ""
}
}
```
### Configuration Options
* **msgBanner**: An object containing message banner text for each supported
language. These messages can be used to display important announcements or
notifications to users in their preferred language.
The message banner is shown just below the top menu on all pages.
The string is set for each language, and may contain HTML code such as `<br>` or
even `<a href>` if necessary. Take note not to break quoting as JSON requires
quoting with `""` around the string.
To display a message banner, simply add the message text to the corresponding
language key. E.g.:
```json
{
"msgBanner": {
"en": "Scheduled system maintenance on 2025-12-09 from 10:00 to 12:00 UTC.",
"sv": "Planerat systemunderhåll den 9 december 2025 kl. 10.00–12.00 UTC."
}
}
```

117
zonemaster/docs/public/configuration/gui/configuring-using-config-ts.md Normal file
View File

@@ -0,0 +1,117 @@
# Simple build-time configuring Zonemaster-GUI using "config.ts"
The `config.ts` configuration file can be used for *build-time* settings of
the Zonemaster-GUI. Any changes to this file require a rebuild of the
installation package.
## Finding "config.ts"
In the source tree the file is found as `config.ts` relative to the root of
the Git tree. The installed GUI does not ship with this file, because the
values defined in this file are baked in the GUI’s HTML and JavaScript files.
## Rebuilding Zonemaster-GUI after update
When `config.ts` is updated, Zonemaster-GUI has to be rebuilt. See
[Build a custom Zonemaster-GUI installation package] for how to get the source
tree and building a custom installation package.
## Default "config.ts" file
The `config.ts` file is the central configuration file for the Zonemaster-GUI
application. It defines various settings that control the behavior and appearance
of the application.
```typescript
import type { Config } from '@/types.ts';
import packageJson from './package.json';
const config: Config = {
defaultLanguage: 'en',
enabledLanguages: ['da', 'en', 'es', 'fi', 'fr', 'nb', 'sv', 'sl'],
baseUrl: import.meta.env.PUBLIC_BASE_URL || '/',
apiBaseUrl: import.meta.env.PUBLIC_API_URL || '/api',
pollingInterval: import.meta.env.PUBLIC_POLLING_INTERVAL || 5000,
clientInfo: {
version: packageJson.version,
id: 'Zonemaster-GUI',
},
siteInfo: {
email: 'contact@zonemaster.net',
siteName: '',
},
setTitle(title: string) {
return `${title} – Zonemaster`;
}
};
export default config;
```
## "config.ts" configuration options
* **defaultLanguage**: The default language to use when no language is specified.
* The default language must be one of the enabled languages.
* The default value is "en".
* If this option is updated see [Updating Apache configuration] for required
matching update of the Apache configuration.
* **enabledLanguages**: An array of language codes that are supported by the
application.
* The array should match the list of language codes in the [Locale setting] in
the Backend configuration.
* The array must only include language codes also included in
`project.inlang/settings.json`, but it may be fewer. To add new languages,
see [Translating Zonemaster-GUI]. `project.inlang/settings.json` must only be
updated in that process.
* **baseUrl**: The base path Zonemaster-GUI is served on. By default it is "/".
* For example, if Zonemaster-GUI is served at
`http://domaintest.xa/zonemaster`, instead of just
`http://domaintest.xa/`, then this option must be set to `/zonemaster`.
* If this option is updated see [Updating Apache configuration] for required
matching update of the Apache configuration.
* **apiBaseUrl**: The base URL for API requests. The default value is `/api`
and must be kept so if `baseUrl` has its default value.
* If `baseUrl` is updated, then this option must also be updated so that this
option is equal to `baseUrl` + '/api', i.e. '/zonemaster/api' in the
example above.
* **pollingInterval**: The interval (in milliseconds) for polling the API. This
is taken from the `PUBLIC_POLLING_INTERVAL` environment variable (default
empty) or defaults to 5000 ms.
* **clientInfo**: Information about the client application. These details are
included in every API request to start tests as (spoofable) indications of
origin. Both are best left as default.
* **version**: The version of the application, taken from package.json.
* **id**: The identifier for the client application.
* **siteInfo**: Information about the site.
* **email**: The contact email address. To be set in the footer in a mailto
URL, if non-empty.
- **siteName**: The name of the site. To be set in the header if non-empty.
## Updating Apache configuration
Preferably do the updates to the `zonemaster.conf-example` file before building
the installation package. If done so the normal installation instruction can be
followed using the custom installation package.
### Finding "zonemaster.conf-example"
In the source tree the file is found as `zonemaster.conf-example` relative to the
root of the Git tree. It is included in the installation package and is installed
as `zonemaster.conf` in a default installation.
### defaultLanguage
If `defaultLanguage` has been updated in `config.ts` the "DEFAULT_LANGUAGE"
variable must be updated in `zonemaster.conf-example`. The same language code
must be used.
### baseUrl
If `baseUrl` has been set to a non-default value in `config.ts` the "BASE_URL"
variable must be defined with the same value. By default the variable is
undefined (`baseUrl` equal to "/").
[Build a custom Zonemaster-GUI installation package]: building-custom-gui.md
[Locale setting]: ../backend.md#locale
[Translating Zonemaster-GUI]: ../../translation/Translating-GUI.md
[Updating Apache configuration]: #updating-apache-configuration

169
zonemaster/docs/public/configuration/gui/configuring-using-theming.md Normal file
View File

@@ -0,0 +1,169 @@
# Configuring Zonemaster-GUI using Theming
## Background
The Zonemaster-GUI is built to be cloned and customized. You have full control
over the styling and layout. That said, to avoid troubles when syncing with
the original repository, we recommend following a few simple guidelines:
- Start by customizing the **theme variables** — this is enough for most use cases.
- If that's not enough, apply **custom CSS** targeting specific elements.
- For large framework changes, **create a new theme** and update `tsconfig.json`.
- For interactive components, **keep changes minimal** to avoid breaking functionality.
- Use **headless mode** for major customizations or when building your own GUI.
## Related documents
For how to use `tsconfig.json` in connection to theming, see
[Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"]. Theming
requires rebuilding Zonemaster-GUI, see
[Build a custom Zonemaster-GUI installation package].
## Basic customization
The Zonemaster-GUI is built around a global theme based on CSS variables
(`./src/themes/default/styles/theme.css`). The easiest way to make your own theme
is to override theme variables in the `./src/themes/default/styles/custom.css` file.
You can tweak colors, fonts, spacing, and more. You'll get surprisingly far by
just updating the theme variables. All class names are prefixed with `zm-` to
avoid conflicts with other styles. This makes it easy to apply custom CSS on top
of the theme to target specific elements.
### Available theme variables
The theme includes variables for:
- **Font sizes and families**: `--font-xxs` through
`--font-supersize`, `--font-body-family`, etc.
- **Spacing**: `--spacing-xxs` through `--spacing-xxl`
- **Colors**: Various color palettes including main, secondary, black, danger,
success, info, warning, and error
- **GUI elements**: Background, text, borders, etc.
- **Buttons**: Size, color, padding
- **Layout**: Width, gaps, header height
- **Breakpoints**: For responsive design
### Example customization
Here's a simple example of customizing the main color and font in `custom.css`:
```css
:root {
/* Change the primary color */
--color-palette-main-50: #4285f4;
--color-palette-main-70: #1a73e8;
/* Change the font */
--font-body-family: 'Roboto', sans-serif;
}
```
### CSS loading order
The CSS files are loaded in the following order (defined in `styles.css`):
1. theme.css (base theme variables)
2. foundation.css and other core styles
3. Component-specific CSS files
4. custom.css (your customizations)
This ensures that your custom styles will override the default styles.
## Modifying structure and layout
There are two layers of the GUI.
### Framework
The framework is the foundation of the GUI and is built with [Astro]. These
files are located under `./src/themes/default`. ' The starting point for these
imports are pages. Pages are simple: they consist of a single component wrapped
inside a layout. *We suggest not modifying the page files*. Instead, create your
own theme, for example `./src/themes/my-theme`. You can still reuse components
from the original theme in your new theme and mix and match the imports from your
custom theme.
Then update tsconfig.json:
```diff
{
"extends": "astro/tsconfigs/strict",
"include": [".astro/types.d.ts", "**/*"],
"exclude": ["dist"],
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
- "@theme/*": ["./src/themes/default/*"]
+ "@theme/*": ["./src/themes/my-theme/*"]
}
}
}
```
### Interactive components
All interactive components are built with [Svelte]. These files are located under
`./src/lib/components`. These are referenced from Astro components. Although care
was taken to make the components as self-contained as possible, some
components may depend on others. In most cases you won't need to modify these
files. A better approach is to modify the CSS.
If you absolutely need to modify these, the suggested method is to create new
components in `./src/lib/components/my-theme` and reference them from the
Astro components. These interactive components contain important functionality
that needs to be carefully considered when modifying.
You might be better off creating a new component from scratch and integrate it
with the RPCAPI yourself.
## Headless mode
For major customizations or when you need complete control over the GUI, you can
use the "headless mode" approach. This involves using the Zonemaster API client
directly without the GUI components.
For detailed information about headless mode, please refer to the [UI.md]
documentation.
## Testing and troubleshooting
### Testing your theme changes
When making theme changes, it's important to test them across different pages and
components to ensure consistency. Here are some tips:
1. **Test on different screen sizes**: Use your browser's developer tools to test
responsive behavior.
2. **Check all interactive states**: Verify hover, focus, active, and disabled
states for interactive elements.
3. **Test with different content**: Make sure your theme works well with both
short and long content.
4. **Verify accessibility**: Ensure sufficient color contrast and that focus
states are visible.
### Common issues and solutions
- **Changes not appearing**: Make sure your `custom.css` file is being loaded.
Check the browser's developer tools to verify.
- **Specificity issues**: If your styles aren't overriding the defaults, you
might need to increase specificity or use `!important` (sparingly).
- **Responsive issues**: Check that your customizations work well at all
breakpoints.
- **Component styling conflicts**: If styling a specific component, target the
component's class directly rather than modifying global variables.
### Development workflow
For a smoother development experience:
1. Start the development server with `npm run dev`
2. Make changes to your `custom.css` file
3. The changes will be applied immediately thanks to hot module reloading
4. Use browser developer tools to inspect elements and test different values
[Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"]: configuring-using-tsconfig-json.md
[Build a custom Zonemaster-GUI installation package]: building-custom-gui.md
[Astro]: https://astro.build/
[Configuration of GUI]: https://doc.zonemaster.net/latest/configuration/gui/README.html
[Svelte]: https://svelte.dev/
[UI.md]: https://github.com/zonemaster/zonemaster-gui/blob/master/docs/UI.md#headless-mode

81
zonemaster/docs/public/configuration/gui/configuring-using-tsconfig-json.md Normal file
View File

@@ -0,0 +1,81 @@
# Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"
The `tsconfig.json` configuration file can be used for *build-time* settings of
Zonemaster-GUI. Any changes to this file require a rebuild of the installation
package.
## Finding "tsconfig.json"
In the source tree the file is found as `tsconfig.json` relative to the root of
the Git tree. It does not exist in the installed Zonemaster-GUI, as the values
have been built-in.
## Rebuilding Zonemaster-GUI after update
When `tsconfig.json` has been updated, Zonemaster-GUI has to be rebuilt. See
[building installation package] for how to get the source tree and building a new
installation package.
## Default "tsconfig`.json"
The `tsconfig.json` file is a TypeScript configuration file that includes path
aliases like `@theme/*` to simplify imports and make theming more manageable.
```json
{
"extends": "astro/tsconfigs/strict",
"include": [".astro/types.d.ts", "**/*"],
"exclude": ["dist"],
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
"@theme/*": ["./src/themes/default/*"]
},
"resolveJsonModule": true,
"esModuleInterop": true
}
}
```
## @theme/* Alias in "tsconfig.json"
The path alias configuration allows importing from the default theme directory
using the `@theme` prefix, which makes it possible to create a customize the
look-and-feel of the Zonemaster-GUI, e.g. set other colors and type faces.
```json
{
"paths": {
"@/*": ["./src/*"],
"@theme/*": ["./src/themes/default/*"]
}
}
```
This alias makes it easier to import theme-specific components and styles
in your code. For example, instead of writing:
```typescript
import Button from '../../themes/default/components/Button';
```
You can use:
```typescript
import Button from '@theme/components/Button';
```
This approach simplifies imports and makes it easier to switch between different
themes by changing the alias path.
## Theming
In the [Theming Zonemaster-GUI] document you will find instructions how to add
custom theming to Zonemaster-GUI.
[Building installation package]: building-custom-gui.md
[Theming Zonemaster-GUI]: https://github.com/zonemaster/zonemaster-gui/blob/master/docs/theming-zonemaster-gui.md

30
zonemaster/docs/public/configuration/profiles.md Normal file
View File

@@ -0,0 +1,30 @@
# 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.
```sh
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][profile properties]
that it should override.
[profile_additional_properties.json]: https://github.com/zonemaster/zonemaster-engine/blob/master/share/profile_additional_properties.json
[Profile properties]: https://metacpan.org/pod/Zonemaster::Engine::Profile#PROFILE-PROPERTIES

9
zonemaster/docs/public/development/README.md Normal file
View File

@@ -0,0 +1,9 @@
# Zonemaster development guide
The development guide provides instructions for various tasks related to the
development of each component of Zonemaster.
Development guides:
* [Zonemaster-CLI development]
[Zonemaster-CLI development]: cli.md

17
zonemaster/docs/public/development/cli.md Normal file
View File

@@ -0,0 +1,17 @@
# Development
## Overview
This is the development guide for Zonemaster-CLI.
It provides instructions for various tasks related to the development of
Zonemaster-CLI.
## Common Developer Actions
### Generate man page
To generate and view a development version of the man page:
```sh
perldoc -oman script/zonemaster-cli
```

32
zonemaster/docs/public/installation/README.md Normal file
View File

@@ -0,0 +1,32 @@
# 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
Most Zonemaster components are available as [Docker] containers. See the dedicated
[Docker document] for more information.
[Docker]: https://www.docker.com/get-started/
[Docker document]: docker.md
[prerequisites]: prerequisites.md
[prerequisites]: prerequisites.md
[Zonemaster-Backend]: zonemaster-backend.md
[Zonemaster-CLI]: zonemaster-cli.md
[Zonemaster-Engine]: zonemaster-engine.md
[Zonemaster-GUI]: zonemaster-gui.md
[Zonemaster-LDNS]: zonemaster-ldns.md

17
zonemaster/docs/public/installation/docker.md Normal file
View File

@@ -0,0 +1,17 @@
# Docker
The following components are available on [Docker Hub], and can conveniently be
downloaded and run without any installation. Through [Docker], Zonemaster can
be run on Linux, MacOS and Windows.
- Zonemaster-CLI: see [Using Zonemaster-CLI Docker] for how to run Zonemaster-CLI on [Docker].
- Zonemaster-Backend: see [Using Zonemaster-Backend Docker] for how to run Zonemaster-Backend
and Zonemaster-CLI on [Docker].
To build your own Docker image, see the [Docker Image Creation] documentation.
[Docker]: https://www.docker.com/get-started/
[Docker Hub]: https://hub.docker.com/u/zonemaster
[Docker Image Creation]: https://github.com/zonemaster/zonemaster/blob/master/docs/internal/maintenance/ReleaseProcess-create-docker-image.md
[Using Zonemaster-Backend Docker]: ../using/backend/Using-Zonemaster-Backend-Docker.md
[Using Zonemaster-CLI Docker]: ../using/cli.md

93
zonemaster/docs/public/installation/prerequisites.md Normal file
View File

@@ -0,0 +1,93 @@
# 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
| Operating System | Version |
|:-----------------|:-------:|
| [Debian] | 13 |
| [Docker] | n/a |
| [FreeBSD] | 14 |
| [Rocky Linux] | 8 |
| [Rocky Linux] | 9 |
| [Rocky Linux] | 10 |
| [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).
## Supported database engine versions
| Operating System | MariaDB | PostgreSQL |
|------------------|---------|------------|
| Debian 13 | 11.8 | 17 |
| Docker | n/a | n/a |
| FreeBSD 14 | 8.0 (*) | 17 |
| Rocky Linux 8 | 10.3 | 10 |
| Rocky Linux 9 | 10.5 | 13 |
| Rocky Linux 10 | 10.11 | 16 |
| Ubuntu 22.04 | 10.6 | 14 |
| Ubuntu 24.04 | 10.11 | 16 |
* (*) 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
| Operating System | Perl |
|------------------|-------|
| Debian 13 | 5.40 |
| Docker | (*) |
| FreeBSD 14 | 5.42 |
| Rocky Linux 8 | 5.26 |
| Rocky Linux 9 | 5.32 |
| Rocky Linux 10 | 5.40 |
| Ubuntu 22.04 | 5.34 |
| Ubuntu 24.04 | 5.38 |
* Zonemaster technically requires Perl version 5.26 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 images 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.
Browser |
------- |
Firefox |
Chrome |
Zonemaster GUI is tested manually and with testing tools. See the
[Zonemaster-gui repository][Zonemaster-GUI] for more details.
[Debian]: https://www.debian.org/
[Docker Hub]: https://hub.docker.com/u/zonemaster
[Docker]: https://www.docker.com/get-started/
[FreeBSD]: https://www.freebsd.org/
[Rocky Linux]: https://rockylinux.org/
[Ubuntu]: https://ubuntu.com/
[Zonemaster-GUI]: https://github.com/zonemaster/zonemaster-gui

842
zonemaster/docs/public/installation/zonemaster-backend.md Normal file
View File

@@ -0,0 +1,842 @@
# Installation: Zonemaster-Backend
## Table of contents
* [1. Overview](#1-overview)
* [2. Prerequisites][prerequisites section]
* [3. Installation on Rocky Linux](#3-installation-on-rocky-linux)
* [3.1 Install Zonemaster::Backend and related dependencies (Rocky Linux)](#31-install-zonemasterbackend-and-related-dependencies-rocky-linux)
* [3.2 Database engine installation (Rocky Linux)](#32-database-engine-installation-rocky-linux)
* [3.3 Database configuration (Rocky Linux)](#33-database-configuration-rocky-linux)
* [3.4 Service configuration and startup (Rocky Linux)](#34-service-configuration-and-startup-rocky-linux)
* [3.5 Post-installation (Rocky Linux)](#35-post-installation-rocky-linux)
* [4. Installation on Debian and Ubuntu](#4-installation-on-debian-and-ubuntu)
* [4.1 Install Zonemaster::Backend and related dependencies (Debian/Ubuntu)](#41-install-zonemasterbackend-and-related-dependencies-debianubuntu)
* [4.2 Database engine installation (Debian/Ubuntu)](#42-database-engine-installation-debianubuntu)
* [4.3 Database configuration (Debian/Ubuntu)](#43-database-configuration-debianubuntu)
* [4.4 Service configuration and startup (Debian/Ubuntu)](#44-service-configuration-and-startup-debianubuntu)
* [4.5 Post-installation (Debian/Ubuntu)](#45-post-installation-debianubuntu)
* [5. Installation on FreeBSD](#5-installation-on-freebsd)
* [5.1 Install Zonemaster::Backend and related dependencies (FreeBSD)](#51-install-zonemasterbackend-and-related-dependencies-freebsd)
* [5.2 Database engine installation (FreeBSD)](#52-database-engine-installation-freebsd)
* [5.3 Database configuration (FreeBSD)](#53-database-configuration-freebsd)
* [5.4 Service startup (FreeBSD)](#54-service-startup-freebsd)
* [5.5 Post-installation (FreeBSD)](#55-post-installation-freebsd)
* [6. Post-installation][Post-installation]
* [6.1 Smoke test](#61-smoke-test)
* [6.2 Troubleshooting installation](#62-troubleshooting-installation)
* [6.3 What to do next?](#63-what-to-do-next)
* [7. Installation with MariaDB](#7-installation-with-mariadb)
* [7.1 MariaDB (Rocky Linux)][MariaDB instructions Rocky Linux]
* [7.2. MariaDB (Debian/Ubuntu)][MariaDB instructions Debian]
* [7.3. MySQL (FreeBSD)][MySQL instructions FreeBSD]
* [8. Installation with PostgreSQL](#8-installation-with-postgresql)
* [8.1. PostgreSQL (Rocky Linux)][PostgreSQL instructions Rocky Linux]
* [8.2. PostgreSQL (Debian/Ubuntu)][PostgreSQL instructions Debian]
* [8.3. PostgreSQL (FreeBSD)][PostgreSQL instructions FreeBSD]
* [9. Cleaning up the database][Removing database]
* [9.1. MariaDB and MySQL](#91-mariadb-and-mysql)
* [9.2. PostgreSQL](#92-postgresql)
* [9.3. SQLite](#93-sqlite)
* [10. Optional features](#10-optional-features)
* [10.1. Metrics](#101-metrics)
* [10.2 Global cache](#102-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][Removing database] and
continue with this installation document.
An alternative to installing Zonemaster-Backend is to run it under [Docker]. See [Using the Backend] for run it under Docker.
## 2. Prerequisites
Before installing Zonemaster::Backend, you should [install Zonemaster::Engine
][Zonemaster::Engine installation].
> **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:
```sh
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-Net-Server perl-Parallel-ForkManager perl-Plack 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:
```sh
sudo cpanm --notest Daemon::Control JSON::RPC JSON::Validator Log::Any Log::Any::Adapter::Dispatch Net::IP::XS Plack::Middleware::ReverseProxy Router::Simple Starman
```
For Rocky Linux 8 only, install DBD::SQLite from CPAN as the one in the system packages repository is too old:
```sh
sudo cpanm --notest DBD::SQLite
```
Install Zonemaster::Backend:
```sh
sudo cpanm --notest Zonemaster::Backend
```
Add Zonemaster user (unless it already exists):
```sh
sudo useradd --system --home-dir=/nonexistent --shell=/usr/sbin/nologin --comment="Zonemaster daemon user" zonemaster
```
Install files to their proper locations:
```sh
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 -Z ./zm-rpcapi.service /etc/systemd/system/
sudo install -v -m 644 -Z ./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:
```sh
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][MariaDB instructions Rocky Linux] and
[PostgreSQL][PostgreSQL instructions Rocky Linux].
### 3.3 Database configuration (Rocky Linux)
Create the database tables:
```sh
(cd / && sudo --user=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:
```sh
sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/zonemaster.conf
```
Enable services at boot time and start them:
```sh
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:
```sh
sudo systemctl restart zm-rpcapi
sudo systemctl restart zm-testagent
```
### 3.5 Post-installation (Rocky Linux)
To check if the daemons are running, do:
```sh
sudo systemctl status --no-pager zm-rpcapi
sudo systemctl status --no-pager 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:
```sh
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.*|sl_SI\.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
sl_SI.utf8
sv_SE.utf8
```
Install dependencies available from binary packages:
```sh
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:
```sh
sudo cpanm --notest JSON::Validator
```
Install Zonemaster::Backend:
```sh
sudo cpanm --notest Zonemaster::Backend
```
Add Zonemaster user (unless it already exists):
```sh
sudo useradd -r -c "Zonemaster daemon user" zonemaster
```
Install files to their proper locations:
```sh
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:
```sh
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][MariaDB instructions Debian] and
[PostgreSQL][PostgreSQL instructions Debian].
### 4.3 Database configuration (Debian/Ubuntu)
Create the database tables:
```sh
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:
```sh
sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/zonemaster.conf
```
Enable services at boot time and start them:
```sh
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:
```sh
sudo systemctl restart zm-rpcapi
sudo systemctl restart zm-testagent
```
### 4.5 Post-installation (Debian/Ubuntu)
To check if the daemons are running, do:
```sh
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:
```sh
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:
```sh
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
```
<!-- JSON::Validator requires YAML::PP, but p5-JSON-Validator currently lacks a dependency on p5-YAML-LibYAML -->
Install Zonemaster::Backend:
```sh
cpanm --notest Zonemaster::Backend
```
Unless they already exist, add `zonemaster` user and `zonemaster` group:
```sh
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:
```sh
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:
```sh
sed -i '' '/[[:<:]]database_file[[:>:]]/ s:=.*:= /var/db/zonemaster/db.sqlite:' /usr/local/etc/zonemaster/backend_config.ini
```
Create database directory:
```sh
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][MySQL instructions FreeBSD] and
[PostgreSQL][PostgreSQL instructions FreeBSD].
### 5.3 Database configuration (FreeBSD)
Create the database tables:
```sh
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:
```sh
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:
```sh
service zm_rpcapi restart
service zm_testagent restart
```
### 5.5 Post-installation (FreeBSD)
To check that the running daemons run:
```sh
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.
```sh
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:
```sh
sudo sed -i '/\bengine\b/ s/=.*/= MySQL/' /etc/zonemaster/backend_config.ini
```
> **Note:** See the [backend configuration] documentation for details.
Install database engine:
```sh
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.
```sh
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](#33-database-configuration-rocky-linux)"
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:
```sh
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:
```sh
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.
```sh
sudo mysql -e "CREATE DATABASE zonemaster;"
```
```sh
sudo mysql -e "CREATE USER 'zonemaster'@'localhost' IDENTIFIED BY 'zonemaster';"
```
```sh
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](#43-database-configuration-debianubuntu)"
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:
```sh
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):
```sh
pkg install mysql80-server p5-DBD-mysql
```
```sh
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.
```sh
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](#53-database-configuration-freebsd)"
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:
```sh
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:
```sh
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.
```sh
sudo systemctl start postgresql
sudo --login --user=postgres psql -c "CREATE USER zonemaster WITH PASSWORD 'zonemaster';"
sudo --login --user=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](#33-database-configuration-rocky-linux)"
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:
```sh
sudo sed -i '/\bengine\b/ s/=.*/= PostgreSQL/' /etc/zonemaster/backend_config.ini
```
Install the database engine and Perl bindings:
```sh
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.
```sh
sudo -u postgres psql -c "CREATE USER zonemaster WITH PASSWORD 'zonemaster';"
```
```sh
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](#43-database-configuration-debianubuntu)"
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:
```sh
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:
```sh
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:
```sh
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. `17`.
```sh
pkg install postgresqlXX-server
```
Enable daemon, initiate and start:
```sh
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.
```sh
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](#53-database-configuration-freebsd)"
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:
```sh
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):
```sh
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:
```sh
sudo -u postgres psql -f $(perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")')/cleanup-postgres.sql
```
FreeBSD (as root):
```sh
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][Backend configuration] to
configure the receiver.
The list of metrics is available in the [Telemetry document][metrics].
### 10.1.1 Installation on Rocky Linux
```sh
sudo cpanm --notest Net::Statsd
```
### 10.1.2 Installation on Debian / Ubuntu
```sh
sudo apt install libnet-statsd-perl
```
### 10.1.3 Installation on Freebsd
```sh
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].
[Backend Environment variables]: ../configuration/backend-environment-variables.md
[Backend configuration]: ../configuration/backend.md
[Declaration of prerequisites]: prerequisites.md
[Global cache in Zonemaster-Engine]: ../configuration/global-cache.md
[JSON-RPC API]: ../using/backend/rpcapi-reference.md
[Main Zonemaster repository]: https://github.com/zonemaster/zonemaster/blob/master/README.md
[MariaDB instructions Debian]: #72-mariadb-debianubuntu
[MariaDB instructions Rocky Linux]: #71-mariadb-rocky-linux
[Metrics]: ../using/backend/telemetry.md#metrics
[MySQL instructions FreeBSD]: #73-mysql-freebsd
[Post-installation]: #6-post-installation
[PostgreSQL instructions Debian]: #82-postgresql-debianubuntu
[PostgreSQL instructions FreeBSD]: #83-postgresql-freebsd
[PostgreSQL instructions Rocky Linux]: #81-postgresql-rocky-linux
[Prerequisites section]: #2-prerequisites
[Profiles]: ../configuration/profiles.md
[Removing database]: #9-cleaning-up-the-database
[Upgrade document]: ../upgrading/backend.md
[Using Zonemaster-Backend for batch testing]: ../using/backend/Using-Zonemaster-Backend-for-batch-testing.md
[Using Zonemaster-Backend JSON-RPC API]: ../using/backend/Using-Zonemaster-Backend-JSON-RPC-API.md
[Zonemaster::CLI installation]: zonemaster-cli.md
[Zonemaster::Engine installation]: zonemaster-engine.md
[Zonemaster::Engine]: https://github.com/zonemaster/zonemaster-engine/blob/master/README.md
[Zonemaster::GUI installation]: zonemaster-gui.md
[Zonemaster::LDNS]: https://github.com/zonemaster/zonemaster-ldns/blob/master/README.md
[Docker]: https://en.wikipedia.org/wiki/Docker_(software)
[Using the Backend]: ../using/backend/

200
zonemaster/docs/public/installation/zonemaster-cli.md Normal file
View File

@@ -0,0 +1,200 @@
# Installation: Zonemaster-CLI
## Table of contents
* [Overview](#overview)
* [Prerequisites for CPAN installation](#prerequisites-for-cpan-installation)
* [Local installation](#local-installation)
* [Installation on Rocky Linux](#installation-on-rocky-linux)
* [Installation on Debian and Ubuntu](#installation-on-debian-and-ubuntu)
* [Installation on FreeBSD](#installation-on-freebsd)
* [Post-installation sanity check](#post-installation-sanity-check)
* [Using Zonemaster-CLI](#using-zonemaster-cli)
* [Global cache](#global-cache)
* [What to do next?](#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][Zonemaster::Engine installation], 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:
```sh
sudo dnf install --assumeyes perl-JSON-XS perl-Try-Tiny perl-Test-Deep perl-Mojolicious
```
```sh
sudo cpanm --notest JSON::Validator
```
> Note: Test::Deep and Mojolicious are indirect dependencies. They are dependencies
> of JSON::Validator.
2) Install Zonemaster::CLI
```sh
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
```sh
curl -LOs https://package.zonemaster.net/setup.sh
sudo sh setup.sh
```
2) Install Zonemaster CLI
```sh
sudo apt install zonemaster-cli
```
3) Update configuration of "locale"
```sh
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.*|sl_SI\.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
sl_SI.utf8
sv_SE.utf8
```
#### Installation from CPAN
1) Install dependencies:
```sh
sudo apt-get install locales libmodule-install-perl libtry-tiny-perl libjson-validator-perl
```
2) Install Zonemaster::CLI:
```sh
sudo cpanm --notest Zonemaster::CLI
```
3) Update configuration of "locale"
```sh
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.*|sl_SI\.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
sl_SI.utf8
sv_SE.utf8
```
### Installation on FreeBSD
1) Become root:
```sh
su -l
```
2) Install dependencies available from binary packages:
```sh
pkg install gmake p5-JSON-XS p5-Locale-libintl p5-Try-Tiny p5-JSON-Validator
```
3) Install Zonemaster::CLI:
```sh
cpanm --notest Zonemaster::CLI
```
## Post-installation sanity check
Run the zonemaster-cli command:
```sh
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:
```sh
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][Zonemaster::Backend
installation] and [Zonemaster::GUI installation] instructions.
* For a [JSON-RPC][JSON-RPC API] frontend, follow the [Zonemaster::Backend
installation] instruction.
[Declaration of prerequisites]: prerequisites.md
[Docker]: https://en.wikipedia.org/wiki/Docker_(software)
[Global cache in Zonemaster-Engine]: ../configuration/global-cache.md
[JSON-RPC API]: ../using/backend/rpcapi-reference.md
[Using the CLI]: ../using/cli.md
[Zonemaster::Backend installation]: zonemaster-backend.md
[Zonemaster::Engine installation]: zonemaster-engine.md
[Zonemaster::Engine]: https://github.com/zonemaster/zonemaster-engine/blob/master/README.md
[Zonemaster::GUI installation]: zonemaster-gui.md
[Zonemaster::LDNS]: https://github.com/zonemaster/zonemaster-ldns/blob/master/README.md

195
zonemaster/docs/public/installation/zonemaster-engine.md Normal file
View File

@@ -0,0 +1,195 @@
# Installation: Zonemaster-Engine
## Table of contents
* [Local installation](#local-installation)
* [Installation on Rocky Linux](#installation-on-rocky-linux)
* [Installation on Debian and Ubuntu](#installation-on-debian-and-ubuntu)
* [Installation on FreeBSD](#installation-on-freebsd)
* [Post-installation sanity check](#post-installation-sanity-check)
* [Troubleshooting installation](#troubleshooting-installation)
* [Global cache](#global-cache)
* [What to do next](#what-to-do-next)
## Local installation
### Installation on Rocky Linux
1) Install the [EPEL] repository:
```sh
sudo dnf install --assumeyes epel-release
sudo crb enable
```
2) Enable SHA-1 in the crypto policy:
```sh
sudo tee /etc/crypto-policies/policies/modules/DNSSEC.pmod <<'EOF'
hash@openssl = SHA1+
sign@openssl = RSA-SHA1+
EOF
sudo update-crypto-policies --set DEFAULT:DNSSEC
```
3) Install locales:
```sh
sudo dnf install --assumeyes glibc-all-langpacks
```
4) Install binary packages:
```sh
sudo dnf install --assumeyes cpanminus gcc libidn2-devel openssl-devel perl-Class-Accessor perl-Clone perl-core perl-Devel-CheckLib 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:
```sh
sudo cpanm --notest Email::Valid Locale::PO Log::Any MIME::Base32 Module::Install::XSUtil Net::IP::XS YAML::XS
```
6) Install Zonemaster::LDNS and Zonemaster::Engine:
```sh
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
```sh
sudo apt update && sudo apt upgrade
```
2) Add Zonemaster packages repository to repository list
```sh
curl -LOs https://package.zonemaster.net/setup.sh
sudo sh setup.sh
```
3) Install Zonemaster Engine
```sh
sudo apt install libzonemaster-engine-perl
```
#### Installation from CPAN
1) Upgrade to latest patch level
```sh
sudo apt update && sudo apt upgrade
```
2) Install dependencies from binary packages:
```sh
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.
```sh
sudo cpanm --notest Zonemaster::LDNS Zonemaster::Engine
```
### Installation on FreeBSD
1) Become root:
```sh
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:
```sh
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:
```sh
cpanm --notest --configure-args="--no-internal-ldns" Zonemaster::LDNS
```
7) Install Zonemaster::Engine:
```sh
cpanm --notest Zonemaster::Engine
```
## Post-installation sanity check
Make sure Zonemaster::Engine is properly installed.
```sh
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.
[EPEL]: https://docs.fedoraproject.org/en-US/epel/
[Global cache configuration]: ../configuration/global-cache.md
[JSON-RPC API]: ../using/backend/rpcapi-reference.md
[Zonemaster::Backend installation]: zonemaster-backend.md
[Zonemaster::CLI installation]: zonemaster-cli.md
[Zonemaster::Engine API]: https://metacpan.org/pod/Zonemaster::Engine
[Zonemaster::GUI installation]: zonemaster-gui.md

284
zonemaster/docs/public/installation/zonemaster-gui.md Normal file
View File

@@ -0,0 +1,284 @@
# Installation: Zonemaster-GUI
## Prerequisites
Before installing Zonemaster-GUI, you should [install Zonemaster::Engine
][Zonemaster::Engine installation] and [Zonemaster::Backend][Zonemaster::Backend
installation].
Prerequisite for FreeBSD is that the package system is updated and activated,
see FreeBSD section of [install Zonemaster::Engine][Zonemaster::Engine
installation].
## Upgrading or installation of custom built Zonemaster-GUI
### Upgrading
If this installation is an upgrade or reinstallation of Zonemaster-GUI and if
changes were made to the shipped configuration files
(`/var/www/html/zonemaster-web-gui/dist/config.json` and the `zonemaster.conf`
Apache configuration file), make sure to back up these files beforehand.
You should also consider saving the old version under a new path instead of
just removing it.
Else upgrading is as simple as removing the old version and installing the new
version in the same way as a new installation.
### Installing a custom built Zonemaster-GUI
If you have done a custom build of Zonemaster-GUI following the instructions in
[building GUI] you will have a zip file that you will use instead of downloading
it from GitHub. Else you can follow the instructions below.
## Installation
This instruction covers the following operating systems:
1. [Rocky Linux](#1-rocky-linux)
2. [Debian and Ubuntu](#2-debian-and-ubuntu)
3. [FreeBSD](#3-freebsd)
### 1. Rocky Linux
#### Install Apache
```sh
sudo dnf update
sudo dnf -y install httpd unzip
```
#### Remove old Zonemaster-GUI
If an old version is installed, remove it first:
```sh
sudo rm -r /var/www/html/zonemaster-web-gui
```
#### Install Zonemaster-GUI
```sh
curl -L -O https://github.com/zonemaster/zonemaster-gui/releases/download/v5.0.1/zonemaster_web_gui_v5.0.1.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_v5.0.1.zip
rm -f zonemaster_web_gui_v5.0.1.zip
```
#### Configure Apache site
```sh
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.
```sh
sudoedit /etc/httpd/conf.d/zonemaster.conf
```
#### Start Apache and allow remote access
```sh
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
```sh
sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y apache2 unzip
```
#### Basic Apache configuration
```sh
sudo a2enmod proxy proxy_http rewrite
sudo a2dissite 000-default
sudo systemctl enable apache2
sudo systemctl restart apache2
```
#### Remove old Zonemaster-GUI
If an old version is installed, remove it first:
```sh
sudo rm -r /var/www/html/zonemaster-web-gui
```
#### Install Zonemaster-GUI
```sh
wget https://github.com/zonemaster/zonemaster-gui/releases/download/v5.0.1/zonemaster_web_gui_v5.0.1.zip -O zonemaster_web_gui_v5.0.1.zip
sudo unzip -d /var/www/html/zonemaster-web-gui zonemaster_web_gui_v5.0.1.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_v5.0.1.zip
```
#### Configure Zonemaster-GUI
```sh
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
```sh
sudo systemctl reload apache2
```
### 3. FreeBSD
For all commands below become root:
```sh
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].
```sh
pkg install apache24
```
#### Enable Apache as a service
```sh
sysrc apache24_enable=yes
```
#### Enable three apache modules in Apache configuration file
```sh
perl -pi -e 's/^#(LoadModule (proxy_module|proxy_http_module|rewrite_module) libexec)/$1/' /usr/local/etc/apache24/httpd.conf
```
#### Start Apache
```sh
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.
#### Remove old Zonemaster-GUI
If an old version is installed, remove it first:
```sh
rm -r /var/www/html/zonemaster-web-gui
```
#### Install Zonemaster-GUI
```sh
fetch https://github.com/zonemaster/zonemaster-gui/releases/download/v5.0.1/zonemaster_web_gui_v5.0.1.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_v5.0.1.zip
rm zonemaster_web_gui_v5.0.1.zip
```
#### Basic Apache configuration
```sh
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
```sh
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-GUI).
2. Verify that the Zonemaster-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] or providers of public certificates.
## Configuring and customizing GUI
It is possible to change the behavior and visual aspects of GUI. See
section [configuring GUI] for how to customize the GUI.
[building GUI]: ../configuration/gui/building-custom-gui.md
[JSON-RPC API]: ../using/backend/rpcapi-reference.md
[Let's Encrypt / Certbot]: https://certbot.eff.org/instructions
[Main Zonemaster repository]: https://github.com/zonemaster/zonemaster/blob/master/README.md
[Tutorial on Apache on FreeBSD]: https://www.digitalocean.com/community/tutorials/how-to-install-an-apache-mysql-and-php-famp-stack-on-freebsd-10-1
[Zonemaster::Backend installation]: zonemaster-backend.md
[Zonemaster::Backend]: https://github.com/zonemaster/zonemaster-backend/blob/master/README.md
[Zonemaster::CLI installation]: zonemaster-cli.md
[Zonemaster::Engine API]: https://metacpan.org/dist/Zonemaster-Engine/view/lib/Zonemaster/Engine/Overview.pod
[Zonemaster::Engine installation]: zonemaster-engine.md
[Zonemaster::Engine]: https://github.com/zonemaster/zonemaster-engine/blob/master/README.md
[Zonemaster::LDNS]: https://github.com/zonemaster/zonemaster-ldns/blob/master/README.md
[Configuring GUI]: ../configuration/gui/README.md

149
zonemaster/docs/public/installation/zonemaster-ldns.md Normal file
View File

@@ -0,0 +1,149 @@
# 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.
```sh
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<Encode>.
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.
#### 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
```sh
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
```sh
TEST_WITH_NETWORK=1 make test
```
[Docker Hub]: https://hub.docker.com/u/zonemaster
[Docker Image Creation]: ../../internal/maintenance/ReleaseProcess-create-docker-image.md
[IDN]: #idn
[Installation instructions for Zonemaster::Engine]: zonemaster-engine.md
[Internal LDNS]: #internal-ldns
[Net::LibIDN]: https://metacpan.org/pod/Net::LibIDN
[USING]: ../using/

9
zonemaster/docs/public/specifications/README.md Normal file
View File

@@ -0,0 +1,9 @@
# Specifications
* [Test Cases](tests/README.md): contains the specifications of the *Test Cases*
that the Zonemaster implementation is based on.
* [Test types](test-types/README.md): contains the specification of *Test Types*,
currently only for undelegated tests.
* [Test zones](test-zones/README.md): contains the specifications of *Test Zones*
for the verification of Test Case implementation.

7
zonemaster/docs/public/specifications/test-types/README.md Normal file
View File

@@ -0,0 +1,7 @@
# Test Types
This directory contains **Test Type** specifications, currently only
specification for undelegated tests.
* [undelegated-test.md](undelegated-test.md)

48
zonemaster/docs/public/specifications/test-types/undelegated-test.md Normal file
View File

@@ -0,0 +1,48 @@
# 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.

8
zonemaster/docs/public/specifications/test-zones/Address-TP/README.md Normal file
View File

@@ -0,0 +1,8 @@
# Specification of test scenarios for Address-TP
Test scenario specifications are available for:
* Address01 *not yet available*
* Address02 *not yet available*
* [Address03](address03.md)

216
zonemaster/docs/public/specifications/test-zones/Address-TP/address01.md Normal file
View File

@@ -0,0 +1,216 @@
# Specification of test scenarios for ADDRESS01
## Table of contents
* [Background](#background)
* [Test Case](#test-case)
* [Test scenarios](#test-scenarios)
* [Test zone names](#test-zone-names)
* [Test scenarios and message tags](#test-scenarios-and-message-tags)
* [Zone setup for test scenarios]
## Background
See the [test zone README file].
## Test Case
This document specifies defined test scenarios for test case [ADDRESS01].
## Test scenarios
The purpose of the test scenarios is to cover all reasonable contexts where
different message tags are outputted when [ADDRESS01] is run on a test zone.
The message tags are defined in the test case ([ADDRESS01]) 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 (`address01.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.
- A01_ADDR_NOT_GLOBALLY_REACHABLE
- A01_DOCUMENTATION_ADDR
- A01_GLOBALLY_REACHABLE_ADDR
- A01_LOCAL_USE_ADDR
- A01_NO_GLOBALLY_REACHABLE_ADDR
- A01_NO_NAME_SERVERS_FOUND
## 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.
| Scenario name | Mandatory message tag | Forbidden message tags |
|:--------------------|:------------------------------------------------------------------------------------------------------------|:-----------------------|
| GOOD-1 | A01_GLOBALLY_REACHABLE_ADDR | 2) |
| MIXED-LOCAL-DOC-1 | A01_LOCAL_USE_ADDR, A01_DOCUMENTATION_ADDR, A01_GLOBALLY_REACHABLE_ADDR | 2) |
| MIXED-LOCAL-DOC-2 | A01_LOCAL_USE_ADDR, A01_DOCUMENTATION_ADDR, A01_GLOBALLY_REACHABLE_ADDR | 2) |
| MIXED-LOCAL-OTHER-1 | A01_LOCAL_USE_ADDR, A01_ADDR_NOT_GLOBALLY_REACHABLE, A01_GLOBALLY_REACHABLE_ADDR | 2) |
| MIXED-LOCAL-OTHER-2 | A01_LOCAL_USE_ADDR, A01_ADDR_NOT_GLOBALLY_REACHABLE, A01_GLOBALLY_REACHABLE_ADDR | 2) |
| MIXED-DOC-OTHER-1 | A01_DOCUMENTATION_ADDR, A01_ADDR_NOT_GLOBALLY_REACHABLE, A01_GLOBALLY_REACHABLE_ADDR | 2) |
| MIXED-DOC-OTHER-2 | A01_DOCUMENTATION_ADDR, A01_ADDR_NOT_GLOBALLY_REACHABLE, A01_GLOBALLY_REACHABLE_ADDR | 2) |
| MIXED-ALL-1 | A01_ADDR_NOT_GLOBALLY_REACHABLE, A01_DOCUMENTATION_ADDR, A01_LOCAL_USE_ADDR, A01_GLOBALLY_REACHABLE_ADDR | 2) |
| MIXED-ALL-2 | A01_ADDR_NOT_GLOBALLY_REACHABLE, A01_DOCUMENTATION_ADDR, A01_LOCAL_USE_ADDR, A01_GLOBALLY_REACHABLE_ADDR | 2) |
| ALL-NON-REACHABLE | A01_ADDR_NOT_GLOBALLY_REACHABLE, A01_LOCAL_USE_ADDR, A01_DOCUMENTATION_ADDR, A01_NO_GLOBALLY_REACHABLE_ADDR | 2) |
| NO_NAME_SERVERS | A01_NO_NAME_SERVERS_FOUND | 2) |
* (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 `SCENARIO.address01.xa`.
* There is no zone file or zone data for the child zone.
* For each scenario zone there are two NS records (ns\[1-2]).
* All NS are in-bailiwick
* All NS have both IPv4 and IPv6 addresses
* All required glue are present in the delegation.
* EDNS, version 0, is included in all responses on queries with EDNS.
* EDNS is not included in responses on queries without EDNS.
| Address designation | Meaning |
|:-----------------------|:------------------------------------------------------------------------------------------------------|
| OK | Globally routable, public IPv4 address or global IPv6 address (not from any special purpose registry) |
| OK_SPECIAL | Globally routable IPv4 or IPv6 address from one of the special purpose registries |
| LOCAL_USE_ADDR | Address part of range used for private networks (loopback, RFC1918, Provider shared, etc.) |
| DOCUMENTATION_ADDR | Address part of range used for documentation purposes |
| NOT_GLOBALLY_REACHABLE | Address part of any other range listed as not globally reachable |
Designations are based on the address block ranges from the
[Special purpose IPv4 addresses] and [Special purpose IPv6 addresses] registries.
### GOOD-1
The "happy path". Everything is fine.
* Zone: good-1.address01.xa
* ns1
* IPv4 address OK
* IPv6 address OK
* ns2
* IPv4 address OK_SPECIAL
* IPv6 address OK_SPECIAL
### MIXED-LOCAL-DOC-1
* Zone: mixed-local-doc-1.address01.xa
* ns1
* IPv4 address LOCAL_USE_ADDR
* IPv6 address OK
* ns2
* IPv4 address OK
* IPv6 address DOCUMENTATION_ADDR
### MIXED-LOCAL-DOC-2
* Zone: mixed-local-doc-2.address01.xa
* ns1
* IPv4 address DOCUMENTATION_ADDR
* IPv6 address OK
* ns2
* IPv4 address OK
* IPv6 address LOCAL_USE_ADDR
### MIXED-DOC-OTHER-1
* Zone: mixed-doc-other-1.address01.xa
* ns1
* IPv4 address DOCUMENTATION_ADDR
* IPv6 address OK
* ns2
* IPv4 address OK
* IPv6 address NOT_GLOBALLY_REACHABLE
### MIXED-DOC-OTHER-2
* Zone: mixed-doc-other-2.address01.xa
* ns1
* IPv4 address NOT_GLOBALLY_REACHABLE
* IPv6 address OK
* ns2
* IPv4 address OK
* IPv6 address DOCUMENTATION_ADDR
### MIXED-LOCAL-OTHER-1
* Zone: mixed-local-other-1.address01.xa
* ns1
* IPv4 address LOCAL_USE_ADDR
* IPv6 address OK
* ns2
* IPv4 address OK
* IPv6 address NOT_GLOBALLY_REACHABLE
### MIXED-LOCAL-OTHER-2
* Zone: mixed-local-other-2.address01.xa
* ns1
* IPv4 address NOT_GLOBALLY_REACHABLE
* IPv6 address OK
* ns2
* IPv4 address OK
* IPv6 address LOCAL_USE_ADDR
### MIXED-ALL-1
* Zone: mixed-all-1.address01.xa
* ns1
* IPv4 address LOCAL_USE_ADDR
* IPv6 address OK
* ns2
* IPv4 address DOCUMENTATION_ADDR
* IPv6 address NOT_GLOBALLY_REACHABLE
### MIXED-ALL-2
* Zone: mixed-all-2.address01.xa
* ns1
* IPv4 address NOT_GLOBALLY_REACHABLE
* IPv6 address LOCAL_USE_ADDR
* ns2
* IPv4 address OK
* IPv6 address DOCUMENTATION_ADDR
### ALL-NON-REACHABLE
All addresses of all nameservers falls within one of the address blocks listed
as not globally reachable. Delegation contains three name servers to cover all
combinations of defined address block types.
* Zone: all-non-reachable.address01.xa
* ns1
* IPv4 address LOCAL_USE_ADDR
* IPv6 address NOT_GLOBALLY_REACHABLE
* ns2
* IPv4 address DOCUMENTATION_ADDR
* IPv6 address LOCAL_USE_ADDR
+ ns3
* IPv4 address NOT_GLOBALLY_REACHABLE
* IPv6 address DOCUMENTATION_ADDR
### NO_NAME_SERVERS
No delegation for the zone and the zone does not exist.
* Zone: no-name-servers.address01.xa
* No delegation
* No zone
[ADDRESS01]: ../../tests/Address-TP/address01.md
[RCODE Name]: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
[Special purpose IPv4 addresses]: https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xml
[Special purpose IPv6 addresses]: https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xml
[Test zone README file]: ../README.md
[Zone setup for test scenarios]: #zone-setup-for-test-scenarios

249
zonemaster/docs/public/specifications/test-zones/Address-TP/address03.md Normal file
View File

@@ -0,0 +1,249 @@
# Specification of Test Scenarios for Address03
## Table of contents
* [Background](#background)
* [Test Case](#test-case)
* [Test scenarios](#test-scenarios)
* [Test zone names](#test-zone-names)
* [All message tags](#all-message-tags)
* [Test scenarios and 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 [Address03].
## Test scenarios
The purpose of the test scenarios is to cover all reasonable contexts where
different message tags are outputted when [Address03] is run on a test zone.
The message tags are defined in the test case ([Address03]) 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 (`address03.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 [Address03] for the specification of the tags.
* NAMESERVER_IP_PTR_MATCH
* NAMESERVER_IP_PTR_MISMATCH
* NAMESERVER_IP_WITHOUT_REVERSE
* NO_RESPONSE_PTR_QUERY
## 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.
| Scenario name | Mandatory message tags | Forbidden message tags |
|:---------------------------|:------------------------------|:----------------------------------------------------|
| ALL-NS-HAVE-PTR-1 | NAMESERVER_IP_PTR_MATCH | 2) |
| ALL-NS-HAVE-PTR-2 | NAMESERVER_IP_PTR_MATCH | 2) |
| NO-NS-HAVE-PTR | NAMESERVER_IP_WITHOUT_REVERSE | 2) |
| INCOMPLETE-PTR-1 | NAMESERVER_IP_WITHOUT_REVERSE | 2) |
| INCOMPLETE-PTR-2 | NAMESERVER_IP_WITHOUT_REVERSE | 2) |
| NON-MATCHING-NAMES | NAMESERVER_IP_PTR_MISMATCH | 2) |
| PTR-IS-GOOD-CNAME-1 | NAMESERVER_IP_PTR_MATCH | 2) |
| PTR-IS-GOOD-CNAME-2 | NAMESERVER_IP_PTR_MATCH | 2) |
| PTR-IS-DANGLING-CNAME | NAMESERVER_IP_WITHOUT_REVERSE | 2) |
| PTR-IS-ILLEGAL-CNAME | NAMESERVER_IP_WITHOUT_REVERSE | NAMESERVER_IP_PTR_MATCH, NAMESERVER_IP_PTR_MISMATCH |
| PTR-RESOLUTION-NO-RESPONSE | NO_RESPONSE_PTR_QUERY | NAMESERVER_IP_PTR_MATCH, NAMESERVER_IP_PTR_MISMATCH |
| PTR-RESOLUTION-SERVFAIL | NO_RESPONSE_PTR_QUERY | NAMESERVER_IP_PTR_MATCH, NAMESERVER_IP_PTR_MISMATCH |
* (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
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.address03.xa`.
* There is a zone file for the child zone.
* The child zone is delegated to two out-of-bailiwick name servers.
* Both name servers have the same content.
* The authoritative name servers for the zone all have an IPv4 and an IPv6
address, and the reverse zones contain a single PTR resource record
matching their names for all of their addresses.
* The NS record set in the child zone is consistent with the parent zone’s
delegation.
* The parent zone is `address03.xa`.
* It is served by two in-bailiwick NS (ns1.address03.xa and
ns2.address03.xa).
* ns1 and ns2 have the same zone content.
* ns1 and ns2 have both IPv4 and IPv6 glue in the delegation of the parent
zone.
* The records matching glue in the zone are identical to the glue records.
* All authoritative name servers for the scenario’s child zones have names
matching ns\<NUMBER\>.child.address03.xa. These name servers’s names are
abbreviated by leaving out address03.xa from their names.
* All responses will have the AA bit set.
* All responses will have the [RCODE Name] "NoError".
### ALL-NS-HAVE-PTR-1
A happy path: a zone whose name server IP addresses have single and correct
PTR records.
* Zone: all-ns-have-ptr-1.address03.xa
* Delegated to: ns1.child and ns2.child.
### ALL-NS-HAVE-PTR-2
Another happy path: like ALL-NS-HAVE-PTR-1, but for one of the name servers,
both its IPv4 and IPv6 addresses have multiple PTR records. In each PTR
resource record set, one of the PTR records matches the name server’s name.
* Zone: all-ns-have-ptr-2.address03.xa
* Delegated to: ns1.child and ns3.child.
* ns3.child’s IP addresses have multiple PTR records, among which one points
to ns3.child.
### NO-NS-HAVE-PTR
None of the name server’s IP addresses have PTR records at all. For one of
them, NODATA is returned on PTR query; for the other, NXDOMAIN is returned.
* Zone: no-ns-have-ptr.address03.xa
* Delegated to: ns4.child and ns5.child.
* ns4.child’s IP addresses have no PTR records; the reverse zone is
configured to provoke NODATA responses on PTR queries by making the
expected node an empty non-terminal.
* ns5.child’s IP addresses have no PTR records; the reverse zone is
configured to provoke NXDOMAIN responses on PTR queries.
### INCOMPLETE-PTR-1
For one of the name servers, the PTR record is missing for its IPv4 address.
* Zone: incomplete-ptr-1.address03.xa
* Delegated to: ns1.child and ns6.child.
* ns6.child’s IPv4 address has no PTR record, but its IPv6 address does.
### INCOMPLETE-PTR-2
For one of the name servers, the PTR record is missing for its IPv6 address.
* Zone: incomplete-ptr-2.address03.xa
* Delegated to: ns1.child and ns7.child.
* ns7.child’s IPv4 address has a PTR record, but its IPv6 address does not.
### NON-MATCHING-NAMES
Both name server’s IP addresses have one or more PTR records, but none
matching the name server name.
* Zone: non-matching-names.address03.xa
* Delegated to: ns8.child and ns9.child.
* ns8.child’s IP addresses have a single PTR record, but its hostname in
RDATA is different from the name server’s name.
* ns9.child’s IP addresses have more than one PTR record, and each of them
has a hostname in RDATA different from the name server’s name.
### PTR-IS-GOOD-CNAME-1
The reverse name of one of the name servers’ IP address has an alias (CNAME)
whose target, with a PTR record, is in the same reverse zone.
* Zone: ptr-is-good-cname-1.address03.xa
* Delegated to: ns1.child and ns10.child.
* ns10.child’s IP addresses have reverse names that are aliased (CNAME) to
another name in the same zone. In other words, resolving the PTR resource
records for their IP addresses returns a CNAME resource record and the PTR
record after walking the CNAME chain.
### PTR-IS-GOOD-CNAME-2
The reverse name of one of the name servers’ IP address has an alias (CNAME)
whose target, with a PTR record, is in a different zone.
* Zone: ptr-is-good-cname-2.address03.xa
* Delegated to: ns1.child and ns11.child.
* ns11.child’s IP addresses have reverse names that are aliased (CNAME) to
another name in a different zone. In other words, resolving the PTR
resource records for their IP addresses returns only a CNAME resource
record, and another query for the name at the target of the CNAME resource
record is needed.
### PTR-IS-DANGLING-CNAME
The reverse name of one of the name servers’ IP address has an alias (CNAME)
whose target does not exist.
* Zone: ptr-is-dangling-cname.address03.xa
* Delegated to: ns5.child and ns12.child.
* ns5.child is configured as described in the NO-NS-HAVE-PTR scenario.
* ns12.child’s IP addresses have reverse names that are aliased to a
nonexistent node. In other words, there is a CNAME pointing to a node
that does not exist.
### PTR-IS-ILLEGAL-CNAME
One of the name servers has IP addresses whose reverse names contain more than
one CNAME resource record.
* Zone: ptr-is-illegal-cname.address03.xa
* Delegated to: ns4.child and ns13.child.
* ns4.child is configured as described in the NO-NS-HAVE-PTR scenario.
* ns13.child’s IP addresses have reverse names that give two CNAME
resource records.
Whether or not NO_RESPONSE_PTR_QUERY is allowed to be outputted is
intentionally left unspecified.
### PTR-RESOLUTION-NO-RESPONSE
One of the name servers has IP addresses whose reverse names fail to resolve
because the authoritative name server for the reverse zone does not respond.
One of the name servers’ IP addresses fail to resolve to PTR records because
an attempt at querying corresponding node in the `in-addr.arpa` or `ip6.arpa`
subtrees returns no response.
* Zone: ptr-resolution-no-response.address03.xa
* Delegated to: ns1.child and ns14.child.
* Querying the PTR records for ns14.child’s IP addresses return no response.
Whether or not NAMESERVER_IP_WITHOUT_REVERSE is allowed to be outputted is
intentionally left unspecified.
### PTR-RESOLUTION-SERVFAIL
One of the name servers has IP addresses whose reverse names fail to resolve
because the authoritative name server for the reverse zone gives a response
whose [RCODE Name] is neither "NoError" nor "NXDomain".
* Zone: ptr-resolution-no-response.address03.xa
* Delegated to: ns1.child and ns15.child.
* Querying the PTR records for ns15.child’s IP addresses return a "ServFail"
response.
Whether or not NAMESERVER_IP_WITHOUT_REVERSE is allowed to be outputted is
intentionally left unspecified.
[ADDRESS03]: ../../tests/Address-TP/address03.md
[RCODE Name]: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
[test scenario README file]: ../README.md
[Test scenarios and setup of test zones]: #test-scenarios-and-setup-of-test-zones

7
zonemaster/docs/public/specifications/test-zones/Basic-TP/README.md Normal file
View File

@@ -0,0 +1,7 @@
# Specification of test scenarios for Basic-TP
Test scenario specifications are available for:
* [Basic01](basic01.md)
* [Basic02](basic02.md)
* Basic03 *not yet available*

502
zonemaster/docs/public/specifications/test-zones/Basic-TP/basic01.md Normal file
View File

@@ -0,0 +1,502 @@
# Specification of test zones for Basic01
## Table of contents
* [Background](#background)
* [Test Case](#test-case)
* [Test scenarios](#test-scenarios)
* [Test zone names](#test-zone-names)
* [Test scenarios and message tags](#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.
Scenario name | Mandatory message tag | Forbidden message tags
:-------------------------|:----------------------------------------------------------------------------------|:----------------------
GOOD-1 | B01_CHILD_FOUND, B01_PARENT_FOUND | 2)
GOOD-MIXED-1 | B01_CHILD_FOUND, B01_PARENT_FOUND | 2)
GOOD-MIXED-2 | B01_CHILD_FOUND, B01_PARENT_FOUND | 2)
GOOD-PARENT-HOST-1 | B01_CHILD_FOUND, B01_PARENT_FOUND | 2)
GOOD-GRANDPARENT-HOST-1 | B01_CHILD_FOUND, B01_PARENT_FOUND | 2)
GOOD-UNDEL-1 | B01_CHILD_FOUND, B01_PARENT_DISREGARDED | 2)
GOOD-MIXED-UNDEL-1 | B01_CHILD_FOUND, B01_PARENT_DISREGARDED | 2)
GOOD-MIXED-UNDEL-2 | B01_CHILD_FOUND, B01_PARENT_DISREGARDED | 2)
NO-DEL-UNDEL-1 | B01_CHILD_FOUND, B01_PARENT_DISREGARDED | 2)
NO-DEL-MIXED-UNDEL-1 | B01_CHILD_FOUND, B01_PARENT_DISREGARDED | 2)
NO-DEL-MIXED-UNDEL-2 | B01_CHILD_FOUND, B01_PARENT_DISREGARDED | 2)
NO-CHILD-1 | B01_NO_CHILD, B01_PARENT_FOUND | 2)
NO-CHILD-2 | B01_NO_CHILD, B01_PARENT_FOUND | 2)
NO-CHLD-PAR-UNDETER-1 | B01_NO_CHILD, B01_PARENT_FOUND, B01_PARENT_UNDETERMINED | 2)
CHLD-FOUND-PAR-UNDET-1 | B01_CHILD_FOUND, B01_PARENT_FOUND, B01_PARENT_UNDETERMINED | 2)
CHLD-FOUND-INCONSIST-1 | B01_CHILD_FOUND, B01_INCONSISTENT_DELEGATION, B01_PARENT_FOUND | 2)
CHLD-FOUND-INCONSIST-2 | B01_CHILD_FOUND, B01_INCONSISTENT_DELEGATION, B01_PARENT_FOUND | 2)
CHLD-FOUND-INCONSIST-3 | B01_CHILD_FOUND, B01_INCONSISTENT_DELEGATION, B01_PARENT_FOUND | 2)
CHLD-FOUND-INCONSIST-4 | B01_CHILD_IS_ALIAS, B01_CHILD_FOUND, B01_INCONSISTENT_DELEGATION, B01_PARENT_FOUND| 2)
CHLD-FOUND-INCONSIST-5 | B01_CHILD_FOUND, B01_INCONSISTENT_DELEGATION, B01_PARENT_FOUND | 2)
CHLD-FOUND-INCONSIST-6 | B01_CHILD_FOUND, B01_INCONSISTENT_DELEGATION, B01_PARENT_FOUND | 2)
CHLD-FOUND-INCONSIST-7 | B01_CHILD_FOUND, B01_INCONSISTENT_DELEGATION, B01_PARENT_FOUND | 2)
CHLD-FOUND-INCONSIST-8 | B01_CHILD_FOUND, B01_INCONSISTENT_DELEGATION, B01_PARENT_FOUND | 2)
CHLD-FOUND-INCONSIST-9 | B01_CHILD_IS_ALIAS, B01_CHILD_FOUND, B01_INCONSISTENT_DELEGATION, B01_PARENT_FOUND| 2)
CHLD-FOUND-INCONSIST-10 | B01_CHILD_FOUND, B01_INCONSISTENT_DELEGATION, B01_PARENT_FOUND | 2)
NO-DEL-UNDEL-NO-PAR-1 | B01_CHILD_FOUND, B01_PARENT_DISREGARDED | 2)
NO-DEL-UNDEL-PAR-UND-1 | B01_CHILD_FOUND, B01_PARENT_DISREGARDED | 2)
NO-CHLD-NO-PAR-1 | B01_NO_CHILD, B01_PARENT_NOT_FOUND, B01_SERVER_ZONE_ERROR | 2)
CHILD-ALIAS-1 | B01_CHILD_IS_ALIAS, B01_NO_CHILD, B01_PARENT_FOUND | 2)
CHILD-ALIAS-2 | B01_CHILD_IS_ALIAS, B01_NO_CHILD, B01_INCONSISTENT_ALIAS, B01_PARENT_FOUND | 2)
ZONE-ERR-GRANDPARENT-1 | B01_CHILD_FOUND, B01_PARENT_FOUND, B01_SERVER_ZONE_ERROR | 2)
ZONE-ERR-GRANDPARENT-2 | B01_CHILD_FOUND, B01_PARENT_FOUND, B01_SERVER_ZONE_ERROR | 2)
ZONE-ERR-GRANDPARENT-3 | B01_CHILD_FOUND, B01_PARENT_FOUND, B01_SERVER_ZONE_ERROR | 2)
ROOT-ZONE | B01_CHILD_FOUND, B01_ROOT_HAS_NO_PARENT | 2)
* (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.
[Basic01]: ../../tests/Basic-TP/basic01.md
[RCODE Name]: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
[Test zone README file]: ../README.md
[Zone setup for test scenarios]: #zone-setup-for-test-scenarios

416
zonemaster/docs/public/specifications/test-zones/Basic-TP/basic02.md Normal file
View File

@@ -0,0 +1,416 @@
# Specification of Test Scenarios for Basic02
## Table of contents
* [Background](#background)
* [Test Case](#test-case)
* [Test scenarios](#test-scenarios)
* [Test zone names](#test-zone-names)
* [All message tags](#all-message-tags)
* [Test scenarios and message tags](#test-scenarios-and-message-tags)
* [Test scenarios and setup of test zones](#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 [Basic02].
## Test scenarios
The purpose of the test scenarios is to cover all reasonable contexts where
different message tags are outputted when [Basic02] is run on a test zone.
The message tags are defined in the test case ([Basic02]) 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 (`basic02.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 [Basic02] for the specification of the tags.
* B02_AUTH_RESPONSE_SOA
* B02_NO_DELEGATION
* B02_NO_WORKING_NS
* B02_NS_BROKEN
* B02_NS_NOT_AUTH
* B02_NS_NO_IP_ADDR
* B02_NS_NO_RESPONSE
* B02_UNEXPECTED_RCODE
## 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.
Scenario name | Mandatory message tag | Forbidden message tags
:------------------------------|:-------------------------------------------|:----------------------
GOOD-1 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-2 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-1 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-2 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-3 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-4 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-5 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-6 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-7 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-8 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-9 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-10 | B02_AUTH_RESPONSE_SOA | 2)
GOOD-UNDEL-11 | B02_AUTH_RESPONSE_SOA | 2)
MIXED-1 | B02_AUTH_RESPONSE_SOA | 2)
NO-DELEGATION-1 | B02_NO_DELEGATION | 2)
NS-BROKEN-1 | B02_NS_BROKEN, B02_NO_WORKING_NS | 2)
NS-NOT-AUTH-1 | B02_NS_NOT_AUTH, B02_NO_WORKING_NS | 2)
NS-NO-IP-1 | B02_NS_NO_IP_ADDR, B02_NO_WORKING_NS | 2)
NS-NO-IP-2 | B02_NS_NO_IP_ADDR, B02_NO_WORKING_NS | 2)
NS-NO-IP-3 | B02_NS_NO_IP_ADDR, B02_NO_WORKING_NS | 2)
NS-NO-IP-UNDEL-1 | B02_NS_NO_IP_ADDR, B02_NO_WORKING_NS | 2)
NS-NO-IP-UNDEL-2 | B02_NS_NO_IP_ADDR, B02_NO_WORKING_NS | 2)
NS-NO-RESPONSE-1 | B02_NS_NO_RESPONSE, B02_NO_WORKING_NS | 2)
UNEXPECTED-RCODE-1 | B02_UNEXPECTED_RCODE, B02_NO_WORKING_NS | 2)
* (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.
`basic02.xb` is a zone for out-of-bailiwick name servers for applicable
scenario.
* The child zone is `SCENARIO.basic02.xa`.
* It is delegated to two name servers, `ns1.SCENARIO.basic02.xa`
and `ns2.SCENARIO.basic02.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.
* All responses will have the AA bit set.
* All responses will have the [RCODE Name] "NoError".
* NS and any glue matches NS and authoritative address records in zone.
* If NS are out of bailiwick, the names are defined in another zone with correct
A and AAAA records.
### GOOD-1
A "happy path". Everything is fine.
* Zone: good-1.basic02.xa
* Zone is set up as default.
### GOOD-2
Like GOOD-1 but name servers are out-of-bailiwick.
* Zone: good-1.basic02.xa
* ns1 is ns1.good-2.basic02.xb.
* ns2 is ns2.good-2.basic02.xb.
* Delegation is without glue.
### Overview of the GOOD-UNDEL-x scenarios
Scenario name | Delegated zone | Undelegated data
:--------------|:------------------------------|:--------------------
GOOD-UNDEL-1 | no delegation | IB with glue
GOOD-UNDEL-2 | no delegation | OOB without glue, NS names are defined
GOOD-UNDEL-3 | IB, no response | OOB without glue, NS names are defined
GOOD-UNDEL-4 | IB, no glue | OOB without glue, NS names are defined
GOOD-UNDEL-5 | IB, no glue | IB with glue
GOOD-UNDEL-6 | OOB, no response | IB with glue
GOOD-UNDEL-7 | OOB, no address records | OOB with glue, NS names are undefined
GOOD-UNDEL-8 | IB, no response | IB, IP redefined
GOOD-UNDEL-9 | OOB, no response | OOB, IP redefined
GOOD-UNDEL-10 | OOB, SERVFAIL/REFUSED | OOB
GOOD-UNDEL-11 | OOB, cannot look addr up | OOB, IP through lookup
### GOOD-UNDEL-1
The zone is not delegated. Undelegated data provides a working zone.
* Zone: good-undel-1.basic02.xa
* The zone is not delegated.
* Else, the zone from undelegated data is set up as default.
* Undelegated data:
* ns1.good-undel-1.basic02.xa/IPv4
* ns1.good-undel-1.basic02.xa/IPv6
* ns2.good-undel-1.basic02.xa/IPv4
* ns2.good-undel-1.basic02.xa/IPv6
### GOOD-UNDEL-2
The zone is not delegated. Undelegated data provides a working zone. NS are
out-of-bailiwick.
* Zone: good-undel-2.basic02.xa
* The zone is not delegated.
* The undelegated data has out-of-bailiwick name servers without glue.
* Normal lookup provides IP addresses for the name server names.
* Else, the zone from undelegated data is set up as default.
* Undelegated data:
* ns1.good-undel-2.basic02.xb
* ns2.good-undel-2.basic02.xb
### GOOD-UNDEL-3
Delegated zone does not respond. There is a working zone from undelegated data.
Those NS are out-of-bailiwick.
* Zone: good-undel-3.basic02.xa
* The name servers in delegation are ns1 and ns2.
* Name servers from delegation do not respond.
* The undelegated data has out-of-bailiwick name servers without glue.
* Normal lookup provides IP addresses for the name server names.
* Else, the zone from undelegated data is set up as default.
* Undelegated data:
* ns3.good-undel-3.basic02.xb
* ns4.good-undel-3.basic02.xb
### GOOD-UNDEL-4
Delegation of zone lacks glue. There is a working zone from undelegated data.
Those NS are out-of-bailiwick.
* Zone: good-undel-4.basic02.xa
* The name servers in delegation are ns1 and ns2.
* There is no glue for ns1 and ns2.
* The undelegated data has out-of-bailiwick name servers without glue.
* Normal lookup provides IP addresses for the name server names.
* Else, the zone from undelegated data is set up as default.
* Undelegated data:
* ns1.good-undel-4.basic02.xb
* ns2.good-undel-4.basic02.xb
### GOOD-UNDEL-5
Delegation of zone lacks glue. There is a working zone from undelegated data.
* Zone: good-undel-5.basic02.xa
* The name servers in delegation ns1 and ns2.
* There is no glue for ns1 and ns2.
* The undelegated data has the same NS names with glue.
* Else, the zone from undelegated data is set up as default.
* Undelegated data:
* ns1.good-undel-5.basic02.xa/IPv4
* ns1.good-undel-5.basic02.xa/IPv6
* ns2.good-undel-5.basic02.xa/IPv4
* ns2.good-undel-5.basic02.xa/IPv6
### GOOD-UNDEL-6
Zone is delegated to out-of-bailiwick NS, but with no response. There is a
working zone from undelegated data.
* Zone: good-undel-6.basic02.xa
* The name servers in delegation are ns1.good-undel-6.basic02.xb and
ns2.good-undel-6.basic02.xb.
* Normal lookup provides IP addresses for the name server names.
* The servers in delegation do not respond.
* The zone from undelegated data is set up as default.
* Undelegated data:
* ns3.good-undel-6.basic02.xa/IPv4
* ns3.good-undel-6.basic02.xa/IPv6
* ns4.good-undel-6.basic02.xa/IPv4
* ns4.good-undel-6.basic02.xa/IPv6
### GOOD-UNDEL-7
Zone is delegated to out-of-bailiwick NS, but with no IP for NS. There is a
working zone from undelegated data, also out-of-bailiwick.
* Zone: good-undel-7.basic02.xa
* The name servers in delegation are ns1.good-undel-7.basic02.xb and
ns2.good-undel-7.basic02.xb.
* ns1 and ns2 are defined, but with no address records.
* The NS in undelegated data use names that are not defined.
* The zone from undelegated data is set up as default.
* Undelegated data:
* ns3.good-undel-7.basic02.xb/IPv4
* ns3.good-undel-7.basic02.xb/IPv6
* ns4.good-undel-7.basic02.xb/IPv4
* ns5.good-undel-7.basic02.xb/IPv6
### GOOD-UNDEL-8
Zone is delegated, but no response from the NS of delegation. There is a working
zone from undelegated data.
* Zone: good-undel-8.basic02.xa
* The name servers in delegation are dns1 and dns2.
* There is no response from dns1 and dns2.
* The NS in undelegated data use the same NS names with other IP addresses.
* Else, the zone from undelegated data is set up as default.
* Undelegated data:
* dns1.good-undel-8.basic02.xa/IPv4
* dns1.good-undel-8.basic02.xa/IPv6
* dns2.good-undel-8.basic02.xa/IPv4
* dns2.good-undel-8.basic02.xa/IPv6
### GOOD-UNDEL-9
Zone is delegated to out-of-bailiwick NS, but with no response. There is a
working zone from undelegated data.
* Zone: good-undel-9.basic02.xa
* The name servers in delegation are dns1.good-undel-9.basic02.xb and
dns2.good-undel-9.basic02.xb.
* Normal lookup provides IP addresses for the name server names.
* The servers in delegation do not respond.
* The NS in undelegated data use the same NS names with other IP addresses.
* The zone from undelegated data is set up as default.
* Undelegated data:
* dns1.good-undel-9.basic02.xb/IPv4
* dns1.good-undel-9.basic02.xb/IPv6
* dns2.good-undel-9.basic02.xb/IPv4
* dns2.good-undel-9.basic02.xb/IPv6
### GOOD-UNDEL-10
Zone is delegated to out-of-bailiwick NS, but with SERVFAIL or REFUSED response.
There is a working zone from undelegated data, also out-of-bailiwick.
* Zone: good-undel-10.basic02.xa
* The name servers in delegation are ns1.good-undel-10.basic02.xb and
ns2.good-undel-10.basic02.xb.
* Normal lookup provides IP addresses for the name server names.
* The servers in delegation respond with SERVFAIL (ns1) or REFUSED (ns2).
* The NS in undelegated data use other IP addresses.
* The zone from undelegated data is set up as default.
* Undelegated data:
* ns3.good-undel-10.basic02.xb/IPv4
* ns3.good-undel-10.basic02.xb/IPv6
* ns4.good-undel-10.basic02.xb/IPv4
* ns4.good-undel-10.basic02.xb/IPv6
### GOOD-UNDEL-11
Zone is delegated to out-of-bailiwick NS whose names are in a zone that is
not reachable (addresses cannot be looked up). There is a working zone from
undelegated data, also out-of-bailiwick.
* Zone: good-undel-11.basic02.xa
* The name servers in delegation are ns1.delegated.good-undel-11.basic02.xb
and ns2.delegated.good-undel-11.basic02.xb.
* Normal lookup fails to provides IP addresses for the name server names
since zone delegated.good-undel-11.basic02.xb cannot be reached.
* delegated.good-undel-11.basic02.xb is delegated to dns1 and dns2 relative
to that domain.
* There is no actual zone for the delegated data (not needed).
* The zone from undelegated data is set up as default.
* The addresses for the NS for the undelegated zone are found via lookup.
* Undelegated data:
* ns3.good-undel-11.basic02.xb
* ns4.good-undel-11.basic02.xb
### MIXED-1
The zone is delegated to four NS, of which ns1 responds correctly, ns2 does
not respond, ns3 returns SERVFAIL and ns4 is not authoritative.
* Zone: mixed-1.basic02.xa
* The zone is set-up as default, but with four NS (ns1-4).
* ns1 gives correct response.
* ns2 does not respond.
* ns3 returns SERVFAIL on all queries.
* ns4 returns all responses with AA flag unset.
### NO-DELEGATION
There is no delegation for the zone.
* Zone: no-delegation.basic02.xa
* No zone.
* No name servers.
* No delegation.
### NS-BROKEN-1
The servers for the zone do not respond with SOA record on SOA query.
* Zone: ns-broken-1.basic02.xa
* No SOA record in response from ns1 and ns2.
* RCODE is NOERROR and AA bit is set.
### NS-NOT-AUTH-1
The servers for the zone do not give authoritative responses.
* Zone: ns-not-auth-1.basic02.xa
* AA bit is unset in responses from ns1 and ns2.
### NS-NO-IP-1
The delegation is without glue.
* Zone: ns-no-ip-1.basic02.xa
* There is no glue in delegation for ns1 and ns2.
* No zone is set up.
### NS-NO-IP-2
The name server are out-of-bailiwick but have no address records.
* Zone: ns-no-ip-2.basic02.xa
* ns1 and ns2 are out-of-bailiwick.
* ns1 is ns1.ns-no-ip-2.basic02.xb.
* ns2 is ns2.ns-no-ip-2.basic02.xb.
* ns1 and ns2 exist as names, but have no address records.
* No zone is set up.
### NS-NO-IP-3
The name server are out-of-bailiwick but the names are not defined.
* Zone: ns-no-ip-3.basic02.xa
* ns1 and ns2 are out-of-bailiwick.
* ns1 is ns1.ns-no-ip-3.basic02.xb.
* ns2 is ns2.ns-no-ip-3.basic02.xb.
* ns1 and ns2 do not exist as names.
* No zone is set up.
### NS-NO-IP-UNDEL-1
The delegated zone works correctly. The undelegated data has in-bailiwick NS
without glue.
* Zone: ns-no-ip-undel-1.basic02.xa
* ns1 and ns2 serves a working zone.
* The undelegated data uses the same NS names but without glue.
* There is no need for a zone for undelegated data.
* Undelegated data:
* ns1.ns-no-ip-undel-1.basic02.xa
* ns2.ns-no-ip-undel-1.basic02.xa
### NS-NO-IP-UNDEL-2
The delegated zone works correctly. The undelegated data has out-of-bailiwick NS
without glue. The NS names have no address records.
* Zone: ns-no-ip-undel-2.basic02.xa
* ns1 and ns2 serves a working zone.
* The undelegated data uses out-of-bailiwick NS.
* NS names exists.
* NS names do not resolve to address records.
* There is no need for a zone for undelegated data.
* Undelegated data:
* ns1.ns-no-ip-undel-2.basic02.xb
* ns2.ns-no-ip-undel-2.basic02.xb
### NS-NO-RESPONSE-1
The name servers do not respond on the queries.
* Zone: ns-no-response-1.basic02.xa
* ns1 and ns2 do not respond to queries.
* No zone is set up.
### UNEXPECTED-RCODE-1
The name servers respond with NXDOMAIN, REFUSED or SERVFAIL on SOA query.
* Zone: unexpected-rcode-1.basic02.xa
* ns1 responds with NXDOMAIN.
* ns2 responds with REFUSED.
* ns3 responds with SERVFAIL.
* No actual zone exists.
[Basic02]: ../../tests/Basic-TP/basic02.md
[test scenario README file]: ../README.md
[RCODE Name]: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
[Test scenarios and setup of test zones]: #test-scenarios-and-setup-of-test-zones

6
zonemaster/docs/public/specifications/test-zones/Connectivity-TP/README.md Normal file
View File

@@ -0,0 +1,6 @@
# Specification of test scenarios for Connectivity-TP
Test scenario specifications are available for:
* [Connectivity04](connectivity04.md)

301
zonemaster/docs/public/specifications/test-zones/Connectivity-TP/connectivity04.md Normal file
View File

@@ -0,0 +1,301 @@
# Specification of Test Scenarios for Connectivity04
## Table of contents
* [Background](#background)
* [Test Case](#test-case)
* [Test scenarios](#test-scenarios)
* [Test zone names](#test-zone-names)
* [All message tags](#all-message-tags)
* [Test scenarios and 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 [Connectivity04].
## Test scenarios
The purpose of the test scenarios is to cover all reasonable contexts where
different message tags are outputted when [Connectivity04] is run on a test zone.
The message tags are defined in the test case ([Connectivity04]) 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 (`connectivity04.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 [Connectivity04] for the specification of the tags.
* CN04_EMPTY_PREFIX_SET
* CN04_ERROR_PREFIX_DATABASE
* CN04_IPV4_DIFFERENT_PREFIX
* CN04_IPV4_SAME_PREFIX
* CN04_IPV4_SINGLE_PREFIX
* CN04_IPV6_DIFFERENT_PREFIX
* CN04_IPV6_SAME_PREFIX
* CN04_IPV6_SINGLE_PREFIX
## 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.
Scenario name | Mandatory message tag | Forbidden message tags
:------------------------|:----------------------------------------------------------------------------------|:--------------------
GOOD-1 | CN04_IPV4_DIFFERENT_PREFIX, CN04_IPV6_DIFFERENT_PREFIX | 2)
GOOD-2 | CN04_IPV4_DIFFERENT_PREFIX | 2)
GOOD-3 | CN04_IPV6_DIFFERENT_PREFIX | 2)
EMPTY-PREFIX-SET-1 | CN04_EMPTY_PREFIX_SET | 2)
EMPTY-PREFIX-SET-2 | CN04_EMPTY_PREFIX_SET | 2)
ERROR-PREFIX-DATABASE-1 | CN04_ERROR_PREFIX_DATABASE | 2)
ERROR-PREFIX-DATABASE-2 | CN04_ERROR_PREFIX_DATABASE | 2)
ERROR-PREFIX-DATABASE-3 | CN04_ERROR_PREFIX_DATABASE | 2)
ERROR-PREFIX-DATABASE-6 | CN04_IPV4_DIFFERENT_PREFIX, CN04_IPV6_DIFFERENT_PREFIX, CN04_ERROR_PREFIX_DATABASE| 2)
ERROR-PREFIX-DATABASE-7 | CN04_ERROR_PREFIX_DATABASE | 2)
ERROR-PREFIX-DATABASE-8 | CN04_ERROR_PREFIX_DATABASE | 2)
HAS-NON-ASN-TXT-1 | CN04_IPV4_DIFFERENT_PREFIX, CN04_IPV6_DIFFERENT_PREFIX | 2)
HAS-NON-ASN-TXT-2 | CN04_EMPTY_PREFIX_SET | 2)
IPV4-ONE-PREFIX-1 | CN04_IPV4_SAME_PREFIX, CN04_IPV4_SINGLE_PREFIX | 2)
IPV4-TWO-PREFIXES-1 | CN04_IPV4_SAME_PREFIX, CN04_IPV4_DIFFERENT_PREFIX | 2)
IPV6-ONE-PREFIX-1 | CN04_IPV6_SAME_PREFIX, CN04_IPV6_SINGLE_PREFIX | 2)
IPV6-TWO-PREFIXES-1 | CN04_IPV6_SAME_PREFIX, CN04_IPV6_DIFFERENT_PREFIX | 2)
IPV4-SINGLE-NS-1 | CN04_IPV4_SINGLE_PREFIX, CN04_IPV4_DIFFERENT_PREFIX | 2)
IPV6-SINGLE-NS-1 | CN04_IPV6_SINGLE_PREFIX, CN04_IPV6_DIFFERENT_PREFIX | 2)
DOUBLE-PREFIX-1 | CN04_IPV4_DIFFERENT_PREFIX, CN04_IPV6_DIFFERENT_PREFIX | 2)
DOUBLE-PREFIX-2 | CN04_IPV4_DIFFERENT_PREFIX, CN04_IPV6_DIFFERENT_PREFIX | 2)
* (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.connectivity04.xa`.
* It is delegated to out-of-bailiwick NS, specified per scenario.
* The names of the NS exist in the parent zone.
* The NS for a child will only reply to NS query and do that
consistently.
* The parent zone is `connectivity04.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.
* All responses will have the [RCODE Name] "NoError".
### GOOD-1
Everything is fine.
* Zone: good-1.connectivity04.xa
* 2 NS.
* Both with IPv4 and IPv6.
* Each NS IP in different prefixes.
### GOOD-2
Everything is fine. IPv4 only.
* Zone: good-2.connectivity04.xa
* 2 NS.
* IPv4 only.
* Each NS IP in different prefixes.
### GOOD-3
Everything is fine. IPv6 only.
* Zone: good-3.connectivity04.xa
* 2 NS.
* IPv4 only.
* Each NS IP in different prefixes.
### EMPTY-PREFIX-SET-1
No ASN data (NXDOMAIN).
* Zone: empty-prefix-set-1.connectivity04.xa
* 1 NS.
* IPv4 and IPv6 on NS.
* The ASN-lookup returns [RCODE Name] NXDOMAIN.
### EMPTY-PREFIX-SET-2
No ASN data (NODATA).
* Zone: empty-prefix-set-2.connectivity04.xa
* 1 NS.
* IPv4 and IPv6 on NS.
* The ASN-lookup returns no TXT record (NODATA).
### ERROR-PREFIX-DATABASE-1
No ASN data due to SERVFAIL.
* Zone: error-prefix-database-1.connectivity04.xa
* 1 NS.
* IPv4 and IPv6 on NS.
* The ASN-lookup returns SERVFAIL.
### ERROR-PREFIX-DATABASE-2
No ASN data due to REFUSED.
* Zone: error-prefix-database-2.connectivity04.xa
* 1 NS.
* IPv4 and IPv6 on NS.
* The ASN-lookup returns REFUSED.
### ERROR-PREFIX-DATABASE-3
No ASN data, no DNS response at all.
* Zone: error-prefix-database-3.connectivity04.xa
* 1 NS.
* IPv4 and IPv6 on NS.
* The ASN-lookup returns no DNS response (no response at all).
### ERROR-PREFIX-DATABASE-4
(Renamed)
### ERROR-PREFIX-DATABASE-5
(Renamed)
### ERROR-PREFIX-DATABASE-6
Extra ASN lookup TXT record with wrong IP prefix.
* Zone: error-prefix-database-6.connectivity04.xa
* 2 NS.
* Both with IPv4 and IPv6.
* Each NS IP in different prefixes.
* For one NS (both IPs) the ASN lookup returns an extra TXT with an IP prefix
that does not match the IP address.
### ERROR-PREFIX-DATABASE-7
ASN lookup TXT record with wrong IP prefix.
* Zone: error-prefix-database-7.connectivity04.xa
* 1 NS.
* IPv4 and IPv6 on NS.
* The ASN-lookup returns one TXT record for both IP with an IP prefix that
does not match the IP address.
### ERROR-PREFIX-DATABASE-8
ASN lookup gives no TXT-record but a CNAME.
* Zone: error-prefix-database-8.connectivity04.xa
* 1 NS.
* IPv4 and IPv6 on NS.
* The ASN-lookup returns no TXT record for both IP but a CNAME record.
### HAS-NON-ASN-TXT-1
IPv4 and IPv6. Extra non-ASN lookup TXT record.
* Zone: has-non-asn-txt-1.connectivity04.xa
* 2 NS.
* Both NS with IPv4 and IPv6.
* Each NS IP in different prefixes.
* For one NS (both IPs) the ASN lookup returns an extra TXT record with the
text "This is not ASN data".
### HAS-NON-ASN-TXT-2
No ASN data, some other TXT record.
* Zone: has-non-asn-txt-2.connectivity04.xa
* 1 NS.
* IPv4 and IPv6 on NS.
* The ASN-lookup returns one TXT record for both IP with the string
"This is not ASN data".
### IPV4-ONE-PREFIX-1
All NS IPs in the same prefix. IPv4 only.
* Zone: ipv4-one-prefix-1.connectivity04.xa
* 2 NS.
* IPv4 only.
* Both NS in the same prefix.
### IPV4-TWO-PREFIXES-1
Two NS in the same prefix. One NS in its own prefix. IPv4 only.
* Zone: ipv4-two-prefixes-1.connectivity04.xa
* 3 NS.
* IPv4 only.
* Two NS in the same prefix.
* One NS in its own prefix.
### IPV6-ONE-PREFIX-1
All NS IPs in the same prefix. IPv6 only.
* Zone: ipv6-one-prefix-1.connectivity04.xa
* 2 NS.
* Ipv6 only.
* Both NS in the same prefix.
### IPV6-TWO-PREFIXES-1
Two NS in the same prefix. One NS in its own prefix. IPv6 only.
* Zone: ipv6-two-prefixes-1.connectivity04.xa
* 3 NS.
* IPv6 only.
* Two NS in the same prefix.
* One NS in its own prefix.
### IPV4-SINGLE-NS-1
One NS, IPv4 only.
* Zone: ipv4-single-ns-1.connectivity04.xa
* 1 NS.
* IPv4 only.
### IPV6-SINGLE-NS-1
One NS, IPv6 only.
* Zone: ipv6-single-ns-1.connectivity04.xa
* 1 NS.
* IPv6 only.
### DOUBLE-PREFIX-1
The IP addresses of the NS are announced from both a larger prefix and a more
specific one.
* Zone: double-prefix-1.connectivity04.xa
* 2 NS
* IPv4 and IPv6.
* The two IPv4 addresses are announced in one large (less specific) prefix that includes
both NS IP addresses.
* Each NS IP address is also announced in a more specific prefix only including
that IP address.
* Same with IPv6.
### DOUBLE-PREFIX-2
The IP addresses of the NS are announced in a larger (less specific) prefix that
includes both NS IP. The addresses of one NS are also announced in more
specific prefixes.
* Zone: double-prefix-2.connectivity04.xa
* 2 NS
* IPv4 and IPv6.
* The two IPv4 addresses are announced in one large (less specific) prefix that
includes both IP addresses.
* The address of one of the NS is also announced in a more specific prefix.
* Same with IPv6.
[Connectivity04]: ../../tests/Connectivity-TP/connectivity04.md
[RCODE Name]: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
[Test scenario README file]: ../README.md
[Test scenarios and setup of test zones]: #test-scenarios-and-setup-of-test-zones

7
zonemaster/docs/public/specifications/test-zones/Consistency-TP/README.md Normal file
View File

@@ -0,0 +1,7 @@
# Specification of test zones for Consistency-TP
Test zone specifications are available for:
* [CONSISTENCY05](consistency05.md)
* [CONSISTENCY06](consistency06.md)

282
zonemaster/docs/public/specifications/test-zones/Consistency-TP/consistency05.md Normal file
View File

@@ -0,0 +1,282 @@
# Specification of test zones for CONSISTENCY05
## Table of contents
* [Background](#background)
* [Test Case](#test-case)
* [Test scenarios](#test-scenarios)
* [Test zone names](#test-zone-names)
* [Test scenarios and message tags](#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.
Scenario name | Mandatory message tag | Forbidden message tags
:-------------------------|:---------------------------------|:-------------------------------------------
ADDRESSES-MATCH-1 | ADDRESSES_MATCH | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE
ADDRESSES-MATCH-2 | ADDRESSES_MATCH | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE
ADDRESSES-MATCH-3 | ADDRESSES_MATCH, CHILD_NS_FAILED | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, NO_RESPONSE
ADDRESSES-MATCH-4 | ADDRESSES_MATCH, CHILD_NS_FAILED | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, NO_RESPONSE
ADDRESSES-MATCH-5 | ADDRESSES_MATCH, NO_RESPONSE | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED
ADDRESSES-MATCH-6 | ADDRESSES_MATCH | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE
ADDRESSES-MATCH-7 | ADDRESSES_MATCH | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE
ADDR-MATCH-DEL-UNDEL-1 | ADDRESSES_MATCH | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE
ADDR-MATCH-DEL-UNDEL-2 | ADDRESSES_MATCH | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE
ADDR-MATCH-NO-DEL-UNDEL-1 | ADDRESSES_MATCH | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE
ADDR-MATCH-NO-DEL-UNDEL-2 | ADDRESSES_MATCH | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE
CHILD-ZONE-LAME-1 | CHILD_ZONE_LAME, NO_RESPONSE | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_NS_FAILED, ADDRESSES_MATCH
CHILD-ZONE-LAME-2 | CHILD_ZONE_LAME, CHILD_NS_FAILED | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, ADDRESSES_MATCH, NO_RESPONSE
IB-ADDR-MISMATCH-1 | IN_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD | OUT_OF_BAILIWICK_ADDR_MISMATCH, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE, ADDRESSES_MATCH
IB-ADDR-MISMATCH-2 | IN_BAILIWICK_ADDR_MISMATCH | OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE, ADDRESSES_MATCH
IB-ADDR-MISMATCH-3 | IN_BAILIWICK_ADDR_MISMATCH, NO_RESPONSE | OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE, ADDRESSES_MATCH
IB-ADDR-MISMATCH-4 | IN_BAILIWICK_ADDR_MISMATCH | OUT_OF_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE, ADDRESSES_MATCH
EXTRA-ADDRESS-CHILD | EXTRA_ADDRESS_CHILD | IN_BAILIWICK_ADDR_MISMATCH, OUT_OF_BAILIWICK_ADDR_MISMATCH, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE, ADDRESSES_MATCH
OOB-ADDR-MISMATCH | OUT_OF_BAILIWICK_ADDR_MISMATCH | IN_BAILIWICK_ADDR_MISMATCH, EXTRA_ADDRESS_CHILD, CHILD_ZONE_LAME, CHILD_NS_FAILED, NO_RESPONSE, ADDRESSES_MATCH
## 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.
[CONSISTENCY05]: ../../tests/Consistency-TP/consistency05.md
[RCODE Name]: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
[Test zone README file]: ../README.md
[Zone setup for test scenarios]: #zone-setup-for-test-scenarios

162
zonemaster/docs/public/specifications/test-zones/Consistency-TP/consistency06.md Normal file
View File

@@ -0,0 +1,162 @@
# Specification of test zones for CONSISTENCY06
## Table of contents
* [Background](#background)
* [Test Case](#test-case)
* [Test scenarios](#test-scenarios)
* [Test zone names](#test-zone-names)
* [Test scenarios and message tags](#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.
Scenario name | Mandatory message tag | Forbidden message tags
:------------------------------|:-------------------------------------|:-------------------------------------------
ONE-SOA-MNAME-1 | ONE_SOA_MNAME | NO_RESPONSE, NO_RESPONSE_SOA_QUERY, MULTIPLE_SOA_MNAMES
ONE-SOA-MNAME-2 | ONE_SOA_MNAME, NO_RESPONSE | NO_RESPONSE_SOA_QUERY, MULTIPLE_SOA_MNAMES
ONE-SOA-MNAME-3 | ONE_SOA_MNAME, NO_RESPONSE_SOA_QUERY | NO_RESPONSE, MULTIPLE_SOA_MNAMES
ONE-SOA-MNAME-4 | ONE_SOA_MNAME, NO_RESPONSE | NO_RESPONSE_SOA_QUERY, MULTIPLE_SOA_MNAMES
MULTIPLE-SOA-MNAMES-1 | MULTIPLE_SOA_MNAMES | NO_RESPONSE, NO_RESPONSE_SOA_QUERY, ONE_SOA_MNAME
MULTIPLE-SOA-MNAMES-2 | MULTIPLE_SOA_MNAMES,NO_RESPONSE | NO_RESPONSE_SOA_QUERY, ONE_SOA_MNAME
MULT-SOA-MNAMES-NO-DEL-UNDEL-1 | MULTIPLE_SOA_MNAMES | NO_RESPONSE, NO_RESPONSE_SOA_QUERY, ONE_SOA_MNAME
MULT-SOA-MNAMES-NO-DEL-UNDEL-2 | MULTIPLE_SOA_MNAMES | NO_RESPONSE, NO_RESPONSE_SOA_QUERY, ONE_SOA_MNAME
NO-RESPONSE | NO_RESPONSE | NO_RESPONSE_SOA_QUERY, MULTIPLE_SOA_MNAMES, ONE_SOA_MNAME
## 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 ns3 equal to ns3
* MNAME in SOA on ns4 equal to ns4
* Undelegated data:
* ns3.mult-soa-mnames-no-del-undel-2.consistency06.xb
* ns4.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.
[CONSISTENCY06]: ../../tests/Consistency-TP/consistency06.md
[RCODE Name]: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
[Test zone README file]: ../README.md
[Zone setup for test scenarios]: #zone-setup-for-test-scenarios

Some files were not shown because too many files have changed in this diff Show More