The Discovery Subsystem

h6. Contents

This page reviews the Discovery subsystem of the GroundWork Monitor Auto Discovery system.

{toc:minLevel=4|maxLevel=5|printable=false}

h4. 1.0 About The Discovery Subsystem

In practice, the discovery process is relatively straightforward, and usually only requires an administrator to answer a few confirmation prompts. However, there are a large number of options and variables that must be defined before this process can be started.

h5. 1.1 Discovery Definitions

In GroundWork Monitor, discovery definitions are used to store the configuration options for a particular discovery process. Once a discovery definition has been created, administrators can simply select the most appropriate discovery definition for the task at hand and immediately begin the associated discovery process, with all of the appropriate options and variables already selected.

In this model, administrators can create separate discovery definitions for each discovery process they may need, with each discrete discovery definition storing the options and variables that are required for a specific discovery process to complete successfully.

For example, administrators can create a discovery definition that simply probes the devices on the local network for a handful of well-known TCP and UDP services, and another discovery definition that probes the devices on a remote network for SNMP management data, with each of these discovery processes subsequently performing different types of synchronization with the configuration database.

Since a discovery definition describes an entire discovery operation from beginning to end, it incorporates all of the options and variables that are needed for the full process to run through completion. More specifically, each discovery definition includes the options and variables that govern the address ranges to be probed, the discovery methods to be used for probing the network addresses, the automation schema definition to be used for processing the results, and the automation action that should be taken upon completion. Some of these options are stored in the discovery definition object itself, while some of them are defined in secondary objects and then referenced by the discovery definition.

The relationship of the major elements of a discovery definition is illustrated in the figure below, and discussed in detail in the following text.
{Note}The important point here is that all of these options and variables must be specified before a discovery definition can be created or executed.{Note}

!bookshelf_discovery_definition_group.jpg|align=left,border=10,bordercolor=#FFFFFF! *Address Ranges* \- Each discovery process is run against one or more IP address specifications. Address ranges are independent objects that are referenced by the discovery definition, but they are defined as part of the discovery definition, or are defined as part of a discovery method that is also associated with the discovery definition (see next section). At least one address range must be specified, but administrators can define as many address ranges as may be needed. Administrators can also enable and disable address ranges on a per-process basis, which is useful for testing a discovery definition against a small network before it is used in production against multiple large networks.

*Discovery Methods* \- The discovery service is able to use multiple kinds of networking technologies in order to detect the services that are active on each device. Discovery methods are independent objects that are referenced by the discovery definition and are also managed separately. At least one discovery method must be defined for each discovery definition, but multiple discovery methods can be associated with a single discovery definition, and each of the discovery methods can also be enabled or disabled for any given discovery process.

By default, GroundWork Monitor uses a discovery method based on the open source nmap utility to probe well-known TCP ports for common Internet services, and also uses SNMP queries to probe discovered devices for common management data. However, the discovery subsystem can also use nmap to probe for common UDP services, and is also capable of importing WMI discovery data generated elsewhere. Administrators can also create their own discovery methods that use arbitrary scripts and commands if needed.

*Automation Schema Definition* \- Once the process of probing the selected networks with the selected discovery methods has completed, the process of matching the discovered devices with host and service profiles begins. This process is governed by the automation subsystem, which uses its own configuration options that are stored in a separate schema definition object (refer to the Automation section below for more information about schema definitions). The schema definition is used to tell the matching process about the format of the discovery data, as well as describing the string syntax to use when mapping the discovery output to the appropriate host and service profiles. Each discovery definition must have just one schema definition.

*Automation Action* \- Once the profile-matching process completes, the Auto Discovery service can either present the results to the administrator for review, or it can add the discovered nodes to the configuration database automatically, and it can even update the configuration database if so desired. This option is controlled by the automation action setting, which offers a choice between _Interactive_, _Automatic_, and _Auto-Commit_ (in the order described above). This option can also be overridden on a per-process basis, thereby allowing the administrator to test a discovery process before having the results automatically committed to GroundWork Monitor's configuration database.

2.0 2.0 h4. Managing Discovery Definitions

Discovery definitions are managed with the Discovery console screen. To access the Discovery console screen, select the Auto Discovery menu item from the main menu. The Discovery screen is the default active screen, but you can also explicitly activate this screen by choosing the Discovery menu item in the top menu bar.

h5. 1.2 Discovery Console Screen

The default Discovery console screen is shown in the figure below. As can be seen in that figure, GroundWork Monitor provides a default discovery definition called _GroundWork-Discovery-Pro_.

