DNS Check

Pull

Synopsis

Director asks a DNS resolver one question from where it runs, and writes the result of every check itself as an ECS document: the response code, the records, the round trip, and the state the name is in — up or down, since when, and after how many checks. Nothing is installed on the resolver.

The DNS Check is one of six service check devices, each checking one service: a Website, an HTTP Check, a TCP Check, a DNS Check, an ICMP Check, and a TLS Check. It is a client: the DNS device is a honeypot listener.

One device, one question. A device asks one name of one type at one resolver. A second resolver is a second device, and the two devices' records compare in a search.

A DNS Check has no datasets. No check has: every check writes its results directly. The console offers it no dataset — see Service Check Datasets.

One Director owns each device.

note

The service check devices need Director 2.2.3 or later.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: dns_check
  tags: <string[]>
  status: <boolean>
  properties:
    record_name: <string>
    record_type: <string>
    resolver: <string>
    expected: <string[]>
    interval: <numeric>
    timeout: <numeric>
  pipelines: <pipeline[]>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be dns_check
tags	N	-	Optional tags
status	N	true	Enable/disable the device

Question

Field	Required	Default	Description
record_name	Y	-	The name asked, as it is written: absolute, with no search domain added, and the hosts file not read. A PTR check may name the address it asks about, which becomes its reverse name; any other type refuses an address
record_type	N	A	A, AAAA, CNAME, MX, NS, PTR, SOA, SRV, or TXT
resolver	N	the system's	An address or a name, with :port when it is not 53. An IPv6 address as it is, or in brackets with a port after them. Left out, the first name server the Director's system lists: /etc/resolv.conf, or on Windows the first network adapter that is up
expected	N	-	Values the answer must hold, every one of them: an address, a name (in any case, with or without its final dot), 10 mail.example.com for an MX, 10 5 5060 sip.example.com for an SRV, or a TXT record's text (its strings joined, compared as it is)

Pipeline

The device takes at most one pre-processing pipeline of its own: the device's pipeline picker in the console, pipelines: in a configuration file. Its results go through it, and through none when the device has none.

Advanced Configuration

Field	Required	Default	Description
interval	N	60	Seconds between checks: a result every interval. At least 10
timeout	N	2	Seconds the question may take, from 1 to 120

A configuration error stops the device with Configuration error, and the message names the property. A number is read whole: a fraction, or one no 32-bit integer holds, is refused, never converted.

How a Check Works

The question goes over UDP, and again over TCP when the answer comes back truncated.

The check is up when the resolver answered NOERROR with a record of the type asked, holding every expected value. Otherwise it is down, and error.type says why:

error.type	When
connection	The resolver could not be reached
timeout	No answer within timeout
dns	The resolver's own name does not resolve
response_code	A response code other than NOERROR
no_answer	NOERROR, with no record of the type asked
expected	The answer does not hold every expected value
malformed	The answer could not be read

A failed question is never an empty answer, nor an empty answer a failed question. NXDOMAIN, and a NOERROR with no record of the type asked, are answers: the result has their dns.response_code and the round trip. A question no answer came to has neither. A check with no resolver to ask writes no result, and is not counted in the state.

Results and State

Every check writes one result, with event.dataset dns_check and definition id 12152, to the metric table:

• dns.question.name, type, class; dns.id, dns.type (answer), dns.op_code, dns.response_code, dns.header_flags; dns.answers (name, type, class, ttl, data), dns.resolved_ip.
• destination.address, ip, port (the resolver); network.transport (udp or tcp), protocol.
• service_check.dns.rtt, and answers (their count).

Every result carries the state the name is in, under state.*. For the state's fields, how to alert on it, and the fields every record carries, see Results and State.

Connection States

State	When
Connected	The name is up
Connection error	The resolver does not answer, or its name does not resolve
Error	It answered wrong: a response code other than NOERROR, no record, or an unexpected answer
Configuration error	No resolver to ask, or a configuration that does not validate

Console

In the console, go to Fleet Management > Devices > DNS Check and click Add new device. The wizard's steps are:

1. General settings, as on every device, with the device's pre-processing pipeline.
2. Check settings: Record name, Record type (Optional), Resolver (Optional), and Expected answer (Optional), one value per line.
3. Advanced settings: Interval and Timeout.
4. Review and create.

There is no Data collection step: a DNS Check has no datasets.

Simulation

The DNS Check is not simulated. What it writes is what its check finds, with the state the name is in, which one generic sample cannot stand in for.

Examples

Mail Exchanger

Checking that a domain's MX record still names its mail server, at a public resolver...

devices: - id: 512300183 name: example-mx type: dns_check status: true properties: record_name: "example.com" record_type: MX resolver: "1.1.1.1" expected: - "10 mail.example.com"

Reverse Lookup

Checking an address's PTR record at the Director's own resolver, every five minutes...

devices: - id: 512300185 name: web01-ptr type: dns_check status: true properties: record_name: "192.0.2.10" record_type: PTR expected: - "web01.example.com" interval: 300