anchor.diff:  <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"/>
  +    <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>
  
positive.code: 
  = OpenNMS 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.
  
  === 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.
  
  ==== 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.
  
   
  
  ===== Entity
  
  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.
  
  ===== 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:
  
  * 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)
  
  ===== 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]
  
  ===== 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.
  
  ===== 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.
  
  ===== Enhanced Directed Discovery
  
  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.
  
  ==== 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.
  
  ===== 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.
  
  ===== 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.
  
  ===== 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".
  
  [source, xml]
  ----
  
negative.code: However, If an IP address is then configured that is within the range,
  the range will be split into two separate ranges and a specific entry is
  added. For example, if a configuration was added through the same UI for
  the IP: 10.12.23.32 having the community name `public`, then the
  resulting configuration will be:
  
  [source,xml]
  ----
  <?xml version="1.0" encoding="UTF-8"?>
  <snmp-config xmlns="http://xmlns.opennms.org/xsd/config/snmp"
               port="161"
               retry="3"
               timeout="800"
               read-community="public"
               version="v1"
               max-vars-per-pdu="10">
  
      <definition retry="1" timeout="2000" read-community="YrusoNoz" version="v2c">
          <range begin="10.1.1.1" end="10.12.23.31"/>
          <range begin="10.12.23.33" end="10.254.254.254"/>
      </definition>
  
      <definition retry="1" timeout="2000" read-community="public" version="v2c">
          <specific>10.12.23.32</specific>
      </definition>
  </snmp-config>
  ----
  
  NOTE: the bold IP addresses show where the range was split and the specific with community name "public" was added.
  
  Now, with SNMP configuration provisioned for our 10 network, we are ready to begin adding nodes.
  Our first example will be to automatically discovery and add all managed entities (nodes, IP interfaces, SNMP Interfaces, and Monitored IP based Services).
  We will then give an example of how to be more _directed_ and deliberate about your discovery by using _Provisioning Groups_.
  
  Automatically discovered entities are analyzed, persisted to the relational data store, and then managed based on the policies defined in the default foreign source definition.
  This is very similar to the way that entities were handled by Capsd by with finer grained sense of control.
  
  ==== Automatic Discovery
  
  Currently in OpenNMS, the ICMP is used to automatically provision node entities into OpenNMS.
  This functionality has been in OpenNMS since is 1.0 release, however, in 1.8, a few of the use cases have been updated with _Provisiond’s_ replacement of _Capsd_.
  
  ===== Separation of Concerns
  
  Version 1.8 _Provisiond_ separates what was called _Capsd_ scanning in to 3 distinct phases: entity scanning, service detection, and node merging.
  These phases are now managed separately by Provisiond.
  Immediately following the import of a node entity, tasks are created for scanning a node to discover the node entity’s interfaces (SNMP and IP).
  As interfaces are found, they are persisted and tasks are scheduled for service detection of each IP interface.
  
  For auto discovered nodes, a node merging phase is scheduled.
  Nodes that have been directly provisioned will not be included in the node process.
  Only in the case the 2 where nodes that have been automatically discovered that appear to be the same node with the node merging phase be activated.
  
  NOTE: the use case and redesign of node merging is still an outstanding issue with the 1.8.0 release
  
  ==== Enhanced Directed Discovery
  
  This new form of provisioning first appears in OpenNMS with version 1.8 and the new Provisiond service.
  It combines the benefits of the Importer’s strictly controlled methodology of directed provisioning (from version 1.6) with OpenNMS’ robustly flexible auto discovery.
  _Enhanced Directed discovery_ begins with an enhanced version of the same import requisition used in directed provisioning and completes with a policy influenced persistence phase that sorts though the details of all the entities and services found during the entity and service scanning phase.
  
  If you are planning to use this form of provisioning, it important to understand the conceptual details of how _Provisiond_ manages entities it is _directed_ to provision.
  This knowledge will enable administrators and systems integrators to better plan, implement, and resolve any issues involved with this provisioning strategy.
  
  ===== Understanding the Process
  
  There are 3 phases involved with directing entities to be discovered: import, node scan, and service scan.
  The import phase also has sub phases: marshal, audit, limited SNMP scan, and re-parent.
  
  ====== Marshal and Audit Phases
  
  It is important to understand that the nodes requisitioned from each foreign source are managed as a complete set.
  Nodes defined in a requisition from the foreign source _CRM_ and _CMDB_, for example, will be managed separately from each other even if they should contain exactly the same node definitions.
  To OpenNMS, these are individual entities and they are managed as a set.
  
  Requisitions are referenced via a URL.
  Currently, the URL can be specified as one of the following protocols: FILE, HTTP, HTTPS, and DNS.
  Each protocol has a protocol handler that is used to stream the XML from a _foreign source_, i.e. http://inv.corp.org/import.cgi?customer=acme or `file:/opt/opennms/etc/imports/acme.xml`.
  The DNS protocol is a special handler developed for Provisioning sets of nodes as a _foreign-source_ from a corporate DNS server.
  See DNS Protocol Handler for details.
  
  Upon the import request (either on schedule or on demand via an Event) the requisition is marshaled into Java objects for processing.
  The nodes defined in the requisition represent what OpenNMS should have as the current set of managed entities from that foreign source.
  The audit phase determines for each node defined (or not defined) in the requisition which are to be processed as an _Add_, _Update_, or _Delete_ operation during the _Import Phase_.
  This determination is made by comparing the set foreign IDs of each node in the requisition set with the set of foreign IDs of currently managed entities in OpenNMS.
  
  The intersection of the IDs from each set will become the Update operations, the extra set of foreign IDs that are in the requisition become the Add operations, and the extra set of foreign IDs from the managed entities become the Delete operations.
  This implies that the foreign IDs from each foreign source must be unique.
  
  Naturally, the first time an import request is processed from a foreign source there will be zero (0) node entities from the set of nodes currently being managed and each node defined in the requisition will become an Add Operation.
  If a requisition is processed with zero (0) node definitions, all the currently managed nodes from that foreign source will become Delete operations (all the nodes, interfaces, outages, alarms, etc. will be removed from OpenNMS).
  
  When nodes are provisioned using the Provisioning Groups Web-UI, the requisitions are stored on the local file system and the file protocol handler is used to reference the requisition.
  Each Provisioning Group is a separate foreign source and unique foreign IDs are generated by the Web-UI.
  An MSP might use Provisioning Groups to define the set of nodes to be managed by customer name where each customer’s set of nodes are maintained in a separate Provisioning Group.
  
  ====== Import Phase
  
  The import phase begins when Provisiond receives a request to import a requisition from a URL.
  The first step in this phase is to load the requisition and marshal all the node entities defined in the requisition into Java objects.
  
  If any syntactical or XML structural problems occur in the requisition, the entire import is abandoned and no import operations are completed.
  
  Once the requisition is marshaled, the requisition nodes are audited against the persisted node entities.
  The set of requisitioned nodes are compared with a subset of persisted nodes and this subset is generated from a database query using the foreign source defined in the requisition.
  The audit generates one of three operations for each requisition node: _insert_, _update_, _delete_ based on each requisitioned node’s foreign ID.
  Delete operations are created for any nodes that are not in the requisition but are in the DB subset, update operations are created for requisition nodes that match a persisted node from the subset (the intersection), and insert operations are created from the remaining requisition nodes (nodes in the requisition that are not in the DB subset).
  
  If a requisition node has an interface defined as the Primary SNMP interface, then during the update and insert operations the node will be scanned for minimal SNMP attribute information.
  This scan find the required node and SNMP interface details required for complete SNMP support of the node and only the IP interfaces defined in the requisition.
  
  NOTE: this not the same as Provisiond SNMP discovery scan phases: node scan and interface scan.
  
  ====== Node Scan Phase
  
  Where directed discovery leaves off and enhanced directed discovery begins is that after all the operations have completed, directed discovery is finished and enhanced directed discovery takes off.
  The requisitioned nodes are scheduled for node scans where details about the node are discovered and interfaces that were not directly provisioned are also discovered.
  All physical (SNMP) and logical (IP) interfaces are discovered and persisted based on any _Provisioning Policies_ that may have defined for the foreign source associated with the import requisition.
  
  ====== Service Scan (detection) Phase
  
  Additionally, the new Provisiond enhanced directed discovery mechanism follows interface discovery with service detection on each IP interface entity.
  This is very similar to the Capsd plugin scanning found in all former releases of OpenNMS accept that the foreign source definition is used to define what services should be detected on these interfaces found for nodes in the import requisition.
  
  == Import Handlers
  
  