When multiple discovery definitions exist, the currently selected discovery definition (e.g. *GroundWork-Discovery-Pro*) is highlighted with a yellow background. When only one discovery definition exists, it is always selected and therefore always highlighted.
Some of the  run-time options and variables that are used for each discovery process are also shown in the main discovery console screen. For example, the available automation *Control Types* (_Interactive, Auto or Auto-Commit_) are shown in the same row as the discovery definition name and description, with the currently defined setting being pre-selected. Meanwhile, all of the known address *Ranges and Filters* are shown in the lower portion of the screen, with the address ranges that are linked to the current discovery definition being preselected.

The automation action and the address ranges can be changed before starting the discovery process, simply by selecting the desired options. By providing access to these options in the main discovery console screen, administrators can modify these settings at run-time without having to directly edit the discovery definition. The default selections for the currently selected discovery definition can be permanently changed by clicking the  *Save* button in the upper right corner. Reference for _Auto Discovery_ can be access directly using the *Help* button and by clicking "*?*" symbol next to various content. New discovery definitions can be created by clicking the *New* button. This topic is discussed in the _Creating Discovery Definitions_ section. Granular modifications to the discovery definition can be made by clicking the *Edit* button. This topic is discussed in the _Editing Discovery Definitions_ section. And, to execute a discovery process using the currently selected discovery definition and run-time options, click the *Go>>* button. This topic is discussed in the _Running Discovery Processes_ section.
\\
\\
Figure: Discovery Console
!bookshelf_discovery_console.jpg|border=1!

h5. 1.3 Creating Discovery Definitions

# To create a new discovery definition, click the *New* button on the discovery console screen. A new screen like the one above will be displayed.
# Fill in the fields to suit your requirements.
# Once the fields have been filled in to your satisfaction, click *Create* to continue. At this point the discovery definition editor screen will be displayed, with the new discovery definition values already loaded. If you do not wish to continue creating a new discovery definition, click *Cancel* to return to the main discovery console screen.

h6. New Auto Discovery Definition Fields

* *Auto discovery definition name* \- Enter a short name for your new discovery definition.
* *Description* \- Enter a description of your new discovery definition.
* *Import/update automation schema* \- This drop-down list shows all of the automation schema definitions that have been created. By default, this list will show _GroundWork-Discovery-Pro_. If you need to use a different schema, you can cancel the current operation and return to this dialog after the appropriate schema definition has been created, or you can continue with the current operation and change the discovery definition later. You must choose an automation schema definition to continue creating a discovery definition. Note that discovery processes can only use schema definitions that have a host-import schema type, although all of the schema definitions regardless of type will be shown in the drop-down list. Refer to the Automation section for information about automation schema definitions and schema types.
* *Default control type* \- This drop-down list shows the three automation control types that are available. _Interactive_ means that the administrator will be required to confirm the results of the discovery process, while _Auto_ means that the results will be added to the GroundWork Monitor configuration database (but the configuration will not be automatically committed), while _Auto-Commit_ means that the results will be added to the configuration database, the changes will be automatically committed, and GroundWork Monitor will immediately begin monitoring those devices. You must choose an automation action to continue, although you can revise your selection later.
* *Create from template* \- Discovery definitions can be saved as _templates_ that allow them to be partially reused (see the discussion in the next section for more details). If you have already saved a discovery definition as a template, you can reuse some of its options and variables by selecting it in the drop-down list. By default, this list box will contain a single entry for the _GroundWork-Default-Pro_ template which is a template that is derived from the default discovery definition. If you do not want to inherit any options from any other definitions, leave this drop-down list empty.
\\
\\
Figure: Discovery Definition
!bookshelf_discovery_definition.jpg|border=1!

h5. 1.4 Editing Discovery Definitions

To edit the options and variables associated with a discovery definition, select the discovery definition that you want to edit in the discovery console screen. Select the *Edit* button.

# This will result in the discovery definition editor screen being displayed with the discovery definition values already loaded (this screen will also be loaded automatically after a new discovery definition is created, as described in the preceding section). The figure shows the discovery definition editor screen, using the values from the default *GroundWork-Discovery-Pro* discovery definition.
# Once you have finished making changes to the discovery definition, select one of the following options click the *Save* button to make the changes permanent;
or
If you would like to create a template of the discovery definition that can be applied to future definitions, click the *Save As Template* button. Templates are stored as XML text files in the {{/usr/local/groundwork/core/monarch/automation/templates}} directory on the GroundWork Monitor server. Template files can be copied into the same directory on another GroundWork Monitor server and will be immediately usable on that system;
or
If you wish to initiate a discovery process using the current settings but without making the changes permanent, click the *Go >>* button. If you want to cancel your changes and return to the main discovery console screen, click the *Close* button.
\\
\\
Figure: Editing Definitions
!bookshelf_editing_definitions.jpg|border=1!

h6. Discovery Definition Fields

