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 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 by setting service enabled="true". The behavior for testing the DHCP server can be modified in the 'dhcp-configuration.xml' configuration file.

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

If you try to start OpenNMS without the opennms-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
Caution
Make sure no DHCP client is running on the OpenNMS 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 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 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 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 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 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>
Note
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.