RIV::Agent module overview

The RIV::Agent module provides an interface for implementing Network Manager discovery agents. A discovery agent is a specialized application that retrieves connectivity-related information for network entities.

RIV::Agent constructor

The RIV::Agent module provides a constructor that creates a discovery agent application object. Use this application object to:

  • Interact with Network Manager core components libraries using the virtual methods exported from the RIV module.
  • Instantiate objects for and interact with the other Perl modules: RIV::Param, RIV::Record, and RIV::RecordCache.

Input data records

Input data records that the discovery service sends are supplied through the RIV::GetResult method. These input data records can be stored as RIV::Record objects, which are nested hash lists to which you can add local and remote neighbors.

Note: All input data records that other services (including the OQL service) send are also supplied through the RIV::GetResult method.

Discovery agents and multiple threads

The RIV::Agent module allows you to implement discovery agents using multiple threads. The threads implementation creates a single master Perl interpreter that gets copied, one for each thread. Thus, if the discovery agent makes use of three threads, there will be three copies of the master interpreter. Specifically, the RIV::Agent module provides the LockThreads and UnLockThreads methods related to discovery agents and multiple threads.

SNMP operation methods

The RIV::Agent module provides methods that discovery agents use to obtain Simple Network Management Protocol (SNMP) information from network devices. These methods obtain this information through the Helper Server. Thus, the Helper Server (and ncp_ctrl) must be running so that the SNMP-related methods can make the appropriate SNMP requests.

The following table identifies and briefly describes the SNMP operation methods that the RIV::Agent module provides:

SNMP method Description
SnmpGet Performs an SNMP get operation.
SnmpGetNext Performs an SNMP get-next operation.
SnmpGetBulk Performs an SNMP get-bulk operation.

See RIV::Agent module reference for the reference (man) pages associated with these methods.

DNS operation methods

The RIV::Agent module provides methods that discovery agents use to obtain Domain Name System (DNS) information from network devices. These methods obtain this information through the Helper Server. Thus, the Helper Server (and ncp_ctrl) must be running so that the DNS-related methods can make the appropriate DNS requests.

The following table identifies and briefly describes the DNS operation methods that the RIV::Agent module provides:

DNS method Description
GetDNSAllIpAddrs Gets all IP addresses corresponding to a particular node name.
GetDNSAllNames Gets all node names corresponding to the specified IP addresses.
GetDNSFirstIpAddr Gets the first IP address in the list of IP addresses for this node.
GetDNSFirstName Gets the first node name in the list of node names for this IP address.

See RIV::Agent module reference for the reference (man) pages associated with these methods.

Ping operation methods

The RIV::Agent module provides methods that discovery agents use to perform ping operations on network devices. Ping operations determine whether a specific IP or subnet address is accessible. Typically, the ping operation sends a packet to the specified address and waits for a reply.

The RIV::Agent module ping operation methods perform the specified ping operation through the Helper Server. Thus, the Helper Server (and ncp_ctrl) must be running so that these ping-related methods can make the appropriate ping requests.

The following table identifies and briefly describes the ping operation methods that the RIV::Agent module provides:

ping method Description
GetPingIP Pings the specified IP address and returns whether a network device exists at that address.
GetPingList Pings the specified list of IP addresses and returns a list of network devices that exist at those addresses.
GetPingSubnet Pings the specified subnet and returns whether one or more devices exist at that subnet.
Ping Pings the specified IP address.
PingList Pings the specified list of IP addresses.
PingSubnet Pings the specified subnet.

See RIV::Agent module reference for the reference (man) pages associated with these methods.

IP and MAC address operation methods

The RIV::Agent module provides methods that discovery agents use to perform operations on Internet Protocol (IP) and Medium Access Control (MAC) addresses. The RIV::Agent module IP and MAC address operation methods perform the specified address operation through the Helper Server. Thus, the Helper Server (and ncp_ctrl) must be running so that these address-related methods can make the appropriate address operation requests.

The following table identifies and briefly describes the IP and MAC address operation methods that the RIV::Agent module provides:

Address method Description
GetIpArp Converts the specified MAC address to an IP address.
GetMacArp Converts the specified IP address to a MAC address.
GetTraceRoute Traces a route to the specified destination IP address and returns a list of network devices that reside on that route.

See RIV::Agent module reference for the reference (man) pages associated with these methods.

Telnet operation methods

The RIV::Agent module provides methods that discovery agents use to obtain network device information through Telnet rather than SNMP. Like the SNMP methods, the Telnet methods obtain network device-related information through the Helper Server. Thus, the Helper Server (and ncp_ctrl) must be running so that the Telnet-related methods can make the appropriate Telnet requests.

The following table identifies and briefly describes the Telnet operation methods that the RIV::Agent module provides:

Telnet method Description
GetMultTelnet Executes multiple Telnet commands on the specified network device.
GetTelnet Executes the specified Telnet command on the specified network device.
GetTelnetCols Executes the specified Telnet command on the specified network device and splits the return data into table columns.

See RIV::Agent module reference for the reference (man) pages associated with these methods.

Network entity operation methods

The RIV::Agent module provides methods that discovery agents use to perform operations on network entities. Specifically, the RIV::Agent module provides methods that perform the following network entity operations:

Network entity method Description
SendNEToDisco Sends processed records from RIV::Record to the returns table of the specified Agent database in Disco.
SendNEToNextPhase Marks the network entity as having completed the current phase and puts the network entity back on the Agent queue ready for processing in the next phase.

See RIV::Agent module reference for the reference (man) pages associated with these methods.

Collector communication operation methods

The RIV::Agent module provides methods that discovery agents can use to call XML-RPC methods supported by Collectors. These XML-RPC Collector supported methods will return an XML response that needs to be parsed. The caller specifies either a custom XML-RPC method or one of the XML-RPC methods that the Network Manager Collector XML Schema defines. The Collector communication methods issue requests through the Helper Server. Thus, the Helper Server (and ncp_ctrl) must be running so that the Collector communication-related methods can make the appropriate XML-RPC requests.

The following table identifies and briefly describes the Collector communication operation methods that the RIV::Agent module provides to make the XML-RPC call:

XML-RPC method Description
GetXMLRPCData Issues an XML-RPC call, via the XML-RPC Helper, on the specified method to the specified host and port.
GetXMLRPCEntityData Issues an XML-RPC call, via the XML-RPC Helper, on the specified method. The Collector contacted will be that referenced in the supplied standard entity record (that is, the .despatch record).

See RIV::Agent module reference for the reference (man) pages associated with these methods.