* *Description* \- Enter a brief description for this discovery definition.
* *Import/update automation schema* \- This drop-down list shows all of the automation schema definitions that have been created. Note that discovery processes can only use schema definitions that have a host-import schema type, although all of the schema definitions regardless of type will be shown in the drop-down list. Refer to the Automation section below for information about automation schema definitions and schema types.
* *Default control type* \- This drop-down list shows the three automation control types that are available. _Interactive_ means that the administrator will be required to confirm the results of the discovery process, while _Auto_ means that the results will be added to the GroundWork Monitor configuration database automatically (but the configuration will not be committed), while _Auto-Commit_ means that the results will be added and the changes will be committed.
* *Traceroute Option* \- This option allows the discovery service to use the traceroute command to automatically determine the parent device of a discovered device. This option is only useful if remote networks are being probed and if the host entries in Nagios have parent-child relationships that reflect network topology. Note that the traceroute command requires ICMP to be enabled on the discovered devices and the intermediary network devices. Also note that the default hop-count and timeout values are tuned for moderately-sized networks, and you may need to override the default values if you intend to probe for devices across a very large or slow wide-area network.
* *Methods* \- This portion of the editor screen shows the discovery methods that will be used to probe discovered devices for their available network services. All of the discovery methods that have been defined are displayed here (including methods that have been created for other discovery definitions), while the discovery methods that are associated with the current discovery definition will be actively selected. On a new installation, this area will only show the _Nmap TCP_ and _SNMP_ discovery methods that are provided with the default installation, although additional discovery methods may be created as needed, and the existing discovery methods may also be modified. New discovery definitions will not have any associated discovery methods unless the administrator used a discovery template during the creation process that had one or more methods already selected. Refer to the Managing Discovery Methods section below for information on creating and managing discovery methods.
* *Ranges and Filters* \- This portion of the editor screen shows the address ranges that will be probed. All of the address ranges that have been defined are displayed here, including those that have been created for other discovery definitions. On a new installation, this area will only show a _local subnet_ address range that was created during installation, although additional address ranges may be created as needed, and the existing address ranges may also be modified. New discovery definitions will not have any associated address ranges unless the administrator used a discovery template during the creation process that had one or more address ranges already selected. Refer to the _Managing Address Ranges_ section below for information on creating and modifying the address ranges.

h5. 1.5 Deleting Discovery Definitions

If you want to delete a discovery definition, you must do so from inside the discovery definition editor screen. Select the discovery definition that you want to delete from the main discovery console screen, and click the *Edit* button. Once the discovery definition editor screen has loaded, click the *Delete* button in the upper right corner. You will then be presented with a confirmation box similar to the following, which will also allow you to delete any discovery methods that may be associated with the discovery definition:

If you want to delete any of the discovery methods associated with the discovery definition, activate the appropriate check box. Once you are satisfied with your choices, click the _Yes_ button to delete the discovery definition and the selected discovery methods, or click the _No_ button to cancel and return to the discovery definition editor screen.
\\
\\
Figure: Deleting Definitions
!bookshelf_deleting_definitions.jpg|border=1!

h4. 2.0 Managing Address Ranges

Address ranges are used to specify the IP addresses that should be probed during the discovery process. Address ranges can be specified in the main discovery console screen, the discovery definition editor screen, and the discovery method editor screen. In all these cases, a portion of the screen will have a *Ranges and Filters* section similar to the figure below.

During installation, GroundWork Monitor examines the server's local IP address and subnet mask and attempts to create a _local subnet_ address range that reflects the local network's properties. This is shown as the _local subnet_ entry with the Range/Filter value of _127.0.0.\*_ in the example below, although your own entry should reflect the IP addressing in use on your local network.

h5. 2.1 Create a New Address Range

You can create as many address ranges as are needed, and multiple address ranges can be assigned to any discovery process. At least one address range must be active in order for a discovery process to execute.

# To create a new address range, fill in the fields with appropriate values and click the *Add Range/Filter* button.
# At this point the newly created address range will appear in the *Ranges and Filters* section of the current screen. Remember that address ranges must be selected before they will be incorporated into a discovery process.
# To delete an address range, click the *delete range/filter* hyperlink next to it. There is no edit function for address ranges. If you wish to change an address range, it must be deleted and recreated.
\\
\\
Figure: Range and Filters
!bookshelf_ranges.jpg|border=1!

h6. Ranges and Filters

