OpenNMS Administrator Reference Guide

Configuration and Administration

OpenNMS Development Team

Benjamin Reed

Marshall Christy

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts and with no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/copyleft/fdl.html


Table of Contents

1. Overview
About This Document
2. Configuration Files
actiond-configuration.xml
c3p0.properties
capsd-configuration.xml
the capsd-configuration tag
Protocol Plugins
categories.xml
Category Groups
Global Options
Categories
chart-configuration.xml
collectd-configuration.xml
create.sql, get*.sql, set*.sql
database-schema.xml
datacollection-config.xml
destinationPaths.xml
dhcpd-configuration.xml
discovery-configuration.xml
eventconf.xml
eventd-configuration.xml
events-archiver-configuration.xml
events.archiver.properties
groups.xml
http-datacollection-config.xml
javamail-configuration.properties
jcifs.properties
jmx-datacollection-config.xml
ksc-performance-reports.xml
linkd-configuration.xml
log4j.properties
log4j-controller.properties
magic-users.properties
map.disable
map.properties
model-importer.properties
monitoring-locations.xml
notifd-configuration.xml
notificationCommands.xml
notifications.xml
nsclient-config.xml
nsclient-datacollection-config.xml
opennms-datasources.xml
opennms-server.xml
opennms.properties
otrs.properties
poll-outages.xml
poller-config.properties
poller-configuration.xml
response-adhoc-graph.properties
response-graph.properties
rrd-configuration.properties
rtc-configuration.xml
scriptd-configuration.xml
service-configuration.xml
site-status-views.xml
snmp-adhoc-graph.properties
snmp-config.xml
snmp-graph.properties
statsd-configuration.xml
surveillance-views.xml
syslogd-configuration.xml
threshd-configuration.xml
thresholds.xml
tl1d-configuration.xml
translator-configuration.xml
trapd-configuration.xml
users.xml
vacuumd-configuration.xml
viewsdisplay.xml
xmlrpcd-configuration.xml
xmpp-configuration.properties

List of Examples

2.1. Example actiond-configuration.xml
2.2. Example capsd-configuration.xml
2.3. Example categories.xml

Chapter 1. Overview

Admin Reference Overview

Table of Contents

About This Document

About This Document

This document covers the configuration of OpenNMS. In the following chapter we will cover each file and what it affects.

Chapter 2. Configuration Files

Table of Contents

actiond-configuration.xml
c3p0.properties
capsd-configuration.xml
the capsd-configuration tag
Protocol Plugins
categories.xml
Category Groups
Global Options
Categories
chart-configuration.xml
collectd-configuration.xml
create.sql, get*.sql, set*.sql
database-schema.xml
datacollection-config.xml
destinationPaths.xml
dhcpd-configuration.xml
discovery-configuration.xml
eventconf.xml
eventd-configuration.xml
events-archiver-configuration.xml
events.archiver.properties
groups.xml
http-datacollection-config.xml
javamail-configuration.properties
jcifs.properties
jmx-datacollection-config.xml
ksc-performance-reports.xml
linkd-configuration.xml
log4j.properties
log4j-controller.properties
magic-users.properties
map.disable
map.properties
model-importer.properties
monitoring-locations.xml
notifd-configuration.xml
notificationCommands.xml
notifications.xml
nsclient-config.xml
nsclient-datacollection-config.xml
opennms-datasources.xml
opennms-server.xml
opennms.properties
otrs.properties
poll-outages.xml
poller-config.properties
poller-configuration.xml
response-adhoc-graph.properties
response-graph.properties
rrd-configuration.properties
rtc-configuration.xml
scriptd-configuration.xml
service-configuration.xml
site-status-views.xml
snmp-adhoc-graph.properties
snmp-config.xml
snmp-graph.properties
statsd-configuration.xml
surveillance-views.xml
syslogd-configuration.xml
threshd-configuration.xml
thresholds.xml
tl1d-configuration.xml
translator-configuration.xml
trapd-configuration.xml
users.xml
vacuumd-configuration.xml
viewsdisplay.xml
xmlrpcd-configuration.xml
xmpp-configuration.properties

actiond-configuration.xml

Actions are external programs called based on events. This file controls the number of concurrent actions allowed as well as a time out for waiting on a return.

outstanding-actions

The maximum number of simultaneous processes launched by Actiond. If the number of launched processes currently running reaches this number, Actiond waits for a process to complete or get terminated before it launches the next process.

max-process-time

The maximum time that a launched process can take to complete. If execution time exceeds this time, the launched process is terminated.

Example 2.1. Example actiond-configuration.xml

Here is an example actiond-configuration.xml.

<?xml version="1.0"?>
<actiond-configuration
        max-outstanding-actions="10"
        max-process-time="120000">
</actiond-configuration>


c3p0.properties

