zonemaster-cli - run Zonemaster tests from the command line
zonemaster-cli zonemaster.net
zonemaster-cli --test=delegation --level=info --no-time zonemaster.net
zonemaster-cli --test=delegation/delegation01 --level=debug zonemaster.net
zonemaster-cli --list_tests
zonemaster-cli is a command-line interface to the Zonemaster test
engine. It takes instructions the user provides as command line arguments,
transforms them into suitable API calls to the engine, runs the test suite
and prints the resulting messages. By default, the messages will be
translated by the engine's translation module, with the corresponding
timestamp and logging level when printed. See the available options
below.
- -h -? --usage --help
- Print the available command line switches, then exit.
- --version
- Print the versions of this program as well as the ones from the underlying
Zonemaster test engine, then exit.
- --level=LEVEL
- Specify the minimum level of a message to be printed. Messages with this
level (or higher) will be printed. The levels are, from highest to lowest:
CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG, DEBUG2 and DEBUG3. The
lowest three levels (DEBUG) add a significant amount of messages to be
shown. They reveal some of the internal workings of the test engine, and
are probably not useful for most users.
Default: NOTICE
- --locale=LOCALE
- Specify which locale to be used by the translation system. If not given,
the translation system itself will look at environment variables to try
and guess. If the requested translation does not exist, it will fallback
to the local locale, and if that doesn't exist either, to English.
- --[no-]json
- Print results as JSON instead of human language.
Default: off
- --[no-]json_stream, --[no-]json-stream
- Stream the results as JSON. Useful to follow the progress in a
machine-readable way.
Default: off
- --[no-]json_translate, --[no-]json-translate
- Deprecated since v2023.1, use --no-raw instead.
For streaming JSON output, include the translated message of
the tag.
- --[no-]raw
- Print messages as raw dumps (message identifiers) instead of translating
them to human language.
- --[no-]time
- Print the timestamp for each message.
Default: on
- --[no-]show_level, --[no-]show-level
- Print the severity level for each message.
Default: on
- --[no-]show_module, --[no-]show-module
- Print the name of the module which produced the message.
Default: off
- --[no-]show_testcase, --[no-]show-testcase
- Print the name of the test case (test case identifier) which produced the
message.
Default: off
- --ns=NAME[/IP]
- Provide information about a nameserver, for undelegated tests. The
argument must be either: (i) a domain name and an IP address, separated by
a single slash character (/), or (ii) only a domain name, in which case a
A and AAAA records lookup for that name is done in the live global DNS
tree (unless overridden by --hints) and from which the results of that
lookup will be used.
This switch can be given multiple times. As long as any of
these switches are present, their aggregated content will be used as the
entirety of the parent-side delegation information.
- --hints=FILENAME
- Name of a root hints file to override the defaults.
- --save=FILENAME
- Write the contents of the accumulated DNS packet cache to a file with the
given name after the testing suite has finished running.
- --restore=FILENAME
- Prime the DNS packet cache with the contents from the file with the given
name before starting the testing suite. The format of the file should be
from one produced by the --save switch.
- --[no-]ipv4
- Allow the sending of IPv4 packets.
Default: on
- --[no-]ipv6
- Allow the sending of IPv6 packets.
Default: on
- --list_tests,
--list-tests
- Print all test cases listed in the test modules, then exit.
- --test=MODULE,
--test=MODULE/TESTCASE
- Limit the testing suite to run only the specified tests. This can be the
name of a testing module, in which case all test cases from that module
will be run, or the name of a module followed by a slash and the name of a
test case (test case identifier) in that module.
- --stop_level=LEVEL,
--stop-level=LEVEL
- Specify the minimum severity level after which the testing suite is
terminated. The levels are, from highest to lowest: CRITICAL, ERROR,
WARNING, NOTICE, INFO, DEBUG, DEBUG2 and DEBUG3.
- --profile=FILE
- Override the Zonemaster Engine default profile data with values from the
given profile JSON file.
- --ds=KEYTAG,ALGORITHM,TYPE,DIGEST
- Provide a DS record for undelegated testing (that is, a test where the
delegating nameserver information is given via --ns switches). The four
pieces of data (keytag, algorithm, type, digest) should be in the same
format they would have in a zone file.
- --[no-]count
- Print a summary, at the end of a run, of the numbers of messages for each
severity level that were logged during the run.
Default: off
- --[no-]progress
- Print an activity indicator ("spinner"). Useful to know that
something is happening during a run.
Default: on (if the process' standard output is a TTY)
- --encoding=ENCODING
- Specify the character encoding that is used for command line arguments.
This will be used to convert non-ASCII names to IDNA format, on which the
testing suite will then be run.
The default value will be taken from the
"LC_CTYPE" environment variable if
possible, and set to UTF-8 if not.
- --nstimes
- Print a summary, at the end of a run, of the times (in milliseconds) the
zone's name servers took to answer.
- --dump_profile,
--dump-profile
- Print the effective profile used in JSON format, then exit.
- --sourceaddr=IPADDR
- Deprecated since v2023.1 (planned removal: v2024.1), use --sourceaddr4
and/or --sourceaddr6 instead.
Specify the source IP address used to send queries. Setting an
IP address not correctly configured on a local network interface causes
cryptic error messages.
- --sourceaddr4=IPADDR
- Specify the source IPv4 address used to send queries. Setting an IPv4
address not correctly configured on a local network interface fails
silently. Can not be combined with --sourceaddr.
- --sourceaddr6=IPADDR
- Specify the source IPv6 address used to send queries. Setting an IPv6
address not correctly configured on a local network interface fails
silently. Can not be combined with --sourceaddr.
- --[no-]elapsed
- Print elapsed time (in seconds) at end of a run.
Default: off
The testing and result analysis performed by Zonemaster Engine is
always guided by a profile. Zonemaster Engine has a default profile with
sensible defaults. Zonemaster CLI allows users to override the default
profile data with values from a profile JSON file with the
"--profile" option. For details on
profiles and how they're respresented in files, see
Zonemaster::Engine::Profile.
If there is a readable file /etc/zonemaster/cli.args (Linux
style), each line in that file will be prepended as an argument on the
command line. If no /etc/zonemaster/cli.args is found (or is not
readable) but /usr/local/etc/zonemaster/cli.args (FreeBSD style) is
found and readable then that file will be used instead. Only one global file
is loaded.
If there is a readable file .zonemaster/cli.args in the
user's home directory, it will be used in the same way even when a global
file has been loaded. Any argument in user's cli.args will override
the same argument in the global config file.
For example, if one would like to by default run with the log
level set to DEBUG and with translation to human-readable messages turned
off, one could put this in the config file:
--raw
--level=DEBUG
Only one argument per line. If the argument has a value there must
be a "=" between argument and value. A line starting with
"#" is a comment. Comments cannot be added on lines with
arguments.
Any arguments actually given on the command line will override
what is in any of the loaded config files.
Calle Dybedahl <calle@init.se> and others from the
Zonemaster project