* *Name* \- Enter a short name for the address range.
* *Type* \- There are two types of address ranges in Auto Discovery: an _include_ range that specifies a range of addresses that should be probed, and an _exclude_ range that specifies a subset of addresses that should not be probed. IP addresses that are not part of an _include_ range are never probed, so you do not need to _exclude_ any addresses unless they fall within the scope of an _include_ range.
* *Range/Filter* \- Address ranges can use any of the following different formats:
** Unqualified hostname (e.g. mybox)
** Qualified hostname (e.g. mybox.mydomain.com)
** Single address (e.g. 192.168.0.1)
** Address range (e.g. 192.168.0.2 - 192.168.0.10)
** Abbreviated address range (e.g. 192.168.42-50)
** CIDR block (e.g. 192.168.144.0/20)
** Comma-separated list of any of the above (e.g. 192.168.0.1, 192.168.0.3)
In Class C specifications, the network (.0) and broadcast (.255) addresses will be automatically ignored. Equivalent addresses will be ignored in CIDR blocks with a subnet prefix smaller than /31.
If you are using a discovery script to generate a list of hosts, you need to put a dummy value into this field in order to make the discovery proceed.

h4. 3.0 Managing Discovery Methods

Discovery methods are used to specify the network services that should be probed for on each IP address. During this process, the discovery service iterates through the list of IP addresses that have been associated with the current discovery definition, executes one or more tests against the current address, and then generates one or more lines of output data that catalogs the services that have been discovered. The output data is then subsequently read and analyzed by the automation subsystem, which maps the host and service data to the appropriate Nagios profiles.
{Note}Discovery methods are executed sequentially, and in some cases will only query devices that were discovered by a previous discovery method. For example, in the figure above the _Nmap TCP_ discovery method will be executed before the _SNMP_ discovery method (this relationship is important to the SNMP discovery method, as will be explained later). You cannot currently reorder discovery methods, so they must be created in the order desired.{Note}

Discovery methods can only be associated with a discovery process in the discovery definition editor screen, which has a _Methods_ section similar to the following. GroundWork Monitor provides two discovery methods by default, both of which are shown in the figure:
* The _Nmap TCP_ discovery method is used to probe devices for common TCP/IP network services such as Web and email services.
* While the _SNMP_ discovery method is used to probe for SNMP management information.

You can modify either of the bundled discovery methods, or you can create your own discovery methods if needed. Multiple discovery method can be assigned to each discovery definition. At least one discovery method must be active in order for a discovery process to execute.

h5. 3.1 Create a New Discovery Method

# Fill in the fields with appropriate values and click the *Add Method* button.
# At this point a discovery method editor screen will be displayed that will allow you to set all of the options and variables associated with the discovery method (the layout of the discovery method editor screen is different for each discovery type).
# If you want to modify an existing discovery method, click the *Edit Method* hyperlink next to the discovery method. This will cause the appropriate discovery method editor screen to be loaded with the contents of the selected discovery method.
\\
\\
Figure: New Discovery Method
!bookshelf_new_method.jpg|border=1!

h6. Discovery Method Fields

* *Name* \- Enter a short name for the discovery method.
* *Type* \- There are four types of discovery methods available, which are described in more detail below. However, it is important to understand that this field is only used to select the software that actually probes the devices, and additional configuration will be required in a separate screen before the discovery method is fully functional.
** _Nmap_ \- This type is used when you want to have the discovery process probe for TCP or UDP network services on the discovered devices. This is the primary discovery method in GroundWork Monitor, and should be used as the first discovery method in most cases. Note that the nmap utility is sometimes classified as an intrusion tool by some security tools and/or personnel, and you may need to coordinate with other groups before using it.
** _SNMP_ \- The SNMP type is used when you want to have the discovery process probe for SNMP management information on the discovered devices.
** _Script_ \- If you want to create your own probes with your own script commands, use the _Script_ type.
** _WMI_ \- This type is used when you want to import Windows-specific host data into GroundWork Monitor. The WMI data is generated by a separate Windows-based program.

The _Nmap_ discovery method uses TCP and UDP connection requests to probe for network services on each discovered device. Whenever a probe succeeds, the discovery method returns a service _match value_ that indicates the service(s) that were discovered, along with host platform identification information (if available). Once all of the probes have completed, the match values will then be subsequently correlated with the appropriate host and service profile(s) for that device by the automation processor.

Multiple nmap service probes can be defined, but they must all be of the same protocol type, and at least one service must be defined.

The figure below shows the discovery method editor for the _Nmap_ type, using the default _Nmap TCP_ discovery method. Also, the options and fields in the nmap discovery method editor screen are shown in the table below (note that different fields will be used for different types of nmap probes).

Once the options and fields have been completed to your satisfaction, click the _Save_ button in the upper right to continue. At this point you will be returned to the discovery definition editor screen that you came from. You can also rename or delete the discovery method by clicking on the appropriate button.
\\
\\
Figure: Nmap Discovery Method
!bookshelf_nmap_method.jpg|border=1!

h6. Nmap Discovery Method Editor Options and Fields