C3P0 is the database connection pooling technology used by OpenNMS. In most cases you should never have to change this file. For details on configuration options, see the c3p0 configuration properties appendix in their documentation.

capsd-configuration.xml

This file defines capabilities (services) to be checked for discovered nodes.

the capsd-configuration tag

The <capsd-configuration> tag at the top of capsd-configuration.xml controls some basic behaviors of Capsd. The following attributes are accepted:

rescan-frequency

How long Capsd should wait before scanning existing nodes for changes in available services, in milliseconds. A value of 86400000 will cause Capsd to rescan nodes every 24 hours.

initial-sleep-time

How long Capsd should wait after OpenNMS starts before doing an initial scan of known nodes. A value of 30000 will cause Capsd to wait 30 seconds after startup before attempting to check known nodes for available services.

max-suspect-thread-pool-size

The maximum number of Java threads to use for scanning hosts upon receiving a discovery/newSuspect event.

max-rescan-thread-pool-size

The maximum number of Java threads to use for the regular rescan that occurs every rescan-frequency milliseconds.

abort-protocol-scans-if-no-route

Flag which determines Capsd's behavior in the event that a NoRouteToHost exception is generated during a protocol plugin scan of an interface. If true, Capsd will abort the protocol scanning process for the interface. Defaults to false.

delete-propagation-enabled

Determine if deleting an service propagates to deleting the interface if the service is the only one remaining on the interface. Likewise for the only interface on a node. Defaults to true.

xmlrpc

Flag which indicates if an external XMLRPC server has to be notified with any event process errors. Defaults to false.

Protocol Plugins

Protocol plugin entries define the services that are available for Capsd to detect. They can refer to any Java class that implements the OpenNMS org.opennms.netmgt.capsd.Plugin interface. A large number of default plugins are provided as a part of OpenNMS.

The following attributes are a part of the <protocol-plugin> tag:

protocol

The name of the protocol. This is a user-configurable value that should match similar service configuration entries in the poller-configuration.xml file. It is recommended that it only contain alphanumeric values. By convention, you can also append a dash and numbers, like so: "HTTP-8080" for common protocols listening on an alternate port.

class-name

The name of the Java class that implements the particular protocol.

scan

Whether or not to scan this particular protocol. If set to "off" Capsd will ignore the protocol plugin. Defaults to on.

Properties

A protocol-plugin entry can optionally contain zero or more property entries which allow specifying configuration to be passed as arguments to the plugin code.

Protocol Configuration

A protocol-plugin entry can optionally contain zero or more protocol-configuration tags which specify a subset of addresses for which the protocol should apply.

Each protocol-configuration entry can contain zero or more of the following ways of specifying addresses and ranges and of overriding other general protocol-plugin defaults:

specific

A single IP address.

range

A range of IP addresses.

property

A protocol-plugin key/value property which overrides the defaults that are part of the container protocol-plugin entry.

scan

Whether or not the addresses defined in the specific and range entries should be scanned. Defaults to on.

Example 2.2. Example capsd-configuration.xml

Here is an example capsd-configuration.xml that defines the ICMP protocol plugin, with a default timeout of 2000 milliseconds, and 1 retry. For the IP addresses 192.168.1.1 and 192.168.2.1 through 192.168.2.254, it will use a timeout of 1000 instead. Scanning is disabled for 192.168.1.2.

<?xml version="1.0"?>
<capsd-configuration 
  rescan-frequency="86400000" 
  initial-sleep-time="30000" 
  max-suspect-thread-pool-size="6"
  max-rescan-thread-pool-size="3">

  <protocol-plugin protocol="ICMP" class-name="org.opennms.netmgt.capsd.plugins.IcmpPlugin" scan="on">
    <protocol-configuration>
      <specific>192.168.1.1</specific>
      <range>
        <begin>192.168.2.1</begin>
        <end>192.168.2.254</end>
      </range>
      <property key="timeout" value="1000" />
    </protocol-configuration>
    <protocol-configuration>
      <specific>192.168.1.2</specific>
      <scan>off</scan>
    </protocol-configuration>
    <property key="timeout" value="2000" />
    <property key="retry" value="1" />
  </protocol-plugin>
</capsd-configuration>


categories.xml

This file allows you to configure the categories of a device based on the mixture of services they run. You can also set expected error and warning levels for when availability drops below a certain percentage. These affect availability reports, as well as how the categories are displayed, if they are defined in viewsdisplay.xml as well.

Category Groups

Technically, the categories.xml file can have more than one "group" of categories. However, the <categorygroup> tag never got fleshed out in the code and it is recommended you do not use more than one <categorygroup> tag.

Global Options

Inside the category group, there are a number of options that can apply to all categories in the group.

name

One (and only one) <name> tag should be in each category group. This is the short name of the category group.

comment

