DhcpMonitor

This monitor is used to monitor the availability and functionality of DHCP servers. This monitor has two parts, the first one is the monitor class DhcpMonitor executed by Pollerd and the second part is a background daemon Dhcpd running inside the OpenNMS HORIZON JVM and listening for DHCP responses. A DHCP server is tested by sending a DISCOVER message. If the DHCP server responds with an OFFER the service is marked as up. The Dhcpd background daemon is disabled by default and has to be activated in service-configuration.xml in OpenNMS HORIZON by setting service enabled="true". The behavior for testing the DHCP server can be modified in the dhcp-configuration.xml configuration file.

It is required to install the {opennms-package-base-name}-plugin-protocol-dhcp before you can use this feature.
Installing the {opennms-package-base-name}-plugin-protocol-dhcp package
{apt-get,yum} install {opennms-package-base-name}-plugin-protocol-dhcp

If you try to start OpenNMS HORIZON without the {opennms-package-base-name}-plugin-protocol-dhcp you will see the following error message in output.log:

An error occurred while attempting to start the "OpenNMS:Name=Dhcpd" service (class org.opennms.netmgt.dhcpd.jmx.Dhcpd).  Shutting down and exiting.
java.lang.ClassNotFoundException: org.opennms.netmgt.dhcpd.jmx.Dhcpd
Make sure no DHCP client is running on the OpenNMS HORIZON server and using port UDP/68. If UDP/68 is already in use, you will find an error message in the manager.log. You can test if a process is listening on udp/68 with sudo ss -lnpu sport = :68.
Monitor facts

Class Name

org.opennms.protocols.dhcp.monitor.DhcpMonitor

Remote Enabled

false

Table 1. Service monitor parameters configured in poller-configuration.xml
Parameter Description Required Default value

retry

Number of retries before the service is marked as down

optional

0

timeout

Time in milliseconds to wait for the DHCP response from the server

optional

3000

rrd-repository

The location to write RRD data. Generally, you will not want to change this from default

optional

$OPENNMS_HOME/share/rrd/response

rrd-base-name

The name of the RRD file to write (minus the extension, .rrd or .jrb)

optional

dhcp

ds-name

This is the name as reference for this particular data source in the RRD file

optional

dhcp

Dhcpd configuration
Table 2. Dhcpd parameters in dhcp-configuration.xml.

Parameter

Description

Required

Default value

port

Defines the port your dhcp server is using

required

5818

macAddress

The MAC address which OpenNMS HORIZON uses for a dhcp request

required

00:06:0D:BE:9C:B2

myIpAddress

This parameter will usually be set to the IP address of the OpenNMS HORIZON server, which puts the DHCP poller in relay mode as opposed to broadcast mode. In relay mode, the DHCP server being polled will unicast its responses directly back to the IP address specified by myIpAddress rather than broadcasting its responses. This allows DHCP servers to be polled even though they are not on the same subnet as the OpenNMS HORIZON server, and without the aid of an external relay. Usage: myIpAddress="10.11.12.13" or myIpAddress="broadcast"

required

broadcast

extendedMode

When extendedMode is false, the DHCP poller will send a DISCOVER and expect an OFFER in return. When extendedMode is true, the DHCP poller will first send a DISCOVER. If no valid response is received it will send an INFORM. If no valid response is received it will then send a REQUEST. OFFER, ACK, and NAK are all considered valid responses in extendedMode. Usage: extendedMode="true" or extendedMode="false"

required

false

requestIpAddress

This parameter only applies to REQUEST queries sent to the DHCP server when extendedMode is true. If an IP address is specified, that IP address will be requested in the query. If targetHost is specified, the DHCP server’s own IP address will be requested. Since a well-managed server will probably not respond to a request for its own IP, this parameter can also be set to targetSubnet. This is similar to targetHost except the DHCP server’s IP address is incremented or decremented by 1 to obtain an ip address that is on the same subnet. (The resulting address will not be on the same subnet if the DHCP server’s subnet is a /32 or /31. Otherwise, the algorithm used should be reliable.) Usage: requestIpAddress="10.77.88.99" or requestIpAddress="targetHost" or requestIpAddress="targetSubnet"

required

false

02 01 dhcp monitor messages broadcast
Figure 1. Visualization of DHCP message flow in broadcast mode
02 02 dhcp monitor messages unicast
Figure 2. Visualization of DHCP message flow in relay mode
Example testing DHCP server in the same subnet

Example configuration how to configure the monitor in the poller-configuration.xml. The monitor will try to send in maximum 3 DISCOVER messages and waits 3 seconds for the DHCP server OFFER message.

Step 1: Configure a DHCP service in poller-configuration.xml
<service name="DHCP" interval="300000" user-defined="false" status="on">
 <parameter key="retry" value="2" />
 <parameter key="timeout" value="3000" />
 <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response" />
 <parameter key="rrd-base-name" value="dhcp" />
 <parameter key="ds-name" value="dhcp" />
</service>

<monitor service="DHCP" class-name="org.opennms.protocols.dhcp.monitor.DhcpMonitor"/>
Step 2: Enable the OpenNMS HORIZON Dhcpd daemon in service-configuration.xml
<service enabled="true">
  <name>OpenNMS:Name=Dhcpd</name>
  <class-name>org.opennms.netmgt.dhcpd.jmx.Dhcpd</class-name>
  <invoke method="start" pass="1" at="start"/>
  <invoke method="status" pass="0" at="status"/>
  <invoke method="stop" pass="0" at="stop"/>
</service>
Step 3: Configure Dhcpd to test a DHCP server in the same subnet as the OpenNMS HORIZON server.
<DhcpdConfiguration
       port="5818"
       macAddress="00:06:0D:BE:9C:B2"
       myIpAddress="broadcast
       extendedMode="false"
       requestIpAddress="127.0.0.1">
</DhcpdConfiguration>
Example testing DHCP server in a different subnet in extended mode

You can use the same monitor in poller-configuration.xml as in the example above.

Configure Dhcpd to test DHCP server in a different subnet. The OFFER from the DHCP server is sent to myIpAddress.
<DhcpdConfiguration
       port="5818"
       macAddress="00:06:0D:BE:9C:B2"
       myIpAddress="10.4.1.234"
       extendedMode="true"
       requestIpAddress="targetSubnet">
</DhcpdConfiguration>
If in extendedMode, the time required to complete the poll for an unresponsive node is increased by a factor of 3. Thus it is a good idea to limit the number of retries to a small number.