From 3a939c1348db608c8285919285fbfa74db9a4d20 Mon Sep 17 00:00:00 2001 From: elie Date: Mon, 27 Aug 2012 07:53:49 +0000 Subject: updated --- docs/pysnmp-tutorial.html | 295 +++++++++++++++++++++++++++++----------------- 1 file changed, 187 insertions(+), 108 deletions(-) (limited to 'docs') diff --git a/docs/pysnmp-tutorial.html b/docs/pysnmp-tutorial.html index 6701124..36fb2d3 100644 --- a/docs/pysnmp-tutorial.html +++ b/docs/pysnmp-tutorial.html @@ -367,9 +367,10 @@ the darkest corners of SNMP specifications all in Python programming language.

-This paper is dedicated to PySNMP revisions from 4.1.x and up. Previous -PySNMP versions do not follow the architecture and interfaces described -in this tutorial. +This paper is dedicated to PySNMP revisions 4.2.3 and up. Since PySNMP API's +evolve over time, older revisions may provide slightly different interfaces +than those described in this tutorial. Please refer to release-specific +documentation for a more precise information.

@@ -560,7 +561,7 @@ operations as well as for rapid prototyping.

-All Command Generator Applications are implemented within a single class: +All Command Generator Applications are implemented by a single class:

@@ -570,6 +571,13 @@ All Command Generator Applications are implemented within a single class:

Create a SNMP Command Generator object.

+ +

+Although instantiation of this class is cheap, in the course of its further +use, SNMP engine configuration is built and maintained though methods infocation. +Therefore it is advised to keep and reuse CommandGenerator instance (or snmpEngine +instance if passed as an initializer) for as long as possible within user applicatin. +

@@ -583,7 +591,9 @@ specific request types.
getCmd( authData, transportTarget, -*varNames +*varNames, +lookupNames=False, +lookupValues=False )
@@ -605,7 +615,7 @@ The getCmd method returns a tuple of errorIndication, errorStatus, errorIndex, -varBinds. +varBinds.

@@ -625,21 +635,38 @@ explanatory text error message.

-The varBinds is a tuple of Managed Objects. Those found in response are bound by position to -Managed Object names passed in request. +The varBinds is a sequence of Managed Objects. +Those found in response are bound by position to Managed Object names passed in request. +

+ +

+If lookupNames parameter evaluates to True, PySNMP will attempt to gather more +information on Managed Objects returned in +varBinds by searching for relevant MIB module and looking up there. Instance of +MibVariable class will be returned as Managed Object names.

+ +

+If lookupValues parameter evaluates to True, Managed Objects Instances values +returned in varBinds may be converted into a more precise type (employing +TEXTUAL-CONVENTION data +from MIB) if PySNMP has relevant MIB loaded. Otherwise response values will belong to +protocol-level Managed Object Instance value types. +

+

-The following code performs SNMP GET operation over SNMPv1: +The following code performs SNMP GET operation over SNMPv2c: 

