anchor.diff:  
   == 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.
  +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.
  +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
  
positive.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[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[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
  
  
negative.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>
  