PipeDisco
Overview
The Unified Assurance 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 (Unified Assurance 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
-
Devices must exist in the Device Catalog for this application to be able to function. Devices can be created in several different ways:
-
Using the "Device Auto Discovery" application. See the application documentation for additional information.
-
Using the Manual Discovery UI:
-
Manually entering all values using the Devices UI:
-
-
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.
-
-
Enable the default Job, unless a specific configuration option is needed.
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 Unified Assurance 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
-
Go to the Jobs UI:
-
Find and select the "Metric NMAP TCP Port Discovery" job, or the custom one that was created for the environment.
-
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).
-
Click on the "Submit" button when done making changes.
-
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
-
Go to the Jobs UI:
-
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.
-
Go to the Rules UI:
-
Expand the path that is set in the job configuration, then open the "base.load" file.
-
In the "PortNames" hash, add additional PORT => DISPLAY-NAME mappings as needed.
-
Save the changes.
-
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 you will need 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