* *Scan Type* \- There are three nmap scan types available, which are as follows:
** _TCP SYN Scan_ \- Network services that use TCP require a full synchronization _handshake_ before data can be exchanged. With the TCP SYN scan method, nmap generates raw connection request packets for the target service(s), but does not fully complete the handshake procedure. Instead, it only waits to see if the connection request is acknowledged or refused before moving to the next TCP port number in the list. Although this method is very fast, it requires custom packets and as such it is only available when the discovery process is run under an account that has root user privileges (GroundWork Monitor uses the necessary privileges by default).
** _TCP Connect Scan_ \- The TCP connect scan method uses standard user-level operating system calls to perform a complete handshake operation with the target TCP service. This method takes longer to successfully determine the results of the connection request, but it works with any user account.
** _UDP Scan_ \- The UDP scan method is for detecting UDP based network services. UDP is a stateless transport protocol and does not have a handshake mechanism, so nmap simply looks for data of some kind and assumes that any response activity is from the expected application.
* *UDP SNMP Check* \- This option determines whether or not a discovered device is also probed with a UDP query to see if SNMP is enabled on the target. If this option is enabled, and if the SNMP discovery method has also been enabled, then only those devices that respond to the UDP query will be probed by the subsequent SNMP discovery method probes. Note that this checkbox is only available when one of the TCP scans have been selected (UDP scans can explicitly probe for SNMP without requiring a separate option).
* *SNMP Match Strings* \- During the TCP scanning process, nmap attempts to identify the host platform and operating system in use on the target device by examining certain characteristics of the TCP protocol handshake, with this information then being recorded in the result data. When this process is successful, the resulting host identifier string can be used as an additional input filter to further limit the number of follow-up SNMP queries. In order to use this option, you must enter a filter string in this field that will match some or all of the device identification strings that you want to use as a limiting filter. Typically, this will be a string such as ”r;cisco” or ”r;hewlett-packard” or some other substring of an nmap host identifier. Multiple strings can be entered but must be separated with a comma. Matches are case-insensitive. Note that this field is only enabled when one of the TCP scans are used (nmap does not have the ability to detect the host operating system with UDP probes, since UDP does not have a handshake).
* *Scan Timeout* \- This option determines the delay between the connection requests that are generated by nmap. Shorter delay periods result in faster scans, but will also timeout quickly when the local GroundWork Monitor host and the remote systems are separated by a long or slow network path. Aggressive delay periods are also known to set off intrusion alarms. The options for this field are _paranoid_, _polite_, _normal_, _aggressive_, and _insane_, which range from very slow to very fast in the order presented. The default value is _insane_ and will yield the fastest results, but may result in missed probes or security problems on some networks.
* *Ports* \- This section of the nmap discovery method editor screen is used to enumerate the port numbers that should be probed and the _match value_ that should be returned when a probe is determined to have succeeded.
To create a new assignment, enter a port number and a match value to be returned upon success, and click the _Add Port_ button. To delete an existing assignment, click the _delete port_ hyperlink next to an entry.
* *Match Values and Actions* \- The match value string will be stored in the resulting log file, where it will then be used to correlate service profiles with the host entry. Note that match values are keyed to existing services, service profiles, host profiles and *discover* values. You are not restricted to these keyed values, though you will be presented with an ordered list of the services, service profiles, host profiles, and discover match values available in your configuration database, or any profiles loaded in the {{/usr/local/groundwork/core/profiles}} directory on the GroundWork server. The effect of selecting one of the keyed service, service profile, or host profile values is determined by the automation schema used. See the section on Automation for details of editing the schema. The default schema will process these as follows:
{Note}Newly created match values will not be useful until the appropriate automation schema definition has also been updated (refer to the Automation Subsystem section for more information on this process).{Note}
** *service-<service name>* \- Assign the named service to the discovered host.
** *service-profile-<service profile name>* \- Assign the named service profile to the discovered host.
** *host-profile-<host profile name>* \- Assign the named host profile to the discovered host.
The match values will have effect only on subsequent methods. The effect of the different match values is as follows:
** *discover-snmp* \- Subsequent SNMP methods will be restricted to hosts that match this port signature (as well as those that match the String and UDP scan options described above).
** *discover-script* \- Subsequent script methods will be restricted to hosts that match this port signature.
** *discover-wmi* \- No effect. This is reserved for future functions.

The *SNMP* discovery method uses SNMP queries to see if a device supports the SNMP protocol. If so, additional probes are used to enumerate the network interfaces on that device, with each interface subsequently being assigned an appropriate service profile. If the device does not respond to the SNMP queries, it is ignored.

