Skip to content

Assure1 Metric Pipe Instance Discovery

Overview

The Assure1 Metric Pipe Instance Discovery runs a local application against a device or set of devices. Each line of the output is then processed via rules to create metric instances.

A default job has been configured to scan ports 1 through 1000, 3306, 3307, 6443, 6446 and 8080. The default rules will create instances for ports 22 (SSH), 23 (Telnet), 80 (HTTP), 8080 (Alternate HTTP), 443 (HTTPS), 389 (LDAP), 902 (VMWare), and 6443 (Assure1 Broker), along with a display instance for a more "readable name". Both the ports that are scanned and ports that are used for instance creation can be customized.

IPv6 Considerations

The default NMAP TCP Port Discovery Agent job has not been updated to support IPv6. The underlying Pipe Instance Discovery job does support IPv6, and nmap can be configured to scan IPv6, but doing so introduces some issues that have not yet been addressed:

  • To force nmap to scan IPv6, add "-6" to the "Command" configuration option. nmap cannot be configured to scan IPv4 and IPv6 at the same time, so the best course is to clone the default "Metric NMAP TCP Port Discovery" job and changing the configuration to only scan IPv6:

    • Add "-6" to the "Command".
    • Set "PreferIPv4" to "Disabled".

    This can then be run in conjunction with IPv4.

  • Even if two jobs are created, a process listening on port tcp/8080 on IPv4 may not be the same process listening to tcp/8080 on IPv6, even if both are running on the same device. As this is possible, Instances should be tracked and marked independently for IPv4 and IPv6. One method of doing this is by naming IPv6 instances "ipv6-tcp-", then adjusting any rules that act on those instances to understand the difference between them (for instance, when measuring transaction times against tcp-8080, IPv4 would always be used, while IPv6 would be forced for ipv6-tcp-8080).

Pipe Instance Discovery Setup

  1. Devices must exist in the Device Catalog for this application to be able to function. Devices can be created in several different ways:

    1. Using the "Device Auto Discovery" application (DeviceAutoDiscovery). See the application documentation for additional information.

    2. Using the Manual Discovery UI:

      Configuration -> Device Discovery -> Manual Discovery

    3. Manually entering all values using the Devices UI:

      Configuration -> Device Catalog -> Devices

  2. Review the logic in the rules files referenced in the configuration to see the processing that will be done on the data returned by the command that is executed:

    • "LoadRules" will be executed during application startup to load data that might be needed during processing.
    • "IncludeRules" will be read during application startup to load additional files that might be called during processing.
    • "BaseRules" will be executed for each device that is selected based on the configuration.

    Update the logic as needed.

  3. Enable the default Job, unless a specific configuration option is needed.

    Configuration -> Broker Control -> Jobs

Default Scheduled Job

Field Value
Package Name coreCollection-app
Job Name Metric NMAP TCP Port Discovery
Job Program bin/core/collection/PipeDisco
Job Arguments
Job Description Runs Custom Command help discovery with rules, requires nmap loaded
Failover Type Standalone (Supported: Standalone, Primary/Backup)
Status Disabled
Privileged (Checked)
Minutes 59
Hours 0
Days *
Months *
WeekDays 0

Default Configuration

Name Value Possible Values Notes
BaseRules collection/metric/pollerdisco/generic/base.rules Text, 255 characters Relative path to Base Rules
BranchDir core/default Text, 255 characters relative path to Rules dir
Command ../../usr/bin/nmap -p1-1000,6443,6446,3306,3307,8080 Text, 255 characters Command run by the agent to gather data from the server.
DeviceZoneID Default First Zone Integer This entry is used to get a more specific list of devices to run the discovery agent against.
IncludeRules collection/metric/pollerdisco/generic/base.includes Text, 255 characters Relative path to Include Rules
LoadRules collection/metric/pollerdisco/generic/base.load Text, 255 characters Relative path to Load Rules
LogFile logs/MetricPipeDiscovery.log Text, 255 characters Relative path to Log File.
LogLevel ERROR OFF, FATAL, ERROR, WARN, INFO, DEBUG Logging level used by application.
Threads 3 Integer Number of process threads created.
PreferIPv4 Enabled Enabled/Disabled Optional - Controls whether or not to prefer IPv4 transport to communicate with Devices. This option is only considered if both IPv4 and IPv6 are available for a device. If this config is missing, IPv6 will be preferred.

Best Practices

The following list shows the best practices for working with this application:

  • The default job configuration is to run at 12:59am every Sunday.

Rules

This poller uses the Assure1 standard rules architecture, which are 100% Perl syntax. Refer to the following articles to assist in rules creation:

Tokens

The agent exposes the following tokens for rules processing.

Token Description
$AppConfig Hash reference to the application configuration name-value pairs that were configured. (i.e. use $AppConfig->{'Host'} to retrieve the set value for 'Host'.)
$DeviceID Device ID
$Row Line of output from command

Example Integrations

Customizing ports that are scanned

  1. Go to the Jobs UI:

    Configuration -> Broker Control -> Jobs

  2. Find and select the "Metric NMAP TCP Port Discovery" job, or the custom one that was created for the environment.

  3. In the "Configuration" section, find and select the "Value" field for the "Command" option. While the entry "../../usr/bin/nmap -p" must remain, nmap will accept any values between 1 and 65,535 as a list of comma separated values. These values can be either single ports (8080) or a range of ports (1-1000).

  4. Click on the "Submit" button when done making changes.

  5. Select the job again, then click on the "Start" button. Verify the additional ports are being scanned.

Customizing ports that are used for instance creation

  1. Go to the Jobs UI:

    Configuration -> Broker Control -> Jobs

  2. Find and select the "Metric NMAP TCP Port Discovery" job, or the custom one that was created for the environment. In the "Configuration" section, make note of the rules files that are used by the application.

  3. Go to the Rules UI:

    Configuration -> Rules

  4. Expand the path that is set in the job configuration, then open the "base.load" file.

  5. In the "PortNames" hash, add additional PORT => DISPLAY-NAME mappings as needed.

  6. Save the changes.

  7. Back on the Jobs UI, select the job again, then click on the "Start" button. Verify the instances are created.

Administration Details

The following list shows the technical details needed for advanced administration of the application:

  • Package - coreCollection-app

  • Synopsis - ./PipeDisco [OPTIONS]

  • Options:

     -c, --AppConfigID N   Application Config ID (Service, Job, or Request ID)
 -d, --DeviceID N      DeviceID (Optional)
 -?, -h, --Help        Print usage and exit

  • Threaded - Multi-Threaded