->>> from pysnmp.entity.rfc3413.oneliner import cmdgen
->>> errorIndication, errorStatus, errorIndex, varBinds = cmdgen.CommandGenerator().getCmd(
-... cmdgen.CommunityData('my-agent', 'public', 0),
+>>> from pysnmp.entity.rfc3413.oneliner import cmdgen           
+>>> cmdGen = cmdgen.CommandGenerator()
+>>> errorIndication, errorStatus, errorIndex, varBinds = cmdGen.getCmd(
+... cmdgen.CommunityData('public'),
 ... cmdgen.UdpTransportTarget(('localhost', 161)),
 ... '1.3.6.1.2.1.1.1.0',
 ... '1.3.6.1.2.1.1.2.0'
@@ -660,7 +687,9 @@ None
 
setCmd(
 authData,
 transportTarget,
-*varBinds
+*varBinds,
+lookupNames=False,
+lookupValues=False
 )

 
 

@@ -669,16 +698,15 @@ Perform SNMP SET request and return a response or error indication.
 

 
 

-The authData and transportTarget parameters
-have he same semantics as in getCmd
+The authData, transportTarget,
+lookupNames and lookupValues  parameters
+have the same semantics as in getCmd
 method.
 

 
 

 The *varBinds input parameter is a sequence of
-Managed Objects to be applied at Agent. The syntax of
-*varBinds is the same as in
-getCmd method.
+Managed Objects to be modified at the Agent.
 

 
 

@@ -687,19 +715,14 @@ The setCmd method returns a tuple of
 errorStatus,
 errorIndex,
 varBinds. 
-

-
-

-The errorIndication, errorStatus and
-errorIndex parameters have the same meaning as in
-getCmd method.
+having the same meaning as in getCmd method.
 

 
 

 
 
 

-The following code performs SNMP SET operation over SNMPv2c:
+The following code performs SNMP SET operation over SNMPv1:
 

 
 

@@ -707,9 +730,9 @@ The following code performs SNMP SET operation over SNMPv2c:
 >>> from pysnmp.entity.rfc3413.oneliner import cmdgen
 >>> from pysnmp.proto import rfc1902
 >>> errorIndication, errorStatus, errorIndex, varBinds = cmdgen.CommandGenerator().setCmd(
-... cmdgen.CommunityData('my-agent', 'public', 1),
+... cmdgen.CommunityData('public', mpModel=0),
 ... cmdgen.UdpTransportTarget(('localhost', 161)),
-... ((1,3,6,1,2,1,1,1,0), rfc1902.OctetString('my system description'))
+... ('1.3.6.1.2.1.1.1.0', rfc1902.OctetString('my system description'))
 ... )
 >>> print(errorIndication)
 None
@@ -725,19 +748,37 @@ notWritable(17)
 
nextCmd(
 authData,
 transportTarget,
-*varNames
+*varNames,
+lookupNames=False,
+lookupValues=False,
+lexicographicMode=False,
+ignoreNonIncreasingOid=False,
+maxRows=0
 )

 
 

 

 Perform SNMP GETNEXT request and return a response or error indication.
 The GETNEXT request type implies referring to Managed Objects whose Object
-Names are next to those used in request.
+Names are "next greater" to those used in request.
 

 
 

-Input parameters to the nextCmd method are the same as to 
-getCmd.
+The authData, transportTarget,
+lookupNames and lookupValues  parameters
+have the same semantics as in getCmd
+method.
+

+
+

+The *varNames parameter is a sequence of
+Managed Objects names to query Agent
+for their "next" greater neignbours' Managed Objects Instances values. Unlike
+the same-named parameter of getCmd method,
+a partial (prefix part of) Managed Objects names are allowed here. For instance,
+a '1.3.6.1' argument would ask the Agent to report Managed Object
+Instance value with the next greater name known to this Agent (which may turn out
+to be '1.3.6.1.2.1.1.1.0').
 

 
 

@@ -755,7 +796,7 @@ The errorIndication, errorStatus and
 

 
 

-The varBindTable parameter is a tuple of
+The varBindTable parameter is a sequence of
 varBinds. Each varBind of 
 varBinds in varBindTable represent a 
 set of Managed Objects whose Object Names reside inside 
@@ -769,13 +810,20 @@ in a single response, and regardless of the prefix property).
 

 
 

-It's also possible to modify the above behaviour so that the 
+It's possible to modify the above behaviour so that the 
 varBindTable returned would contain *all*
-Managed Objects from those passed in request up till the end of
+Managed Objects from those passed in request up to the end of
 the list of available Managed Objects at the Agent. This option
-is enabled by setting the lexicographicMode
-attribute of the CommandGenerator class instance
-to True.
+is enabled by passing the lexicographicMode=True
+parameter to nextCmd method.
+

+
+

+In some cases application is also interested in some contiguous set of Managed
+Objects Instances not necessarily strictly belonging to the same subtree.
+The maxRows=NNN parameter to nextCmd would stop
+Command Generator once the required number (NNN) of Managed Objects Instances are
+retrieved from the Agent.
 

 
 

@@ -796,7 +844,7 @@ over SNMPv3:
 >>> errorIndication, errorStatus, errorIndex, varBindTable = cmdgen.CommandGenerator().nextCmd(
 ... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
 ... cmdgen.UdpTransportTarget(('localhost', 161)),
-... (1,3,6,1,2,1,1)
+... '1.3.6.1.2.1.1'
 ... )
 >>> print(errorIndication)
 None
@@ -821,20 +869,27 @@ None
 transportTarget,
 nonRepeaters,
 maxRepetitions,
-*varNames
+*varNames,
+lookupNames=False,
+lookupValues=False,
+lexicographicMode=False,
+ignoreNonIncreasingOid=False,
+maxRows=0
 )
 
 

 

 Perform SNMP GETBULK request and return a response or error indication.
 The GETBULK request type has the same semantics as GETNEXT one except that
