SNMP

目录

简介

Represents SNMP session.

类摘要

SNMP

class SNMP {

/* 属性 */

public int $max_oids ;

public int $valueretrieval ;

public bool $quick_print ;

public bool $enum_print ;

public int $oid_output_format ;

public bool $oid_increasing_check ;

public int $exceptions_enabled ;

public array $info ;

/* 方法 */

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

public bool close ( void )

public mixed get ( mixed $object_id [, bool $preserve_keys = FALSE ] )

public int getErrno ( void )

public string getError ( void )

public mixed getnext ( mixed $object_id )

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

public bool setSecurity ( string $sec_level [, string $auth_protocol = [, string $auth_passphrase = [, string $priv_protocol = [, string $priv_passphrase = [, string $contextName = [, string $contextEngineID = ]]]]]] )

public array walk ( string $object_id [, bool $suffix_as_key = FALSE [, int $max_repetitions [, int $non_repeaters ]]] )

/* 常量 */

const integer SNMP::ERRNO_NOERROR = 0 ;

const integer SNMP::ERRNO_GENERIC = 2 ;

const integer SNMP::ERRNO_TIMEOUT = 4 ;

const integer SNMP::ERRNO_ERROR_IN_REPLY = 8 ;

const integer SNMP::ERRNO_OID_NOT_INCREASING = 16 ;

const integer SNMP::ERRNO_OID_PARSING_ERROR = 32 ;

const integer SNMP::ERRNO_MULTIPLE_SET_QUERIES = 64 ;

const integer SNMP::ERRNO_ANY = 126 ;

const integer SNMP::VERSION_1 = 0 ;

const integer SNMP::VERSION_2C = 1 ;

const integer SNMP::VERSION_2c = 1 ;

const integer SNMP::VERSION_3 = 3 ;

}

属性

max_oids
Maximum OID per GET/SET/GETBULK request

valueretrieval
Controls the method how the SNMP values will be returned

SNMP_VALUE_LIBRARYThe return values will be as returned by the Net-SNMP library.
SNMP_VALUE_PLAINThe return values will be the plain value without the SNMP type hint.
SNMP_VALUE_OBJECTThe return values will be objects with the properties "value" and "type", where the latter is one of the SNMP_OCTET_STR, SNMP_COUNTER etc. constants. The way "value" is returned is based on which one of SNMP_VALUE_LIBRARY, SNMP_VALUE_PLAIN is set

quick_print
Value of quick_print within the NET-SNMP library

Sets the value of quick_print within the NET-SNMP library. When this is set (1), the SNMP library will return 'quick printed' values. This means that just the value will be printed. When quick_print is not enabled (default) the UCD SNMP library prints extra information including the type of the value (i.e. IpAddress or OID). Additionally, if quick_print is not enabled, the library prints additional hex values for all strings of three characters or less.

enum_print
Controls the way enum values are printed

Parameter toggles if walk/get etc. should automatically lookup enum values in the MIB and return them together with their human readable string.

oid_output_format
Controls OID output format

SNMP_OID_OUTPUT_FULL.iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.sysUpTimeInstance
SNMP_OID_OUTPUT_NUMERIC.1.3.6.1.2.1.1.3.0
SNMP_OID_OUTPUT_MODULEDISMAN-EVENT-MIB::sysUpTimeInstance
SNMP_OID_OUTPUT_SUFFIXsysUpTimeInstance
SNMP_OID_OUTPUT_UCDsystem.sysUpTime.sysUpTimeInstance
SNMP_OID_OUTPUT_NONEUndefined

oid_increasing_check
Controls disabling check for increasing OID while walking OID tree

Some SNMP agents are known for returning OIDs out of order but can complete the walk anyway. Other agents return OIDs that are out of order and can cause SNMP::walk to loop indefinitely until memory limit will be reached. PHP SNMP library by default performs OID increasing check and stops walking on OID tree when it detects possible loop with issuing warning about non-increasing OID faced. Set oid_increasing_check to FALSE to disable this check.

exceptions_enabled
Controls which failures will raise SNMPException instead of warning. Use bitwise OR'ed SNMP::ERRNO_* constants. By default all SNMP exceptions are disabled.

info
Read-only property with remote agent configuration: hostname, port, default timeout, default retries count

预定义常量

SNMP Error Types

SNMP::ERRNO_NOERROR
No SNMP-specific error occurred.

SNMP::ERRNO_GENERIC
A generic SNMP error occurred.

SNMP::ERRNO_TIMEOUT
Request to SNMP agent timed out.

SNMP::ERRNO_ERROR_IN_REPLY
SNMP agent returned an error in reply.

