Revision as of 15:28, 21 June 2012

Provisiond is a new daemon replacing capsd and extending the importer service. It's used to read nodes from a file, detect services on the nodes...

Concepts

The high level concepts for the provisioning components can be found in the User's Guide. To summarize, provisioning is a mechanism for importing node and service definitions either from an external source such as DNS or HTTP or via the web UI within Open NMS.

To understand the information flow, we must first talk about provisioning requisitions.

Provisioning Requisitions

Two types of provisioning requisitions exist, the system wide Default Provisioning Requisition and user defined provisioning requisitions.

The default provisioning requisition does not contain nodes in and of itself, but it does specify default detectors and policies. When creating new provisioning requisitions, the detectors and policies defined within the default will be copied to the new requisition's foreign-source definition so it's worth spending a little time to add any detectors you may wish to use later to the default. We'll talk about how to do this as we go through this page.

It is expected that there may be a large number of user defined provisioning requisitions, though it may be worth considering one of the following approaches:

• A provisioning requisition per customer
• A provisioning requisition per business unit
• A provisioning requisition per device type within a business unit

There are no right answers, only what works for your given circumstance.

Detectors

Detectors specify which of the Open NMS provisioning detectors should be run against nodes identified within this provisioning requisition.

List of the available detectors at the time of writing:

• datagram.DnsDetector
• datagram.NtpDetector
• dhcp.DhcpDetector
• endpoint.EndPointDetector
• generic.GpDetector
• icmp.IcmpDetector
• jdbc.AbstractJdbcDetector
• jdbc.JdbcDetector
• jdbc.JdbcStoredProcedureDetector
• jmx.AbstractJsr160Detector
• jmx.JBossDetector
• jmx.JMXDetector
• jmx.Jsr160Detector
• jmx.MX4JDetector
• loop.LoopDetector
• msexchange.MSExchangeDetector
• radius.RadiusAuthDetector
• simple.AsyncLineOrientedDetector.
• simple.AsyncMultilineDetector
• simple.CitrixDetector
• simple.DominoIIOPDetector
• simple.FtpDetector
• simple.HttpDetector
• simple.HttpsDetector
• simple.ImapDetector
• simple.LdapDetector
• simple.LineOrientedDetector
• simple.MultilineHttpDetector
• simple.NotesHttpDetector
• simple.NrpeDetector
• simple.Pop3Detector
• simple.SmtpDetector
• simple.TcpDetector
• smb.SmbDetector
• sms.SmsDetector
• snmp.BgpSessionDetector
• snmp.DiskUsageDetector
• snmp.HostResourceSWRunDetector
• snmp.SnmpDetector.SnmpExchange
• snmp.SnmpDetector
• snmp.Win32ServiceDetector
• ssh.SshDetector
• wmi.WmiDetector

Each of the above are prefixed with org.opennms.netmgt.provision.detector within the web UI. Detailed API documentation for each of the detectors can be found at http://www.opennms.org/documentation/java-apidocs-stable/org/opennms/netmgt/provision/detector/

So we may wish to add a detector for telnet thus:

name  Telnet
class org.opennms.netmgt.provision.detector.simple.TcpDetector

  key   Port
  value 23

The key and value pairs available will be different for each detector.

N.B. Detectors will only detect the service, they will not monitor it. In order to monitor the service, you'll need to look at the documentation for Collectd (pull a value and graph) or Pollerd (check a value is as expected) depending on which style of monitoring you require.

Policies

Policies specify rules which are applied to nodes defined within a provisioning requisition.

List of the available policies at the time of writing:

• MatchingIpInterfacePolicy
• MatchingSnmpInterfacePolicy
• NodeCategorySettingPolicy

Each of the above are prefixed with org.opennms.netmgt.provision.persist.policies within the web UI. Detailed API documentation for each of the policy modules can be found at http://www.opennms.org/documentation/java-apidocs-stable/org/opennms/netmgt/provision/persist/policies/

Policies consist of rules, match types and actions which differ depending on the policy.

N.B. The last policy to match wins if there are multiple policies that may match.

"Match IP interface" Policy

Apply a rule based on the IP address of the interface. If we wanted to ignore interfaces having addresses in the 10.0.0.0/24 RFC1918 address space, we'd define a rule as follows:

name    Ignore_10.0.0.0/24
class   org.opennms.netmgt.provision.persist.policies.MatchingIpInterfacePolicy

   key    action
   value  DO_NOT_PERSIST

   key    matchBehavior
   value  ALL_PARAMETERS

     key    ipAddress
     value  ~10\..*

To explain each of these key and action pairs:

• action DO_NOT_PERSIST
  • Don't persist this interface IP address within the database, it's as if we hadn't seen it. Other options can be found within the MatchingIpInterfacePolicy.Action API documentation:
    • MANAGE / UNMANAGE (specify if the given interface should be polled)
    • ENABLE_SNMP_POLL / DISABLE_SNMP_POLL (specify if the given interface should be SNMP polled)
    • ENABLE_COLLECTION / DISABLE_COLLECTION (specify if stats should be gathered for the interface)

• matchBehavior ALL_PARAMETERS
  • Match all conditions specified below. Other options for this can be found within the BasePolicy.Match API documentation:
    • ALL_PARAMETERS (logical AND)
    • NO_PARAMETERS (logical NOT)
    • ANY_PARAMETER (logical OR)

• ipAddress ~10\..*
  • Match the interface IP address against the regular expression. MatchingIpInterfacePolicy API documentation:
    • hostName

"Match SNMP interface" Policy

Like the Matching IP Interface Policy, this policy controls the whether discovered SNMP interface entities are to be persisted and whether or not OpenNMS should collect performance metrics from the SNMP agent for Interface’s index (MIB2 IfIndex).

