Book/snmp-Phpdoc专题

SNMP

简介
安装／配置
预定义常量
SNMP 函数
- snmp_get_quick_print — 返回 UCD 库中 quick_print 设置的当前值
- snmp_get_valueretrieval — Return the method how the SNMP values will be returned
- snmp_read_mib — Reads and parses a MIB file into the active MIB tree
- snmp_set_enum_print — Return all values that are enums with their enum value instead of the raw integer
- snmp_set_oid_numeric_print — Set the OID output format
- snmp_set_oid_output_format — Set the OID output format
- snmp_set_quick_print — 设置 UCD SNMP 库中 quick_print 的值
- snmp_set_valueretrieval — Specify the method how the SNMP values will be returned
- snmp2_get — Fetch an SNMP object
- snmp2_getnext — Fetch the SNMP object which follows the given object id
- snmp2_real_walk — Return all objects including their respective object ID within the specified one
- snmp2_set — Set the value of an SNMP object
- snmp2_walk — Fetch all the SNMP objects from an agent
- snmp3_get — Fetch an SNMP object
- snmp3_getnext — Fetch the SNMP object which follows the given object id
- snmp3_real_walk — Return all objects including their respective object ID within the specified one
- snmp3_set — Set the value of an SNMP object
- snmp3_walk — Fetch all the SNMP objects from an agent
- snmpget — 获取一个 SNMP 对象
- snmpgetnext — Fetch the SNMP object which follows the given object id
- snmprealwalk — 返回指定的所有对象，包括它们各自的对象 ID
- snmpset — 设置一个 SNMP 对象
- snmpwalk — 从代理返回所有的 SNMP 对象
- snmpwalkoid — 查询关于网络实体的信息树
SNMP — The SNMP class
- SNMP::close — Close SNMP session
- SNMP::__construct — Creates SNMP instance representing session to remote SNMP agent
- SNMP::get — Fetch an SNMP object
- SNMP::getErrno — Get last error code
- SNMP::getError — Get last error message
- SNMP::getnext — Fetch an SNMP object which follows the given object id
- SNMP::set — Set the value of an SNMP object
- SNMP::setSecurity — Configures security-related SNMPv3 session parameters
- SNMP::walk — Fetch SNMP object subtree
SNMPException — The SNMPException class

简介

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 = -1 [, int $retries = -1 ]] )

public bool close ( void )

public arraybool get ( arraystring $objectId [, bool $preserveKeys = false ] )

public int getErrno ( void )

public string getError ( void )

public arraybool getnext ( arraystring $objectId )

public arraybool set ( arraystring $objectId , arraystring $type , arraystring $value )

public bool setSecurity ( string $securityLevel [, string $authProtocol = "" [, string $authPassphrase = "" [, string $privacyProtocol = "" [, string $privacyPassphrase = "" [, string $contextName = "" [, string $contextEngineId = "" ]]]]]] )

public arraybool walk ( arraystring $objectId [, bool $suffixAsKey = false [, int $maxRepetitions = -1 [, int $nonRepeaters = -1 ]]] )

/* 常量 */

const int SNMP::ERRNO_NOERROR = 0 ;

const int SNMP::ERRNO_GENERIC = 2 ;

const int SNMP::ERRNO_TIMEOUT = 4 ;

const int SNMP::ERRNO_ERROR_IN_REPLY = 8 ;

const int SNMP::ERRNO_OID_NOT_INCREASING = 16 ;

const int SNMP::ERRNO_OID_PARSING_ERROR = 32 ;

const int SNMP::ERRNO_MULTIPLE_SET_QUERIES = 64 ;

const int SNMP::ERRNO_ANY = 126 ;

const int SNMP::VERSION_1 = 0 ;

const int SNMP::VERSION_2C = 1 ;

const int SNMP::VERSION_2c = 1 ;

const int 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_LIBRARY`	The return values will be as returned by the Net-SNMP library.
`SNMP_VALUE_PLAIN`	The return values will be the plain value without the SNMP type hint.
`SNMP_VALUE_OBJECT`	The 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 NET-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_MODULE`	DISMAN-EVENT-MIB::sysUpTimeInstance
`SNMP_OID_OUTPUT_SUFFIX`	sysUpTimeInstance
`SNMP_OID_OUTPUT_UCD`	system.sysUpTime.sysUpTimeInstance
`SNMP_OID_OUTPUT_NONE`	Undefined

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 = -1 [, int $retries = -1 ]] )

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 port	127.0.0.1
IPv6 with default port	::1 or [::1]
IPv4 with specific port	127.0.0.1:1161
IPv6 with specific port	[::1]:1161
FQDN with default port	host.domain
FQDN with specific port	host.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_1	SNMP community
SNMP::VERSION_2C	SNMP community
SNMP::VERSION_3	SNMPv3 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 arraybool SNMP::get ( arraystring $objectId [, bool $preserveKeys = false ] )

Fetch an SNMP object specified in objectId using GET query.

参数

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

objectId
The SNMP object (OID) or objects

preserveKeys
When objectId is a array and preserveKeys set to true keys in results will be taken exactly as in objectId, otherwise SNMP::oid_output_format property is used to determinate the form of keys.

返回值

Returns SNMP objects requested as string or array depending on objectId 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 arraybool SNMP::getnext ( arraystring $objectId )

Fetch an SNMP object that follows specified objectId.

参数

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

objectId
The SNMP object (OID) or objects

返回值

Returns SNMP objects requested as string or array depending on objectId type or false on error.

错误／异常

范例

示例 #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 arraybool SNMP::set ( arraystring $objectId , arraystring $type , arraystring $value )

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

参数

objectId
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类型
i	INTEGER
u	INTEGER
s	STRING
x	HEX STRING
d	DECIMAL STRING
n	NULLOBJ
o	OBJID
t	TIMETICKS
a	IPADDRESS
b	BITS

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


U	unsigned int64
I	signed int64
F	float
D	double

这些值大都会使用与 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。

错误／异常

范例

示例 #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 $securityLevel [, string $authProtocol = "" [, string $authPassphrase = "" [, string $privacyProtocol = "" [, string $privacyPassphrase = "" [, string $contextName = "" [, string $contextEngineId = "" ]]]]]] )

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

参数

securityLevel
the security level (noAuthNoPriv|authNoPriv|authPriv)

authProtocol
the authentication protocol (MD5 or SHA)

authPassphrase
the authentication pass phrase

privacyProtocol
the privacy protocol (DES or AES)

privacyPassphrase
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 arraybool SNMP::walk ( arraystring $objectId [, bool $suffixAsKey = false [, int $maxRepetitions = -1 [, int $nonRepeaters = -1 ]]] )

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

参数

objectId
Root of subtree to be fetched

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

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

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

错误／异常

范例

示例 #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 suffixAsKey example

suffixAsKey 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 mixed 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.