-the latter queries a bulk of Managed Objects at once.
+the latter is able to report multiple Managed Objects per each Managed Object
+name passed in request.
 

 
 

 The authData, transportTarget,
-*varNames input parameters to the bulkCmd 
-method are the same as to  nextCmd.
+*varNames, lookupNames, lookupValues,
+lexicographicMode and maxRows input parameters to the
+bulkCmd method are the same as of nextCmd.
 

 
 

@@ -846,7 +901,7 @@ instance with in a request.
 

 The maxRepetitions parameter indicates for how many instances
 of Managed Objects in the rest of *varNames, besides first 
-nonRepeaters ones, should be queried with single request.
+nonRepeaters ones, should be queried within  a single request.
 

 
 

@@ -855,12 +910,9 @@ The bulkCmd method returns a tuple of
 errorStatus,
 errorIndex,
 varBindTable.
+having same meaning as in nextCmd method.
 

 
-

-The errorIndication, errorStatus,
-errorIndex and varBindTable parameters have
-the same meaning as in getCmd method.
 

 

 
@@ -877,7 +929,7 @@ over SNMPv3:
 ... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
 ... cmdgen.UdpTransportTarget(('localhost', 161)),
 ... 0, 25, # nonRepeaters, maxRepetitions
-... (1,3,6,1,2,1,1)
+... '1.3.6.1.2.1.1'
 ... )
 >>> print(errorIndication)
 None
@@ -942,12 +994,6 @@ to be generated. Supported values include "trap" for
 unconfirmed notification or "inform" for a confirmed one.
 

 
-

-Be advised, that when using confirmed notification, Notification Receiver
-must know ContextEngineID of Notification Originator to be able to
-process and acknowledge confirmed notification.
-

-
 

 The notificationType parameter indicates the kind of
 event to notify Manager about in form of SMI NOTIFICATION-TYPE object
@@ -979,12 +1025,14 @@ The following code sends SNMP TRAP over SNMPv3:
 
 >>> from pysnmp.entity.rfc3413.oneliner import cmdgen, ntforg
 >>> from pysnmp.proto.api import v2c
->>> errorIndication = ntforg.NotificationOriginator().sendNotification(
+>>>
+>>> ntfOrg = ntforg.NotificationOriginator()
+>>> errorIndication = ntfOrg.sendNotification(
 ... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
 ... cmdgen.UdpTransportTarget(('localhost', 162)),
 ... 'trap',
-... (('SNMPv2-MIB', 'coldStart'),),
-... ((1,3,6,1,2,1,1,3,0), v2c.TimeTicks(44100))
+... cmdgen.MibVariable('SNMPv2-MIB', 'coldStart'),
+... ('1.3.6.1.2.1.1.3.0', v2c.TimeTicks(44100))
 )
 >>> print(errorIndication)
 None
@@ -1034,7 +1082,9 @@ asynchronous interface uses a callback function for delivering responses.
 authData,
 transportTarget,
 varNames,
-(cbFun, cbCtx)
+(cbFun, cbCtx),
+lookupNames=False,
+lookupValues=False
 )
 
 

@@ -1087,10 +1137,12 @@ it must return a true value. Otherwise, it returns false.
 
 
 

-The authData, transportTarget and
-varNames parameters have the same meaning as in
-getCmd
-method.
+The authData, transportTarget,
+varNames, lookupNames and
+lookupValues parameters have the same meaning as in
+getCmd method except that
+varNames is passed as a sequence, not as individual
+Managed Objects Instances names.
 

 
 

@@ -1107,7 +1159,9 @@ matching subsequent response to this request.
 authData,
 transportTarget,
 varBinds,