One (and only one) <comment> tag should be in each category group. This is a longer description of the category group.

common

A common rule that will be applied to every category in the category group, in addition to that category's specific rule. The <common> tag should contain a single set of <rule> tags. For example:

<common>
	<rule><![CDATA[IPADDR != '0.0.0.0']]></rule>
</common>

Categories

Inside the category group, there can be a <categories> tag which can contain one or more <category> tags. The following tags are allowed in a category.

label

A descriptive label for the category. This needs to be unique across all categories, and will be displayed in the UI if the category is referenced in viewsdisplay.xml.

comment

An optional tag with a detailed comment describing the category.

normal

The normal threshold value for the category in percent. The UI displays the category in green if the overall availability for the category is equal to or greater than this value.

warning

The warning threshold value for the category in percent. The UI displays the category in yellow if the overall availability for the category is equal to or greater than this value but less than the normal threshold. If availability is less than this value, the category is displayed in red.

service

An optional tag specifying the service relevant to this category. For a node ID/IP address/service tuple to be added to a category, it will need to pass the category's rule and the service will need to be in the category service list. If there are no services defined, all tuples that pass the rule are added to the category.

rule

The rule that defines what nodes/interfaces/services match the category. It can match on services (IsSERVICE), IP addresses, and a number of other criteria.

Example 2.3. Example categories.xml

Here is an example categories.xml that defines a series of categories. It defines a global <rule> that makes sure that we get all IP devices in the 192.168 class B, and then individual categories which have more specific rules.

<catinfo>
	<header>
	</header>
	<categorygroup>
		<name>WebConsole</name>
		<comment>Service Level Availability by Functional Group</comment>
		<common>
			<rule><![CDATA[IPADDR IPLIKE '192.168.*.*']]></rule>
		</common>
		<categories>
			<category>
				<label><![CDATA[Overall Service Availability]]></label>
				<comment>This category reflects overall availability of every device on the 192.168.*.* network.</comment>
				<normal>99.99</normal>
				<warning>97</warning>
				<rule><![CDATA[IPADDR != '0.0.0.0']]></rule>
			</category>

			<category>
				<label><![CDATA[Pingable Routers]]></label>
				<comment>This category represents pingable routers with the "Router" service.</comment>
				<normal>99.99</normal>
				<warning>97</warning>
				<service>ICMP</service>
				<service>Router</service>
				<rule><![CDATA[(isICMP & isRouter)]]></rule>
			</category>
			<category>
				<label><![CDATA[VectaStar Elements]]></label>
				<comment>This category includes all managed interfaces which are related to the VectaStar system.</comment>
				<normal>99.99</normal>
				<warning>97</warning>
				<rule><![CDATA[(nodeSysOID like '.1.3.6.1.4.1.5419.1.3500.%')]]></rule>
			</category>
		</categories>
	</categorygroup>
</catinfo>


chart-configuration.xml

Used by some chart-generation code in the web UI.

collectd-configuration.xml

Configures various portions of data collection for RRD data.

create.sql, get*.sql, set*.sql

The create.sql file is the template for creating the OpenNMS database. It is used by the installer, and generally should not be modified. The get*.sql and set*.sql files define a series of stored procedures used in parts of the OpenNMS code.

database-schema.xml

This file is used internally by OpenNMS for the filtering system when formatting database queries. It is not meant to be modified by end-users.

datacollection-config.xml

This file is used for collecting data into round-robin databases for use in thresholding and graphing.

destinationPaths.xml

This file contains definitions for notifiation destination paths. It specifies whom to notify and by what method they should be notified.

dhcpd-configuration.xml

Configures the built-in DHCP daemon in OpenNMS (used for DHCP capability scanning and polling).

discovery-configuration.xml

This file defines the ranges of addresses to discover, (ping sweep) as well as time-outs, number of retries, and number of threads to dedicate to discovery. This file also provides initial-sleep-time and restart-sleep-time. These values are in milliseconds and control how long after OpenNMS is started, that discovery should begin it's initial pass through the addresses, and how long to wait between each additional pass.

eventconf.xml

This file defines the Universal Event Identifiers or UEIs as well as their event masks, descriptions, log messages, and severity levels.

eventd-configuration.xml

This file defines operating parameters for Eventd such as time outs and number of listener threads.

events-archiver-configuration.xml

Configuration for the event archiver daemon.

events.archiver.properties

Logging configuration for the event archiver daemon.

groups.xml

This file holds information about user groups, used for determining group membership for notifications.

http-datacollection-config.xml

This file defines configuration for collecting RRD data from HTTP and HTTPS.

javamail-configuration.properties

This file contains configuration for sending e-mail from OpenNMS for notifications, as well as the mail transport monitor.

jcifs.properties

This file defines configuration for accessing Windows SMB (CIFS) shares from OpenNMS.

jmx-datacollection-config.xml

