Nameserver test service

This service allows registrars to test their nameserver before trying to activate a domain they created in reserved state or before changing nameserver information for a domain.
This test service is available as a simple text-based protocol.

Protocol description

The nameserver test service reads ASCII text from its TCP socket in a line-based fashion. Each command is separated by an empty line from the following command, very similar to separation between headers and body for mime messages.

Protocol description (request)

A single command looks like the following:

1. XXXX Request identifier (alpha-numeric)
2. mode Command type
3. args ... Arguments for the command specified in mode

The request identifier and the command type may apear exactly once for each command. A command ends on the first empty line encountered, whitespace is considered separator between the individual fields.

Sessions are closed by two consecutive empty lines or using the command 'quit'

The individual commands can be sent without waiting for an answer, reuse of a command identifier before having got matching response is not recommended, as responses will also have that same identifier.

Supported command types

• live Active test, ignoring cached information
• cached Test based on cached information
• update Active test, but updating cache on success
• cfg Change some session configuration settings
• quit Close session (not domain or nameserver)
• help Show small help message (not domain or nameserver)

live, cached and update nameserver tests take at least two arguments, the first one being the domain name to be tested, the following onces being nameserver definitions.
The domain name may be followed by DS records where DS record fields are separated by a colon (':') and comma (',') is used as separator between DS records and domain name.
The nameserver definition is defined as host name followed by optional IP address. The host name and IP address are separated by a comma and IP address is required only when glue records are required. Note that IP addresses are ignored for nameservers that need no glue record with exception of test if nameserver resolves to given IP address.

cfg configuration command takes two arguments, the name of the configuration option that should be changed and the new value for that option. The supported options are:

• machine-output: Toggle output mode between human readable test result description and machine-readable result description with message codes and list of values for substitution into the matching message string.
  Permitted values are on and true to switch to machine readable output, off and false to switch to human readable output

help allows an optional argument with the name of command to describe

quit command takes no arguments and closes connection after processing, without waiting for pending tests to complete and send back their results.

Protocol description (response)

A response is composed of multiple lines, a header line giving global result status and at least one detail line.

The header line looks like the following:

1. [code] Result code of the response
   • [help] Response is a help/usage notification
   • [miss] A cache-only request failed because of incomplete information in cache, client should repeat the test in update or live mode
   • [ok] Successful test
   • [warn] Successful test, but with warnings
   • [err] Failed test
2. XXXX Request identifier
3. text... Human readable result message

The detail lines looks like the following:

1. [code] Result code of the detail item
   • [NN] Notification
   • [II] Information
   • [WW] Warning
   • [EE] Error
2. text... Human readable detail message

1. [code] Result code of the detail item
   • [NN] Notification
   • [II] Information
   • [WW] Warning
   • [EE] Error
2. id An ID that identifies the message
3. args ... All arguments required for substitution in message string that matches message code in id. All arguments are put between single quotes, characters ' and \ being escaped as \' and \\.

As for commands, each response is terminated by an empty line.

Note: Responses are not guarateed to arrive in the same order as commands have been sent. Because of response times of queried nameservers the delay between a command and it's response is not known in advance, but when the total time is longer than 5 seconds some nameservers fail to respond.

Machine result code listing

When working in machine-output mode all test result detail lines are of the form [code] id args .... The id may be one of the following (list may be enlarged without prior notice, all unknown codes should be handled gracefully):

In the matching english message (used for human-readable responses) all $$0$$ are place-holders for the arguments at position indicated by the number between the dollar signs. Argument positions start at 0 for the first argument. For a short description of each such argument, look at the tooltip associated to each argument place-holder.

1. MSG_CACHE_NOADDRHOST: A nameserver with given IP address does not exist in the nameserver-test cache.
   English: Missing host '$$0$$' with address '$$1$$' from cache
2. MSG_CACHE_NOHOST: A given nameserver does not exist in nameserver-test cache.
   English: Missing host '$$0$$' from cache
3. MSG_CFG_BAD_VALUE: The new value for a given configuration option could not be understood.
   English: Invalid configuration value for $$0$$
4. MSG_CFG_NO_SUCH_OPTION: The given configuration option is unknown.
   English: Unknown configuration option $$0$$
5. MSG_CFG_UPDATED: The given configuration option has been changed.
   English: Configuration option $$0$$ updated