-(cbFun, cbCtx)
+(cbFun, cbCtx),
+lookupNames=False,
+lookupValues=False
 )
 
 

@@ -1117,9 +1171,12 @@ Prepare SNMP SET request to be dispatched. Return the
 

 
 

-The authData and transportTarget
-parameters have the same meaning as in 
-CommandGenerator.getCmd method.
+The authData, transportTarget,
+varNames, lookupNames and
+lookupValues parameters have the same meaning as in
+ method except that
+varBinds is passed as a sequence, not as individual
+Managed Objects Instances.
 

 
 

@@ -1128,11 +1185,6 @@ have the same meaning as in 
 AsynCommandGenerator.asyncGetCmd method.
 

 
-

-The varBinds parameter has the same meaning as in 
-CommandGenerator.setCmd method
-except that here it is passed in as a tuple.
-

 

 
 
@@ -1142,7 +1194,9 @@ except that here it is passed in as a tuple.
 authData,
 transportTarget,
 varNames,
-(cbFun, cbCtx)
+(cbFun, cbCtx),
+lookupNames=False,
+lookupValues=False
 )
 
 

@@ -1152,9 +1206,12 @@ Prepare SNMP GETNEXT request to be dispatched. Return the
 

 
 

-The authData and transportTarget
-parameters have the same meaning as in 
-CommandGenerator.nextCmd method.
+The authData, transportTarget,
+varNames, lookupNames and
+lookupValues parameters have the same meaning as in
+nextCmd method except that
+varNames is passed as a sequence, not as individual
+Managed Objects Instances names.
 

 
 

@@ -1179,7 +1236,9 @@ except that here it is passed in as a tuple.
 nonRepeaters,
 maxRepetitions,
 varNames,
-(cbFun, cbCtx)
+(cbFun, cbCtx),
+lookupNames=False,
+lookupValues=False
 )
 
 

@@ -1190,9 +1249,12 @@ Prepare SNMP GETBULK request to be dispatched. Return the
 
 

 The authData, transportTarget,
-nonRepeaters and maxRepetitions
-parameters have the same meaning as in 
-CommandGenerator.nextCmd method.
+nonRepeaters, maxRepetitions
+varNames, lookupNames and
+lookupValues parameters have the same meaning as in
+bulkCmd method except that
+varNames is passed as a sequence, not as individual
+Managed Objects Instances names.
 

 
 

@@ -1201,11 +1263,6 @@ have the same meaning as in 
 AsynCommandGenerator.asyncGetCmd method.
 

 
-

-The varNames parameter has the same meaning as in 
-CommandGenerator.bulkCmd method
-except that here it is passed in as a tuple.
-

 

 
 
@@ -1255,7 +1312,7 @@ SNMPv3:
 >>> sendRequestHandle = asynCommandGenerator.asyncGetCmd(
 ... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'), 
 ... cmdgen.UdpTransportTarget(('localhost', 161)), 
-... ((1,3,6,1,2,1,1,1,0),), 
+... ('1.3.6.1.2.1.1.1.0',), 
 ... (cbFun, None))
 >>> print(sendRequestHandle)
 1
@@ -1402,8 +1459,8 @@ SNMPv3:
 ... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
 ... cmdgen.UdpTransportTarget(('localhost', 162)),
 ... 'inform',
-... ('SNMPv2-MIB', 'coldStart'),
-... ((1,3,6,1,2,1,1,1,0), v2c.TimeTicks(44100)),
+... cmdgen.MibVariable('SNMPv2-MIB', 'coldStart'),
+... ('1.3.6.1.2.1.1.1.0', v2c.TimeTicks(44100)),
 ... (cbFun, None))
 >>> print(sendRequestHandle)
 1
@@ -1456,15 +1513,16 @@ passed in as a string.
 

 Optional authKey parameter is a secret key (string typed)
 used within USM for SNMP PDU authorization. Setting it to a non-empty
-value implies MD5-based PDU authentication to take effect. Default hashing 
-method may be changed by means of further authProtocol 
-parameter.
+value implies MD5-based PDU authentication (usmHMACMD5AuthProtocol)
+to take effect. Default hashing method may be changed by means of further
+authProtocol parameter.
 

 
 

 Optional privKey parameter is a secret key (string typed)
 used within USM for SNMP PDU encryption. Setting it to a non-empty