This file contains configuration for datacollection using the Java Management eXtensions.

ksc-performance-reports.xml

This file contains configuration for KSC reports.

linkd-configuration.xml

Configuration for the link daemon, used to collect path/link information from routers for use in maps.

log4j.properties

This file defines logging information, including log size and rotation, as well as what level of logging should happen for different parts of the OpenNMS code.

log4j-controller.properties

???

magic-users.properties

This file includes special users, and takes precedence over users.xml for the users that it has information about. This is used internally to control permissions for certain functions that interact with the web UI.

map.disable

If this file exists, maps will not be enabled in the web UI.

map.properties

This file configures the SVG map feature.

model-importer.properties

Information used by the model importer.

monitoring-locations.xml

This file configures the monitoring locations used by the remote poller.

notifd-configuration.xml

Configures the notification daemon including auto-acknowledgement and notification queues.

notificationCommands.xml

This file defines how to accomplish various contact methods defined in destinationPaths.xml. This would include the location of executable and aliases for each type of contact along with any other information needed to send information of the specific type.

<command type="email">
	<name>/bin/mail</name>
	<lookup>email</lookup>
	<lookup>mail</lookup>
	<comment>for sending email notifications</comment>
	<argument streamed="false">
		<substitution>-s</substitution>
		<switch>-subject</switch>
	</argument>
	<argument streamed="false">
		<switch>-email</switch>
	</argument>
	<argument streamed="true">
		<switch>-tm</switch>
	</argument>
</command>

notifications.xml

This file defines which events or UEIs warrant notification and where the notifications should be sent and escalated to.

<notification name="nodeAdded">
	<uei><![CDATA[http://uei.opennms.org/nodes/nodeAdded]]></uei>
	<rule><![CDATA[IPADDR IPLIKE *.*.*.*]]></rule>
	<destinationPath>Email-Network/Systems</destinationPath>
	<text-message>OpenNMS has discovered a new node named %parm[nodelabel]%.    Please be advised.</text-message>
	<subject>%parm[nodelabel]% discovered.</subject>
</notification>

nsclient-config.xml

Configure the NSClient poller.

nsclient-datacollection-config.xml

Configure data collection through NSClient.

opennms-datasources.xml

This file defines information for accessing the OpenNMS database.

opennms-server.xml

Defines information about the management server.

opennms.properties

Sets global properties for the OpenNMS JVM.

otrs.properties

Configures properties for the OTRS ticketing plugin.

poll-outages.xml

Configures scheduled outages.

poller-config.properties

Configures various classes and settings used by the web UI relating to pollers.

poller-configuration.xml

This file is used to define packages as well as set up the various pollers. A package includes several items such as address ranges, services, outage calendars, and down time models.

response-adhoc-graph.properties

Settings related to graphing adhoc reports.

response-graph.properties

Settings related to making response-time graphs.

rrd-configuration.properties

Configuration for the RRD backend, including choosing RRDtool or JRobin for making round-robin files and graphing.

rtc-configuration.xml

This file defines properties for RTC (Real Time Console) such as the rolling window used to calculate percentages of down time, web UI refresh interval and how often RTC sends updates to the web interface.

scriptd-configuration.xml

Configure BSF languages used in Scriptd.

service-configuration.xml

This file defines opennms services to start. This is VM specific and controls which services are started in which VMs

site-status-views.xml

???

snmp-adhoc-graph.properties

Settings related to graphing adhoc SNMP reports.

snmp-config.xml

This file is used to define community strings for addresses or address ranges, one snmp-config entry per community.

snmp-graph.properties

This file is used to define RRD configurations for generating reports.

statsd-configuration.xml

Configuration for Statsd (Top N reports).

surveillance-views.xml

How many freaking *-view things do we have?!?

syslogd-configuration.xml

Configures the syslog daemon.

threshd-configuration.xml

Configure which thresholding packages used to trigger alerts when various thresholds are reached.

thresholds.xml

Configure thresholding groups based on RRD data.

tl1d-configuration.xml

Configure the TL1 daemon for interacting with telecom devices.

translator-configuration.xml

Translate incoming events based on a set of criteria.

trapd-configuration.xml

This file defines information for the OpenNMS SNMP trap daemon.

users.xml

This file holds information about users and their contact information. This information is used for authentication in the web UI, as well as notifications.

vacuumd-configuration.xml

Configure Vacuumd, a daemon which periodically runs a series of commands to keep OpenNMS running well (delete old events, clean up the database, etc.)

viewsdisplay.xml

This file defines layout of categories for display in the web UI. The actual categories are defined in the categories.xml file.

xmlrpcd-configuration.xml

Configure Xmlrpcd, used to be able to pass XML events back and forth between OpenNMS and external tools.

xmpp-configuration.properties

Configure the XMPP (Jabber) notification strategy.