Skip to content

Check dns

Overview

Performs a DNS lookup and resolves a hostname to one or more IP addresses. Queries the name servers configured on the local machine (e.g. those listed in /etc/resolv.conf). Measures and alerts on the lookup response time. Works with both IPv4 and IPv6.

Data Collection:

  • Uses Python's socket.getaddrinfo() to perform DNS resolution
  • Only the name servers configured on the machine running this check are queried - you cannot query other DNS servers
  • When no arguments are given, the check resolves localhost and names each address it gets once, whatever socket types the operating system lists it for (Linux returns every address once each for TCP, UDP and raw sockets, Windows once)
  • The connection type can be narrowed down using --type (udp, udp6, tcp, tcp6); the protocol is then shown with each address
  • The operating system's resolver has no timeout of its own; the check stops waiting after --timeout seconds
  • On Windows the resolver reports only an error code ("getaddrinfo failed"); the check names what it means, for example "host not found"

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/dns
Nagios/Icinga Check Name check_dns
Check Interval Recommendation Every 15 minutes
Can be called without parameters Yes
Runs on Cross-platform
Compiled for Windows Yes

Help

usage: dns [-h] [-V] [--always-ok] [-c CRIT] [-H HOSTNAME] [--no-perfdata]
           [-p PORT] [--timeout TIMEOUT] [--type {udp,udp6,tcp,tcp6}]
           [-w WARN]

Performs a DNS lookup and resolves a hostname to one or more IP addresses.
Queries the name servers configured on the local machine (e.g. those listed in
/etc/resolv.conf). Measures and alerts on the lookup response time. Works with
both IPv4 and IPv6.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --always-ok           Always returns OK.
  -c, --critical CRIT   CRIT threshold for DNS lookup time in milliseconds.
                        Default: None
  -H, --hostname HOSTNAME
                        Hostname or IP address to resolve. Default: localhost
  --no-perfdata         Suppress the performance data section from the output.
                        The status message and the exit code are unaffected,
                        so alerting keeps working while trending data is
                        dropped.
  -p, --port PORT       Port number to query. Default: 53
  --timeout TIMEOUT     Network timeout in seconds. Default: 8 (seconds)
  --type {udp,udp6,tcp,tcp6}
                        Connection type to narrow the list of returned
                        addresses.
  -w, --warning WARN    WARN threshold for DNS lookup time in milliseconds.
                        Default: None

Documentation:
https://linuxfabrik.github.io/monitoring-plugins/check-plugins/dns/

Usage Examples

./dns --hostname=$(hostname)
./dns --hostname=www.example.org --type=udp --port=53 --warning=1000 --critical=5000

Output:

Lookup for webserver.example.com returns 192.0.2.43 (ip4:53)

States

  • OK if the hostname resolves successfully and the lookup time is below the thresholds.
  • WARN if the name does not resolve, if the lookup returns no address, on socket errors, or if the lookup takes longer than --timeout.
  • WARN if the DNS lookup time is >= --warning.
  • CRIT if the DNS lookup time is >= --critical.
  • --always-ok suppresses all alerts and always returns OK.

Perfdata / Metrics

Name Type Description
time Seconds DNS lookup time in milliseconds.

Credits, License