anchor.diff:  
  +[opennms-provisioning]
   = OpenNMS Provisioning
   
  +[provisioning]
   == Provisioning
   
   === Summary
   
  -The introduction of OpenNMS version 1.8 empowers enterprises and
  -services providers like never before with a new service daemon for
  -maintaining the managed entity inventory in OpenNMS. This new daemon,
  -Provisiond, unifies all previous entity control mechanisms available in
  -1.6 (Capsd and the Importer), into a new and improved, massively
  -parallel, policy based provisioning system. System integrators should
  -note, Provisiond comes complete with a RESTFul Web Service API for easy
  -integration with external systems such as CRM or external inventory
  -systems as well as an adapter API for interfacing with other management
  -systems such as configuration management.
  -
  -OpenNMS 1.0, introduced almost a decade ago now, provided a capabilities
  -scanning daemon, Capsd, as the mechanism for provisioning managed
  -entities. Capsd, deprecated with the release of 1.8.0, provided a rich
  -automatic provisioning mechanism that simply required an IP address to
  -seed its algorithm for creating and maintaining the managed entities
  -(nodes, interfaces, and IP based services). Version 1.2 added and
  -XML-RPC API as a more controlled (directed) strategy for provisioning
  -services that was mainly used by non telco based service providers (i.e.
  -managed hosting companies). Version 1.6 followed this up with yet
  -another and more advanced mechanism called the Importer service daemon.
  -The Importer provided large service providers with the ability to
  -strictly control the OpenNMS entity provisioning with an XML based API
  -for completely defining and controlling the entities where no discovery
  -and service scanning scanning was feasible.
  -
  -The Importer service improved OpenNMS' scalability for maintaining
  -managed entity databases by an order of magnitude. This daemon, while
  -very simple in concept and yet extremely powerful and flexible
  -provisioning improvement, has blazed the trail for Provisiond. The
  -Importer service has been in production for 3 years in service provider
  -networks maintaining entity counts of more than 50,000 node level
  -entities on a single instances of OpenNMS. It is a rock solid
  -provisioning tool.
  -
  -Provisiond begins a new era of managed entity provisioning in OpenNMS.
  +The introduction of OpenNMS version 1.8 empowers enterprises and services providers like never before with a new service daemon for maintaining the managed entity inventory in OpenNMS.
  +This new daemon, _Provisiond_, unifies all previous entity control mechanisms available in 1.6 (_Capsd_ and the _Importer_), into a new and improved, massively parallel, policy based provisioning system.
  +System integrators should note, _Provisiond_ comes complete with a _RESTFul Web Service API_ for easy integration with external systems such as CRM or external inventory systems as well as an adapter API for interfacing with other management systems such as configuration management.
  +
  +OpenNMS 1.0, introduced almost a decade ago now, provided a capabilities scanning daemon, Capsd, as the mechanism for provisioning managed entities.
  +_Capsd_, deprecated with the release of 1.8.0, provided a rich automatic provisioning mechanism that simply required an IP address to seed its algorithm for creating and maintaining the managed entities (nodes, interfaces, and IP based services).
  +Version 1.2 added and _XML-RPC API_ as a more controlled (directed) strategy for provisioning services that was mainly used by non telco based service providers (i.e. managed hosting companies).
  +Version 1.6 followed this up with yet another and more advanced mechanism called the _Importer service daemon_.
  +The _Importer_ provided large service providers with the ability to strictly control the OpenNMS entity provisioning with an XML based API for completely defining and controlling the entities where no discovery and service scanning scanning was feasible.
  +
  +The Importer service improved OpenNMS' scalability for maintaining managed entity databases by an order of magnitude.
  +This daemon, while very simple in concept and yet extremely powerful and flexible provisioning improvement, has blazed the trail for Provisiond.
  +The Importer service has been in production for 3 years in service provider networks maintaining entity counts of more than 50,000 node level entities on a single instances of OpenNMS.
  +It is a rock solid provisioning tool.
  +
  +_Provisiond_ begins a new era of managed entity provisioning in OpenNMS.
   
   === Concepts
   
  -Provisioning is a term that is familiar to service providers (a.k.a.
  -operators, a.k.a. telephone companies) and OSS systems but not so much
  -in the non OSS enterprises.
  -
  -Provisiond receives "requests" for adding managed entities via 2 basic
  -mechanisms, the OpenNMS traditional “New Suspect” event, typically via
  -the Discovery daemon, and the import requisition (XML definition of node
  -entities) typically via the Provisioning Groups UI. If you are familiar
  -with all previous releases of OpenNMS, you will recognize the New
  -Suspect Event based Discovery to be what was previously the Capsd
  -component of the auto discovery behavior. You will also recognize the
  -import requisition to be of the Model Importer component of OpenNMS.
  -Provisiond now unifies these two separate components into a massively
  -parallel advanced policy based provisioning service.
  +_Provisioning_ is a term that is familiar to service providers (a.k.a. operators, a.k.a. telephone companies) and OSS systems but not so much in the non OSS enterprises.
  +
  +Provisiond receives "requests" for adding managed entities via 2 basic mechanisms, the OpenNMS traditional "New Suspect" event, typically via the _Discovery daemon_, and the import requisition (XML definition of node entities) typically via the Provisioning Groups UI.
  +If you are familiar with all previous releases of OpenNMS, you will recognize the _New Suspect Event_ based _Discovery_ to be what was previously the _Capsd_ component of the auto discovery behavior.
  +You will also recognize the import requisition to be of the _Model Importer_ component of OpenNMS.
  +_Provisiond_ now unifies these two separate components into a massively parallel advanced policy based provisioning service.
   
   ==== OpenNMS Provisioning Terminology
   
  -The following terms are used with respect to OpenNMS’ provisioning
  -system and are essential for understanding the material presented in
  -this guide.
  -
  - 
  +The following terms are used with respect to OpenNMS’ provisioning system and are essential for understanding the material presented in this guide.
   
   ===== Entity
   
  -Entities are managed objects in OpenNMS such as Nodes, IP interfaces,
  -SNMP Interfaces, and Services.
  +Entities are managed objects in OpenNMS such as Nodes, IP interfaces, SNMP Interfaces, and Services.
   
   ===== Foreign Source and Foreign ID
   
  -The Importer service from 1.6 introduced the idea of foreign sources and
  -foreign IDs. The Foreign Source uniquely identifies a provisioning
  -source and is still a basic attribute of importing node entities into
  -OpenNMS. The concept is to provide an external (foreign) system with a
  -way to uniquely identify itself and any node entities that it is
  -requesting (via a requisition) to be provisioned into OpenNMS. The
  -Foreign ID is the unique node ID maintained in foreign system and the
  -foreign source uniquely identifies the external system in OpenNMS.
  -
  -OpenNMS uses the combination of the foreign source and foreign ID become
  -the unique foreign key when synchronizing the set of nodes from each
  -source with the nodes in the OpenNMS DB. This way the foreign system
  -doesn’t have to keep track of the OpenNMS node IDs that are assigned
  -when a node is first created. This is how Provisiond can
  -
  -decided if a node entity from an import requisition is new, has been
  -changed, or needs to be deleted.
  +The _Importer_ service from 1.6 introduced the idea of foreign sources and foreign IDs.
  +The _Foreign Source_ uniquely identifies a provisioning source and is still a basic attribute of importing node entities into OpenNMS.
  +The concept is to provide an external (foreign) system with a way to uniquely identify itself and any node entities that it is requesting (via a requisition) to be provisioned into OpenNMS.
  +
  +The _Foreign ID_ is the unique node ID maintained in foreign system and the foreign source uniquely identifies the external system in OpenNMS.
  +
  +OpenNMS uses the combination of the foreign source and foreign ID become the unique foreign key when synchronizing the set of nodes from each source with the nodes in the OpenNMS DB.
  +This way the foreign system doesn’t have to keep track of the OpenNMS node IDs that are assigned when a node is first created.
  +This is how _Provisiond_ can decided if a node entity from an import requisition is new, has been changed, or needs to be deleted.
   
   ===== Foreign Source Definition
   
  -Additionally, the foreign source has been extended to also contain
  -specifications for how entities should be discovered and managed on the
  -nodes from each foreign source. The name of the foreign source has
  -become pervasive within the provisioning system and is used to simply
  -some of the complexities by weaving this name into:
  +Additionally, the foreign source has been extended to also contain specifications for how entities should be discovered and managed on the nodes from each foreign source.
  +The name of the foreign source has become pervasive within the provisioning system and is used to simply some of the complexities by weaving this name into:
   
   * the name of the provisioning group in the Web-UI
  -
  -* the name of the file containing the persisted requisition (as well as
  -the pending requisition if it is in this state)
  -
  -* the foreign-source attribute value inside the requisition (obviously,
  -but, this is pointed out to indicate that the file name doesn’t
  -necessarily have to equal the value of this attribute but is highly
  -recommended as an OpenNMS best practice)
  -
  -* the building attribute of the node defined in the requisition (this
  -value is called “site” in the Web-UI and is assigned to the building
  -column of the node’s asset record by Provisiond and is the default value
  -used in the Site Status View feature)
  +* the name of the file containing the persisted requisition (as well as the pending requisition if it is in this state)
  +* the foreign-source attribute value inside the requisition (obviously, but, this is pointed out to indicate that the file name doesn’t necessarily have to equal the value of this attribute but is highly recommended as an OpenNMS best practice)
  +* the building attribute of the node defined in the requisition (this value is called “site” in the Web-UI and is assigned to the building column of the node’s asset record by Provisiond and is the default value used in the Site Status View feature)
   
   ===== Import Requisition
   
  -Import requisition is the terminology OpenNMS uses to represent the set
  -of nodes, specified in XML, to be provisioned from a foreign source into
  -OpenNMS. The requisition schema (XSD) can be found at the following
  -location.
  -
  -http://xmlns.opennms.org/xsd/config/model-import[http://xmlns.opennms.org/xsd/config/model-import]
  +Import requisition is the terminology OpenNMS uses to represent the set of nodes, specified in XML, to be provisioned from a foreign source into OpenNMS.
  +The requisition schema (XSD) can be found at the following location. http://xmlns.opennms.org/xsd/config/model-import[http://xmlns.opennms.org/xsd/config/model-import]
   
   ===== Auto Discovery
   
  -Auto discovery is the term used by OpenNMS to characterize the automatic
  -provisioning of nodes entities. Currently, OpenNMS uses an ICMP ping
  -sweep to find IP address on the network. For the IPs that respond and
  -that are not currently in the DB, OpenNMS generates a new suspect event.
  -When this event is received by Provisiond, it creates a node and it
  -begins a node scan based on the default foreign source definition.
  +Auto discovery is the term used by OpenNMS to characterize the automatic provisioning of nodes entities.
  +Currently, OpenNMS uses an ICMP ping sweep to find IP address on the network.
  +For the IPs that respond and that are not currently in the DB, OpenNMS generates a new suspect event.
  +When this event is received by Provisiond, it creates a node and it begins a node scan based on the default foreign source definition.
   
   ===== Directed Discovery
   
  -Provisiond takes over for the Model Importer found in version 1.6 which
  -implemented a unique, first of its kind, controlled mechanism for
  -specifying managed entities directly into OpenNMS from one or more data
  -sources. These data sources often were in the form of an in-housed
  -developed inventory or stand-alone provisioning system or even a set of
  -element
  -
  - 
  -
  -management systems. Using this mechanism, OpenNMS is directed 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.
  +Provisiond takes over for the Model Importer found in version 1.6 which implemented a unique, first of its kind, controlled mechanism for specifying managed entities directly into OpenNMS from one or more data sources.
  +These data sources often were in the form of an in-housed developed inventory or stand-alone provisioning system or even a set of element management systems.
  +Using this mechanism, OpenNMS is directed 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.
   
   ===== Enhanced Directed Discovery
   
  -Directed discovery is enhanced with the capability to scan nodes that
  -have been directed nodes for entities (interfaces.
  +Directed discovery is enhanced with the capability to scan nodes that have been directed nodes for entities (interfaces.
   
   ===== Policy Based Discovery
   
  -The phrase, Policy based Directed Discovery, is a term that represents
  -the latest step in OpenNMS’ provisioning evolution and best describes
  -the new provisioning architecture now in OpenNMS for maintaining its
  -inventory of managed entities. This term describes the control that is
  -given over the Provisioning system to OpenNMS users for managing the
  -behavior of the NMS with respect to the new entities that are being
  -discovered. Current behaviors include persistence, data collection,
  -service monitoring, and categorization policies.
  +The phrase, Policy based Directed Discovery, is a term that represents the latest step in OpenNMS’ provisioning evolution and best describes the new provisioning architecture now in OpenNMS for maintaining its inventory of managed entities.
  +This term describes the control that is given over the Provisioning system to OpenNMS users for managing the behavior of the NMS with respect to the new entities that are being discovered.
  +Current behaviors include persistence, data collection, service monitoring, and categorization policies.
   
   ==== Addressing Scalability
   
  -The explosive growth and density of the IT systems being deployed today
  -to support not traditional IP services is impacting management systems
  -like never before and is demanding from them tremendous amounts of
  -scalability. The scalability of a management system is defined by its
  -capacity for maintaining large numbers of managing entities coupled with
  -its efficiency of managing the entities.
  -
  -Today, It is not uncommon for OpenNMS deployments to find node entities
  -with tens of thousands of physical interfaces being reported by SNMP
  -agents due to virtualization (virtual hosts, interfaces, as well as
  -networks). An NMS must be capable of using the full capacity every
  -resource of its computing platform (hardware and OS) as effectively as
  -possible in order to manage these environments. The days of writing
  -scripts or single threaded applications will just no longer be able to
  -do the work required an NMS when dealing with the scalability challenges
  -facing systems and systems administrators working in this domain.
  +The explosive growth and density of the IT systems being deployed today to support not traditional IP services is impacting management systems like never before and is demanding from them tremendous amounts of scalability.
  +The scalability of a management system is defined by its capacity for maintaining large numbers of managing entities coupled with its efficiency of managing the entities.
  +
  +Today, It is not uncommon for OpenNMS deployments to find node entities with tens of thousands of physical interfaces being reported by SNMP agents due to virtualization (virtual hosts, interfaces, as well as networks).
  +An NMS must be capable of using the full capacity every resource of its computing platform (hardware and OS) as effectively as possible in order to manage these environments.
  +The days of writing scripts or single threaded applications will just no longer be able to do the work required an NMS when dealing with the scalability challenges facing systems and systems administrators working in this domain.
   
   ===== Parallelization and Non-Blocking I/O
   
  -Squeezing out every ounce of power from a management system’s platform
  -(hardware and OS) is absolutely required to complete all the work of a
  -fully functional NMS such as OpenNMS. Fortunately, the hardware and CPU
  -architecture of a modern computing platform provides multiple CPUs with
  -multiple cores having instruction sets that include support for atomic
  -operations. While these very powerful resources are being provided by
  -commodity systems, it makes the complexity of developing applications to
  -use them vs. not using them, orders of magnitude more complex. However,
  -because of scalability demands of our complex IT environments,
  -multi-threaded NMS applications are now essential and this has fully
  -exposed the complex issues of concurrency in software development.
  -
  -OpenNMS has stepped up to this challenge with its new concurrency
  -strategy. This strategy is based on a technique that combines the
  -efficiency of parallel (asynchronous) operations (traditionally used by
  -most effectively by single threaded applications) with the power of a
  -fully current, non-blocking, multi-threaded design. The non-blocking
  -component of this new concurrency strategy added greater complexity but
  -OpenNMS gained orders of magnitude in increased scalability. Note: Java
  -Runtimes, based on the Sun JVM, have provided implementations for
  -processor based atomic operations and is the basis for OpenNMS’
  -non-blocking concurrency algorithms.
  +Squeezing out every ounce of power from a management system’s platform (hardware and OS) is absolutely required to complete all the work of a fully functional NMS such as OpenNMS.
  +Fortunately, the hardware and CPU architecture of a modern computing platform provides multiple CPUs with multiple cores having instruction sets that include support for atomic operations.
  +While these very powerful resources are being provided by commodity systems, it makes the complexity of developing applications to use them vs. not using them, orders of magnitude more complex.
  +However, because of scalability demands of our complex IT environments, multi-threaded NMS applications are now essential and this has fully exposed the complex issues of concurrency in software development.
  +
  +OpenNMS has stepped up to this challenge with its new concurrency strategy.
  +This strategy is based on a technique that combines the efficiency of parallel (asynchronous) operations (traditionally used by most effectively by single threaded applications) with the power of a fully current, non-blocking, multi-threaded design.
  +The non-blocking component of this new concurrency strategy added greater complexity but OpenNMS gained orders of magnitude in increased scalability.
  +
  +NOTE: Java Runtimes, based on the Sun JVM, have provided implementations for processor based atomic operations and is the basis for OpenNMS’ non-blocking concurrency algorithms.
   
   ===== Provisioning Policies
   
  -Just because you can, doesn’t mean you should! Because the massively
  -parallel operations being created for Provisiond allows tremendous
  -numbers of nodes, interfaces, and services to be very rapidly discovered
  -and persisted, doesn’t
  -
  -mean it should. A policy API was created for Provisiond that allows
  -implementations to be developed that can be applied to control the
  -behavior of Provisiond. The 1.8 release includes a set of flexible
  -provisioning policies that control the persistence of entities and their
  -attributes constrain monitoring behavior.
  -
  - 
  -
  -When nodes are imported or re-scanned, there is, potentially, a set of
  -zero or more provisioning policies that are applied. The policies are
  -defined in the foreign source’s definition. The policies for an
  -auto-discovered node or nodes from provisioning groups that don’t have a
  -foreign source definition, are the policies defined in the default
  -foreign source definition.
  +Just because you can, doesn’t mean you should!
  +Because the massively parallel operations being created for _Provisiond_ allows tremendous numbers of nodes, interfaces, and services to be very rapidly discovered and persisted, doesn’t mean it should.
  +A _policy API_ was created for _Provisiond_ that allows implementations to be developed that can be applied to control the behavior of _Provisiond_.
  +The 1.8 release includes a set of flexible provisioning policies that control the persistence of entities and their attributes constrain monitoring behavior.
  +
  +When nodes are imported or re-scanned, there is, potentially, a set of zero or more provisioning policies that are applied.
  +The policies are defined in the foreign source’s definition.
  +The policies for an auto-discovered node or nodes from provisioning groups that don’t have a foreign source definition, are the policies defined in the default foreign source definition.
   
   ===== The Default Foreign Source Definition
   
  -Contained in the libraries of the Provisioning service is the "template"
  -or default foreign source. The template stored in the library is used
  -until the OpenNMS admin user alters the default from the Provisioning
  -Groups WebUI. Upon edit, this template is exported to the OpenNMS etc/
  -directory with the file name: "default-foreign-source.xml".
  +Contained in the libraries of the Provisioning service is the "template" or default foreign source.
  +The template stored in the library is used until the OpenNMS admin user alters the default from the _Provisioning Groups_ WebUI.
  +Upon edit, this template is exported to the OpenNMS 'etc/' directory with the file name: 'default-foreign-source.xml'.
   
   [source, xml]
   ----
  
positive.code: <foreign-source date-stamp="2009-10-16T18:04:12.844-05:00"
                  name="default"
                  xmlns="http://xmlns.opennms.org/[http://xmlns.opennms.org/xsd/config/foreign-source">
    <scan-interval>1d</scan-interval>
    <detectors>
      <detector
          class="org.opennms.netmgt.provision.detector.datagram.DnsDetector"
          name="DNS"/>
      <detector
          class="org.opennms.netmgt.provision.detector.simple.FtpDetector"
          name="FTP"/>
      <detector
          class="org.opennms.netmgt.provision.detector.simple.HttpDetector"
          name="HTTP"/>
      <detector
          class="org.opennms.netmgt.provision.detector.simple.HttpsDetector"
          name="HTTPS"/>
      <detector
          class="org.opennms.netmgt.provision.detector.icmp.IcmpDetector"
          name="ICMP"/>
      <detector
          class="org.opennms.netmgt.provision.detector.simple.ImapDetector"
          name="IMAP"/>
      <detector
          class="org.opennms.netmgt.provision.detector.simple.LdapDetector"
          name="LDAP"/>
      <detector
          class="org.opennms.netmgt.provision.detector.simple.NrpeDetector"
          name="NRPE"/>
      <detector
          class="org.opennms.netmgt.provision.detector.simple.Pop3Detector"
          name="POP3"/>
      <detector
          class="org.opennms.netmgt.provision.detector.radius.RadiusAuthDetector"
          name="Radius"/>
      <detector
          class="org.opennms.netmgt.provision.detector.simple.SmtpDetector"
          name="SMTP"/>
      <detector
          class="org.opennms.netmgt.provision.detector.snmp.SnmpDetector"
          name="SNMP"/>
      <detector class="org.opennms.netmgt.provision.detector.ssh.SshDetector"
                name="SSH"/>
    </detectors>
    <policies/>
  </foreign-source>
  
negative.code: 
  == Getting Started
  
  An NMS is of no use until it is setup for monitoring and entities are added to the system.
  OpenNMS installs with a base configuration with a configuration that is sufficient get service level monitoring and performance management quickly up and running.
  As soon as managed entities are provisioned, the base configuration will automatically begin monitoring and reporting.
  
  Generally speaking, there are two methods of provisioning in OpenNMS: _Auto Discovery_ and _Directed Discovery_.
  We'll start with _Auto Discovery_, but first, we should quickly review the configuration of SNMP so that newly discovered devices can be immediately scanned for entities as well as have reporting and thresholding available.
  
  === Provisioning the SNMP Configuration
  
  OpenNMS requires that the SNMP configuration to be properly setup for your network in order to properly understand Network and Node topology as well as to automatically enabled performance data collection.
  Network topology is updated as nodes (a.k.a. devices or hosts) are provisioned.
  Navigate to the _Admin/Configure SNMP Community Names_ as shown below.
  
  NOTE: Provisiond includes an option to add community information in the _Single Node_ provisioning interface.
  This, is equivalent of entering a single IP address in the screen with the convenience of setting the community string at the same time a node is provisioned.
  See the _Quick Node Add_ feature below for more details about this capability.
  
  This screen sets up SNMP within OpenNMS for agents listening on IP addresses 10.1.1.1 through 10.254.254.254.
  These settings are optimized into the 'snmp-configuration.xml' file.
  Optimization means that the minimal configuration possible will be written.
  Any IP addresses already configured that are eclipsed by this range will be removed.
  Here is the resulting configuration.
  
  [source, xml]
  .Sample snmp-config.xml
  