In this example, we are going to create a policy that doesn’t persist interfaces that are AAL5 over ATM or type 49 (ifType). Following the same steps as when creating an IP Management Policy, edit the foreign source definition and create a new policy. Let’s call it: “noAAL5s”. We’ll use Match SNMP Interface class for each policy and add a parameter with ifType as the key and “49” as the value.

name    noAAL5s
class   org.opennms.netmgt.provision.persist.policies.MatchingSnmpInterfacePolicy

   key    action
   value  DO_NOT_PERSIST

   key    matchBehaviour
   value  ALL_PARAMETERS

     key    ifType
     value  49

To explain each of these key and action pairs:

• action DO_NOT_PERSIST
  • Don't persist this interface IP address within the database, it's as if we hadn't seen it. Other options can be found within the MatchingIpInterfacePolicy.Action API documentation:
    • MANAGE / UNMANAGE (specify if the given interface should be polled)
    • ENABLE_SNMP_POLL / DISABLE_SNMP_POLL (specify if the given interface should be SNMP polled)
    • ENABLE_COLLECTION / DISABLE_COLLECTION (specify if stats should be gathered for the interface)

• matchBehavior ALL_PARAMETERS
  • Match all conditions specified below. Other options for this can be found within the BasePolicy.Match API documentation:
    • ALL_PARAMETERS (logical AND)
    • NO_PARAMETERS (logical NOT)
    • ANY_PARAMETER (logical OR)

• ifType 49
  • Match the interface type to 49. Other options can be found within the MatchingSnmpInterfacePolicy API documentation:
    • ifAdminStatus
    • ifAlias
    • ifDescr
    • ifIndex
    • ifName
    • ifOperStatus
    • ifSpeed
    • ifType
    • ipAddress
    • netmask
    • physAddr

"Set Node Category" Policy

With this policy, nodes entities will automatically be assigned categories. The policy is defined in the same manner as the IP and SNMP interface polices.

Let's add the 'Production' tag all nodes in this provisioning requisition:

name    Tag production
class   org.opennms.netmgt.provision.persist.policies.NodeCategorySettingPolicy

   key    category
   value  Production

   key    matchBehaviour
   value  ALL_PARAMETERS

To explain each of these key and action pairs:

• category Production
  • Add the category Production

• matchBehaviour ALL_PARAMETERS
  • Match all conditions specified below. Other options for this can be found within the BasePolicy.Match API documentation:
    • ALL_PARAMETERS (logical AND)
    • NO_PARAMETERS (logical NOT)
    • ANY_PARAMETER (logical OR)

In the same way that we did for the other policies, it's possible to add conditions below the match behavior but we didn't do that in this case.

Use Cases

Import data from a file

Services are defined in the file

All the services are known and are defined in the file (See importer daemon)

Services are detected by Detectors

In the file, only the hostname and ip are defined, the capabilities are discovered by the detectors

Mix capabilities detection and fixed service definition ?

Mix the 2 above methods

Interaction with Discovery

Interaction with newSuspect event, how is it processed. is it what the default provision requisition is for ?

Interaction with discoveryd is disabled by default. To enable it set the org.opennms.provisiond.enableDiscovery option to true in the opennms.properties file.

Is it possible to mix discovery and file imports ?

On the same install of openNMS, can you have some parts of the network scanned by discovery, and other parts provisioned by a file import ?

How to add detectors for custom protocols

Example with TcpDetector and/or HttpDetector

Obsolete files

Does provisiond obsolete capsd-configuration ? importer daemon config files ?

Tips and tricks

Renaming provisioning requisitions

Provisioning requisitions can be renamed after creation, but it is not a simple process. The below procedure has been successfully tested on 1.9.90. This may void your warranty.

Content courtesy of Tarus Balog:

Imagine the requisition name is "abc" and you want to change it to "xyz". Steps:

1. Stop OpenNMS, and make a backup of your DB and etc directories in case something goes wrong.

2. change the file names in etc/imports/ and etc/foreign-sources from "abc.xml" to "xyz.xml"

3. change the foreign-source attribute value in each of those files from "abc" to "xyz"

4. In the opennms database, update the foreignsource column of applicable rows in the node table to reflect the new name. Sample SQL:

UPDATE node SET foreignsource = 'xyz' WHERE foreignsource='abc';

5. Start OpenNMS.

Creating policies to control node import behavior

You can define policies to control many aspects of the node import process in Provisiond. Here are some examples:

Assign surveillance categories to a node

This example will assign the category "P-ICMP-1min" to all nodes in a given provisioning requisition:

 <policy class="org.opennms.netmgt.provision.persist.policies.NodeCategorySettingPolicy" name="Category7">
   <parameter value="P-ICMP-1min" key="category"/>
   <parameter value="ALL_PARAMETERS" key="matchBehavior"/>
 </policy>

You could then use this surveillance category and filters to control what nodes have a 60 second ICMP poller assigned.

Enable data collection only for active SNMP interfaces whose name matches a certain pattern

This example will enable data collection (e.g. set the snmpCollect flag to "C") for SNMP interfaces whose names begin with Fa, Gi, or Vl, *and* whose administrative interface state (ifAdminStatus) is "up":

 <policy class="org.opennms.netmgt.provision.persist.policies.MatchingSnmpInterfacePolicy" name="EnableCollection">
   <parameter value="ENABLE_COLLECTION" key="action"/>
   <parameter value="ALL_PARAMETERS" key="matchBehavior"/>
   <parameter value="~(^Fa.*|^Gi.*|^Vl.*)" key="ifName"/>
   <parameter value="1" key="ifAdminStatus"/>
 </policy>