SNMP

class SNMP (View source)

Represents SNMP session.

Constants

VERSION_1

VERSION_2c

VERSION_2C

VERSION_3

ERRNO_NOERROR

ERRNO_ANY

ERRNO_GENERIC

ERRNO_TIMEOUT

ERRNO_ERROR_IN_REPLY

ERRNO_OID_NOT_INCREASING

ERRNO_OID_PARSING_ERROR

ERRNO_MULTIPLE_SET_QUERIES

Properties

int $max_oids
int $valueretrieval
bool $quick_print
bool $enum_print
int $oid_output_format
bool $oid_increasing_check
int $exceptions_enabled
array $info

Methods

__construct(int $version, string $hostname, string $community, int $timeout = 1000000, int $retries = 5)

Creates SNMP instance representing session to remote SNMP agent

bool
close()

Close SNMP session

bool
setSecurity(string $sec_level, string $auth_protocol, string $auth_passphrase, string $priv_protocol, string $priv_passphrase, string $contextName, string $contextEngineID)

Configures security-related SNMPv3 session parameters

mixed
get(mixed $object_id, bool $preserve_keys = false)

Fetch an SNMP object

mixed
getnext(mixed $object_id)

Fetch an SNMP object which follows the given object id

array|false
walk(string $object_id, bool $suffix_as_keys = false, int $max_repetitions, int $non_repeaters)

Fetch SNMP object subtree

bool
set(string $object_id, mixed $type, mixed $value)

Set the value of an SNMP object

int
getErrno()

Get last error code

string
getError()

Get last error message

Details

at line 126
__construct(int $version, string $hostname, string $community, int $timeout = 1000000, int $retries = 5)

Since: 5.4

Creates SNMP instance representing session to remote SNMP agent

Parameters

int $version

SNMP protocol version: SNMP::VERSION_1, SNMP::VERSION_2C, SNMP::VERSION_3.
string $hostname

The SNMP agent. hostname may be suffixed with optional SNMP agent port after colon. IPv6 addresses must be enclosed in square brackets if used with port. If FQDN is used for hostname it will be resolved by php-snmp library, not by Net-SNMP engine. Usage of IPv6 addresses when specifying FQDN may be forced by enclosing FQDN into square brackets. Here it is some examples:

IPv4 with default port127.0.0.1
IPv6 with default port::1 or [::1]
IPv4 with specific port127.0.0.1:1161
IPv6 with specific port[::1]:1161
FQDN with default porthost.domain
FQDN with specific porthost.domain:1161
FQDN with default port, force usage of IPv6 address[host.domain]
FQDN with specific port, force usage of IPv6 address[host.domain]:1161
string $community

The purpuse of community is SNMP version specific:

SNMP::VERSION_1SNMP community
SNMP::VERSION_2CSNMP community
SNMP::VERSION_3SNMPv3 securityName
int $timeout

[optional] The number of microseconds until the first timeout.
int $retries

[optional] The number of retries in case timeout occurs.

at line 134
bool close()

Since: 5.4

Close SNMP session

Return Value

bool

TRUE on success or FALSE on failure.

at line 149
bool setSecurity(string $sec_level, string $auth_protocol, string $auth_passphrase, string $priv_protocol, string $priv_passphrase, string $contextName, string $contextEngineID)

Since: 5.4

Configures security-related SNMPv3 session parameters

Parameters

string $sec_level

the security level (noAuthNoPriv|authNoPriv|authPriv)
string $auth_protocol

[optional] the authentication protocol (MD5 or SHA)
string $auth_passphrase

[optional] the authentication pass phrase
string $priv_protocol

[optional] the privacy protocol (DES or AES)
string $priv_passphrase

[optional] the privacy pass phrase
string $contextName

[optional] the context name
string $contextEngineID

[optional] the context EngineID

Return Value

bool

TRUE on success or FALSE on failure.

at line 160
mixed get(mixed $object_id, bool $preserve_keys = false)

