From 16d7c73f177f81d3090bcb11e97c80c9315a72c3 Mon Sep 17 00:00:00 2001 From: elie Date: Thu, 17 Sep 2015 19:55:32 +0000 Subject: async command generator documented + fixes --- TODO.txt | 9 + .../docs/v3arch/asyncore/oneliner/contents.rst | 16 +- pysnmp/entity/rfc3413/oneliner/cmdgen.py | 312 ++++++++++++++++++++- pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py | 14 +- pysnmp/entity/rfc3413/oneliner/sync/ntforg.py | 4 +- 5 files changed, 320 insertions(+), 35 deletions(-) diff --git a/TODO.txt b/TODO.txt index ae8ded1..3d2117d 100644 --- a/TODO.txt +++ b/TODO.txt @@ -54,3 +54,12 @@ Sparse notes on major existing problems/plans may need a means to deal only with specific node types. * redesign proto.errind.ErrorIndication + +* move LCD and var-bind management routines from Async* classes + +* make oneliner helper routines more general, not bound to asyncore-based + implementation + +* improve oneliner modules layout to make it possible to create more + transport-specific oneliner interfaces + diff --git a/docs/source/docs/v3arch/asyncore/oneliner/contents.rst b/docs/source/docs/v3arch/asyncore/oneliner/contents.rst index 5a52135..2c0e3a8 100644 --- a/docs/source/docs/v3arch/asyncore/oneliner/contents.rst +++ b/docs/source/docs/v3arch/asyncore/oneliner/contents.rst @@ -21,6 +21,11 @@ other tasks till pending message is sent out (by I/O dispacher) and response is arrived. At that point a previously supplied callback function will be invoked and response data will be passed along. +SNMP security configuration is conveyed to SNMP engine via +:py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData` +and :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` +classes: + .. toctree:: :maxdepth: 2 @@ -32,17 +37,6 @@ messaging possibly handling other I/O activities in the same time. The synchronous version is advised to employ for singular and blocking operations as well as for rapid prototyping. -.. toctree:: - :maxdepth: 2 - - /docs/v3arch/asyncore/oneliner/manager/cmdgen/async.rst - /docs/v3arch/asyncore/oneliner/agent/ntforg/async.rst - -SNMP security configuration is conveyed to SNMP engine via -:py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData` -and :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` -classes: - .. toctree:: :maxdepth: 2 diff --git a/pysnmp/entity/rfc3413/oneliner/cmdgen.py b/pysnmp/entity/rfc3413/oneliner/cmdgen.py index d6f51e4..31a4e45 100644 --- a/pysnmp/entity/rfc3413/oneliner/cmdgen.py +++ b/pysnmp/entity/rfc3413/oneliner/cmdgen.py @@ -231,17 +231,17 @@ class AsyncCommandGenerator: return __varBinds - def unmakeVarBinds(self, snmpEngine, varBinds, lookupMib=False): + def unmakeVarBinds(self, snmpEngine, varBinds, lookupMib=True): if lookupMib: mibViewController = self.getMibViewController(snmpEngine) varBinds = [ ObjectType(ObjectIdentity(x[0]), x[1]).resolveWithMib(mibViewController) for x in varBinds ] return varBinds - # Async SNMP apps + # Standard SNMP apps follow def getCmd(self, snmpEngine, authData, transportTarget, contextData, - varBinds, cbInfo, lookupMib=False): + varBinds, cbInfo, lookupMib=True): """Performs SNMP GET query. Based on passed parameters, prepares SNMP GET packet @@ -257,14 +257,16 @@ class AsyncCommandGenerator: Class instance representing SNMP credentials. transportTarget : :py:class:`~pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget` or :py:class:`~pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget` - Class instance representing transport type along with SNMP peer address. + Class instance representing transport type along with SNMP peer + address. contextData : :py:class:`~pysnmp.entity.rfc3413.oneliner.ctx.ContextData` - Class instance representing SNMP ContextEngineId and ContextName values. + Class instance representing SNMP ContextEngineId and ContextName + values. - varBinds : :py:class:`~pysnmp.smi.rfc1902.ObjectType` - One or more class instances representing MIB variables to place - into SNMP request. + varBinds : tuple + A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class + instances representing MIB variables to place into SNMP request. cbInfo : tuple @@ -277,7 +279,7 @@ class AsyncCommandGenerator: ---------------- lookupMib : bool `lookupMib` - load MIB and resolve response MIB variables at - the cost of slightly reduced performance. Default is `False`. + the cost of slightly reduced performance. Default is `True`. Notes ----- @@ -289,11 +291,12 @@ class AsyncCommandGenerator: * sendRequestHandle (int): Unique request identifier. Can be used for matching multiple ongoing requests with received responses. * errorIndication (str): True value indicates SNMP engine error. - * errorStatus (str): Non-zero value indicates SNMP PDU error. - * errorIndex (int): Non-zero value refers to *varBinds[errorIndex-1] + * errorStatus (str): True value indicates SNMP PDU error. + * errorIndex (int): Non-zero value refers to `varBinds[errorIndex-1]` * varBinds (tuple): A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances - representing MIB variables returned in SNMP response. + representing MIB variables returned in SNMP response in exactly + the same order as `varBinds` in request. * `cbCtx` : Original user-supplied object. Returns @@ -359,7 +362,95 @@ class AsyncCommandGenerator: ) def setCmd(self, snmpEngine, authData, transportTarget, contextData, - varBinds, cbInfo, lookupMib=False): + varBinds, cbInfo, lookupMib=True): + """Performs SNMP SET query. + + Based on passed parameters, prepares SNMP SET packet + (:RFC:`1905#section-4.2.5`) and schedules its transmission by + I/O framework at a later point of time. + + Parameters + ---------- + snmpEngine : :py:class:`~pysnmp.entity.engine.SnmpEngine` + Class instance representing SNMP engine. + + authData : :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData` or :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` + Class instance representing SNMP credentials. + + transportTarget : :py:class:`~pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget` or :py:class:`~pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget` + Class instance representing transport type along with SNMP peer + address. + + contextData : :py:class:`~pysnmp.entity.rfc3413.oneliner.ctx.ContextData` + Class instance representing SNMP ContextEngineId and ContextName + values. + + varBinds : tuple + A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class + instances representing MIB variables to place into SNMP request. + + cbInfo : tuple + + * `cbFun` - user-supplied callable that is invoked to pass + SNMP response data or error to user at a later point of time. + * `cbCtx` - user-supplied object passing additional parameters + to/from `cbFun`. Default is `None`. + + Other Parameters + ---------------- + lookupMib : bool + `lookupMib` - load MIB and resolve response MIB variables at + the cost of slightly reduced performance. Default is `True`. + + Notes + ----- + User-supplied `cbFun` callable must have the following call + signature: + + * snmpEngine (:py:class:`~pysnmp.entity.engine.SnmpEngine`): + Class instance representing SNMP engine. + * sendRequestHandle (int): Unique request identifier. Can be used + for matching multiple ongoing requests with received responses. + * errorIndication (str): True value indicates SNMP engine error. + * errorStatus (str): True value indicates SNMP PDU error. + * errorIndex (int): Non-zero value refers to `varBinds[errorIndex-1]` + * varBinds (tuple): A sequence of + :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances + representing MIB variables returned in SNMP response in exactly + the same order as `varBinds` in request. + * `cbCtx` : Original user-supplied object. + + Returns + ------- + sendRequestHandle : int + Unique request identifier. Can be used for matching received + responses with ongoing requests. + + Raises + ------ + PySnmpError + Or its derivative indicating that an error occurred while + performing SNMP operation. + + Examples + -------- + >>> from pysnmp.entity.rfc3413.oneliner.cmdgen import * + >>> def cbFun(snmpEngine, sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds, cbCtx): + ... print(errorIndication, errorStatus, errorIndex, varBinds) + >>> + >>> snmpEngine = SnmpEngine() + >>> g = AsyncCommandGenerator() + >>> g.setCmd(snmpEngine, + ... CommunityData('public'), + ... UdpTransportTarget(('demo.snmplabs.com', 161)), + ... ContextData(), + ... ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysContact', 0), 'info@snmplabs.com'), + ... (cbFun, None)) + >>> snmpEngine.transportDispatcher.runDispatcher() + (None, 0, 0, [ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.4.0')), DisplayString('info@snmplabs.com'))]) + >>> + + """ def __cbFun(snmpEngine, sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds, cbCtx): @@ -392,7 +483,97 @@ class AsyncCommandGenerator: ) def nextCmd(self, snmpEngine, authData, transportTarget, contextData, - varBinds, cbInfo, lookupMib=False): + varBinds, cbInfo, lookupMib=True): + """Performs SNMP GETNEXT query. + + Based on passed parameters, prepares SNMP GETNEXT packet + (:RFC:`1905#section-4.2.2`) and schedules its transmission by + I/O framework at a later point of time. + + Parameters + ---------- + snmpEngine : :py:class:`~pysnmp.entity.engine.SnmpEngine` + Class instance representing SNMP engine. + + authData : :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData` or :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` + Class instance representing SNMP credentials. + + transportTarget : :py:class:`~pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget` or :py:class:`~pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget` + Class instance representing transport type along with SNMP peer + address. + + contextData : :py:class:`~pysnmp.entity.rfc3413.oneliner.ctx.ContextData` + Class instance representing SNMP ContextEngineId and ContextName + values. + + varBinds : tuple + A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class + instances representing MIB variables to place into SNMP request. + + cbInfo : tuple + + * `cbFun` - user-supplied callable that is invoked to pass + SNMP response data or error to user at a later point of time. + * `cbCtx` - user-supplied object passing additional parameters + to/from `cbFun`. Default is `None`. + + Other Parameters + ---------------- + lookupMib : bool + `lookupMib` - load MIB and resolve response MIB variables at + the cost of slightly reduced performance. Default is `True`. + + Notes + ----- + User-supplied `cbFun` callable must have the following call + signature: + + * snmpEngine (:py:class:`~pysnmp.entity.engine.SnmpEngine`): + Class instance representing SNMP engine. + * sendRequestHandle (int): Unique request identifier. Can be used + for matching multiple ongoing requests with received responses. + * errorIndication (str): True value indicates SNMP engine error. + * errorStatus (str): True value indicates SNMP PDU error. + * errorIndex (int): Non-zero value refers to `varBinds[errorIndex-1]` + * varBinds (tuple): A sequence of sequences (e.g. 2-D array) of + :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances + representing a table of MIB variables returned in SNMP response. + Inner sequences represent table rows and ordered exactly the same + as `varBinds` in request. Response to GETNEXT always contain a + single row. + * `cbCtx` : Original user-supplied object. + + Returns + ------- + sendRequestHandle : int + Unique request identifier. Can be used for matching received + responses with ongoing requests. + + Raises + ------ + PySnmpError + Or its derivative indicating that an error occurred while + performing SNMP operation. + + Examples + -------- + >>> from pysnmp.entity.rfc3413.oneliner.cmdgen import * + >>> def cbFun(snmpEngine, sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds, cbCtx): + ... print(errorIndication, errorStatus, errorIndex, varBinds) + >>> + >>> snmpEngine = SnmpEngine() + >>> g = AsyncCommandGenerator() + >>> g.nextCmd(snmpEngine, + ... CommunityData('public'), + ... UdpTransportTarget(('demo.snmplabs.com', 161)), + ... ContextData(), + ... ObjectType(ObjectIdentity('SNMPv2-MIB', 'system')), + ... (cbFun, None)) + >>> snmpEngine.transportDispatcher.runDispatcher() + (None, 0, 0, [ [ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.1.0')), DisplayString('SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m'))] ]) + >>> + + """ def __cbFun(snmpEngine, sendRequestHandle, errorIndication, errorStatus, errorIndex, varBindTable, cbCtx): @@ -422,7 +603,108 @@ class AsyncCommandGenerator: def bulkCmd(self, snmpEngine, authData, transportTarget, contextData, nonRepeaters, maxRepetitions, varBinds, cbInfo, - lookupMib=False): + lookupMib=True): + """Performs SNMP GETBULK query. + + Based on passed parameters, prepares SNMP GETBULK packet + (:RFC:`1905#section-4.2.3`) and schedules its transmission by + I/O framework at a later point of time. + + Parameters + ---------- + snmpEngine : :py:class:`~pysnmp.entity.engine.SnmpEngine` + Class instance representing SNMP engine. + + authData : :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData` or :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` + Class instance representing SNMP credentials. + + transportTarget : :py:class:`~pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget` or :py:class:`~pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget` + Class instance representing transport type along with SNMP peer + address. + + contextData : :py:class:`~pysnmp.entity.rfc3413.oneliner.ctx.ContextData` + Class instance representing SNMP ContextEngineId and ContextName + values. + + nonRepeaters : int + One MIB variable is requested in response for the first + `nonRepeaters` MIB variables in request. + + maxRepetitions : int + `maxRepetitions` MIB variables are requested in response for each + of the remaining MIB variables in the request (e.g. excluding + `nonRepeaters`). Remote SNMP engine may choose lesser value than + requested. + + varBinds : tuple + A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class + instances representing MIB variables to place into SNMP request. + + cbInfo : tuple + + * `cbFun` - user-supplied callable that is invoked to pass + SNMP response data or error to user at a later point of time. + * `cbCtx` - user-supplied object passing additional parameters + to/from `cbFun`. Default is `None`. + + Other Parameters + ---------------- + lookupMib : bool + `lookupMib` - load MIB and resolve response MIB variables at + the cost of slightly reduced performance. Default is `True`. + + Notes + ----- + User-supplied `cbFun` callable must have the following call + signature: + + * snmpEngine (:py:class:`~pysnmp.entity.engine.SnmpEngine`): + Class instance representing SNMP engine. + * sendRequestHandle (int): Unique request identifier. Can be used + for matching multiple ongoing requests with received responses. + * errorIndication (str): True value indicates SNMP engine error. + * errorStatus (str): True value indicates SNMP PDU error. + * errorIndex (int): Non-zero value refers to `varBinds[errorIndex-1]` + * varBinds (tuple): A sequence of sequences (e.g. 2-D array) of + :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances + representing a table of MIB variables returned in SNMP response. + Inner sequences represent table rows and ordered exactly the same + as `varBinds` in request. Number of rows might be less or equal + to `maxRepetitions` value in request. + * `cbCtx` : Original user-supplied object. + + Returns + ------- + sendRequestHandle : int + Unique request identifier. Can be used for matching received + responses with ongoing requests. + + Raises + ------ + PySnmpError + Or its derivative indicating that an error occurred while + performing SNMP operation. + + Examples + -------- + >>> from pysnmp.entity.rfc3413.oneliner.cmdgen import * + >>> def cbFun(snmpEngine, sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds, cbCtx): + ... print(errorIndication, errorStatus, errorIndex, varBinds) + >>> + >>> snmpEngine = SnmpEngine() + >>> g = AsyncCommandGenerator() + >>> g.bulkCmd(snmpEngine, + ... CommunityData('public'), + ... UdpTransportTarget(('demo.snmplabs.com', 161)), + ... ContextData(), + ... 0, 2, + ... ObjectType(ObjectIdentity('SNMPv2-MIB', 'system')), + ... (cbFun, None)) + >>> snmpEngine.transportDispatcher.runDispatcher() + (None, 0, 0, [ [ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.1.0')), DisplayString('SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m')), ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.2.0')), ObjectIdentifier('1.3.6.1.4.1.424242.1.1')] ]) + >>> + + """ def __cbFun(snmpEngine, sendRequestHandle, errorIndication, errorStatus, errorIndex, varBindTable, cbCtx): diff --git a/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py b/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py index 5c82718..c0f8af1 100644 --- a/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py +++ b/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py @@ -42,9 +42,9 @@ def getCmd(snmpEngine, authData, transportTarget, contextData, errorIndication : str True value indicates SNMP engine error. errorStatus : str - Non-zero value indicates SNMP PDU error. + True value indicates SNMP PDU error. errorIndex : int - Non-zero value refers to *varBinds[errorIndex-1] + Non-zero value refers to `varBinds[errorIndex-1]` varBinds : tuple A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances representing MIB variables returned in SNMP response. @@ -152,9 +152,9 @@ def setCmd(snmpEngine, authData, transportTarget, contextData, errorIndication : str True value indicates SNMP engine error. errorStatus : str - Non-zero value indicates SNMP PDU error. + True value indicates SNMP PDU error. errorIndex : int - Non-zero value refers to *varBinds[errorIndex-1] + Non-zero value refers to `varBinds[errorIndex-1]` varBinds : tuple A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances representing MIB variables returned in SNMP response. @@ -273,9 +273,9 @@ def nextCmd(snmpEngine, authData, transportTarget, contextData, errorIndication : str True value indicates SNMP engine error. errorStatus : str - Non-zero value indicates SNMP PDU error. + True value indicates SNMP PDU error. errorIndex : int - Non-zero value refers to *varBinds[errorIndex-1] + Non-zero value refers to `varBinds[errorIndex-1]` varBinds : tuple A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances representing MIB variables returned in SNMP response. @@ -456,7 +456,7 @@ def bulkCmd(snmpEngine, authData, transportTarget, contextData, errorIndication : str True value indicates SNMP engine error. errorStatus : str - Non-zero value indicates SNMP PDU error. + True value indicates SNMP PDU error. errorIndex : int Non-zero value refers to *varBinds[errorIndex-1] varBinds : tuple diff --git a/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py b/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py index e16fd7c..93e047e 100644 --- a/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py +++ b/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py @@ -51,9 +51,9 @@ def sendNotification(snmpEngine, authData, transportTarget, contextData, errorIndication : str True value indicates SNMP engine error. errorStatus : str - Non-zero value indicates SNMP PDU error. + True value indicates SNMP PDU error. errorIndex : int - Non-zero value refers to \*varBinds[errorIndex-1] + Non-zero value refers to `varBinds[errorIndex-1]` varBinds : tuple A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances representing MIB variables returned in SNMP response. -- cgit v1.2.1