In addition, devices that respond to SNMP are optionally queried for specific metrics. These metrics are specified outside the user interface in a configuration file, located at {{/usr/local/groundwork/core/monarch/automation/conf/snmp_scan_input.cfg}}.

The format of this file is OID=matchstring where OID is a numeric SNMP object identifier, and matchstring is an arbitrary string used to map services or service profiles to hosts that are capable of responding to SNMP queries for the specified OID.

This is an advanced option. Configuration requires knowledge of the SNMP MIB on the device to be probed. GroundWork Monitor has several examples supplied in the default file. The necessary schema values required to process these samples are included in the default automation schema for the default discovery definition in GroundWork Monitor.

Note that an SNMP discovery method that is associated with a discovery definition will be used with all of the address ranges associated with the current discovery process. SNMP queries use UDP, which does not provide a handshake mechanism, and therefore requires a timeout interval to detect failure (the default value is 15 seconds). This means that SNMP probes can be very time consuming, especially on large networks.

For this reason, Auto Discovery allows SNMP discovery methods to be linked to TCP scans, which are much faster. In this arrangement, only those devices that have been successfully discovered with TCP probes are also probed with follow-on SNMP queries (the Nmap TCP method contains a quick UDP scan option for this purpose). Furthermore, administrators can also limit queries to specific types of host platforms, thereby forgoing the need to enumerate the network interfaces on all devices. For more information about this process, refer to the Nmap Discovery Methods section above.

The figure shows the discovery method editor for the _SNMP_ type, with no preloaded values. Once the options and fields have been completed to your satisfaction, click the _Save_ button in the upper right to continue. At this point you will be returned to the discovery definition editor screen that you came from. You can also rename or delete the discovery method by clicking on the appropriate button.

{Note}SNMP community strings are not passed from Auto Discovery to Auto Configure since community strings are often security sensitive. It is recommended that custom Auto Discovery mechanisms that need to distinguish between available community strings match against OIDs that are present in one community string but not the other.{Note}
\\

* *SNMP Version* \- The SNMP discovery method supports SNMP versions 1, 2c, and 3. Version 1 of SNMP is the simplest and has the widest support, but also lacks some of the efficiency in version 2c. SNMP version 3 offers the highest security, but is not as widely supported as other versions. By default, the SNMP discovery method uses SNMP version 2c which is the most efficient and has wide support. Version 2c should be used unless you know that your network devices are configured to use version 3.
* *SNMP v3* \- The SNMP v3 fields are disabled unless SNMP version 3 is selected. If you use version 3, you will need to provide the authentication information in the SNMP v3 fields.
* *Community Strings* \- This field is disabled unless version 1 or 2 is selected. If you use version 1 or 2, provide one value in the Community Strings field to be used with the lookup queries.

The _WMI_ discovery method uses independent scans of the Windows Management Interface to probe Windows devices for their disk, memory, and CPU resources. These scans require a GroundWork Windows Child Server. The figure shows the discovery method editor for the _WMI_ type, with no preloaded values. The WMI discovery method editor screen only provides one option, which is the WMI Type that should be probed for. There are two WMI scan types available, which are as follows:

h6. WMI Discovery Method Editor Options and Fields

* *Server* \- This scan type loads all discovery output available from GroundWork Windows Child Servers. The Windows Child Server must be independently configured to upload these results to the GroundWork Server.
* *Proxy* \- This option remains unimplemented. Selecting it will have no effect.
{Note}There is no address range management area in the WMI discovery method editor screen, since there is no actual scanning.{Note}

Once the options and fields have been completed to your satisfaction, click the _Save_ button in the upper right to continue. At this point you will be returned to the discovery definition editor screen that you came from. You can also rename or delete the discovery method by clicking on the appropriate button.
\\
\\
Figure: WMI Discovery Method

The *Script* discovery method is designed to allow administrators to create their own discovery probes. Although the Auto Discovery subsystem provides discovery methods that can locate most of the common network services, sometimes an administrator will want to create their own discovery methods. Towards that end, the Script method can be used to look for almost any kind of device characteristic imaginable, with the only requirements being that the Groundwork host is able to execute a command and return the necessary output, and that Nagios is able to use a service definition that appropriately describes the desired resource.

For example, an administrator may want to catalog the hosts that are currently reachable on the network, using a tool such as ping to discover and monitor those hosts, instead of using TCP and SNMP probes to monitor all of the services running on all of the hosts. In this scenario, an administrator could use a simple script that called the ping utility and then generated the necessary output for each IP address, with the result data subsequently being used to associate the correct Nagios host and service profiles with the discovered devices. Once this script was associated with a custom discovery method, the administrator could perform the ping discovery process whenever needed.

By the same token, these same principles can also be used to measure other types of network services, such as discovering devices on AppleTalk or DECnet networks, or discovering local applications that are running on remote hosts, simply by creating the necessary script and mapping the output to the appropriate Nagios profiles.

