Assure1 Metric SNMP Network Interface Discovery Agent¶

Overview¶

The Assure1 Metric SNMP Network Interface Discovery Agent is used to connect to devices and find the interfaces available for polling. Using rules, metric instances are created, which will be used for future polling.

SNMP Network Interface Discovery Agent Setup¶

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. See the application documentation for additional information:
  
  (DeviceAutoDiscovery)
2. Using the Manual Discovery UI:
  
  Configuration -> Device Discovery -> Manual Discovery
3. Manually entering all values using the Devices UI:
  
  Configuration -> Device Catalog -> Devices
Devices must by SNMP discovered for this application to be able to get data from the devices. See the "Device SNMP Discovery" application for additional information:

DeviceSNMPDiscovery
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 SNMP Network Interface Discovery
Job Program	bin/core/collection/SNMPInterfaceDiscoveryAgent
Job Arguments
Job Description	Runs SNMP Discovery on all SNMP Enabled Devices
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/interface/disco/base.rules	Text, 255 characters	Relative path to Base Rules.
BranchDir	core/default	Text, 255 characters	relative path to Rules dir.
DeviceZoneID	Default First Zone	Integer	Used to get a more specific list of devices to run the discovery agent against.
IncludeRules	collection/metric/interface/disco/base.includes	Text, 255 characters	Relative path to Include Rules.
InterfaceType		Text, 255 characters	The poller supports the InterfaceType configuration. Valid entries are "IfName", "IfAlias", "IfDescr", or "IfIndex" for the instance name. By default InterfaceType is unset and uses "IfDescr".
LoadRules	collection/metric/interface/disco/base.load	Text, 255 characters	Relative path to Load Rules.
LogFile	logs/MetricSNMPInterfaceDiscovery.log	Text, 255 characters	Relative path to Log File.
LogLevel	ERROR	OFF, FATAL, ERROR, WARN, INFO, DEBUG	Logging level used by application.
Threads	5	Integer	The number of process threads created.
TimeOut	5	Integer	The time out for the SNMP connection.
PollByIP	Enabled	Enabled/Disabled	Optional - If enabled, the device IP address will be used to ping the device instead of the device DNS name.
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:59 am every Sunday.

Rules¶

This agent 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'.)
$InterfaceInfo->{DeviceInfo}	Device Label with DeviceID, DNS, IPv4, IPv6, and the IP used for communication (pipe delimited)
$InterfaceInfo->{DeviceID}	DeviceID for Device being discovered
$InterfaceInfo->{Device}	IP address used for communication with this device (could be IPv4 or IPv6)
$InterfaceInfo->{Name}	Interface poll name used by Network Interface Poller
$InterfaceInfo->{ifName}	Standard IF-MIB Variable ifName
$InterfaceInfo->{ifAlias}	Standard IF-MIB Variable ifAlias
$InterfaceInfo->{ifDescr}	Standard IF-MIB Variable ifDescr
$InterfaceInfo->{ifSpeed}	Standard IF-MIB Variable ifSpeed
$InterfaceInfo->{ifType}	Standard IF-MIB Variable ifType
$InterfaceInfo->{ifPhysAddress}	Standard IF-MIB Variable ifPhysAddress
$InterfaceInfo->{ifOpr}	Standard IF-MIB Variable ifOperStatus
$InterfaceInfo->{ifAdm}	Standard IF-MIB Variable ifAdminStatus

Example Integration¶

Adding/Updating a custom Interface Display Name¶

In the rules, after retrieving the instance ID using FindInstanceID, a custom display name can be added/updated to the interface using the "AddDisplayInstance" or "UpdateDisplayInstance" library functions.

Note: Both the "Add" and "Update" library functions should be called as "Update" will not add the custom name if it does not already exist, and "Add" will not update the custom name if it already exists.

if ( $InterfaceInfo->{ifName} ne "" ) {
    ($ErrorFlag, $Message) = AddDisplayInstance({
        DBH        => \$RulesDBH,
        DeviceID   => $InterfaceInfo->{DeviceID},
        InstanceID => $InstanceID,
        CustomName => $InterfaceInfo->{ifName}
    });
    ($ErrorFlag, $Message) = UpdateDisplayInstance({
        DBH        => \$RulesDBH,
        DeviceID   => $InterfaceInfo->{DeviceID},
        InstanceID => $InstanceID,
        CustomName => $InterfaceInfo->{ifName}
    });
    $Log->Message("DEBUG", " -> ifName " . $InterfaceInfo->{ifName} . " was inserted/updated as a Custom Name for device " . $InterfaceInfo->{DeviceInfo} . ".");
}
else {
    ($ErrorFlag, $Message) = AddDisplayInstance({
        DBH        => \$RulesDBH,
        DeviceID   => $InterfaceInfo->{DeviceID},
        InstanceID => $InstanceID,
        CustomName => $InterfaceInfo->{ifDescr}
    });
    ($ErrorFlag, $Message) = UpdateDisplayInstance({
        DBH        => \$RulesDBH,
        DeviceID   => $InterfaceInfo->{DeviceID},
        InstanceID => $InstanceID,
        CustomName => $InterfaceInfo->{ifDescr}
    });
    $Log->Message("DEBUG", " -> ifDescr " . $InterfaceInfo->{ifDescr} . " was inserted/updated as a Custom Name for device " . $InterfaceInfo->{DeviceInfo} . ".");
}

Administration Details¶

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

Package - coreCollection-app
Synopsis - ./SNMPInterfaceDiscoveryAgent [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