Quickstart

To give an example we want to provide two requisitions from an poor man’s inventory as XLS file (myInventory.xls). The first requisition has a worksheet containing all routers and the second worksheet has all servers of our network. This example can be found in examples/source/xlsExample.

myRouter.png
Figure 1. Worksheet with Router

In line 5, 6 and 7 there is a router defined with more than one IP interface. All three interfaces will be manually provisioned. The private IP interface with 192.168.30.1 is not used for SNMP agent communication. The services ICMP, SNMP and StrafePing are forced on some IP interfaces. For all other IP interfaces you can use the OpenNMS Provisiond mechanism scanning IP interface table from SNMP and the detectors for additional services. The server will also be categorized in Backbone and Office.

myServer.png
Figure 2. Worksheet with Server

The OpenNMS requisition should be provided via HTTP and we use OpenNMS Provisiond to synchronize it on a regular basis. We build the following file structure:

File structure with two requisitions using a single spreadsheet
[root@localhost opennms-pris]# pwd && tree
/opt/opennms-pris
.
├── documentation
├── examples
├── global.properties
├── lib
├── opennms-pris.jar
├── opennms-pris.service
├── opennms-pris.sh
├── requisitions/
|   ├── myInventory.xls
|   ├── myRouter
|   |   └── requisition.properties
|   └── myServer
|       └── requisition.properties
└── scriptsteps
    ├── custom
    └── default

Providing the OpenNMS requisition over HTTP we create the following global.properties

Use the HTTP web server
### File: global.properties
# Start web server
# The web server listens on all interfaces and can be accessed on TCP port 8000
# URL: http://${your-ip}:8000/requisitions/${name-requisition-cfg}

driver = http
host = 0.0.0.0
port = 8000

The HTTP server listens on localhost port 8000/TCP. We have to create two directories, myServer and myRouter, each containing a requisition.properties file. Both requisition.properties files reference the main myInventory.xls file which contains two worksheets named myServer and myRouter. The requisition.properties is the same for both requisitions. It is possible to create different script or mapping steps for each requisition.

Configuration of the myRouter requisition
### File: myRouter/requisition.properties
# This example imports devices from a spreadsheet
# named "myRouter" from the myInventory.xls file
# Path to the XLS fils is relative to
# requisitions.properties
source = xls
source.file = ../myInventory.xls

### default no-operation mapper
mapper = echo
Configuration of the myServer requisition
### File: myRouter/requisition.properties
# This example imports devices from a spreadsheet
# named "myRouter" from the myInventory.xls file
# Path to the XLS fils is relative to
# requisitions.properties
source = xls
source.file = ../myInventory.xls

### default no-operation mapper
mapper = echo

It is not necessary to restart the PRIS server if you change properties files or the XLS file. All changes will be applied from the next request against the server. With the given configuration you see the result of the OpenNMS requisitions with the URL http://localhost:8000/requisitions/myRouter and http://localhost:8000/requisitions/myServer which can be used in OpenNMS Provisiond.

requisitions-http.png
Figure 3. Output of PRIS server for both configured requisitions

To get the requisition provided from PRIS automatically into OpenNMS you can configure Provisiond with a schedule. Create following to entries in provisiond-configuration.xml and they will automatically be synchronized every night at 0h:0m:0s and 1h:0m:0s.

Configuration from OpenNMS Provisiond with provisiond-configuration.xml
<requisition-def import-name="myRouter" import-url-resource="http://localhost:8000/requisitions/myRouter">
  <cron-schedule>0 0 0 * * ? *</cron-schedule>
</requisition-def>

<requisition-def import-name="myServer" import-url-resource="http://localhost:8000/requisitions/myServer">
  <cron-schedule>0 0 1 * * ? *</cron-schedule>
</requisition-def>