6. MSG_EMPTY_ANSWER: A nameserver replied with an empty answer, this nameserver does not know the tested domain name.
   English: Answer for $$0$$ query from $$1$$ at address $$2$$ contains no answer
7. MSG_GLUENS_NO_IPADDRESS: A local nameserver which requires a glue record had no IP address provided and thus cannot be resolved/used.
   English: Missing address for local nameserver $$0$$
8. MSG_MULTI_SOA_ANSWER: A given nameserver provided multiple SOA records in its answer.
   English: Nameserver '$$0$$' at address '$$1$$' returned too many SOA records ($$2$$)
9. MSG_MULTIPLE_MASTER: For the tested domain name multiple masters are advertised by the nameservers.
   English: There exists multiple master servers for domain '$$0$$':
10. MSG_NO_ANSWER: A nameserver did not answer to any of the DNS queries sent to it.
    English: No answer from $$0$$ at address $$1$$
11. MSG_NO_ANSWER_FOR_QUERY: A nameserver did not answer to a given DNS query.
    English: No answer for $$0$$ query from $$1$$ at address $$2$$
12. MSG_NO_AUTH_NAMESERVER: The nameserver test returned no authoritative nameserver.
    English: No working authoritative nameserver found
13. MSG_NON_AUTH_ANSWER: A nameserver answered with a non-authoritative response to a given query. Probably this nameserver is just a resolver.
    English: Answer for $$0$$ query from $$1$$ at address $$2$$ is not authoritative
14. MSG_NS_ADV_NO_GLUE: A given nameserver does not show it's own IP address as glue record.
    English: Nameserver '$$0$$' at address '$$1$$' does not provide it's address as glue record
15. MSG_NS_NO_ADV_SELF: A given nameserver does not list itself as authoritative server for the tested domain.
    English: Nameserver '$$0$$' at address '$$1$$' does not advertise itself as nameserver
16. MSG_NS_ZONE_MASTER: List nameservers that advertise a given zone master.
    English: Master '$$0$$' is advertised by nameservers at addresses: $$1$$
17. MSG_NSTEST_DOMAIN: Indicates the domain name for which the test is being performed.
    English: Nameserver test for domain $$0$$
18. MSG_NSTEST_HOST_DISCOVERED: Indicates a discovered nameserver. (nameserver not listed in the test request)
    English: Nameserver $$0$$ at $$1$$ (discovered)
19. MSG_NSTEST_HOST_PROVIDED: Indicates a nameserver provided in the request. (nameserver listed in request)
    English: Nameserver $$0$$ at $$1$$ (provided)
20. MSG_QUERY_FAILED: A nameserver replied with a failure code for a given query.
    English: $$0$$ query failed for nameserver '$$1$$' at address '$$2$$' ($$3$$)
21. MSG_REQ_BAD_COMMAND: Unknown command.
    English: Unknown command '$$0$$'
22. MSG_REQ_BAD_HOSTNAME: Invalid/non-welformed host name.
    English: Invalid host name '$$0$$'
23. MSG_REQ_BAD_IPADDRESS: Invalid/non-wellformed IP address for given nameserver.
    English: Failed to decode IP address '$$1$$' for host '$$0$$'
24. MSG_REQ_PARSE_FAILED: Invalid/non-wellformed command, command could not be parsed.
    English: Request parsing error
25. MSG_REQ_TOO_FEW_ARGS: Missing arguments for command. More arguments expected.
    English: Too few arguments
26. MSG_RESOLVE_FAILED: Could not resolve given non-glue nameserver.
    English: Failed to resolve external nameserver '$$0$$'
27. MSG_RESOLVE_NOMATCH: The nameserver resolved to another IP address than the prodived/previously detected IP address.
    English: External nameserver '$$0$$' does not resolve to provided address '$$1$$'
28. MSG_SINGLE_AUTH_NAMESERVER: Only a single authoritative nameserver was detected.
    English: Only one working authoritative nameserver found
29. MSG_SYS_SESSION_END: Server ending session. (after quit command)
    English: Closing connection
30. MSG_SYS_USAGE: Line of usage information - always in english.
    English: $$0$$
31. MSG_TOO_FEW_AUTH_NAMESERVER: Not enough authoritative nameservers were found, indicates expected minimum count.
    English: At least $$0$$ nameservers required