In order to clarify these points, the script below represents a fully-functional discovery script that uses the Nagios {{check_icmp}} utility to ping a target device, looks up hostname data associated with the target, and then generates an appropriately formatted response line based on the discovered data.

{code}#!/usr/local/groundwork/perl/bin/perl
#
# ping_discovery.pl
# v1.0
#
# Copyright 2008 GroundWork Open Source, Inc.
use strict;
use warnings;
use Net::hostent;
use Socket;
# first make sure we got a valid IP address as the first parameter
if (! defined $ARGV[0]) {
die "Fatal error: input does not include a valid IP address \n";
}
if ($ARGV[0] !~ /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/) {
die "Fatal error: input does not include a valid IP address \n";
}
# predefine all variables
my $hostaddr = $ARGV[0];
my $ping = "";
my $host = "";
my $hostname = "";
my $hostalias = "";
my $hostprofile = "";
my $svcprofile = "";
my $service = "";
my $output = "";
# ping the specified IP address and store the results
$ping = qx(/usr/local/groundwork/nagios/libexec/check_icmp -H $hostaddr) or die;
# if we get an OK or WARNING response, start looking for hostname information
if (($ping =~ /^(OK.+)\|/) || ($ping =~ /^(WARNING.+)\|/)) {
# clean the test results
$ping = $1;
chomp ($ping);
# see if any hostname information is defined for the host
if ($host = gethost($hostaddr)) {
# if the hostname is an FQDN, use the short version
if ($host->name =~ /^(\S+?)\./) {
$hostname = $1;
}
else {
$hostname = $host->name;
}
# if an alias is defined and is different from the short
# hostname, use it
if ((@{$host->aliases}) && (@{$host->aliases}[0] ne $hostname)) {
$hostalias = @{$host->aliases}[0];
}
# otherwise, if the original hostname is an FQDN, use that
# for the alias
elsif ($host->name =~ /^(\S+?)\./) {
$hostalias = $host->name;
}
# if all else fails, reuse the hostname for the alias
else {
$hostalias = $hostname;
}
}
# host does not have a known hostname, so reuse the IP address
else {
$hostname = $hostaddr;
$hostalias = $hostaddr;
}
# set the Nagios profile data
$hostprofile = "host-profile-service-ping";
$svcprofile = "service-ping";
$service = "icmp_ping_alive";
# generate the appropriate output for the automation schema definition
# name;;alias;;address;;description;;parent;;profile;;service profile;;service
$output = $hostname . ";;" .
$hostalias . ";;" .
$hostaddr . ";;" .
$ping . ";;" .
";;" .
$hostprofile . ";;" .
$svcprofile . ";;" .
$service ;
}
# host did not respond to ping, so return empty response data
# name;;alias;;address;;description;;parent;;profile;;service profile;;service
else {
$output = ";;" .
";;" .
";;" .
";;" .
";;" .
";;" .
";;";
}
# return the output
print $output . "\n";
exit;{code}

As can be seen, the example script reads the input for an IP address that has been passed to it by Groundwork during the discovery process, and then calls the Nagios {{check_icmp}} command to ping the target address. If the target device responds to any of the probes (as determined by an OK or WARNING command response), then a series of hostname lookups are performed in order to determine the device's name and alias. Finally, the host and service profile attributes are filled in with canned values, and the response data is returned. Meanwhile, devices that did not respond to any of the probes successfully are simply ignored, and a row of empty values are returned.

{Note} The example script is intended to be executed separately for each target IP address, with each individual address being passed to the script by GroundWork Monitor according to the address ranges that were registered with the discovery definition.{Note}

In order for GroundWork to successfully use the script, the script output must correlate with the field layout defined in the automation schema definition that is associated with the current discovery definition. For example, the script above is intended to be used with the default GroundWork schema definition, which has a predefined layout and matching rules. If the default schema definition is used, the output file will contain the same fields as described in the Automation Data Files section below.

In particular, it is crucial that every explicit host record contain a host name and IP address field in order to indicate the specific host that the record applies to, or else the automation processor will infer that the current record is an update to the previous host record and will append or overwrite some of the field data. Similarly, every host that is probed must generate a line of response data in order for the discovery processor to know that the script has performed its task. This may either be a row of completely blank fields (as in the sample script above), or a row that contains the host name and address which indicates that the record data applies to an explicit host. Refer to the discussion in The Automation Process section below for more information about the file layout rules and how the contents of the file are analyzed and used.