Since: 5.4

Fetch an SNMP object

Parameters

mixed $object_id

The SNMP object (OID) or objects
bool $preserve_keys

[optional] When object_id is a array and preserve_keys set to TRUE keys in results will be taken exactly as in object_id, otherwise SNMP::oid_output_format property is used to determinate the form of keys.

Return Value

mixed

SNMP objects requested as string or array depending on object_id type or FALSE on error.

at line 173
mixed getnext(mixed $object_id)

Since: 5.4

Fetch an SNMP object which follows the given object id

Parameters

mixed $object_id

The SNMP object (OID) or objects

Return Value

mixed

SNMP objects requested as string or array depending on object_id type or FALSE on error.

at line 189
array|false walk(string $object_id, bool $suffix_as_keys = false, int $max_repetitions, int $non_repeaters)

Since: 5.4

Fetch SNMP object subtree

Parameters

string $object_id

Root of subtree to be fetched
bool $suffix_as_keys

[optional]

By default full OID notation is used for keys in output array. If set to TRUE subtree prefix will be removed from keys leaving only suffix of object_id.
int $max_repetitions

[optional]

This specifies the maximum number of iterations over the repeating variables. The default is to use this value from SNMP object.
int $non_repeaters

[optional]

This specifies the number of supplied variables that should not be iterated over. The default is to use this value from SNMP object.

Return Value

array|false

associative array of the SNMP object ids and their values on success or FALSE on error. When a SNMP error occures SNMP::getErrno and SNMP::getError can be used for retrieving error number (specific to SNMP extension, see class constants) and error message respectively.

at line 262
bool set(string $object_id, mixed $type, mixed $value)

Since: 5.4 <p>When count of OIDs in object_id array is greater than max_oids object property set method will have to use multiple queries to perform requested value updates. In this case type and value checks are made per-chunk so second or subsequent requests may fail due to wrong type or value for OID requested. To mark this a warning is raised when count of OIDs in object_id array is greater than max_oids. When count of OIDs in object_id array is greater than max_oids object property set method will have to use multiple queries to perform requested value updates. In this case type and value checks are made per-chunk so second or subsequent requests may fail due to wrong type or value for OID requested. To mark this a warning is raised when count of OIDs in object_id array is greater than max_oids.</p>

Set the value of an SNMP object

Parameters

string $object_id

The SNMP object id
mixed $type

The MIB defines the type of each object id. It has to be specified as a single character from the below list.

types:

=The type is taken from the MIB
iINTEGER
uINTEGER
sSTRING
xHEX STRING
dDECIMAL STRING
nNULLOBJ
oOBJID
tTIMETICKS
aIPADDRESS
bBITS

If OPAQUE_SPECIAL_TYPES was defined while compiling the SNMP library, the following are also valid:

types:

Uunsigned int64
Isigned int64
Ffloat
Ddouble

Most of these will use the obvious corresponding ASN.1 type. 's', 'x', 'd' and 'b' are all different ways of specifying an OCTET STRING value, and the 'u' unsigned type is also used for handling Gauge32 values.

If the MIB-Files are loaded by into the MIB Tree with "snmp_read_mib" or by specifying it in the libsnmp config, '=' may be used as the type parameter for all object ids as the type can then be automatically read from the MIB.

Note that there are two ways to set a variable of the type BITS like e.g. "SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}":

  • Using type "b" and a list of bit numbers. This method is not recommended since GET query for the same OID would return e.g. 0xF8.
  • Using type "x" and a hex number but without(!) the usual "0x" prefix.

See examples section for more details.

mixed $value

The new value.

Return Value

bool

TRUE on success or FALSE on failure.

at line 270
int getErrno()

Since: 5.4

Get last error code

Return Value

int

one of SNMP error code values described in constants chapter.

at line 278
string getError()

Since: 5.4

Get last error message

Return Value

string

String describing error from last SNMP request.