<chapter>
<title>Overview</title><subtitle>Admin Reference Overview</subtitle><section>
<title>About This Document</title><para>
This document covers the configuration of OpenNMS. In the following
chapter we will cover each file and what it affects.
</para>
</section>
</chapter><chapter>
<title>Configuration Files</title><section>
<title>actiond-configuration.xml</title><para>
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.
</para><glosslist>
<glossentry>
<glossterm>outstanding-actions</glossterm><glossdef>
<para>
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.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>max-process-time</glossterm><glossdef>
<para>
The maximum time that a launched process can take to complete.
If execution time exceeds this time, the launched process is
terminated.
</para>
</glossdef>
</glossentry>
</glosslist><example>
<title>Example <code>actiond-configuration.xml</code></title><para>
Here is an example <filename>actiond-configuration.xml</filename>.
<programlisting><?xml version="1.0"?>
<actiond-configuration
max-outstanding-actions="10"
max-process-time="120000">
</actiond-configuration></programlisting>
</para>
</example>
</section><section>
<title>c3p0.properties</title><para>
<ulink>C3P0</ulink> 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 <ulink>the
c3p0 configuration properties appendix</ulink> in their documentation.
</para>
</section><section>
<title>capsd-configuration.xml</title><para>
This file defines capabilities (services) to be checked for discovered nodes.
</para><section>
<title>the <code>capsd-configuration</code> tag</title><para>
The <capsd-configuration> tag at the top of
<filename>capsd-configuration.xml</filename> controls some basic behaviors
of Capsd. The following attributes are accepted:
</para><glosslist>
<glossentry>
<glossterm>rescan-frequency</glossterm><glossdef>
<para>
How long Capsd should wait before scanning existing nodes for
changes in available services, in milliseconds. A value of
<code>86400000</code> will cause Capsd to rescan nodes every
24 hours.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>initial-sleep-time</glossterm><glossdef>
<para>
How long Capsd should wait after OpenNMS starts before doing an
initial scan of known nodes. A value of <code>30000</code>
will cause Capsd to wait 30 seconds after startup before
attempting to check known nodes for available services.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>max-suspect-thread-pool-size</glossterm><glossdef>
<para>
The maximum number of Java threads to use for scanning hosts
upon receiving a <code>discovery/newSuspect</code> event.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>max-rescan-thread-pool-size</glossterm><glossdef>
<para>
The maximum number of Java threads to use for the regular rescan
that occurs every <code>rescan-frequency</code> milliseconds.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>abort-protocol-scans-if-no-route</glossterm><glossdef>
<para>
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 <code>false</code>.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>delete-propagation-enabled</glossterm><glossdef>
<para>
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 <code>true</code>.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>xmlrpc</glossterm><glossdef>
<para>
Flag which indicates if an external XMLRPC server has to be notified
with any event process errors. Defaults to <code>false</code>.
</para>
</glossdef>
</glossentry>
</glosslist>
</section><section>
<title>Protocol Plugins</title><para>
Protocol plugin entries define the services that are available for
Capsd to detect. They can refer to any Java class that implements the
OpenNMS <code>org.opennms.netmgt.capsd.Plugin</code> interface. A
large number of default plugins are provided as a part of OpenNMS.
</para><section>
<para>
The following attributes are a part of the <protocol-plugin> tag:
</para><glosslist>
<glossentry>
<glossterm>protocol</glossterm><glossdef>
<para>
The name of the protocol. This is a user-configurable value that should match
similar service configuration entries in the <filename>poller-configuration.xml</filename>
file. It is recommended that it only contain alphanumeric values. By
convention, you can also append a dash and numbers, like so:
"<code>HTTP-8080</code>" for common protocols listening on an alternate
port.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>class-name</glossterm><glossdef>
<para>The name of the Java class that implements the particular protocol.</para>
</glossdef>
</glossentry><glossentry>
<glossterm>scan</glossterm><glossdef>
<para>
Whether or not to scan this particular protocol. If set to "off" Capsd will
ignore the protocol plugin. Defaults to <code>on</code>.
</para>
</glossdef>
</glossentry>
</glosslist>
</section><section>
<title>Properties</title><para>
A <code>protocol-plugin</code> entry can optionally contain zero or more
<code>property</code> entries which allow specifying configuration to be
passed as arguments to the plugin code.
</para>
</section><section>
<title>Protocol Configuration</title><para>
A <code>protocol-plugin</code> entry can optionally contain zero or more
<code>protocol-configuration</code> tags which specify a subset of addresses
for which the protocol should apply.
</para><para>
Each <code>protocol-configuration</code> entry can contain zero or more of
the following ways of specifying addresses and ranges and of overriding
other general <code>protocol-plugin</code> defaults:
</para><glosslist>
<glossentry>
<glossterm>specific</glossterm><glossdef>
<para>A single IP address.</para>
</glossdef>
</glossentry><glossentry>
<glossterm>range</glossterm><glossdef>
<para>A range of IP addresses.</para>
</glossdef>
</glossentry><glossentry>
<glossterm>property</glossterm><glossdef>
<para>
A <code>protocol-plugin</code> key/value property which overrides
the defaults that are part of the container <code>protocol-plugin</code>
entry.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>scan</glossterm><glossdef>
<para>
Whether or not the addresses defined in the <code>specific</code>
and <code>range</code> entries should be scanned. Defaults to
<code>on</code>.
</para>
</glossdef>
</glossentry>
</glosslist>
</section><example>
<title>Example <code>capsd-configuration.xml</code></title><para>
Here is an example <filename>capsd-configuration.xml</filename> that defines
the <code>ICMP</code> 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.
<programlisting><?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></programlisting>
</para>
</example>
</section>
</section><section>
<title>categories.xml</title><para>
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 <filename>viewsdisplay.xml</filename> as well.
</para><section>
<title>Category Groups</title><para>
Technically, the <filename>categories.xml</filename> 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.
</para>
</section><section>
<title>Global Options</title><para>
Inside the category group, there are a number of options that can
apply to all categories in the group.
</para><glosslist>
<glossentry>
<glossterm>name</glossterm><glossdef>
<para>
One (and only one) <name> tag should be in each
category group. This is the short name of the
category group.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>comment</glossterm><glossdef>
<para>
One (and only one) <comment> tag should be in each
category group. This is a longer description of the
category group.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>common</glossterm><glossdef>
<para>
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:
<programlisting><common>
<rule><![CDATA[IPADDR != '0.0.0.0']]></rule>
</common></programlisting>
</para>
</glossdef>
</glossentry>
</glosslist>
</section><section>
<title>Categories</title><para>
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.
</para><glosslist>
<glossentry>
<glossterm>label</glossterm><glossdef>
<para>
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 <filename>viewsdisplay.xml</filename>.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>comment</glossterm><glossdef>
<para>
An optional tag with a detailed comment describing the category.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>normal</glossterm><glossdef>
<para>
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.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>warning</glossterm><glossdef>
<para>
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.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>service</glossterm><glossdef>
<para>
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.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>rule</glossterm><glossdef>
<para>
The rule that defines what nodes/interfaces/services match the
category. It can match on services (Is<emphasis>SERVICE</emphasis>),
IP addresses, and a number of other criteria.
</para>
</glossdef>
</glossentry>
</glosslist>
</section><example>
<title>Example <filename>categories.xml</filename></title><para>
Here is an example <filename>categories.xml</filename> 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.
<programlisting><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></programlisting>
</para>
</example>
</section><section>
<title>chart-configuration.xml</title><para>
Used by some chart-generation code in the web UI.
</para>
</section><section>
<title>collectd-configuration.xml</title><para>
Configures various portions of data collection for RRD data.
</para>
</section><section>
<title>create.sql, get*.sql, set*.sql</title><para>
The <filename>create.sql</filename> 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.
</para>
</section><section>
<title>database-schema.xml</title><para>
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.
</para>
</section><section>
<title>datacollection-config.xml</title><para>
This file is used for collecting data into round-robin databases for use in
thresholding and graphing.
</para>
</section><section>
<title>destinationPaths.xml</title><para>
This file contains definitions for notifiation destination paths. It
specifies whom to notify and by what method they should be notified.
</para>
</section><section>
<title>dhcpd-configuration.xml</title><para>
Configures the built-in DHCP daemon in OpenNMS (used for DHCP capability
scanning and polling).
</para>
</section><section>
<title>discovery-configuration.xml</title><para>
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.
</para>
</section><section>
<title>eventconf.xml</title><para>
This file defines the Universal Event Identifiers or UEIs as well as their event masks,
descriptions, log messages, and severity levels.
</para>
</section><section>
<title>eventd-configuration.xml</title><para>
This file defines operating parameters for Eventd such as time outs and number of
listener threads.
</para>
</section><section>
<title>events-archiver-configuration.xml</title><para>
Configuration for the event archiver daemon.
</para>
</section><section>
<title>events.archiver.properties</title><para>
Logging configuration for the event archiver daemon.
</para>
</section><section>
<title>groups.xml</title><para>
This file holds information about user groups, used for determining group
membership for notifications.
</para>
</section><section>
<title>http-datacollection-config.xml</title><para>
This file defines configuration for collecting RRD data from HTTP and HTTPS.
</para>
</section><section>
<title>javamail-configuration.properties</title><para>
This file contains configuration for sending e-mail from OpenNMS for
notifications, as well as the mail transport monitor.
</para>
</section><section>
<title>jcifs.properties</title><para>
This file defines configuration for accessing Windows SMB (CIFS) shares
from OpenNMS.
</para>
</section><section>
<title>jmx-datacollection-config.xml</title><para>
This file contains configuration for datacollection using the Java Management
eXtensions.
</para>
</section><section>
<title>ksc-performance-reports.xml</title><para>
This file contains configuration for KSC reports.
</para>
</section><section>
<title>linkd-configuration.xml</title><para>
Configuration for the link daemon, used to collect path/link information
from routers for use in maps.
</para>
</section><section>
<title>log4j.properties</title><para>
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.
</para>
</section><section>
<title>log4j-controller.properties</title><para>???</para>
</section><section>
<title>magic-users.properties</title><para>
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.
</para>
</section><section>
<title>map.disable</title><para>
If this file exists, maps will not be enabled in the web UI.
</para>
</section><section>
<title>map.properties</title><para>
This file configures the SVG map feature.
</para>
</section><section>
<title>model-importer.properties</title><para>
Information used by the model importer.
</para>
</section><section>
<title>monitoring-locations.xml</title><para>
This file configures the monitoring locations used by the remote poller.
</para>
</section><section>
<title>notifd-configuration.xml</title><para>
Configures the notification daemon including auto-acknowledgement
and notification queues.
</para>
</section><section>
<title>notificationCommands.xml</title><para>
This file defines how to accomplish various contact methods defined
in <filename>destinationPaths.xml</filename>. 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.
</para><programlisting><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></programlisting>
</section><section>
<title>notifications.xml</title><para>
This file defines which events or UEIs warrant notification and where the
notifications should be sent and escalated to.
</para><programlisting><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></programlisting>
</section><section>
<title>nsclient-config.xml</title><para>
Configure the NSClient poller.
</para>
</section><section>
<title>nsclient-datacollection-config.xml</title><para>
Configure data collection through NSClient.
</para>
</section><section>
<title>opennms-datasources.xml</title><para>
This file defines information for accessing the OpenNMS database.
</para>
</section><section>
<title>opennms-server.xml</title><para>
Defines information about the management server.
</para>
</section><section>
<title>opennms.properties</title><para>
Sets global properties for the OpenNMS JVM.
</para>
</section><section>
<title>otrs.properties</title><para>
Configures properties for the OTRS ticketing plugin.
</para>
</section><section>
<title>poll-outages.xml</title><para>
Configures scheduled outages.
</para>
</section><section>
<title>poller-config.properties</title><para>
Configures various classes and settings used by the web UI relating to pollers.
</para>
</section><section>
<title>poller-configuration.xml</title><para>
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.
</para>
</section><section>
<title>response-adhoc-graph.properties</title><para>
Settings related to graphing adhoc reports.
</para>
</section><section>
<title>response-graph.properties</title><para>
Settings related to making response-time graphs.
</para>
</section><section>
<title>rrd-configuration.properties</title><para>
Configuration for the RRD backend, including choosing RRDtool or JRobin
for making round-robin files and graphing.
</para>
</section><section>
<title>rtc-configuration.xml</title><para>
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.
</para>
</section><section>
<title>scriptd-configuration.xml</title><para>
Configure BSF languages used in Scriptd.
</para>
</section><section>
<title>service-configuration.xml</title><para>
This file defines opennms services to start. This is VM specific and controls which
services are started in which VMs
</para>
</section><section>
<title>site-status-views.xml</title><para>???</para>
</section><section>
<title>snmp-adhoc-graph.properties</title><para>
Settings related to graphing adhoc SNMP reports.
</para>
</section><section>
<title>snmp-config.xml</title><para>
This file is used to define community strings for addresses or address ranges, one
snmp-config entry per community.
</para>
</section><section>
<title>snmp-graph.properties</title><para>
This file is used to define RRD configurations for generating reports.
</para>
</section><section>
<title>statsd-configuration.xml</title><para>
Configuration for Statsd (Top N reports).
</para>
</section><section>
<title>surveillance-views.xml</title><para>How many freaking *-view things do we have?!?</para>
</section><section>
<title>syslogd-configuration.xml</title><para>
Configures the syslog daemon.
</para>
</section><section>
<title>threshd-configuration.xml</title><para>
Configure which thresholding packages used to trigger alerts when various
thresholds are reached.
</para>
</section><section>
<title>thresholds.xml</title><para>
Configure thresholding groups based on RRD data.
</para>
</section><section>
<title>tl1d-configuration.xml</title><para>
Configure the TL1 daemon for interacting with telecom devices.
</para>
</section><section>
<title>translator-configuration.xml</title><para>
Translate incoming events based on a set of criteria.
</para>
</section><section>
<title>trapd-configuration.xml</title><para>
This file defines information for the OpenNMS SNMP trap daemon.
</para>
</section><section>
<title>users.xml</title><para>
This file holds information about users and their contact information.
This information is used for authentication in the web UI, as well as
notifications.
</para>
</section><section>
<title>vacuumd-configuration.xml</title><para>
Configure Vacuumd, a daemon which periodically runs a series of commands
to keep OpenNMS running well (delete old events, clean up the database,
etc.)
</para>
</section><section>
<title>viewsdisplay.xml</title><para>
This file defines layout of categories for display in the web UI. The actual
categories are defined in the categories.xml file.
</para>
</section><section>
<title>vulnscand-configuration.xml</title><para>
Configure Vulnscand, the Nessus vulnerability scanning integration.
</para>
</section><section>
<title>xmlrpcd-configuration.xml</title><para>
Configure Xmlrpcd, used to be able to pass XML events back and forth
between OpenNMS and external tools.
</para>
</section><section>
<title>xmpp-configuration.properties</title><para>
Configure the XMPP (Jabber) notification strategy.
</para>
</section>
</chapter>