SNMP::ERRNO_OID_NOT_INCREASING
SNMP agent faced OID cycling reporning non-increasing OID while executing (BULK)WALK command. This indicates bogus remote SNMP agent.

SNMP::ERRNO_OID_PARSING_ERROR
Library failed while parsing OID (and/or type for SET command). No queries has been made.

SNMP::ERRNO_MULTIPLE_SET_QUERIES
Library will use multiple queries for SET operation requested. That means that operation will be performed in a non-transaction manner and second or subsequent chunks may fail if a type or value failure will be faced.

SNMP::ERRNO_ANY
All SNMP::ERRNO_* codes bitwise OR'ed.

SNMP Protocol Versions

SNMP::VERSION_1

SNMP::VERSION_2C, SNMP::VERSION_2c

SNMP::VERSION_3

SNMP::close

Close SNMP session

说明

public bool SNMP::close ( void )

Frees previously allocated SNMP session object.

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

范例

示例 #1 SNMP::close example

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  # ...
  # get, walk, etc goes here
  # ...
  $session->close();
?>

参见

  • SNMP::__construct

SNMP::__construct

Creates SNMP instance representing session to remote SNMP agent

说明

public SNMP::__construct ( int $version , string $hostname , string $community [, int $timeout = 1000000 [, int $retries = 5 ]] )

The function description goes here.

参数

version
SNMP protocol version: SNMP::VERSION_1, SNMP::VERSION_2C, SNMP::VERSION_3.

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

community
The purpuse of community is SNMP version specific:

SNMP::VERSION_1SNMP community
SNMP::VERSION_2CSNMP community
SNMP::VERSION_3SNMPv3 securityName

timeout
The number of microseconds until the first timeout.

retries
The number of retries in case timeout occurs.

返回值

Returns SNMP object representing remote SNMP agent.

错误/异常

SNMP::__construct throws an exception when parameters count or types are wrong or unknown SNMP protocol version specified.

范例

示例 #1 Fetching sysLocation

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $sysdescr = $session->get("sysDescr.0");
  echo "$sysdescr\n";
?>

以上例程的输出类似于:

STRING: Test server

参见

  • SNMP::close

SNMP::get

Fetch an SNMP object

说明

public mixed SNMP::get ( mixed $object_id [, bool $preserve_keys = FALSE ] )

Fetch an SNMP object specified in object_id using GET query.

参数

If object_id is a string, then SNMP::get will return SNMP object as string. If object_id is a array, all requested SNMP objects will be returned as associative array of the SNMP object ids and their values.

object_id
The SNMP object (OID) or objects

preserve_keys
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.

返回值

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

错误/异常

本方法默认不抛出任何异常。如果要在某些库出错时抛出 SNMPException 异常,用户需要将 SNMP 类参数 exceptions_enabled 设定为相应的值。更多细节见 SNMP::$exceptions_enabled 的解释

范例

示例 #1 Single SNMP object

Single SNMP object may be requested in two ways: as string resulting string return value or as single-element array with associative array as output.

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $sysdescr = $session->get("sysDescr.0");
  echo "$sysdescr\n";
  $sysdescr = $session->get(array("sysDescr.0"));
  print_r($sysdescr);
?>

以上例程的输出类似于:

STRING: Test server
Array
(
    [SNMPv2-MIB::sysDescr.0] => STRING: Test server
)

示例 #2 Multiple SNMP objects

$session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $results = $session->get(array("sysDescr.0", "sysName.0"));
  print_r($results);
  $session->close();

以上例程的输出类似于:

Array
(
    [SNMPv2-MIB::sysDescr.0] => STRING: Test server
    [SNMPv2-MIB::sysName.0] => STRING: myhost.nodomain
)

参见

  • SNMP::getErrno
  • SNMP::getError

SNMP::getErrno

Get last error code

说明

public int SNMP::getErrno ( void )

Returns error code from last SNMP request.

返回值

Returns one of SNMP error code values described in constants chapter.

范例

示例 #1 SNMP::getErrno example

<?php
$session = new SNMP(SNMP::VERSION_2c, '127.0.0.1', 'boguscommunity');
var_dump(@$session->get('.1.3.6.1.2.1.1.1.0'));
var_dump($session->getErrno() == SNMP::ERRNO_TIMEOUT);
?>

以上例程会输出:

bool(false)
bool(true)

参见

  • SNMP::getError

SNMP::getError

Get last error message

说明

public string SNMP::getError ( void )

Returns string with error from last SNMP request.

返回值

String describing error from last SNMP request.

范例

示例 #1 SNMP::getError example

