DNS¶

The dns health check allows you to query a DNS server to ensure that it responds. Optionally, the response can be validated (eg. to ensure a certain IP address is contained within the response).

Configuration Keys¶

The following configuration options apply to the DNS health check method:

Key	Type	Default
`query`	String	undef
`query_type`	String	`soa`
`response`	Optional Pattern	undef
`tcp`	Bool	`False`
`port`	Integer	`53`
`dns_timeout`	Integer/Float	`5`
`require_resolve`	Bool	`True`

Remote Check Options¶

As this is a remote check, the following additional options are supported:

Key	Type	Default
`host`	String	undef
`address_family`	Optional String	undef
`all_valid`	Bool	`False`

Host¶

The host field contains the IP address or hostname that the health check should be executed against. If a hostname is supplied, each health check execution will perform a DNS resolution to ensure the current IP is used.

As the hostname may resolve to multiple addresses and/or address families (eg. IPv4 and IPv6) the address_family and all_valid options can be used to control what happens in those situations.

Warning

If specifying a host name instead of an IP address, temporary DNS resolution errors will cause the health check to fail. Specify an IP address to avoid this behaviour.

Address Family¶

The address_family key is used when host is set to a hostname. Should the hostname resolve to an IPv4 and IPv6 address you may want the check to only be sent to a single address family rather than both.

The values ipv4 or ipv6 are supported. If not defined there is no filtering for IPv4 or IPv6 addresses applied.

All Valid¶

The all_valid key is used when host is set to a hostname. If the hostname resolves to multiple IP addresses and all_valid is set to True, the health check will be executed against all IP addresses available. Should the health check to any IP address fail the service will be marked as down.

If set to the default False value a successful health check from any IP address is considered valid and the service will be marked up.

Query¶

The query field defines the name for the DNS query. By default, a soa query will be sent; combined with the query_type option you may query record types other than soa.

Query Type¶

The query_type field defines the type of DNS query to send. Valid options are:

a
aaaa
any
cname
mx
ns
ptr
soa
srv
txt

The soa query type is used by default.

Response¶

The response field can define a regex/pattern of valid responses. As an example, you may want to verify that a certain IP address is returned in the response.

TCP¶

By default DNS queries are sent using UDP; to use TCP instead set the tcp option to True.

Port¶

The port option can be used to send DNS queries to an alternative port other than 53.

DNS Timeout¶

A 5 second timeout is applied to DNS queries; you may raise or lower the timeout value if required.

Require Resolve¶

The require_resolve option can be disabled to allow any type of DNS response including NXDOMAIN. If set to the default value of True, responses from the DNS server must return a valid result.

Examples¶

Some examples of DNS health checks:

BasicCNAMEIP Regex

A basic configuration:

---

# The list of health checks
checks:

  - name: Example DNS Service
    description: Perform a basic SOA query for example.com to 192.0.2.255. If the query returns a response, 192.0.2.255 would be advertised with BGP.
    args:
      method: dns
      host: 192.0.2.255 # Note DNS queries are being sent to 192.0.2.255 which should be bound to loopback
      query: example.com
    prefixes:
      - 192.0.2.255
    nexthop: self

To validate a CNAME record contains expected content:

---

# The list of health checks
checks:

  - name: Example DNS CNAME Test
    description: Perform a CNAME query for www.example.com to 192.0.2.1 and verify the CNAME target contains the word "example"
    args:
      method: dns
      host: 192.0.2.1
      query: www.example.com
      type: cname
      pattern: example
    prefixes:
      - 192.0.2.253
    nexthop: self

To send a A query to a name server and validate the returned IP address with a regex:

---

# The list of health checks
checks:

  - name: DNS query with IP regex and neighbor filtering
    description: >
      Send an A query for "example.com" to 192.0.2.1 and ensure the response contains the IP address 192.0.2.250 using a regex.
      The routes to advertise will be filtered to specific neighbors.
    args:
      method: dns
      host: 192.0.2.1
      query: example.com
      query_type: a
      response: ^192\.0\.2\.250$
    nexthop: 192.168.0.3
    prefixes:
      - 192.0.2.2
      - 192.0.2.3
    neighbors:
      - 192.0.2.230
      - 192.0.2.231
      - 192.0.2.232