
[[auto-discovery]]
= Auto Discovery
:description: How to automatically add nodes to {page-component-title} through discovery scans.

Auto discovery is the process of automatically adding nodes to {page-component-title}.
This is done through discovery, which is run either periodically on a schedule or as one-off, unscheduled operations.

NOTE: Make sure you complete the tasks in xref:quick-start/inventory.adoc[] before adding nodes.

== Configure discovery

Configuring discovery specifies the parameters that {page-component-title} uses when scanning for nodes.
To configure discovery for a requisition, follow these steps:

. Log in to the {page-component-title} web UI as a user with admin permissions.

. Click menu:Manage Inventory[Scheduled Node Discovery] in the side menu.
. Or, click menu:Administration[Configure OpenNMS] in the side menu, then under Provisioning, click *Configure Discovery*.
+
NOTE: To configure a discovery scan to run only once, click *Run Single Discovery Scan* instead, and configure it as appropriate.

. (Optional) Under General Settings, define the scheduling options (sleep time, retries, timeout, and so on).
. Under Specific Addresses, click *Add New* to add an IP address for discovery:
** Type the target IP address, the timeout, and the maximum number of retries in the appropriate boxes.
** Choose a requisition from the *Foreign Source* list.
Any discovered nodes will be added to this requisition upon discovery.
** (Optional) If you have any installed Minions, choose one from the *Location* list.
** Click *Add* to save the configuration settings.
. (Optional) Include specific URLs by clicking *Add New* under Include URLs:
** Type the target URL, the timeout, and the maximum number of retries in the appropriate boxes.
** Choose a requisition from the *Foreign Source* list.
** (Optional) If you have any installed Minions, choose one from the *Location* list.
** Click *Add* to save the configuration settings.
. (Optional) Exclude specific URLs by clicking *Add New* under Exclude URLs:
** Type the target URL in the *URL* box.
** Choose a requisition from the *Foreign Source* list.
** (Optional) If you have any installed Minions, choose one from the *Location* list.
** Click *Add* to save the configuration settings.
. (Optional) Set an inclusive range of IP addresses to add for discovery by clicking *Add New* under Include Ranges:
** Type the beginning and ending IP addresses, the timeout, and the maximum number of retries in the appropriate boxes.
** Choose a requisition from the *Foreign Source* list.
** (Optional) If you have any installed Minions, choose one from the *Location* list.
** Click *Add* to save the configuration settings.
. (Optional) Set an inclusive range to remove from discovery by clicking *Add New* under Exclude Ranges:
** Type the beginning and ending IP addresses in the appropriate boxes.
** (Optional) If you have any installed Minions, choose one from the *Location* list.
** Click *Add* to save the configuration settings.
. Click *Save and Restart Discovery*.

After the discovery process is finished, navigate to the requisition that you specified to view the nodes that were found:

. Click menu:Manage Inventory[Provisioning Requisitions] in the side menu, then click *Edit Default FS*.
. Or, click menu:Administration[Configure OpenNMS] in the side menu, then under Provisioning, click *Manage Provisioning Requisitions*.
. Find the requisition that you specified for the discovery process.
. (Optional) Click *Edit* beside the requisition's name to manage its nodes.
** Click *Edit* beside a node's name to update its information.
** Click *Delete* beside a node's name to remove it from the requisition.
** Click *Synchronize* to update the {page-component-title} database with any changes.

Repeat the steps in this section for each requisition that you want to provision.

[[ga-provisioning-auto-discovery-detectors]]
== Automatic discovery detectors

Automatic discovery with detectors lets you specify the services to detect, as well as the ICMP ping, for specified IP addresses.
Discovery sends a new suspect event only when the specified detectors succeed.

NOTE: A definition that does not include specific detectors will fall back to ICMP ping for discovery.

.Sample discovery configuration with detectors
[source, xml]
----
<discovery-configuration xmlns="http://xmlns.opennms.org/xsd/config/discovery" packets-per-second="1"
    initial-sleep-time="30000" restart-sleep-time="86400000" retries="1" timeout="2000">

    <definition location="MINION" foreign-source="ApexOffice">

		<detectors>
			<detector name="reverse-dns-lookup" class-name="org.opennms.netmgt.provision.detector.rdns.ReverseDNSLookupDetector"/>
			<detector name="SNMP" class-name="org.opennms.netmgt.provision.detector.snmp.SnmpDetector">
				<parameter key="timeout" value="5000"/>
				<parameter key="ttl" value="120000"/>
			</detector>
		</detectors>

		<specific>10.0.0.5</specific>

		<include-range>
			<begin>192.168.0.1</begin>
			<end>192.168.0.254</end>
		</include-range>

    <exclude-range>
			<begin>192.168.0.120</begin>
			<end>192.168.0.125</end>
		</exclude-range>

		<include-url>file:/opt/opennms/etc/include.txt</include-url>

	</definition>

</discovery-configuration>
----

== Configure manual discovery

In addition to the configuration settings above, there are some optional settings you can configure via `$\{OPENNMS_HOME}/etc/discovery-configuration.xml`:

[cols="1,3,1"]
|===
| Name	| Description	| Default Value

| packets-per-second
| Number of ICMP packets that will be generated each second.
| 1

| initial-sleep-time
| Amount of time, in milliseconds, before the discovery process begins after {page-component-title} has started.
This delay allows {page-component-title} to fully start before generating new events.
| 30000 (30 seconds)

| restart-sleep-time
| The time, in milliseconds, before the discovery process starts following its last run.
| 86400000 (1 day)

| timeout
| The amount of time, in milliseconds, that the discovery process will wait for a response from a given IP address before moving on.
| 2000

| retries
| The maximum number of attempts to query a given IP address before moving on.
| 1

| foreign-source
| Foreign source requisition to which discovered nodes will be added.
| _Blank_

| location
| Monitoring location where the discovery batch will run.
This is used only when at least one Minion has been deployed.
| _Default_

| chunk-size
| Defines the number of IP addresses to delegate to each Minion for scanning, when using a monitoring location.
| 100
|===

[caption=]
.Discovery range configuration tags and examples
[cols="1,3a"]
|===
| Tag	| Description

| specific
| Specify individual IP addresses to discover.
May be repeated multiple times. +
[source, xml]
<specific>ip-address</specific>

| include-range
| Specify a range of IP addresses to discover.
May be repeated multiple times. +
[source, xml]
----
<include-range>
    <begin>start-ip-address</begin>
    <end>end-ip-address</end>
</include-range>
----

| exclude-range
| Specify a range of IP addresses to exclude from discovery. +
[source, xml]
----
<exclude-range>
    <begin>start-ip-address</begin>
    <end>end-ip-address</end>
</exclude-range>
----
NOTE: The `exclude-range` tag will override addresses only in an `include-range`.
It will not override specific IP addresses or addresses included in a file.
There is no "specific" version of the exclude tag.
To exclude a specific IP address, use an `exclude-range` where the beginning and ending IP address is the same.

| include-url
| Specify the full path to a text file containing one IP address per line to include in discovery.
You can embed comments in this file.
Any content on a line after a `#` character is ignored. +
You can use the following path formats:
[source, xml]
----
<include-url>file:filename</include-url>
<include-url>http://IPADDRESS/filename</include-url>
<include-url>file:///path/to/file/on/local/server</include-url>
----
|===