<?php
$session = new SNMP(SNMP::VERSION_2c, '127.0.0.1', 'boguscommunity');
var_dump(@$session->get('.1.3.6.1.2.1.1.1.0'));
var_dump($session->getError());
?>

以上例程会输出:

bool(false)
string(26) "No response from 127.0.0.1"

参见

  • SNMP::getErrno

SNMP::getnext

Fetch an SNMP object which follows the given object id

说明

public mixed SNMP::getnext ( mixed $object_id )

Fetch an SNMP object that follows specified object_id.

参数

If object_id is a string, then SNMP::getnext will return SNMP object as string. If object_id is a array, all requested SNMP objects will be returned as associative array of the SNMP object ids and their values.

object_id
The SNMP object (OID) or objects

返回值

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

错误/异常

本方法默认不抛出任何异常。如果要在某些库出错时抛出 SNMPException 异常,用户需要将 SNMP 类参数 exceptions_enabled 设定为相应的值。更多细节见 SNMP::$exceptions_enabled 的解释

范例

示例 #1 Single SNMP object

Single SNMP object may be requested in two ways: as string resulting string return value or as single-element array with associative array as output.

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $nsysdescr = $session->getnext("sysDescr.0");
  echo "$nsysdescr\n";
  $nsysdescr = $session->getnext(array("sysDescr.0"));
  print_r($nsysdescr);
?>

以上例程的输出类似于:

OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
Array
(
    [SNMPv2-MIB::sysObjectID.0] => OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
)

示例 #2 Miltiple SNMP objects

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $results = $session->getnext(array("sysDescr.0", "sysName.0"));
  print_r($results);
  $session->close();
?>

以上例程的输出类似于:

Array
(
    [SNMPv2-MIB::sysObjectID.0] => OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
    [SNMPv2-MIB::sysLocation.0] => STRING: Nowhere
)

参见

  • SNMP::getErrno
  • SNMP::getError

SNMP::set

Set the value of an SNMP object

说明

public bool SNMP::set ( mixed $object_id , mixed $type , mixed $value )

Requests remote SNMP agent setting the value of one or more SNMP objects specified by the object_id.

参数

object_id
The SNMP object id

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.

type
MIB 定义了各个对象 id 的类型。必须是下面列出的单个字符之一。

=MIB类型
iINTEGER
uINTEGER
sSTRING
xHEX STRING
dDECIMAL STRING
nNULLOBJ
oOBJID
tTIMETICKS
aIPADDRESS
bBITS

如果在编译 SNMP 库时定义了 OPAQUE_SPECIAL_TYPES,那么下列值是合法的:

Uunsigned int64
Isigned int64
Ffloat
Ddouble

这些值大都会使用与 ASN.1 相符的类型。's','x','d' 以及 'b' 都是指定一个八字节字符串值的方式。并且 'u' 无符号类型也可用于处理 Gauge32 值。

如果 MIB 文件是用 "snmp_read_mib" 或者通过在 libsnmp config 中指定而加载入 MIB 树时, '=' 可以被用作为所有对象的 type 参数,因为 type 可以被自动从 MIB 中读取。

注意有两种方式可以设定 BITS 类型的变量,例如 "SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}":

  • 使用 "b" 类型以及一个位数的列表。不推荐使用此方法,因为 GET 查询对同一个 OID 将会返回例如 0xF8。
  • 使用 "x" 类型以及一个十六进制数但是不需要通常的 "0x" 前缀。

更多细节见范例部分。

value
The new value.

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

错误/异常

本方法默认不抛出任何异常。如果要在某些库出错时抛出 SNMPException 异常,用户需要将 SNMP 类参数 exceptions_enabled 设定为相应的值。更多细节见 SNMP::$exceptions_enabled 的解释

范例

示例 #1 Set single SNMP object id

<?php
  $session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
  $session->set('SNMPv2-MIB::sysContact.0', 's', "Nobody");
?>

示例 #2 Set multiple values using single SNMP::set call

<?php
  $session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
  $session->set(array('SNMPv2-MIB::sysContact.0', 'SNMPv2-MIB::sysLocation.0'), array('s', 's'), array("Nobody", "Nowhere"));
// or
  $session->set(array('SNMPv2-MIB::sysContact.0', 'SNMPv2-MIB::sysLocation.0'), 's', array("Nobody", "Nowhere"));
?>

示例 #3 Using SNMP::set for setting BITS SNMP object id

<?php
  $session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
  $session->set('FOO-MIB::bar.42', 'b', '0 1 2 3 4');
// or
  $session->set('FOO-MIB::bar.42', 'x', 'F0');
?>

参见

  • SNMP::get

SNMP::setSecurity

Configures security-related SNMPv3 session parameters

说明