32. MSG_TRUNCATED_ANSWER_FOR_QUERY: The answer for a DNS query got truncated because it doesn't fit into response UDP packet. This would require DNS client to re-issue the query using TCP.
    English: Answer for $$0$$ query from $$1$$ at address $$2$$ is truncated
33. : Internal error
    English: Internal error
34. MSG_UDP_EMPTY_ANSWER: A nameserver replied with an empty answer using UDP, this nameserver does not know the tested domain name.
    English: [UDP] Answer for $$0$$ query from $$1$$ at address $$2$$ contains no answer
35. MSG_TCP_EMPTY_ANSWER: A nameserver replied with an empty answer using TCP, this nameserver does not know the tested domain name.
    English: [TCP] Answer for $$0$$ query from $$1$$ at address $$2$$ contains no answer
36. MSG_UDP_NS_ADV_NO_GLUE: A given nameserver does not show it's own IP address as glue record when asked using UDP.
    English: [UDP] Nameserver '$$0$$' at address '$$1$$' does not provide it's address as glue record
37. MSG_TCP_NS_ADV_NO_GLUE: A given nameserver does not show it's own IP address as glue record when asked using TCP.
    English: [TCP] Nameserver '$$0$$' at address '$$1$$' does not provide it's address as glue record
38. MSG_UDP_NS_NO_ADV_SELF: A given nameserver does not list itself as authoritative server for the tested domain when asked using UDP.
    English: [UDP] Nameserver '$$0$$' at address '$$1$$' does not advertise itself as nameserver
39. MSG_TCP_NS_NO_ADV_SELF: A given nameserver does not list itself as authoritative server for the tested domain when asked using TCP.
    English: [TCP] Nameserver '$$0$$' at address '$$1$$' does not advertise itself as nameserver
40. MSG_UDP_MULTI_SOA_ANSWER: A given nameserver provided multiple SOA records in its answer while asked using UDP.
    English: [UDP] Nameserver '$$0$$' at address '$$1$$' returned too many SOA records ($$2$$)
41. MSG_TCP_MULTI_SOA_ANSWER: A given nameserver provided multiple SOA records in its answer while asked using TCP.
    English: [TCP] Nameserver '$$0$$' at address '$$1$$' returned too many SOA records ($$2$$)
42. MSG_UDP_RESOLVE_NOMATCH: The nameserver resolved to another IP address than the prodived/previously detected IP address.
    English: [UDP] External nameserver '$$0$$' does not resolve to provided address '$$1$$'
43. MSG_TCP_RESOLVE_NOMATCH: The nameserver resolved to another IP address than the prodived/previously detected IP address.
    English: [TCP] External nameserver '$$0$$' does not resolve to provided address '$$1$$'
44. MSG_UDP_NO_ANSWER_FOR_QUERY: A nameserver did not answer to a given DNS query using UDP.
    English: [UDP] No answer for $$0$$ query from $$1$$ at address $$2$$
45. MSG_TCP_NO_ANSWER_FOR_QUERY: A nameserver did not answer to a given DNS query using TCP.
    English: [TCP] No answer for $$0$$ query from $$1$$ at address $$2$$
46. MSG_UDP_NO_ANSWER: A nameserver did not answer to any of the DNS queries sent to it using UDP.
    English: [UDP] No answer from $$0$$ at address $$1$$
47. MSG_TCP_NO_ANSWER: A nameserver did not answer to any of the DNS queries sent to it using TCP.
    English: [TCP] No answer from $$0$$ at address $$1$$
48. MSG_UDP_QUERY_FAILED: A nameserver replied with a failure code for a given query using UDP.
    English: [UDP] $$0$$ query failed for nameserver '$$1$$' at address '$$2$$' ($$3$$)
49. MSG_TCP_QUERY_FAILED: A nameserver replied with a failure code for a given query using TCP.
    English: [TCP] $$0$$ query failed for nameserver '$$1$$' at address '$$2$$' ($$3$$)
50. MSG_UDP_NON_AUTH_ANSWER: A nameserver answered with a non-authoritative response to a given query using UDP. Probably this nameserver is just a resolver.
    English: [UDP] Answer for $$0$$ query from $$1$$ at address $$2$$ is not authoritative
