lib-snmp 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793554432/FIN+5.3.1+lib-snmp 中文整理基于 FIN 5.3.1

导读： 本页为 lib-snmp 的 API / 标签 / 函数参考文档。

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

---

目录（导读）

• lib
• meta
• docs
• tags
• funcs
• Overview
• Agent Connectivity
  • Security
• Management Information Base (MIB)
• Current Points
• Writable Points
  • def
• snmpGet(conn, arg)
  • supertypes
• snmpPing(conn)
• snmpReadTable(conn, table)
• snmpSyncCur(points)
  • enum
  • usage
  • tags

---

概述（中译）

SNMP 连接器

---

API 正文（英文）

docs

Overview • Agent Connectivity • Management Information Base (MIB) • Current Points • Writable Points

---

tags

snmpAuthProtocol	If the snmpSecurityLevel indicates that authentication is required, then this is the digest algorithm to use
snmpCommunity	If the snmpVersion is 2c, then this is the name of the SNMP community to use when messaging with the remote agent
snmpConn	SNMP connector
snmpConnRef	Used on a proxy object to reference its parent snmpConn
snmpCur	SNMP address to use for current-value subscription
snmpDesc	For learned points, this is the description of the point as found in its MIB OBJECT-TYPE definition
snmpMibType	For learned points, this is the human-readable qualified name (qname) of the point
snmpMibsUri	Applied to snmpConn to define the collection of MIB files to load
snmpPoint	Point which synchronizes data via an SNMP connector
snmpPrivProtocol	If the snmpSecurityLevel indicates that message privacy is required, then this is the encryption algorithm to use
snmpProtocol	Applied to snmpConn to indicate the network protocol to use for communicating with a remote agent
snmpSecurityLevel	If the snmpVersion is 3, then this is the security level to use for messaging with the remote agent
snmpVersion	Applied to snmpConn to indicate the SNMP protocol version to use for messaging with the remote agent
snmpWrite	SNMP address to use for writing a point

---

funcs

snmpGet	Synchronously read the current value of the object-type specified by arg
snmpPing	Deprecated - use connPing()
snmpReadTable	Synchronously read an SNMP table and return it as a Grid
snmpSyncCur	Deprecated - use connSyncCur()

---

lib snmp

Overview

The SnmpExt implements connector support for the Simple Network Management Protocol (SNMP).

Agent Connectivity

To access a remote SNMP agent, we use the snmp URI scheme. If you don't specify a port, the default is 161. The SnmpExt supports both UDP and TCP/IP connectivity. By default, TCP/IP is used. Use snmpProtocol to change the transport protocol.

uri: `snmp://agent.com`

Security

The connector supports two modes of security: 1) Community-based authentication (SNMPv2c) and 2) User-based Security Model - USM (SNMPv3). See the docs on snmpConn for details about the security-related tags.

Management Information Base (MIB)

SNMP connectors can be configured to load MIB module definitions from disk into a MIB database. The connector's snmpMibsUri tag indicates the directory to search for MIB files. All files not starting with a . are parsed as module definition files and loaded into the MIB. See that tag's doc for more details.

When the SnmpExt first starts, it will install a minimal, default set of MIBs into data/mibs/default/. You can add additional MIBs to this collection, or create your own collection.

The MIB is used primarily when learning a remote agent via the Builder App. Only object types specified in the MIB will be available for learning. Further, writable points are only supported if they correspond to a type in the MIB since we need the information from the MIB to know how to map its type in Haystack to the expected SNMP type on the agent.

Current Points

SNMP proxy points are configured with the snmpCur tag, which maps to the object identifier for the point in the MIB. For example, this point maps the HOST-RESOURCES-MIB::hrSystemUptime point in the remote agent and converts it from centiseconds to days:

point
snmpConnRef: @mySnmpConn
snmpCur: "1.3.6.1.2.1.25.1.1.0"
snmpMibType: "HOST-RESOURCES-MIB::hrSystemUptime"
curConvert: "cs => day"
unit: "day"

Writable Points

SNMP proxy points are configured to write to remote agent points via the snmpWrite tag. If you use the Builder App to learn SNMP points, it will automatically configure a point as writable if its object-type definition in the MIB has MAX-ACCESS of readWrite or higher.

point
writable
snmpConnRef: @mySnmpConn
snmpWrite: "1.3.6.1.2.1.1.4.0"
snmpMibType: "SNMPv2-MIB::sysContact"

---

---

def

func:snmpGet

snmpGet(conn, arg)