public bool SNMP::setSecurity ( string $sec_level [, string $auth_protocol = [, string $auth_passphrase = [, string $priv_protocol = [, string $priv_passphrase = [, string $contextName = [, string $contextEngineID = ]]]]]] )

setSecurity configures security-related session parameters used in SNMP protocol version 3

参数

sec_level
the security level (noAuthNoPriv|authNoPriv|authPriv)

auth_protocol
the authentication protocol (MD5 or SHA)

auth_passphrase
the authentication pass phrase

priv_protocol
the privacy protocol (DES or AES)

priv_passphrase
the privacy pass phrase

contextName
the context name

contextEngineID
the context EngineID

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

范例

示例 #1 SNMP::setSecurity example

<?php
  $session = new SNMP(SNMP::VERSION_3, $hostname, $rwuser, $timeout, $retries);
  $session->setSecurity('authPriv', 'MD5', $auth_pass, 'AES', $priv_pass, '', 'aeeeff');
?>

参见

  • SNMP::__construct

SNMP::walk

Fetch SNMP object subtree

说明

public array SNMP::walk ( string $object_id [, bool $suffix_as_key = FALSE [, int $max_repetitions [, int $non_repeaters ]]] )

SNMP::walk is used to read SNMP subtree rooted at specified object_id.

参数

object_id
Root of subtree to be fetched

suffix_as_key
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.

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

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

返回值

Returns an 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.

错误/异常

本方法默认不抛出任何异常。如果要在某些库出错时抛出 SNMPException 异常,用户需要将 SNMP 类参数 exceptions_enabled 设定为相应的值。更多细节见 SNMP::$exceptions_enabled 的解释

范例

示例 #1 SNMP::walk example

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $fulltree = $session->walk(".");
  print_r($fulltree);
  $session->close();
?>

以上例程的输出类似于:

Array
(
    [SNMPv2-MIB::sysDescr.0] => STRING: Test server
    [SNMPv2-MIB::sysObjectID.0] => OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
    [DISMAN-EVENT-MIB::sysUpTimeInstance] => Timeticks: (1150681750) 133 days, 4:20:17.50
    [SNMPv2-MIB::sysContact.0] => STRING: Nobody
    [SNMPv2-MIB::sysName.0] => STRING: server.localdomain
    ...
)

示例 #2 suffix_as_key example

suffix_as_key may be used when merging multiple SNMP subtrees into one. This example maps interface names to their type.

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $session->valueretrieval = SNMP_VALUE_PLAIN;
  $ifDescr = $session->walk(".1.3.6.1.2.1.2.2.1.2", TRUE);
  $session->valueretrieval = SNMP_VALUE_LIBRARY;
  $ifType = $session->walk(".1.3.6.1.2.1.2.2.1.3", TRUE);
  print_r($ifDescr);
  print_r($ifType);
  $result = array();
  foreach($ifDescr as $i => $n) {
    $result[$n] = $ifType[$i];
  }
  print_r($result);
?>

以上例程的输出类似于:

Array
(
    [1] => igb0
    [2] => igb1
    [3] => ipfw0
    [4] => lo0
    [5] => lagg0
)
Array
(
    [1] => INTEGER: ieee8023adLag(161)
    [2] => INTEGER: ieee8023adLag(161)
    [3] => INTEGER: ethernetCsmacd(6)
    [4] => INTEGER: softwareLoopback(24)
    [5] => INTEGER: ethernetCsmacd(6)
)
Array
(
    [igb0] => INTEGER: ieee8023adLag(161)
    [igb1] => INTEGER: ieee8023adLag(161)
    [ipfw0] => INTEGER: ethernetCsmacd(6)
    [lo0] => INTEGER: softwareLoopback(24)
    [lagg0] => INTEGER: ethernetCsmacd(6)
)

参见

  • SNMP::getErrno
  • SNMP::getError

简介

Represents an error raised by SNMP. You should not throw a SNMPException from your own code. See Exceptions for more information about Exceptions in PHP.

类摘要

SNMPException

class SNMPException extends RuntimeException {

/* 属性 */

protected string $code ;

/* 继承的属性 */

protected string $message ;

protected int $code ;

protected string $file ;

protected int $line ;

/* 继承的方法 */

final public string Exception::getMessage ( void )

final public Throwable Exception::getPrevious ( void )

final public int Exception::getCode ( void )

final public string Exception::getFile ( void )

final public int Exception::getLine ( void )

final public array Exception::getTrace ( void )

final public string Exception::getTraceAsString ( void )

public string Exception::__toString ( void )

final private void Exception::__clone ( void )

}

属性

code
SNMPlibrary error code. Use Exception::getCode to access it.