snmpget() - send a SNMP get-request to the remote agent¶

    @result = snmpget(
                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                [\%param_hash],
                @oids
            );

This function performs a SNMP get-request query to gather data from the remote agent on the host specified. The message is built using the list of OBJECT IDENTIFIERs passed as an array. Each OBJECT IDENTIFIER is placed into a single SNMP GetRequest-PDU in the same order that it held in the original list.

The requested values are returned in an array in the same order as they were requested. In scalar context the first requested value is returned.

snmpgetnext() - send a SNMP get-next-request to the remote agent¶

    @result = snmpgetnext(
                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                [\%param_hash],
                @oids
            );

This function performs a SNMP get-next-request query to gather data from the remote agent on the host specified. The message is built using the list of OBJECT IDENTIFIERs passed as an array. Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same order that it held in the original list.

The requested values are returned in an array in the same order as they were requested. The OBJECT IDENTIFIER number is added as a prefix to each value using a colon as a separator, like '1.3.6.1.2.1.2.2.1.2.1:ethernet'. In scalar context the first requested value is returned.

snmpgetbulk() - send a SNMP get-bulk-request to the remote agent¶

    @result = snmpgetbulk(
                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                $nonrepeaters,
                $maxrepetitions,
                [\%param_hash],
                @oids
            );

This function performs a SNMP get-bulk-request query to gather data from the remote agent on the host specified.

• The $nonrepeaters value specifies the number of variables in the @oids list for which a single successor is to be returned. If it is null or undefined, a value of 0 is used.
• The $maxrepetitions value specifies the number of successors to be returned for the remaining variables in the @oids list. If it is null or undefined, the default value of 12 is used.
• The message is built using the list of OBJECT IDENTIFIERs passed as an array. Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same order that it held in the original list.

The requested values are returned in an array in the same order as they were requested.

NOTE: This function can only be used when the SNMP version is set to SNMPv2c or SNMPv3.

snmpwalk() - walk OBJECT IDENTIFIER tree(s) on the remote agent¶

    @result = snmpwalk(
                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                [\%param_hash],
                @oids
            );

This function performs a sequence of SNMP get-next-request or get-bulk-request (if the SNMP version is 2 or higher) queries to gather data from the remote agent on the host specified. The initial message is built using the list of OBJECT IDENTIFIERs passed as an array. Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same order that it held in the original list. Queries continue until all the returned OBJECT IDENTIFIERs are no longer a child of the base OBJECT IDENTIFIERs.

The requested values are returned in an array in the same order as they were requested. The OBJECT IDENTIFIER number is added as a prefix to each value using a colon as a separator, like '1.3.6.1.2.1.2.2.1.2.1:ethernet'. If only one OBJECT IDENTIFIER is requested, just the "instance" part of the OBJECT IDENTIFIER is added as a prefix, like '1:ethernet', '2:ethernet', '3:fddi'.

snmpset() - send a SNMP set-request to the remote agent¶

    @result = snmpset(
                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                [\%param_hash],
                $oid1, $type1, $value1,
                [$oid2, $type2, $value2 ...]
            );

This function is used to modify data on the remote agent using a SNMP set-request. The message is built using the list of values consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value to be set. The object type can be one of the following strings:

    integer | int
    string | octetstring | octet string
    oid | object id | object identifier
    ipaddr | ip addr4ess
    timeticks
    uint | uinteger | uinteger32 | unsigned int | unsigned integer | unsigned integer32
    counter | counter 32
    counter64
    gauge | gauge32

The object type may also be an octet corresponding to the ASN.1 type. See the Net::SNMP documentation for more information.

The requested values are returned in an array in the same order as they were requested. In scalar context the first requested value is returned.

snmptrap() - send a SNMP trap to the remote manager¶

    @result = snmptrap(
                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                $enterprise,
                $agentaddr,
                $generictrap,
                $specifictrap,
                [\%param_hash],
                $oid1, $type1, $value1, 
                [$oid2, $type2, $value2 ...]
            );

This function sends a SNMP trap to the remote manager on the host specified. The message is built using the list of values consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value to be set. The object type can be one of the following strings:

    integer | int
    string | octetstring | octet string
    oid | object id | object identifier
    ipaddr | ip addr4ess
    timeticks
    uint | uinteger | uinteger32 | unsigned int | unsigned integer | unsigned integer32
    counter | counter 32
    counter64
    gauge | gauge32

The object type may also be an octet corresponding to the ASN.1 type. See the Net::SNMP documentation for more information.

A true value is returned if sending the trap is successful. The undefined value is returned when a failure has occurred.

