Skip to main content
Network

NSLookup

Query a DNS record directly from a DNS server and get alerted when the answer is missing, fails, or lacks the expected value.

The NSLookup check queries a record for a hostname directly from a DNS server, much like the nslookup command-line tool. It reports when the server does not answer, returns an error, returns no matching record, or an expected value is missing. The check runs on the device with the octoja agent on Windows, Linux, and macOS (each in x64 and Arm64 builds), every 5 minutes by default.

Steps

  1. Open the device.
  2. Choose Checks → Add Check → NSLookup.
  3. Enter the Hostname and Record type and adjust the other fields if needed.

To cover several devices, assign the check with a config package. One check queries exactly one hostname and one record type. Add further checks for other names or types.

Settings

FieldTypeRequiredDefaultDescription
HostnamestringYes—Name to look up, e.g. example.com. An IP address for PTR lookups. A short name is completed with the device's DNS suffixes
Record typeselection: A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRVYesADNS record type to query
DNS server (optional)stringNo—IP address or hostname of the DNS server to query, e.g. 192.0.2.53. Leave empty to use the DNS server configured on the device
Expected value (optional)stringNo—If set, the answer must contain this value, e.g. 192.0.2.10 or v=spf1
Timeout (ms)integerNo5000Time allowed for the whole lookup, including resolving the DNS server and every attempt with DNS suffixes. Values outside 500–60000 are clamped
  • Without DNS server (optional), the check uses the first DNS server of an active network adapter on the device. A hostname you enter is first resolved through the device, and the first returned address is queried. Queries always go to port 53.
  • Short names without a dot, such as srv-dc, are tried with the device's DNS suffixes first, then without a suffix. A name containing a dot or ending in a dot (srv-dc.) is queried unchanged.
  • For PTR lookups, the check builds the reverse-lookup name from an IP address automatically.

Matching the expected value

Record typeComparison
MX, TXT, SOA, SRVA record must contain the value as a substring. For example, mail.example.com matches an MX record 10 mail.example.com
A, AAAA, CNAME, NS, PTRA record must equal the value exactly. A trailing dot is ignored

Matching is case-insensitive in both cases. It is enough for one of the returned records to match.

Results

ConditionResultShown as
The server returns at least one record of the selected type, and it contains the expected value if one is setOKServer, response time, response code and records
Only an alias (CNAME) comes back instead of the selected typeWarningOnly an alias (CNAME) was returned, not the requested record type.
The answer contains no record of the selected typeCriticalNo records of the requested type were returned.
No record contains the expected valueCriticalThe expected value was not found in the answer.
The server answers with NXDOMAIN, SERVFAIL, REFUSED or another error codeCriticalDescription of the response code
The server does not answer within Timeout (ms)CriticalThe DNS server did not answer in time.
The server cannot be reachedCriticalThe DNS server could not be reached with the reason
No DNS server is configured on the device, or the hostname in DNS server (optional) cannot be resolvedCriticalNo DNS server is configured on this device. or The configured DNS server could not be resolved.
The hostname is not a valid DNS name, the answer cannot be parsed, or an unexpected error occursErrorError message

The check reports:

  • Hostname and record type
  • The name actually queried, under Queried, when a short name was completed with a DNS suffix
  • The address of the DNS server queried
  • Response time in milliseconds and response code, e.g. NOERROR
  • Up to 16 records of the selected type
  • Whether the expected value was found, if one is configured

Notes

  • The check sends the DNS query itself instead of using the operating system's resolver. To test whether names resolve on the device, use the DNS Resolution check.
  • The query is sent over UDP. If the server reports a truncated answer, the check repeats it over TCP.

See also: Set up alerts for a check

Was this helpful?

Still need help? Ask the team