Discovery agent definition files

The discovery agent definition files define the operation of the discovery agents.

Filtering devices using the definition files

Note: Network Manager kills all discovery agents at the end of data collection stage 3. This ensures that the next discovery restarts the agents and forces the agents to reread their configuration files at the beginning of a discovery, thereby detecting any changes to the configuration files.

You can apply a filter to a discovery agent by editing the supported devices filter within the DiscoAgentSupportedDevices( ); section of the discovery agent definition file ($NCHOME/precision/disco/agents/*.agnt). All discovery agents have a definition file in this directory, regardless of whether the agent is text-based or precompiled.

The supported devices filter is a filter against the attributes of the agentTemplate.despatch table.

The DiscoAgentSupportedDevices( ); section accepts full OQL comparison tests using comparison operators such as like, < , > , = , and <>.

Tip: Altering agent definition files can introduce parse errors. To check your agent for parse errors, run the agent in debug mode and examine the debug output.

Example: filtering devices sent to the CDP agent

The following example shows the DiscoAgentSupportedDevices(); section of the CDP.agnt agent definition file. Only network entities that match the specified Object IDs are processed by the CDP agent, that is, only devices that use the Cisco Discovery Protocol. The CDP agent does not process devices with the Object ID 1.3.6.1.4.1.9.1.226.

            DiscoAgentSupportedDevices
            (
                        " (
                                    ( m_ObjectId like '1\.3\.6\.1\.4\.1\.9\..*' )
                                    AND
                                    ( m_ObjectId <> '1.3.6.1.4.1.9.1.226' )
                        ) "
            );

Example: using wildcards in device filters

The following example shows the use of wild cards in the IP address column. The agent only accepts devices with an IP address beginning 10.10.2.

            DiscoAgentSupportedDevices
            (
                        " ( m_UniqueAddress like '10\.10\.2\..*' ) "
            );

Example: using multiple device filter conditions

The following example shows the combination of multiple filter conditions. The agent accepts only devices that have the Object ID 1.3.6.1.4.1.9.5.7.. have an IP address starting with 10.10.. and do not have the name clandestine.

            DiscoAgentSupportedDevices
            (
                        "(
                                ( m_ObjectId = '1.3.6.1.4.1.9.5.7' )
                                AND
                                ( m_UniqueAddress like '^10\.10\..*' )
                                AND
                                ( m_Name not like '.*[cC]landestin[eE].*' )
                        )"
            );

Enabling multi-threaded operation for Perl discovery agents

The number of threads used by discovery agents is set in the DiscoAgents.cfg configuration file. Perl agents must have multi-threaded operation enabled before the setting in the DiscoAgents.cfg configuration file has any effect.

To enable multi-threaded operation for a Perl discovery agent, add the following line to its definition file:

DiscoAgentDefaultThreads( 10 );

The insert above specifies that the agent uses 10 threads by default. If you set a different number of threads in the DiscoAgents.cfg configuration file, that value overrides the value in the agent definition file.

Restriction: Many of the add-on CPAN modules often used with Perl are not thread safe. Perl discovery agents using such modules might need to be restricted to a single thread.

Filtering topology data returned by a discovery agent

To filter topology data returned by a single agent, define a filter within the relevant agent (.agnt) file.

Example: filtering out subscriber cable-modem interfaces

The CMTS.agnt agent file retrieves data from cable modems connected to a cable modem terminating services device. This example describes a filter added to the CMTS.agnt file which filters out subscriber cable modem interfaces from topology data returned for the CMTS devices. The example filter is as follows:

DiscoAgentReturnsFilterList
{
      DiscoReturnsFilter
      {
            "(
             m_LocalNbr->m_IfType = 229
            )"
      }
};

Sample: defining multiple topology filters

The following example illustrates how to define multiple topology data filters within an agent. The first filter specifies that each time a record is returned where the interface ifIndex value is 4, then the m_Name, m_HaveAccess, m_LocalNbr->m_SubnetMask, and m_RemoteNbr->m_RemoteNbrPhysAddr fields must be deleted from the record. The second filter deletes records returned when the interface ifIndex value is 5.

DiscoAgentReturnsFilterList
{
      DiscoReturnsFilter
      {
            "(
             m_LocalNbr->m_IfIndex = 4
            )"
            DiscoDeleteFields {
                  "m_Name",
                  "m_HaveAccess",
                  "m_LocalNbr->m_SubnetMask",
                  "m_RemoteNbr->m_RemoteNbrPhysAddr",
            }
      }
      DiscoReturnsFilter
      {
            "(
             m_LocalNbr->m_IfIndex = 5
            )"
      }
};

Example: Disabling partial matching

The following example could be appended to the IpForwardingTable.agnt definition file to ensure that if a router with m_ObjectId='1.3.6.1.4.1.9.1.48' is discovered (that is, a Cisco 7505 router), partial matching is attempted only when the router is running IOS version 12.2 or higher.

            DiscoRouterPartialMatchRestrictions
            (
                        "(m_ObjectId='1.3.6.1.4.1.9.1.48', m_OSVersion>='12.2',
                        m_MibVar='sysDescr')"
            );

Example: Disabling partial matching using wildcards

The following example ensures that partial matching is not used on Cisco 2600 routers, Cisco 7505 routers running an IOS revision lower than 12.2, and Redstone routers.

            DiscoRouterPartialMatchRestrictions
            (
                        "(m_ObjectId='1.3.6.1.4.1.9.1.209'),
                        (m_ObjectId='1.3.6.1.4.1.9.1.48', m_OSVersion>='12.2',
                         m_MibVar='sysDescr'),
                        (m_ObjectId like '1\.3\.6\.1\.4\.1\.2773\..*')"
            );