51. MSG_TCP_NON_AUTH_ANSWER: A nameserver answered with a non-authoritative response to a given query using TCP. Probably this nameserver is just a resolver.
    English: [TCP] Answer for $$0$$ query from $$1$$ at address $$2$$ is not authoritative
52. MSG_FAILED: A nameserver replied with a failure code for a given query.
    English: Query failed for nameserver '$$0$$' at address '$$1$$' ($$2$$)
53. MSG_UDP_FAILED: A nameserver replied with a failure code for a given query.
    English: [UDP] Query failed for nameserver '$$0$$' at address '$$1$$' ($$2$$)
54. MSG_TCP_FAILED: A nameserver replied with a failure code for a given query.
    English: [TCP] Query failed for nameserver '$$0$$' at address '$$1$$' ($$2$$)
55. MSG_ANSWER_DIFFERING_FOR_QUERY: The answers for the same query coming via UDP and TCP differ
    English: Answer for $$0$$ query from $$1$$ at address $$2$$ differs between UDP and TCP transports
56. MSG_TRUNCATED_ANSWER_FOR_QUERY_NO_TCP: The answer for a DNS query got truncated because it doesn't fit into response UDP packet. The attempt to re-issue the query using TCP failed.
    English: Answer for $$0$$ query from $$1$$ at address $$2$$ is truncated but TCP query impossible
57. MSG_TCP_TRUNCATED_ANSWER_FOR_QUERY: The answer for a DNS query sent via TCP has truncated flag set. This makes no sense.
    English: TCP answer for $$0$$ query from $$1$$ at address $$2$$ is unexpectedly truncated
58. MSG_REQ_BAD_DS_RECORD: The indicated DS record is malformed It must contain keytag, algorithm, digest type and HEX representation of digest.
    English: Invalid DS record '$$0$$'
59. MSG_DNSSEC_OK: DNSSEC successfully validated.
    English: "[DNSSEC] Validation successful using NS '$$0$$' at address '$$1$$': $$2$$
60. MSG_DNSSEC_NO_KEY: No DNSKEY record available.
    English: "[DNSSEC] No DNSKEY record found using NS '$$0$$' at address '$$1$$': $$2$$
61. MSG_DNSSEC_KEY_2_DS_FAILED: An error occured while trying to convert available DNSKEY records into DS records.
    English: [DNSSEC] Failed to convert DNSKEY to DS using NS '$$0$$' at address '$$1$$': $$2$$
62. MSG_DNSSEC_DS_NO_MATCH: There was no match between listed DS records and available DNSKEYs.
    English: [DNSSEC] No DS - DNSKEY match found using NS '$$0$$' at address '$$1$$': $$2$$
63. MSG_DNSSEC_VALIDATION_FAILED: The DNSSEC validation failed, verify key material, key/signature expiration dates and zone consistency! The validation error may give a hint at what is wrong.
    English: [DNSSEC] Validation failed using NS '$$0$$' at address '$$1$$': $$2$$
64. MSG_DNSSEC_TIMEOUT: DNSSEC validation took too much time, make sure DNS servers are not overloaded!
    English: "[DNSSEC] Timeout while validating using NS '$$0$$' at address '$$1$$'
65. MSG_DNSSEC_CACHE_NOADDRHOST: No DNSSEC validation is available from cache for the given list of DS records.
    English: [DNSSEC] Missing host '$$0$$' with address '$$1$$' from cache

Sample test session

In this sample session we indicate lines sent to service with '⇒' and replied lines with '⇐' at beginning of line.

In the above request a test for restena.lu was executed in live mode, discovering 3 new nameservers (the two ultradns ones and the IPv6 based ns1.restena.lu).
The second sample show setting configuration option in order to switch to machine readable output and same query executed in this mode.

In the above request a test for dns.lu was executed in cache-only mode, but as cache did not know anything about it returns a global result of 'miss', the detail information has no real meaning as data was missing from cache.

In the above request a test for dns.lu was executed in update mode, this implied doing a live test and updating the cache on successful test. A subsequent 'cached' test would return the same information.

In the above request a test for restena.lu was executed with DNSSEC validation. The DS record is presented with colon as field separator and separated from domain name with a comma. (response details have been omitted)

Finally when finished doing the tests, we close our test-session using quit command (a second empty line after last command closes the session as well)