When the trap is sent as SNMPv2c, the $enterprise, $agentaddr, $generictrap, and $specifictrap arguments are ignored. Furthermore, the first two (oid, type, value) tuples should be:

• sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', 'timeticks', $timeticks)
• snmpTrapOID.0 - ('1.3.6.1.6.3.1.1.4.1.0', 'oid', $oid)

NOTE: This function can only be used when the SNMP version is set to SNMPv1 or SNMPv2c.

snmpmaptable() - walk OBJECT IDENTIFIER tree(s) on the remote agent¶

    $result = snmpmaptable(
                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                \&function,
                [\%param_hash],
                @oids
            );

This function performs a sequence of SNMP get-next-request or get-bulk-request (if the SNMP version is 2 or higher) queries to gather data from the remote agent on the host specified. The initial message is built using the list of OBJECT IDENTIFIERs passed as an array. Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same order that it held in the original list. Queries continue until all the returned OBJECT IDENTIFIERs are no longer a child of the base OBJECT IDENTIFIERs. The OBJECT IDENTIFIERs must correspond to column entries for a conceptual row in a table. They may however be columns in different tables as long as each table is indexed the same way.

•

The \&function argument will be called once per row of the table. It will be passed the row index as a partial OBJECT IDENTIFIER in dotted notation, e.g. "1.3" or "10.0.1.34", and the values of the requested table columns in that row.

The number of rows in the table is returned on success. The undefined value is returned when a failure has occurred.

snmpmaptable4() - walk OBJECT IDENTIFIER tree(s) on the remote agent¶

    $result = snmpmaptable4(
                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                \&function,
                $maxrepetitions,
                [\%param_hash],
                @oids
            );

This function performs a sequence of SNMP get-next-request or get-bulk-request (if the SNMP version is 2 or higher) queries to gather data from the remote agent on the host specified. The initial message is built using the list of OBJECT IDENTIFIERs passed as an array. Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same order that it held in the original list. Queries continue until all the returned OBJECT IDENTIFIERs are no longer a child of the base OBJECT IDENTIFIERs. The OBJECT IDENTIFIERs must correspond to column entries for a conceptual row in a table. They may however be columns in different tables as long as each table is indexed the same way.

• The \&function argument will be called once per row of the table. It will be passed the row index as a partial OBJECT IDENTIFIER in dotted notation, e.g. "1.3" or "10.0.1.34", and the values of the requested table columns in that row.
• The $maxrepetitions argument specifies the number of rows to be returned by a single get-bulk-request. If it is null or undefined, the default value of 12 is used.

The number of rows in the table is returned on success. The undefined value is returned when a failure has occurred.

