
[[ga-provisioning-introduction]]
= Provisioning
:description: Overview of inventory provisioning in {page-component-title}: automatic and directed discovery, and node asset import.

Provisioning is a process that imports node and service definitions either from an external source, such as DNS or HTTP, or via the {page-component-title} web UI.
The Provisiond daemon maintains your managed entity inventory through policy-based provisioning.

Provisiond comes with a RESTful Web Service API for easy integration with external systems such as a configuration management database (CMDB) or external inventory systems.
It also includes an adapter API for interfacing with other management systems such as configuration management.

[[provisioning-works]]
== How it works

Provisiond receives requests to add managed entities (nodes, IP interfaces, SNMP interfaces, services) via three basic mechanisms:

* xref:deep-dive/provisioning/auto-discovery.adoc[Automatic discovery] (typically via the Discovery daemon).
* xref:deep-dive/provisioning/directed-discovery.adoc[Directed discovery] using an import requisition (typically via the Provisioning UI).
* xref:development:rest/nodes.adoc[Node asset import] through the REST API or the https://docs.opennms.com/pris/1.2.0/index.html[provisioning integration server] (PRIS).

{page-component-title} lets you control Provisiond behavior by creating provisioning policies that include scanning frequency, IP ranges, and which services to detect.

Regardless of the method, provisioning is an iterative process: you will need to fine-tune your results to exclude or add things to what you monitor.

[[discovery-auto]]
== Automatic discovery

{page-component-title} uses an ICMP ping sweep to find IP addresses on the network and provision node entities.
Use <<deep-dive/provisioning/auto-discovery.adoc#ga-provisioning-auto-discovery-detectors, auto discovery with detectors>> in addition to the ICMP IP address ping to specify services that you need to detect.

Use xref:reference:provisioning/handlers/introduction.adoc#import-handlers[import handlers] to provision nodes from other data sources such as DNS zone records and VMware.

Automatically discovered entities are analyzed, persisted to the relational data store, and managed based on the policies defined in the <<deep-dive/provisioning/foreign-source.adoc#foreign-source-definition, default foreign source definition>>:

* Scanned to discover node entity’s interfaces (SNMP and IP).
* Interfaces are persisted.
* Service detection of each IP interface.
* Node merging.

NOTE: Merging occurs only when two automatically discovered nodes appear to be the same node.
Nodes <<deep-dive/provisioning/directed-discovery.adoc#discovery-directed, discovered directly>> are not included in the node merging process.

[[discovery-directed]]
== Directed discovery

Directed discovery lets you specify what you want to provision based on an existing data source such as an in-house inventory, a standalone provisioning system, or a set of element management systems.
Using an import requisition, this mechanism directs {page-component-title} to add, update, or delete a node entity exactly as defined by the external source.
No discovery process is used for finding more interfaces or services.

IMPORTANT: An import requisition is a definition of node entities to provision from an external source into {page-component-title}.
See the https://xmlns.opennms.org/xsd/config/model-import[requisition schema] (XSD) for more information.

=== The process

Directed discovery involves three phases:

* Import (with three sub-phases)
** Marshal
** Audit
** Limited SNMP scan
* Node scan
* Service scan

The import phase begins when Provisiond receives a request to import a requisition from a URL.
The requisition is marshalled into Java objects for processing.
An audit, based on the unique foreign ID of the foreign source, determines whether the node already exists; the imported object is then added, updated, or deleted from the inventory.

NOTE: If any syntactical or structural problems occur in the requisition, the entire import is abandoned and no import operations are completed.

If a requisition node has an interface defined as the primary SNMP interface, the node is scanned for minimal SNMP attribute information during the update and add operations.

The node-scan phase discovers details about the node and interfaces that were not directly provisioned.
All physical (SNMP) and logical (IP) interfaces are discovered and persisted based on any provisioning policies that may have been defined for the foreign source associated with the import requisition.

After interface discovery, provisiond moves to service detection on each IP interface entity.

