NAME

Net::SNMP::HostInfo - Access the IP statistics of a MIB-II host

SYNOPSIS

use Net::SNMP::HostInfo;

$host = shift || 'localhost';
$password = shift || 'public';

$hostinfo = Net::SNMP::HostInfo->new(Hostname => $host,
                                     Community => $password);

print "Packets Received = ", $hostinfo->ipInReceives, "\n";
print "Output Requests = ", $hostinfo->ipOutRequests, "\n";

print "TCP Segments Received = ", $hostinfo->tcpInSegs, "\n";
print "TCP Segments Sent = ", $hostinfo->tcpOutSegs, "\n";

print "UDP Datagrams Received = ", $hostinfo->udpInDatagrams, "\n";
print "UDP Datagrams Sent = ", $hostinfo->udpOutDatagrams, "\n";

DESCRIPTION

Net::SNMP::HostInfo is a class that simplifies access to the IP, TCP, and UDP information of a MIB-II compliant network host, such as a router or a PC.

You can use it to retrieve numerous statistics on IP, ICMP, TCP, and UDP, as well as the IP routing table (ipRouteTable), the IP address table (ipAddrTable), the ARP table (ipNetToMediaTable), the TCP connection table (tcpConnTable), and the UDP listener table (udpTable). Browse the list of available methods to see what values are available.

METHODS

new

Creates a new Net::SNMP::HostInfo object. You can specify the following optional parameters:

Hostname => $hostname

The hostname of the target device; defaults to 'localhost'.

Community => $community

The community string of the target device; defaults to 'public'.

Session => $session

An alternative to specifying the Hostname and Community parameters: you can use an existing Net::SNMP session for all Net::SNMP::HostInfo queries.

Decode => $decode

If true, certain values, such as ipForwarding, will be returned as strings instead of numbers. For example, ipForwarding will be returned as 'forwarding(1)' or 'not-forwarding(2)'. The following values are affected:

ipForwarding
tcpRtoAlgorithm
ipNetToMediaType (ipNetToMediaTable)
ipRouteType (ipRouteTable)
ipRouteProto (ipRouteTable)
tcpConnState (tcpConnTable)

Additionally, ethernet addresses returned by ipNetToMediaPhysAddress will be prettified.

Here are some examples:

$hostinfo = Net::SNMP::HostInfo->new(Hostname => 'quartz',
                                     Community => 'crystal',
                                     Decode => 1);

$interfaces = Net::SNMP::Interfaces->new(Hostname => 'quartz',
                                         Community => 'crystal');
$hostinfo = Net::SNMP::HostInfo->new(Session => $interfaces->session,
                                     Decode => 1);

($session, $error) = Net::SNMP->session(-hostname => 'quartz',
                                        -community => 'crystal');
$hostinfo = Net::SNMP::HostInfo->new(Session => $session,
                                     Decode => 1);

session

Returns the Net::SNMP session object being used. The session can be then used for other SNMP queries.

ipForwarding

"The indication of whether this entity is acting as an IP gateway in respect to the forwarding of datagrams received by, but not addressed to, this entity. IP gateways forward datagrams. IP hosts do not (except those source-routed via the host).

