Fine-Grained provisioning using provision.pl

provision.pl provides an example command-line interface to the provisioning-related Horizon REST API endpoints.

The script has many options, but the first three optional parameters are described here:

You can run ${OPENNMS_HOME}/bin/provision.pl --help to see all of the available options.

--username (default: admin)
--password (default: admin)
--url (default: http://localhost:8980/opennms/rest)

Create a new requisition

provision.pl provides easy access to the requisition REST service using the requisition option:

${OPENNMS_HOME}/bin/provision.pl requisition customer1

This command will create a new, empty (containing no nodes) requisition in Horizon.

The new requisition starts life in the pending state. This lets you iteratively build the requisition and then later actually import the nodes in the requisition into Horizon. This handles all adds/changes/deletes at once. So, you could be making changes all day and then at night either have a schedule in Horizon that imports the group automatically or you can send a command through the REST service from an outside system to have the pending requisition imported/reimported.

You can get a list of all existing requisitions with the list option of the provision.pl script:

${OPENNMS_HOME}/bin/provision.pl list

Create a new Node

${OPENNMS_HOME}/bin/provision.pl node add customer1 1 node-a

This command creates a node element in the requisition customer1 called node-a using the script’s node option. The node’s foreign-ID is 1 but it can be any alphanumeric value as long as it is unique within the requisition. Note the node has no interfaces or services yet.

Add an Interface Element to that Node

${OPENNMS_HOME}/bin/provision.pl interface add customer1 1 127.0.0.1

This command adds an interface element to the node element using the interface option to the provision.pl command and it can now be seen in the pending requisition by running provision.pl requisition list customer1.

Add a Couple of Services to that Interface

${OPENNMS_HOME}/bin/provision.pl service add customer1 1 127.0.0.1 ICMP
${OPENNMS_HOME}/bin/provision.pl service add customer1 1 127.0.0.1 SNMP

This adds the 2 services to the specified 127.0.0.1 interface and is now in the pending requisition.

Set the Primary SNMP Interface

${OPENNMS_HOME}/bin/provision.pl interface set customer1 1 127.0.0.1 snmp-primary P

This sets the 127.0.0.1 interface to be the node’s Primary SNMP interface.

Add a couple of Node Categories

${OPENNMS_HOME}/bin/provision.pl category add customer1 1 Routers
${OPENNMS_HOME}/bin/provision.pl category add customer1 1 Production

This adds the two categories to the node and is now in the pending requisition.

These categories are case-sensitive but do not have to be already defined in Horizon. They will be created on the fly during the import if they do not already exist.

Setting Asset Fields on a Node

${OPENNMS_HOME}/bin/provision.pl asset add customer1 1 serialnumber 9999

This will add value of 9999 to the asset field: serialnumber.

Deploy the Import Requisition (Creating the Group)

${OPENNMS_HOME}/bin/provision.pl requisition import customer1

This will cause Horizon Provisiond to import the pending customer1 requisition. The formerly pending requisition will move into the deployed state inside Horizon.

Deleting a Node from a Requisition

Very much the same as the add, except that a single delete command and a re-import is required. What happens is that the audit phase is run by Provisiond and it will be determined that a node has been removed from the requisition and the node will be deleted from the DB and all services will stop activities related to it.

${OPENNMS_HOME}/bin/provision.pl node delete customer1 1 node-a
${OPENNMS_HOME}/bin/provision.pl requisition import customer1

This completes the life cycle of managing a node element, iteratively, in a import requisition.