//ui-provd: the contextual help from the external requisition screen links to this help, using the URL https://docs.opennms.com/horizon/latest/reference/provisioning/handlers/introduction.html. Ensure link in UI does not break if changing this section of docs.

[[dns-handler]]
= DNS Handler
:description: Learn how to configure and use the DNS handler in OpenNMS {page-component-title} to request a zone transfer from a DNS server to retrieve A and AAAA records.

The DNS handler requests a zone transfer (AXFR) from a DNS server.
The A and AAAA records are retrieved and used to build an import requisition.
This is useful for organizations that use DNS, possibly coupled with an IP management tool, as the database of record for nodes in the network.
Rather than ping sweeping the network or entering the nodes manually into the {page-component-title} Requisition UI, you can manage nodes via one or more DNS servers.

The format of the URL for this protocol handler is: `dns://<host>[:port]/<zone>[/<foreign-source>/][?expression=<regex>]`

== Configure DNS requisition

ifeval::["{page-component-title}" == "Horizon"]
Prior to {page-component-title} 30, you set external requisitions in the `provisiond-configuration.xml` file.
This file is no longer available.
You must use the UI or the xref:development:rest/config_management.adoc#config-rest-api[config management REST API] to configure an external requisition.
endif::[]

To configure a DNS requisition, follow the steps in xref:reference:provisioning/handlers/introduction.adoc#create-req-def[Create an external requisition], but specify DNS as the type, and set the host, DNS zone, requisition name, schedule, and rescan behavior.

You can also define <<location-dns,location>> or <<regex,expression parameters>> in the *Advanced Options* area.

== DNS import samples

=== Simple

[source]
----
dns://my-dns-server/myzone.com
----

This URL imports all A and AAAA records from the zone `myzone.com` on the host `my-dns-server` via port 53 (default DNS port).
Since the foreign source is not specified, it will be added to the default requisition.

[[regex]]
=== Regular expression filter

[source]
----
dns://my-dns-server/myzone.com/portland/?expression=^por-.*
----

This URL imports all nodes from the same server and zone, but only imports the nodes in the zone that match the regular expression `^port-.*`.
The matching nodes will be assigned to a requisition named 'portland'.

NOTE: The content of your expression must be URL encoded otherwise characters such as `?`, `+`, and slashes will be considered part of the query string and not the expression.

[source]
----
dns://my-dns-server/myzone.com/portland/?expression=^por[0-9]%3F
----

[[location-dns]]
=== Location

You can use the `location` parameter to assign a single location to all nodes in this requisition.
This would apply only if you use Minions in your network.

[source]
----
dns://my-dns-server/myzone.com/portland/?location=Raleigh
----

By prefixing with a `~`, you can specify a URL-encoded regular expression to determine the location based on the host entries.
The following example derives the location based on the subdomain.
This example uses a URL-encoded regular expression with exactly one capturing group containing the subdomain.

[source]
----
Expression: ^(?:.*\.|)(.*?)\.hs-fulda\.de\.$
dns://my-dns-server/hs-fulda.de/?location=~%5E%28%3F%3A.%2A%5C.%7C%29%28.%2A%3F%29%5C.hs-fulda%5C.de%5C.%24
----

This will associate nodes for the host entries `foo.e46.hs-fulda.de.` and `bar.e46.hs-fulda.de.` to the location `e46` while hosts like `aaa.g51.hs-fulda.de` and `bbb.g51.hs-fulda.de` will be assigned location `g51`.

TIP: You can use online tools like https://www.urlencoder.org to encode your parameters.

== DNS setup

The DNS import handler performs an AXFR zone transfer request to collect DNS resource records for use in provisioning nodes.
Zone transfers are designed for zone replication between DNS servers.
You may want to provide additional security mechanisms to protect your DNS infrastructure.
At a minimum, you should always restrict AXFR requests to only trusted IP addresses and/or use a hidden, read-only secondary DNS server for {page-component-title}.

You may want to set up a secondary DNS server on your {page-component-title} and configure the rest of the DNS servers to allow transfers to your {page-component-title} server.
This allows you to point the DNS import handler to `localhost`.

NOTE: There is no encryption or authentication available for AXFR transfer requests.
Transaction signatures (TSIG) to prevent IP spoofing attempts are currently not supported by {page-component-title}.

A quick way to test if zone transfers are working is:

[source, console]
----
dig -t AXFR @<dnsServer> <zone>
----

== Trigger manual import

You can manually trigger an import by sending a reload event.

[source, console]
----
./send-event.pl -p 'url dns://my-dns-server/hs-fulda.de/?expression=^por[0-9]%3F&location=Raleigh' uei.opennms.org/internal/importer/reloadImport
----