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

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