The script output is captured by GroundWork and stored in a file in the {{/usr/local/groundwork/core/monarch/automation/data}} directory, with the file name reflecting the name of the discovery definition. The data in the results file will only be processed by the automation subsystem after the discovery process has completed. Once a script has been created, it must be registered as a discovery method before it can be used. The figure shows the discovery method editor for the _Script_ type, with no preloaded values.

Once the options and fields have been completed to your satisfaction, click the _Save_ button in the upper right to continue. At this point you will be returned to the discovery definition editor screen that you came from. You can also rename or delete the discovery method by clicking on the appropriate button.
\\
\\
Figure: Script Discovery Method
!bookshelf_script_method.jpg|border=1!

h6. Script Method Editor Options and Fields

* *Script type* \- The only currently supported type is the _Custom_ type.
* *Run Mode* \- The _Run Mode_ type determines whether the script is executed for every IP address, or if it is only executed one time during the discovery process. If the _Batch Mode_ checkbox is disabled then the script will be executed for every IP address, but if the checkbox is enabled then the script will only be executed one time.
* *Command Line* \- You must provide the full path to the command that will be used for the discovery method. The script file must be stored in the {{/usr/local/groundwork/core/monarch/automation/scripts}} directory, and the {{nagios}} user account must have sufficient permissions to execute the script.
\\
\\
You can specify parameters and arguments to the script in this field, either as hard-coded arguments or environment variables that are usually available to the nagios user account. If the script is being executed for each host address, the variables can also refer to Nagios macro definitions such as $HOST$ or $user21$, with these macros being expanded by GroundWork Monitor before they are passed to the command line. However, if the script is being executed in batch mode, the macros are not expanded, and will not be available to the script.

* *Ranges and Filters* \- This section of the discovery method editor screen allows you to link this specific discovery method to a specific address range. If a discovery definition will use multiple discovery methods for multiple address ranges, and if the current discovery method is only useful for some of the address ranges, then you may wish to enable a specific address range for this discovery method. However, in those cases where the discovery definition uses all of the defined discovery methods with all of the active address ranges, no address ranges should be explicitly enabled in the discovery method (they will be included by the discovery definition at run-time instead).

h5. 3.6 Deleting Discovery Methods

If you want to delete a discovery method, you must do so from inside the discovery method editor screen.

# Go to the discovery definition editor screen, and click the *edit method* hyperlink next to the discovery method that you want to delete.
# Once the discovery method editor screen has loaded, click the *Delete* button in the upper right corner. You will then be presented with a confirmation box similar to the figure below.
# Click *Yes* to delete the discovery method, or click the *No* button to cancel and return to the discovery method editor screen.
\\
\\
Figure: Deleting Discovery Methods
!bookshelf_deleting_methods.jpg|border=1!

h4. 4.0 Running Discovery Processes

A discovery definition can be executed from either the main discovery console screen or the discovery definition editor screen simply by clicking the _Go>>_ button in the upper right corner. Note that you can change the automation action or enable and disable address range(s) at run-time, and those changes will be incorporated into the selected discovery process when it starts, but all other options can only be changed in the discovery definition editor.

When the discovery process starts, an output file is created in {{/usr/local/groundwork/core/monarch/automation/data}} with a filename that is based on the name of the discovery definition being used. If another instance of the selected discovery process has already been executed but its output data has not yet been fully processed, this file will already exist, and you will be presented with a screen where you may choose to discard the previous output and begin a new discovery job, or you may choose to forgo the discovery process and skip directly to the automation process, or you may cancel the request and return to the main discovery console screen.

If you are still proceeding with the discovery execution, you will next be presented with a screen similar to the following, which warns that the discovery operation may trigger intrusion-detection software or set off other kinds of security alarms. Note that you may need to coordinate with network security personnel before conducting these operations in order to avoid undesirable problems that may result from these false alarms. You must acknowledge the warning by activating the _Accept_ toggle and clicking the _Go>>_ button before the discovery operation will proceed.
\\
\\
Figure: Start Discovery
!bookshelf_start_discovery.jpg|border=1!

Once the discovery process begins, you will then be presented with a status screen similar to the following. This screen will be updated in real-time as each host is probed. At this point, you will be unable to change any details unless you cancel the current operation and start over. The amount of time required to complete the discovery process will depend on numerous factors, such as the size of the address range(s) and the type of discovery method(s) in use, the network latency between the GroundWork Monitor server and the remote devices, and a variety of other factors. As a general rule of thumb, it takes approximately 10 minutes to scan a small network with the default discovery definition and all of its associated options.

After all of the IP addresses have been probed, the _Next>>_ button will become accessible, and you may then proceed with the automation process that will match the discovered devices to their appropriate host and service profiles and perform any necessary database updates. This subject is discussed in the Automation Subsystem section.
\\
\\
Figure: Discovery Process
!bookshelf_discovery_process.jpg|border=1!