Copyright © 2004-2013 The OpenNMS Group, Inc.
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
List of Examples
Table of Contents
Table of Contents
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.
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.
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
Here is an example
<?xml version="1.0"?> <actiond-configuration max-outstanding-actions="10" max-process-time="120000"> </actiond-configuration>
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.
This file defines capabilities (services) to be checked for discovered nodes.
The <capsd-configuration> tag at the top of
capsd-configuration.xml controls some basic behaviors
of Capsd. The following attributes are accepted:
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
How long Capsd should wait after OpenNMS starts before doing an
initial scan of known nodes. A value of
will cause Capsd to wait 30 seconds after startup before
attempting to check known nodes for available services.
The maximum number of Java threads to use for scanning hosts
upon receiving a
The maximum number of Java threads to use for the regular rescan
that occurs every
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
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
Flag which indicates if an external XMLRPC server has to be notified
with any event process errors. Defaults to
Protocol plugin entries define the services that are available for
Capsd to detect. They can refer to any Java class that implements the
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:
The name of the protocol. This is a user-configurable value that should match
similar service configuration entries in the
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
The name of the Java class that implements the particular protocol.
Whether or not to scan this particular protocol. If set to "off" Capsd will
ignore the protocol plugin. Defaults to
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-plugin entry can optionally contain zero or more
protocol-configuration tags which specify a subset of addresses
for which the protocol should apply.
protocol-configuration entry can contain zero or more of
the following ways of specifying addresses and ranges and of overriding
A single IP address.
A range of IP addresses.
protocol-plugin key/value property which overrides
the defaults that are part of the container
Whether or not the addresses defined in the
range entries should be scanned. Defaults to
Example 2.2. Example
Here is an example
capsd-configuration.xml that defines
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>
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.
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.
Inside the category group, there are a number of options that can apply to all categories in the group.
One (and only one) <name> tag should be in each category group. This is the short name of the category group.
One (and only one) <comment> tag should be in each category group. This is a longer description of the category group.
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>
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.
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
An optional tag with a detailed comment describing the category.
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.
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.
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.
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
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 '.22.214.171.124.4.1.5419.1.3500.%')]]></rule> </category> </categories> </categorygroup> </catinfo>
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.
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.
This file is used for collecting data into round-robin databases for use in thresholding and graphing.
This file contains definitions for notifiation destination paths. It specifies whom to notify and by what method they should be notified.
Configures the built-in DHCP daemon in OpenNMS (used for DHCP capability scanning and polling).
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.
This file defines the Universal Event Identifiers or UEIs as well as their event masks, descriptions, log messages, and severity levels.
This file defines operating parameters for Eventd such as time outs and number of listener threads.
This file holds information about user groups, used for determining group membership for notifications.
This file defines configuration for collecting RRD data from HTTP and HTTPS.
This file contains configuration for sending e-mail from OpenNMS for notifications, as well as the mail transport monitor.
This file defines configuration for accessing Windows SMB (CIFS) shares from OpenNMS.
This file contains configuration for datacollection using the Java Management eXtensions.
Configuration for the link daemon, used to collect path/link information from routers for use in maps.
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.
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.
Configures the notification daemon including auto-acknowledgement and notification queues.
This file defines how to accomplish various contact methods defined
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>
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>
Configures various classes and settings used by the web UI relating to pollers.
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.
Configuration for the RRD backend, including choosing RRDtool or JRobin for making round-robin files and graphing.
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.
This file defines opennms services to start. This is VM specific and controls which services are started in which VMs
This file is used to define community strings for addresses or address ranges, one snmp-config entry per community.
Configure which thresholding packages used to trigger alerts when various thresholds are reached.
This file holds information about users and their contact information. This information is used for authentication in the web UI, as well as notifications.
Configure Vacuumd, a daemon which periodically runs a series of commands to keep OpenNMS running well (delete old events, clean up the database, etc.)
This file defines layout of categories for display in the web UI. The actual categories are defined in the categories.xml file.
Configure Xmlrpcd, used to be able to pass XML events back and forth between OpenNMS and external tools.