Skip to content

USING.md

Latest commit

 

History

History
264 lines (198 loc) · 9.02 KB

USING.md

File metadata and controls

264 lines (198 loc) · 9.02 KB
Raw

Using the CLI

Table of contents

Docker or local installation

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

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

Using Docker

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

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

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

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

Local installation

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

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

Invoking the command line tool using Docker

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

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

or

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

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

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

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

Invoking the command line tool using local installation

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

zonemaster-cli zonemaster.net

or

zonemaster-cli zonemaster.net --no-ipv6

More details on the command line tool invocation

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

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

The test and output can be modified with different options:

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

The same test as above with the three options included:

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

To see all available command line options, use the --help command.

zonemaster-cli --help

Using Docker or local installation

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

Test reports

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

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

Translation

In Docker

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

LANG Language
da Danish
en English
fi Finnish
fr French
nb Norwegian
es Spanish
sv Swedish

E.g.:

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

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

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

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

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

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

In local installation

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

LOCALE Language
da_DK.UTF-8 Danish
en_US.UTF-8 English
fi_FI.UTF-8 Finnish
fr_FR.UTF-8 French
nb_NO.UTF-8 Norwegian
es_ES.UTF-8 Spanish
sv_SE.UTF-8 Swedish

E.g.:

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

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

Advanced use

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

Only run specific test cases

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

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

Or all test case in the Connectivity test level:

zonemaster-cli --test Connectivity example.com

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

zonemaster-cli --list_tests

Undelegated test

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

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

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

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