-value implies MD5-based PDU authentication and DES-based encryption to 
+value implies MD5-based PDU authentication (usmHMACMD5AuthProtocol)
+and DES-based encryption (usmDESPrivProtocol) to 
 take effect. Default hashing and/or encryption methods may be changed by 
 means of further authProtocol and/or 
 privProtocol parameters.
@@ -1505,7 +1563,6 @@ All these symbols are defined in
 
 

 
class CommunityData(
-securityName,
 communityName,
 mpModel=1
 )

@@ -1514,11 +1571,6 @@ All these symbols are defined in
 Create an object holding Community-Based Security Model specific configuration
 parameters.
 

-

-Mandatory securityName parameter is Community-Based Security 
-Model username passed in as a string. For most purposes this can be an
-arbitrary string.
-

 
 

 Mandatory communityName parameter is SNMPv1/SNMPv2c Community name 
@@ -1538,8 +1590,9 @@ Optional mpModel parameter indicates whether SNMPv2c
 
 

 Transport configuration object is Transport domain specific.
-UdpTransportTarget class represents an Agent
-accessible through UDP domain transport.
+UdpTransportTarget class represents a pair of
+network endpoints (remote and optionally local addresses) of a
+UDP-over-IPv4 transport.
 

 
 
@@ -1551,18 +1604,22 @@ accessible through UDP domain transport.
 )
 

 

-Create an object representing a single Agent accessible through UDP socket.
+Create an object representing a network path connecting two
+SNMP entities through a UDP/IPv4 socket.
 

 

-Mandatory transportAddr parameter indicates destination
-Agent address in form of tuple of FQDN, port
+Mandatory transportAddr parameter indicates remote address
+in form of tuple of FQDN, port
 where FQDN is a string and port is an 
 integer.
 

 

 Optional timeout and retries parameters
 may be used to modify default response timeout (1 second) and number 
-of succesive request retries (5 times).
+of succesive request retries (5 times). Optional localAddr
+parameter may be used for sending queries from specific local interface.
+The syntax of localAddr is the same as the syntax of
+transportAddr.
 

 

 

@@ -1592,7 +1649,17 @@ which is derived from PyASN1
 ObjectIdentifier.
 In most cases, PySNMP APIs will automatically create an instance of
 ObjectIdentifier class from its initialization value. Therefore it's
-allowed to use a plain tuple of integers as a Managed Object Name.
+allowed to use a plain string of dot-separated numbers or a tuple of
+integers as a Managed Object Name.
+

+
+
+

+In order to make use of additional information related to Managed Objects,
+such as their human-friendly representation, associated value type, description
+and other details contained in MIBs, the MibVariable
+class instances may be used interchangeably instead of ObjectName
+objects.
 

 
 
@@ -1777,11 +1844,23 @@ PyASN1 OctetString.
 
 
 
+
+

+All the above types are directly used by SNMP protocol and can be exchanged
+between user application and PySNMP in the course of SNMP engine operations
+through PySNMP APIs. However, by SNMP design, some additional information
+on specific Managed Objects Instances value ranges and human-friendly representation
+can be carried by MIBs in form of TEXTUAL-CONVENTION SMI constructs.
+PySNMP implements this feature in form of TextualConvention class
+which is actually a derivative of one of the above Managed Objects Instance Value
+classes so objects of these classes can be used interchangeably in all PySNMP APIs.
+

+
 

-It's PySNMP design decision to always use SMIv2
-definitions for Managed Objects at the high-level API regardless of SNMP
-protocol version being used. For instance, an SNMPv3 Manager will always report
-SMIv2 types even when talking to SNMPv1 Agent (which is SMIv1-compliant).
+With PySNMP's SNMPv3 architecture, SMIv2 definitions for Managed
+Objects are always used regardless of the underlying SNMP protocol version being talked
+with a peer. For instance, an SNMPv3 Manager will always report SMIv2 types even when 
+working to SNMPv1 Agent (which is SMIv1-compliant).
 

 
 

-- 
cgit v1.2.1