Synchronously read the current value of the object-type specified by arg.

Params:

• conn: the SNMP connector to read against
• arg: the OID of the object-type to read (e.g. "1.3.6.1.2.11.1.0")

NOTE: this function is incubating and subject to change.

---

meta

admin	✓
def	func:snmpGet
is	func
lib	lib:snmp
name	snmpGet

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:snmpPing

snmpPing(conn)

Deprecated - use connPing()

---

meta

admin	✓
def	func:snmpPing
deprecated	✓
is	func
lib	lib:snmp
name	snmpPing

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:snmpReadTable

snmpReadTable(conn, table)

Synchronously read an SNMP table and return it as a Grid.

Params:

• conn: the SNMP connector to read against.
• table: the qname of the table to read (e.g. "SNMPv2-MIB::sysORTable").

Each column's metadata includes tag snmpColIdentity which is the OID of the column object-type in the MIB. In addition to the columns specified in the MIB, each row will have a column snmpRowIndex. This value is the common OID suffix for each cell in the row. In other words, it represents the row index. Each table cell's OID is therefore:

col.meta["snmpColIdentity"] + "." + row["snmpRowIndex"]

Examples:

grid = read(snmpConn and dis=="SNMP Demo").snmpReadTable("SNMPv2-MIB::sysORTable")

NOTE: this function is incubating and subject to change.

---

meta

admin	✓
def	func:snmpReadTable
is	func
lib	lib:snmp
name	snmpReadTable

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:snmpSyncCur

snmpSyncCur(points)

Deprecated - use connSyncCur()

---

meta

admin	✓
def	func:snmpSyncCur
deprecated	✓
is	func
lib	lib:snmp
name	snmpSyncCur

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

snmpAuthProtocol

If the snmpSecurityLevel indicates that authentication is required, then this is the digest algorithm to use.

The snmpConn password is used both for the auth pass phrase and the priv pass phrase.

---

meta

def	snmpAuthProtocol
enum	See below
is	str
lib	lib:snmp
tagOn	snmpConn

---

enum

MD5
SHA

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

snmpCommunity

If the snmpVersion is 2c, then this is the name of the SNMP community to use when messaging with the remote agent.

---

meta

def	snmpCommunity
is	str
lib	lib:snmp
tagOn	snmpConn

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

snmpConn

SNMP connector. See snmp.

---

meta

connFeatures
def	snmpConn
icon	snmp
is	conn
lib	lib:snmp

---

usage

snmpConn  conn

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
conn	Connector for communication to a remote system

---

tags

actorTimeout	Timeout for messages send to the connector's actor thread
connErr	Error message associated when connStatus indicates an error condition
connLinger	Linger timeout used to keep a connector open
connOpenRetryFreq	Duration used for connector open retries
connPingFreq	Duration used to configure the auto-ping feature on a given connector
connState	Current connection state of a connector as one of the predefined strings
connStatus	Current status of a connector as one of the predefined strings See Connectors
connTuningRef	Reference to a tuning configuration defined by a connTuning rec
dis	Display name for an entity
disabled	Indicates the entity is in a disabled state
id	Defines the unique identifier of an entity in system using a ref value type
password	Manages password which is hashed/stored to the password store
snmpAuthProtocol	If the snmpSecurityLevel indicates that authentication is required, then this is the digest algorithm to use
snmpCommunity	If the snmpVersion is 2c, then this is the name of the SNMP community to use when messaging with the remote agent
snmpMibsUri	Applied to snmpConn to define the collection of MIB files to load
snmpPrivProtocol	If the snmpSecurityLevel indicates that message privacy is required, then this is the encryption algorithm to use
snmpProtocol	Applied to snmpConn to indicate the network protocol to use for communicating with a remote agent
snmpSecurityLevel	If the snmpVersion is 3, then this is the security level to use for messaging with the remote agent
snmpVersion	Applied to snmpConn to indicate the SNMP protocol version to use for messaging with the remote agent
uri	Universal resource identifier
username	Username for an authentication account

---

---

def

snmpConnRef

Used on a proxy object to reference its parent snmpConn

---

meta

def	snmpConnRef
is	ref
lib	lib:snmp
of	snmpConn
tagOn	snmpPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
ref	Reference to an entity

---

---

def

snmpCur

SNMP address to use for current-value subscription. It is formatted as the SNMP object identifier for that point.

---

meta

def	snmpCur
is	str
lib	lib:snmp
tagOn	snmpPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

snmpDesc