Note that for some managed nodes, this object may take on only a subset of the values possible. Accordingly, it is appropriate for an agent to return a `badValue' response if a management station attempts to change this object to an inappropriate value."

Possible values are:

forwarding(1),    
not-forwarding(2) 

ipDefaultTTL

"The default value inserted into the Time-To-Live field of the IP header of datagrams originated at this entity, whenever a TTL value is not supplied by the transport layer protocol."

ipInReceives

"The total number of input datagrams received from interfaces, including those received in error."

ipInHdrErrors

"The number of input datagrams discarded due to errors in their IP headers, including bad checksums, version number mismatch, other format errors, time-to-live exceeded, errors discovered in processing their IP options, etc."

ipInAddrErrors

"The number of input datagrams discarded because the IP address in their IP header's destination field was not a valid address to be received at this entity. This count includes invalid addresses (e.g., 0.0.0.0) and addresses of unsupported Classes (e.g., Class E). For entities which are not IP Gateways and therefore do not forward datagrams, this counter includes datagrams discarded because the destination address was not a local address."

ipForwDatagrams

"The number of input datagrams for which this entity was not their final IP destination, as a result of which an attempt was made to find a route to forward them to that final destination. In entities which do not act as IP Gateways, this counter will include only those packets which were Source-Routed via this entity, and the Source- Route option processing was successful."

ipInUnknownProtos

"The number of locally-addressed datagrams received successfully but discarded because of an unknown or unsupported protocol."

ipInDiscards

"The number of input IP datagrams for which no problems were encountered to prevent their continued processing, but which were discarded (e.g., for lack of buffer space). Note that this counter does not include any datagrams discarded while awaiting re-assembly."

ipInDelivers

"The total number of input datagrams successfully delivered to IP user-protocols (including ICMP)."

ipOutRequests

"The total number of IP datagrams which local IP user-protocols (including ICMP) supplied to IP in requests for transmission. Note that this counter does not include any datagrams counted in ipForwDatagrams."

ipOutDiscards

"The number of output IP datagrams for which no problem was encountered to prevent their transmission to their destination, but which were discarded (e.g., for lack of buffer space). Note that this counter would include datagrams counted in ipForwDatagrams if any such packets met this (discretionary) discard criterion."

ipOutNoRoutes

"The number of IP datagrams discarded because no route could be found to transmit them to their destination. Note that this counter includes any packets counted in ipForwDatagrams which meet this `no-route' criterion. Note that this includes any datagarms which a host cannot route because all of its default gateways are down."

ipReasmTimeout

"The maximum number of seconds which received fragments are held while they are awaiting reassembly at this entity."

ipReasmReqds

"The number of IP fragments received which needed to be reassembled at this entity."

ipReasmOKs

"The number of IP datagrams successfully re- assembled."

ipReasmFails

"The number of failures detected by the IP re- assembly algorithm (for whatever reason: timed out, errors, etc). Note that this is not necessarily a count of discarded IP fragments since some algorithms (notably the algorithm in RFC 815) can lose track of the number of fragments by combining them as they are received."

ipFragOKs

"The number of IP datagrams that have been successfully fragmented at this entity."

ipFragFails

"The number of IP datagrams that have been discarded because they needed to be fragmented at this entity but could not be, e.g., because their Don't Fragment flag was set."

ipFragCreates

"The number of IP datagram fragments that have been generated as a result of fragmentation at this entity."

ipAddrTable

"The table of addressing information relevant to this entity's IP addresses."

Returns a list of Net::SNMP::HostInfo::IpAddrEntry objects.

ipRouteTable

"This entity's IP Routing table."

Returns a list of Net::SNMP::HostInfo::IpRouteEntry objects.

ipNetToMediaTable

"The IP Address Translation table used for mapping from IP addresses to physical addresses."

Returns a list of Net::SNMP::HostInfo::IpNetToMediaEntry objects.

ipRoutingDiscards

"The number of routing entries which were chosen to be discarded even though they are valid. One possible reason for discarding such an entry could be to free-up buffer space for other routing entries."

icmpInMsgs

"The total number of ICMP messages which the entity received. Note that this counter includes all those counted by icmpInErrors."

icmpInErrors

"The number of ICMP messages which the entity received but determined as having ICMP-specific errors (bad ICMP checksums, bad length, etc.)."

icmpInDestUnreachs

"The number of ICMP Destination Unreachable messages received."

icmpInTimeExcds

"The number of ICMP Time Exceeded messages received."

icmpInParmProbs

"The number of ICMP Parameter Problem messages received."

icmpInSrcQuenchs

"The number of ICMP Source Quench messages received."

icmpInRedirects

"The number of ICMP Redirect messages received."

icmpInEchos

"The number of ICMP Echo (request) messages received."

icmpInEchoReps

"The number of ICMP Echo Reply messages received."

icmpInTimestamps

"The number of ICMP Timestamp (request) messages received."

icmpInTimestampReps

"The number of ICMP Timestamp Reply messages received."

icmpInAddrMasks

"The number of ICMP Address Mask Request messages received."

icmpInAddrMaskReps

"The number of ICMP Address Mask Reply messages received."

icmpOutMsgs

"The total number of ICMP messages which this entity attempted to send. Note that this counter includes all those counted by icmpOutErrors."

icmpOutErrors

"The number of ICMP messages which this entity did not send due to problems discovered within ICMP such as a lack of buffers. This value should not include errors discovered outside the ICMP layer such as the inability of IP to route the resultant datagram. In some implementations there may be no types of error which contribute to this counter's value."

icmpOutDestUnreachs

