Arguments for test case messages
Introduction
This document defines arguments. An argument is defined with its name, its
type of value and its usage and formatting. The arguments are primarily used in
a Zonemaster-Engine message, but can also be used in messages output by
Zonemaster-CLI and Zonemaster-Backend. The messages, in the form of msgid
strings, are primarily defined in the Perl modules for the test cases, e.g.
Basic.pm. The arguments are also used in the translated messages, in the form
of msgstr strings, in the PO files, e.g. fr.po and sv.po. When an
argument is used in a message (msgid or msgstr) it is represented by its
name which is put within curly brackets, e.g. as {ns}.
When a message is created or updated only arguments defined in this document should be used. If there is not a defined argument that can be used for the message then a new argument must be defined and this document is to be updated.
Multiple instances of the same argument
In a message the same argument can only be used once. In case a message needs more than one instance of an argument, the instances need to be disambiguated. This is done by adding different suffixes to the argument's name. The suffix is an underscore ("_") followed by a descriptive string of lower case "a-z0-9". The suffixed argument name is not to be listed in this document, it is just an instance of the argument name without the specific suffix.
Example of multiple instances
If two arguments of type "List of IP addresses" are to be used in a message, then
both argument names should be ns_ip_list following the list of defined
arguments below. If the relevant suffixes for those are "nsec" (connected to an
NSEC record type) and "nsec3" (connected to an NSEC3 record type) then two
resulting argument names should be ns_ip_list_nsec and ns_ip_list_nsec3,
respectively.
The following is a message (msgid in this case) where this is in use:
The zone is inconsistent on NSEC and NSEC3. NSEC is fetched from nameservers with IP addresses "{ns_ip_list_nsec}". NSEC3 is fetched from nameservers with IP addresses "{ns_ip_list_nsec3}".
Defined arguments
When a suitable argument is found in this list, it should also be used in new and updated messages (msgids and msgstr).
| Argument name | Type of value | Description and formatting |
|---|---|---|
| algo_descr | Text | The human readable description of a DNSSEC algorithm as in table in DNSSEC05. |
| algo_mnemo | Text | The mnemonic of a DNSSEC algorithm as in table in DNSSEC05. |
| algo_num | Non-negative integer | The numeric value for a DNSSEC algorithm as in table in DNSSEC05. |
| cli_arg | Text | Command line (CLI) argument to an option, valid or invalid |
| domain | Domain name | A domain name. If "nsname", "mailtarget" or "query_name" is also applicable, use that one instead. |
| ds_algo_descr | Text | The human readable description of a DS Digest algorithm. |
| ds_algo_mnemo | Text | The mnemonic of a DS Digest algorithm. |
| ds_algo_num | Non-negative integer | The numeric value for a DS Digest algorithm. |
| int | integer | An integer. If "algo_num", "ds_also_num", "keytag", "soaserial" or some other specific name is applicable, use that instead. |
| ip_prefix | IP prefix | An IP prefix (i.e., an IP address with a network mask in CIDR notation). |
| keytag | Non-negative integer | A keytag for a DNSKEY record or a keytag used in a DS or RRSIG record. |
| label | Domain name label | A single label, i.e. the string between the dots, from a domain name. |
| locale | Locale label | A locale label, user provided or taken from the environment |
| mailtarget | Domain name | The domain name of the mailserver in an MX RDATA. |
| mailtarget_list | List of domain names | A list of name servers, as specified by "mailtarget", separated by ";". |
| module | A Zonemaster test module, or all | The name of a Zonemaster test module. |
| module_list | List of Zonemaster test modules | A list of Zonemaster test modules, separated by ":". |
| ns | Domain name and IP address pair | The name and IP address of a name server, separated by "/". |
| ns_ip | IP address | The IP address of a name server. |
| ns_ip_list | List of IP addresses | A list of name servers, as specified by "ns_ip", separated by ";". |
| ns_list | List of domain name and IP address pairs | A list of name servers, as specified by "ns", separated by ";". |
| nsname | Domain name | The domain name of a name server. |
| nsname_list | List of domain names | A list of name servers, as specified by "nsname", separated by ";". |
| query_name | Domain name | A query domain name (QNAME), as defined in RFC1035, section 4.1.2. |
| rcode | An RCODE Name | An RCODE Name (not numeric code) from DNS RCODEs. |
| rrtype | A Resource Record TYPE Name | A Resource Record TYPE Name (not numeric code) from DNS RR TYPEs. |
| soaserial | Non-negative integer | The numeric value for the SERIAL field in an SOA record. Integer in range 0-4,294,967,295 |
| soaserial_list | List of non-negative integers | A list of non-negative integers, as specified by "soaserial", separated by ";". |
| string | Text | The content of the RDATA of a TXT resource record. |
| testcase | A Zonemaster test case, or all | A test case identifier. |
| unicode_name | Unicode name of a code point | The name is a string in ASCII only and in upper case, e.g. "LATIN SMALL LETTER A" |
Preliminary or proposed arguments
The arguments in in this table are not fully defined. If used it should follow the pattern of defined arguments, be fully defined and moved to the list of defined arguments.
| Argument name | Type of value | Description and formatting |
|---|---|---|
| AS number | An Autonomous Space number for an IP address. | |
| Address record type (A or AAAA) | Used to tell the difference between IPv4 and IPv6. | |
| Count of different SOA RNAMEs. | Total number of different SOA RNAME fields seen. | |
| Count of different SOA serial numbers | Total number of different SOA serial numbers seen. | |
| Count of different sets of NS name/IP seen. | Total number of different sets of nameserver information seen. | |
| Count of different time parameter sets seen | Total number of different sets of SOA time parameters seen. | |
| Count of domain names | A count of domain names. | |
| Count of nameservers | A count of nameservers. | |
| DNS packet size | The size in octets of a DNS packets. | |
| DNSKEY key length | The key length for a DNSKEY. The interpretation of this value various quite a bit with the algorithm. Be careful when using it for algorithms that aren't RSA-based. | |
| DNSSEC delegation verification failure reason | A somewhat human-readable reason why the delegation step between the tested zone and its parent is not secure. | |
| dlength (?) | Domain name label length | The length of a domain name label. |
| Duration in seconds | An integer number of seconds. | |
| fqdn (?) | FQDN | A fully qualified domain name (with terminating dot). |
| fqdnlength (?) | FQDN length | The length of an FQDN. |
| IP address | An IPv4 or IPv6 address. | |
| IP address or nothing | An IPv4 or IPv6 address, or no value. | |
| IP range | An IP range. | |
| IP reserved range description | A brief description what an IP range is reserved for. | |
| Largest SOA serial number seen | The numerically largest SOA serial value seen. | |
| List of AS numbers | A list of Autonomous Space numbers. | |
| List of DNSKEY keytags | A list of keytags from DNSKEY records. | |
| List of DS keytags | A list of keytags from DS records. | |
| List of DS/DNSKEY/RRSIG keytags | A list of keytags from DS, DNSKEY or RRSIG records. | |
| List of IP addresses | A list of IP addresses. | |
| List of MX domain names | A list of domain names from MX records. | |
| List of RR types | A list of RR types, typically from an NSEC or NSEC3 record. | |
| List of SOA RNAMEs | A list of RNAME values from SOA records. | |
| List of SOA serial numbers | A list of serial number values from SOA records. | |
| List of domain names | A list of domain names. | |
| NS names from child | A list of nameserver names taken from a zone's child servers. | |
| NS names from parent | A list of nameserver names taken from a zone's parent servers. | |
| NSEC3 iteration count | An iteration count from an NSEC3PARAM record. | |
| Number of DNSKEY RRs in packet | The number of DNSKEY records found in a packet. | |
| Number of RRSIG RRs in packet | The number of RRSIG records found in a packet. | |
| Number of SOA RRs in packet | The number of SOA records found in a packet. | |
| Protocol (UDP or TCP) | The protocol used for a query. | |
| RFC reference | A reference to an RFC. | |
| rrtype (?) | RR type | The type of RR the message pertains to. |
| RRSIG Expiration date | The time when a signature expires. | |
| RRSIG validation error message | The human-readable reason why the cryptographic validation of a signature failed. | |
| SOA MNAME | The MNAME value from a SOA record. | |
| SOA RNAME | The RNAME value from a SOA record. | |
| SOA expire | The expire value from a SOA record. | |
| SOA expire minimum value | The lowest value considered OK for the SOA expire field. | |
| SOA minimum | The minimum value from a SOA record. | |
| SOA minimum maximum value | The highest value considered OK for the SOA minimum field. | |
| SOA minimum minimum value | The lowest value considered OK for the SOA minimum field. | |
| SOA refresh | The refresh value from a SOA record. | |
| SOA refresh minimum value | The lowest value considered OK for the SOA refresh field. | |
| SOA retry | The retry value from a SOA record. | |
| SOA retry minimum value | The lowest value considered OK for the SOA retry field. | |
| SOA serial number | The serial number value from a SOA record. | |
| Smallest SOA serial number seen | The smallest value seen in a SOA serial field in the tested zone. | |
| TLD | The name of a top-level domain. | |
time_t value when RRSIG validation was attempted | The time when an RRSIG validation was attempted, in Unix time_t format. |
Message names marked with a question mark should not be considered stable.