For learned points, this is the description of the point as found in its MIB OBJECT-TYPE definition.

---

meta

def	snmpDesc
is	str
lib	lib:snmp
tagOn	snmpPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

snmpMibType

For learned points, this is the human-readable qualified name (qname) of the point. It is formatted as <module-name>::<type-name>.

---

meta

def	snmpMibType
is	str
lib	lib:snmp
tagOn	snmpPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

snmpMibsUri

Applied to snmpConn to define the collection of MIB files to load. This URI must be a path relative to the project's home directory, and it must be a directory. The directory tree at this uri will be searched and all files will be loaded as MIB module definitions.

---

meta

def	snmpMibsUri
is	uri
lib	lib:snmp
tagOn	snmpConn

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
uri	Universal resource identifier

---

---

def

snmpPoint

Point which synchronizes data via an SNMP connector.

---

meta

def	snmpPoint
is	connPoint
lib	lib:snmp

---

usage

snmpPoint  point

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
point	Data point such as a sensor or actuator
connPoint	Point associated with a connector for data synchronization with a remote system

---

tags

connTuningRef	Reference to a tuning configuration defined by a connTuning rec
cur	Supports current value
curCalibration	Calibration value to apply to adjust the value read from the connector before updating curVal
curConvert	Conversion to apply when reading curVal from connector
dis	Display name for an entity
disMacro	Display name using macro syntax
disabled	Indicates the entity is in a disabled state
enum	Defines an eumeration of string key names
equipRef	Reference to equip which contains this entity
ghgFactorHis	Identifies point record with interval emission factor data that the Greenhouse Gas Emission Engine uses to calculate emissions
his	Supports historization of data
hisConvert	Conversion to apply when reading history data from connector
id	Defines the unique identifier of an entity in system using a ref value type
kind	Kind name used to identity a value data type
maxVal	Inclusive maximum for a numeric value
minVal	Inclusive minimum for a numeric value
navName	Navigation name commonly used with disMacro to create computed display strings
pointFunction	Classifies the point as a sensor, command, or setpoint
pointQuantity	Quantity the point senses or controls
pointSubject	What the point senses or controls
siteRef	Reference to site which contains the entity
snmpConnRef	Used on a proxy object to reference its parent snmpConn
snmpCur	SNMP address to use for current-value subscription
snmpDesc	For learned points, this is the description of the point as found in its MIB OBJECT-TYPE definition
snmpMibType	For learned points, this is the human-readable qualified name (qname) of the point
snmpWrite	SNMP address to use for writing a point
spaceRef	Reference to space which contains this entity
systemRef	Reference to system
tz	Timezone identifier from standard timezone database
unit	Unit identifier from standard unit database
writable	Supports writing data
writeConvert	Conversion to apply when writing writeVal to the connector

---

---

def

snmpPrivProtocol

If the snmpSecurityLevel indicates that message privacy is required, then this is the encryption algorithm to use.

The snmpConn password is used both for the auth pass phrase and the priv pass phrase.

---

meta

def	snmpPrivProtocol
enum	See below
is	str
lib	lib:snmp
tagOn	snmpConn

---

enum

DES
AES

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

snmpProtocol

Applied to snmpConn to indicate the network protocol to use for communicating with a remote agent. Valid values are udp and tcp. If not specified, then tcp is used.

---

meta

def	snmpProtocol
enum	See below
is	str
lib	lib:snmp
tagOn	snmpConn

---

enum

tcp
udp

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

snmpSecurityLevel

If the snmpVersion is 3, then this is the security level to use for messaging with the remote agent.

---

meta

def	snmpSecurityLevel
enum	See below
is	str
lib	lib:snmp
tagOn	snmpConn

---

enum

authPriv	Indicates both user authentication and privacy (encryption) for the mesages.
authNoPriv	Indicates user authentication, but no privacy for the messages.
noAuthNoPriv	Indicates no user authentication or privacy for the messages.

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

snmpVersion

Applied to snmpConn to indicate the SNMP protocol version to use for messaging with the remote agent. The version will dictate additional required tags on the connector. See snmpConn for details.

---

meta

def	snmpVersion
enum	See below
is	str
lib	lib:snmp
tagOn	snmpConn

---

enum

2c	SNMPv2C - Community-based authentication
3	SNMPv3 - User-based security model (USM)

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

snmpWrite

SNMP address to use for writing a point. It is formatted as the SNMP object identifier for that point.

---

meta

def	snmpWrite
is	str
lib	lib:snmp
tagOn	snmpPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters