
= DNS Resolver

:description: Learn how {page-component-title} uses the DNS Resolver internally to provide lookup functionality as required.

OpenNMS modules and functions use the DNS Resolver internally to provide lookup functionality as required.

== Modules that use DNS Resolution
* <<deep-dive/telemetryd/introduction.adoc#ga-telemetryd, Telemetryd>>


== Configuring DNS Resolution
To customize the DNS servers that are queried, use the following commands:
[source]
----
$ ssh -p 8201 admin@localhost
...
admin@minion()> config:edit org.opennms.features.dnsresolver.netty
admin@minion()> property-set nameservers 8.8.8.8,4.2.2.2:53,[::1]:5353
admin@minion()> property-set query-timeout-millis 5000
admin@minion()> property-set max-cache-size 10000
admin@minion()> config:update
----

If no nameservers are set (or set to an empty string), the servers configured by the system running the JVM will be used.

The resolved host names are cached for their TTL as specified in the returned DNS records.
Customize TTL handling by setting the `min-ttl-seconds`, `max-ttl-seconds` and `negative-ttl-seconds` properties in the above configuration.

== Configuring Circuit Breaker

Circuit Breaker functionality exists that helps prevent your DNS infrastructure from being flooded with requests when multiple failures occur.
Enabled by default, you can disable it by setting `breaker-enabled` to `false`.

You can modify additional parameters to tune the functionality of the circuit breaker:
[source]
----
$ ssh -p 8201 admin@localhost
...
admin@minion()> config:edit org.opennms.features.dnsresolver.netty
admin@minion()> property-set breaker-enabled true
admin@minion()> property-set breaker-failure-rate-threshold 80
admin@minion()> property-set breaker-wait-duration-in-open-state 15
admin@minion()> property-set breaker-ring-buffer-size-in-half-open-state 10
admin@minion()> property-set breaker-ring-buffer-size-in-closed-state 100
admin@minion()> config:update
----

NOTE: If the circuit breaker is disabled, the lookup statistics `lookupsSuccessful` and `lookupsFailed` are no longer tracked.

== Configuring Bulkhead
A bulkhead limits the number of concurrent DNS lookups that can be made.

You can modify additional parameters to tune the functionality of the circuit breaker:
[source]
----
$ ssh -p 8201 admin@localhost
...
admin@minion()> config:edit org.opennms.features.dnsresolver.netty
admin@minion()> property-set bulkhead-max-concurrent-calls 1000
admin@minion()> property-set bulkhead-max-wait-duration-millis 5100
admin@minion()> config:update
----