snmpwalkhash() - send a SNMP get-next-request to the remote agent¶

    @result = snmpwalkhash(
                [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
                \&function(),
                [\%param_hash],
                @oids,
                [\%hash]
            );

This function performs a sequence of SNMP get-next-request or get-bulk-request (if the SNMP version is 2 or higher) queries to gather data from the remote agent on the host specified. The message is built using the list of OBJECT IDENTIFIERs passed as an array. Each OBJECT IDENTIFIER is placed into a single SNMP GetNextRequest-PDU in the same order that it held in the original list. Queries continue until all the returned OBJECT IDENTIFIERs are outside of the tree specified by the initial OBJECT IDENTIFIERs.

The \&function is called once for every returned value. It is passed a reference to a hash, the hostname, the textual OBJECT IDENTIFIER, the dotted-numberic OBJECT IDENTIFIER, the instance, the value and the requested textual OBJECT IDENTIFIER. That function can customize the result so the values can be extracted later by hosts, by oid_names, by oid_numbers, by instances... like these:

    $hash{$host}{$name}{$inst} = $value;
    $hash{$host}{$oid}{$inst} = $value;
    $hash{$name}{$inst} = $value;
    $hash{$oid}{$inst} = $value;
    $hash{$oid . '.' . $ints} = $value;
    $hash{$inst} = $value;
    ...

If the last argument to snmpwalkhash is a reference to a hash, that hash reference is passed to the passed-in function instead of a local hash reference. That way the function can look up other objects unrelated to the current invocation of snmpwalkhash.

The snmpwalkhash routine returns the hash.

snmpmapOID() - add textual OBJECT INDENTIFIER mapping¶

    snmpmapOID(
        $text1, $oid1,
        [ $text2, $oid2 ...]
    );

This routine adds entries to the table that maps textual representation of OBJECT IDENTIFIERs to their dotted notation. For example,

    snmpmapOID('ciscoCPU', '1.3.6.1.4.1.9.9.109.1.1.1.1.5.1');

allows the string 'ciscoCPU' to be used as an OBJECT IDENTIFIER in any SNMP query routine.

This routine doesn't return anything.

snmpLoad_OID_Cache() - Read a file of cached OID mappings¶

    $result = snmpLoad_OID_Cache(
                $file
    );

This routine opens the file named by the $file argument and reads it. The file should contain text, OBJECT IDENTIFIER pairs, one pair per line. It adds the pairs as entries to the table that maps textual representation of OBJECT IDENTIFIERs to their dotted notation. Blank lines and anything after a '#' or between '--' is ignored.

This routine returns 0 on success and -1 if the $file could not be opened.

snmpMIB_to_OID() - Read a MIB file for textual OID mappings¶

    $result = snmpMIB_to_OID(
                $file
    );

This routine opens the file named by the $file argument and reads it. The file should be an SNMP Management Information Base (MIB) file that describes OBJECT IDENTIFIERs supported by an SNMP agent. per line. It adds the textual representation of the OBJECT IDENTIFIERs to the text-to-OID mapping table.

This routine returns the number of entries added to the table or -1 if the $file could not be opened.

snmpQueue_MIB_File() - queue a MIB file for reading "on demand"¶

    snmpQueue_MIB_File(
        $file1,
        [$file2, ...]
    );

This routine queues the list of SNMP MIB files for later processing. Whenever a text-to-OBJECT IDENTIFIER lookup fails, the list of queued MIB files is consulted. If it isn't empty, the first MIB file in the list is removed and passed to snmpMIB_to_OID(). The lookup is attempted again, and if that still fails the next MIB file in the list is removed and passed to snmpMIB_to_OID(). This process continues until the lookup succeeds or the list is exhausted.

This routine doesn't return anything.

1. SNMPv1 get-request for sysUpTime¶

This example gets the sysUpTime from a remote host.

    #! /usr/local/bin/perl
    use strict;
    use Net_SNMP_util;
    my ($host, $ret)
    $host = shift || 'localhost';
    $ret = snmpget($host, 'sysUpTime');
    print("sysUpTime for $host is $ret\n");
    exit 0;

2. SNMPv3 set-request of sysContact¶

This example sets the sysContact information on the remote host to "Help Desk x911". The parameters passed to the snmpset function are for the demonstration of syntax only. These parameters will need to be set according to the SNMPv3 parameters of the remote host used by the script.

    #! /usr/local/bin/perl
    use strict;
    use Net_SNMP_util;
    my($host, %v3hash, $ret);
    $host = shift || 'localhost';
    $v3hash{'-version'}         = 'snmpv3';
    $v3hash{'-username'}        = 'myv3Username';
    $v3hash{'-authkey'}         = '0x05c7fbde31916f64da4d5b77156bdfa7';
    $v3hash{'-authprotocol'}    = 'md5';
    $v3hash{'-privkey'}         = '0x93725fd3a02a48ce02df4e065a1c1746';
    $ret = snmpset($host, \%v3hash, 'sysContact', 'string', 'Help Desk x911');
    print "sysContact on $host is now $ret\n";
    exit 0;

3. SNMPv2c walk for ifTable¶

This example gets the contents of the ifTable by sending get-bulk-requests until the responses are no longer part of the ifTable. The ifTable can also be retrieved using "snmpmaptable".

    #! /usr/local/bin/perl
    use strict;
    use Net_SNMP_util;
    my($host, @ret, $oid, $val);
    $host = shift || 'localhost';
    @ret = snmpwalk($host . ':::::2', 'ifTable');
    foreach $val (@ret) {
        ($oid, $val) = split(':', $val, 2);
        print "$oid => $val\n";
    }
    exit 0;

4. SNMPv2c maptable collecting ifDescr, ifInOctets, and ifOutOctets.¶

This example collects a table containing the columns ifDescr, ifInOctets, and ifOutOctets. A printing function is called once per row.

    #! /usr/local/bin/perl
    use strict;
    use Net_SNMP_util;
    sub printfun($$$$) {
        my($inst, $desc, $in, $out) = @_;
        printf "%3d %-52.52s %10d %10d\n", $inst, $desc, $in, $out;
    }
    my($host, @ret);
    $host = shift || 'localhost';
    printf "%-3s %-52s %10s %10s\n", "Int", "Description", "In", "Out";
    @ret = snmpmaptable($host . ':::::2', \&printfun,
                        'ifDescr', 'ifInOctets', 'ifOutOctets');
    exit 0;