DNS Importing

From OpenNMS
Jump to navigation Jump to search

DNS Importing

The new Provisioning service in OpenNMS is continuously improving and adapting to the needs of the community. One of the most recent enhancements to the system is built upon the very flexible and extensible API of referencing an import requisition's location via a URL. Most commmonly, these URLs are files on the file system (i.e. file:/opt/opennms/etc/imports/<my-provisioning-requisition.xml>) as requisitions created by the Provisioning Requisitions UI. However, these same requistions for adding, updating, and deleting nodes (based on the original model importer) can also come from URLs specifying the HTTP protocol:

http://myinventory.server.org/nodes.cgi)

Now, using Java's extensible protocol handling specification, a new protocol handler was created so that a URL can be specified for requesting a Zone Transfer (AXFR) request from a DNS server. The A records are recorded and used to build an import requisition. This is handy for organizations that use DNS (possibly coupled with an IP management tool) as the data base of record for nodes in the network. So, rather than ping sweeping the network or entering the nodes manually into OpenNMS Provisioning UI, nodes can be managed via 1 or more DNS servers.

The format of the URL for this new protocol handler is:

dns://<host>[:port]/<zone>[/<foreign-source>/][?expression=<regex>][&amp;services=service1,service2,...servicen]

Note: The [&amp;services=service1,service2,...servicen] section is only valid in 1.9.8+; see NMS-4633

A few simple examples:

Simple

dns://my-dns-server/myzone.com

will import all A records from the host "my-dns-server" on port 53 (default port) from zone "myzone.com" and since the foreign source (a.k.a. the name of the requisition) is not specified it will default to the specified zone.

Using a Regular Expression Filter and Specifying a Destination Provisioning Requisition

dns://my-dns-server/myzone.com/Portland Servers/?expression=^port-.*

This will import all nodes in the zone "myzone.com" from DNS server "my-dns-server" whose fully qualified hostname matches the regular expression "^port-.*". Furthermore, these nodes will be assigned to the provisioning requisition (or foreign source) called "Portland Servers".

Specifying What Services to Provision On DNS-imported Nodes

dns://my-dns-server/myzone.com/Portland Servers/?expression=^port-.*&amp;services=ICMP

By default, nodes imported via DNS will have the ICMP and SNMP services provisioned on them. A recent enhancement in 1.9.8+ permits the specification of exactly what services to provision on the node. This example builds on the previous example by specifying that *only* the ICMP service is to be provisioned by default. Additional services can then be added to the default foreign source of the provisioning requisition. Note the escaping of ampersand (&amp;) required in the URL.

URL Encoding

If your expression requires URL encoding (for example you need to use a "?" in the expression) it must be properly encoded.

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

DNS Setup

Currently, the DNS server requires to be setup to allow a zone transfer from the OpenNMS server. It is recommended that a secondary DNS server is running on OpenNMS and that the OpenNMS server be allowed to request a zone transfer. A quick way to test if zone transfers are working is:

dig -t AXFR @<dnsServer> <zone>

OpenNMS first tries to do an incremental zone transfer using IXFR. If the above command works, but you are seeing a java.io.EOFException in /opt/opennms/logs/daemon/provisiond.log then try running this command:

dig +tcp -t ixfr=0 @<dnsServer> <zone>

It is likely your DNS server is responding but not configured properly to handle an IXFR, therefore opennms will throw an exception vs. trying the AXFR.

Configuration

The configuration of the Provisoning system has moved from a properties file (model-importer.properties) to an XML based configuration container. The configuration is now extensible to allow the definition of 0 or more import requisitions each with their own cron based schedule for automatic importing from various sources (intended for integration with external URL such as http and this new dns protocol handler.

A default configuration is provided in the OpenNMS etc/ directory and is called: provisiond-configuration.xml. This default configuration has an example for scheduling an import from a DNS server running on the localhost requesting nodes from the zone, localhost and will be imported once per day at the stroke of midnight. Not very practical but is a good example.

 <?xml version="1.0" encoding="UTF-8"?>
  <provisiond-configuration 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://xmlns.opennms.org/xsd/config/provisiond-configuration"
    foreign-source-dir="/opt/opennms/etc/foreign-sources" 
    requistion-dir="/opt/opennms/etc/imports" 
    importThreads="8" scanThreads="10" rescanThreads="10" writeThreads="8" >
  <!--  
    http://quartz.sourceforge.net/javadoc/org/quartz/CronTrigger.html
        Field Name     Allowed Values      Allowed Special Characters
        Seconds        0-59                , - * /
        Minutes        0-59                , - * /
        Hours          0-23                , - * /
        Day-of-month   1-31                , - * ? / L W C
        Month          1-12 or JAN-DEC     , - * /
        Day-of-Week    1-7 or SUN-SAT      , - * ? / L C #
        Year (Opt)     empty, 1970-2099    , - * /
   -->
    <requisition-def import-name="localhost" import-url-resource="dns://localhost/localhost">
      <cron-schedule>0 0 0 * * ? *</cron-schedule> <!-- daily, at midnight -->
    </requisition-def>
  </provisiond-configuration>

Configuration Reload

Like many of the daemon configuration in the 1.7 branch, the configurations are reloadable without having to restart OpenNMS, using the reloadDaemonConfig uei:

/opt/opennms/bin/send-event.pl uei.opennms.org/internal/reloadDaemonConfig --parm 'daemonName Provisiond'

This means that you don't have to restart OpenNMS every time you update the configuration.