"The number of ICMP Destination Unreachable messages sent."

icmpOutTimeExcds

"The number of ICMP Time Exceeded messages sent."

icmpOutParmProbs

"The number of ICMP Parameter Problem messages sent."

icmpOutSrcQuenchs

"The number of ICMP Source Quench messages sent."

icmpOutRedirects

"The number of ICMP Redirect messages sent. For a host, this object will always be zero, since hosts do not send redirects."

icmpOutEchos

"The number of ICMP Echo (request) messages sent."

icmpOutEchoReps

"The number of ICMP Echo Reply messages sent."

icmpOutTimestamps

"The number of ICMP Timestamp (request) messages sent."

icmpOutTimestampReps

"The number of ICMP Timestamp Reply messages sent."

icmpOutAddrMasks

"The number of ICMP Address Mask Request messages sent."

icmpOutAddrMaskReps

"The number of ICMP Address Mask Reply messages sent."

tcpRtoAlgorithm

"The algorithm used to determine the timeout value used for retransmitting unacknowledged octets."

Possible values are:

other(1),    
constant(2), 
rsre(3),     
vanj(4)     

tcpRtoMin

"The minimum value permitted by a TCP implementation for the retransmission timeout, measured in milliseconds. More refined semantics for objects of this type depend upon the algorithm used to determine the retransmission timeout. In particular, when the timeout algorithm is rsre(3), an object of this type has the semantics of the LBOUND quantity described in RFC 793."

tcpRtoMax

"The maximum value permitted by a TCP implementation for the retransmission timeout, measured in milliseconds. More refined semantics for objects of this type depend upon the algorithm used to determine the retransmission timeout. In particular, when the timeout algorithm is rsre(3), an object of this type has the semantics of the UBOUND quantity described in RFC 793."

tcpMaxConn

"The limit on the total number of TCP connections the entity can support. In entities where the maximum number of connections is dynamic, this object should contain the value -1."

tcpActiveOpens

"The number of times TCP connections have made a direct transition to the SYN-SENT state from the CLOSED state."

tcpPassiveOpens

"The number of times TCP connections have made a direct transition to the SYN-RCVD state from the LISTEN state."

tcpAttemptFails

"The number of times TCP connections have made a direct transition to the CLOSED state from either the SYN-SENT state or the SYN-RCVD state, plus the number of times TCP connections have made a direct transition to the LISTEN state from the SYN-RCVD state."

tcpEstabResets

"The number of times TCP connections have made a direct transition to the CLOSED state from either the ESTABLISHED state or the CLOSE-WAIT state."

tcpCurrEstab

"The number of TCP connections for which the current state is either ESTABLISHED or CLOSE- WAIT."

tcpInSegs

"The total number of segments received, including those received in error. This count includes segments received on currently established connections."

tcpOutSegs

"The total number of segments sent, including those on current connections but excluding those containing only retransmitted octets."

tcpRetransSegs

"The total number of segments retransmitted - that is, the number of TCP segments transmitted containing one or more previously transmitted octets."

tcpConnTable

"A table containing TCP connection-specific information."

Returns a list of Net::SNMP::HostInfo::TcpConnEntry objects.

tcpInErrs

"The total number of segments received in error (e.g., bad TCP checksums)."

tcpOutRsts

"The number of TCP segments sent containing the RST flag."

udpInDatagrams

"The total number of UDP datagrams delivered to UDP users."

udpNoPorts

"The total number of received UDP datagrams for which there was no application at the destination port."

udpInErrors

"The number of received UDP datagrams that could not be delivered for reasons other than the lack of an application at the destination port."

udpOutDatagrams

"The total number of UDP datagrams sent from this entity."

udpTable

"A table containing UDP listener information."

Returns a list of Net::SNMP::HostInfo::UdpEntry objects.

ACKNOWLEDGEMENTS

David M. Town - Author of Net::SNMP

Jonathan Stowe - Author of Net::SNMP::Interfaces

AUTHOR

James Macfarlane, <jmacfarla@cpan.org>

SEE ALSO

RFC 1213 MIB-II, Net::SNMP, Net::SNMP::HostInfo::IpAddrEntry, Net::SNMP::HostInfo::IpRouteEntry, Net::SNMP::HostInfo::IpNetToMediaEntry, Net::SNMP::HostInfo::TcpConnEntry, Net::SNMP::HostInfo::UdpEntry