Watchdog: DNS

Checks whether a host name resolves via DNS, optionally to an expected IPv4 address and through a custom resolver. Type dns, runner Dashboard or Agent.

Deutsche Version

Back to check types

Watchdog: DNS

The check resolves a host name and optionally verifies that an expected IPv4 address is among the answers.

Property	Value
Type identifier	`dns`
Runner	Dashboard or Agent
Target in the email	`Hostname`

Fields

Field	Key	Default	Meaning
Hostname	`hostname`		Required. The name to resolve
Expected IP	`expected_ip`	empty	Optional. `FAIL` if this address is not in the answer. Empty only checks that the name resolves
Custom resolver	`resolver`	empty	Optional. IP address of a DNS server instead of the system resolver

Behaviour

Without a custom resolver the check asks the system resolver and receives the name's IPv4 addresses. With a custom resolver it calls the dig program (dig +short +time=5 @<resolver> <hostname> A) and reads only valid IP addresses from the output.

Situation	Status	Message
Name resolves, no expected IP set or it is present	`OK`	`<hostname> → <IP>, <IP>`
Expected IP missing from the answer	`FAIL`	`Expected IP <IP> not found for <hostname> (resolved: ...)`
Name does not resolve	`FAIL`	`DNS resolution failed for <hostname>: Name or service not known`
Answer without records	`FAIL`	`DNS returned no records for <hostname>`
Resolver is not a valid IP	`FAIL`	`Invalid resolver "<value>": must be a valid IP address`
Resolver is a private or reserved address	`FAIL`	`Resolver "<value>" is a private or reserved IP address and is not allowed`
`dig` fails	`FAIL`	`DNS resolution via <resolver> failed for <hostname> (exit <code>)`
No host name configured	`UNKNOWN`	`No hostname configured`

A custom resolver needs dig to be available in the container. The bundled Dockerfile does not install it. Without dig the check ends with exit 127.

Only A records (IPv4) are evaluated, IPv6 addresses do not appear in the answer. The check rejects private resolver addresses such as 10.0.0.53.