diff options
Diffstat (limited to 'docs/source/docs/contents.rst')
| -rw-r--r-- | docs/source/docs/contents.rst | 371 |
1 files changed, 333 insertions, 38 deletions
diff --git a/docs/source/docs/contents.rst b/docs/source/docs/contents.rst index 1e6dc2f..d2447f1 100644 --- a/docs/source/docs/contents.rst +++ b/docs/source/docs/contents.rst @@ -5,57 +5,352 @@ Library reference .. toctree:: :maxdepth: 2 -As dealing with many features may overwhelm developers who aim at a +Dealing with many SNMP features may quickly overwhelm developers who aim at a quick and trivial task, PySNMP employs a layered architecture approach where the topmost programming API tries to be as simple as possible -to allow immediate solutions for most common use cases. For instance -it will let you perform SNMP GET/SET/WALK operations by pasting code -snippets from this web-site right into your Python interactive session. +to allow immediate solutions for most common use cases. +It will let you perform SNMP GET/SET/WALK and TRAP/INFORM operations by +pasting code snippets from PySNMP documentation and example scripts +right into your Python interactive session. + +Synchronous SNMP +---------------- + +Most simple and strightforward way to use PySNMP is by employing its +Synchronous, blocking API. It's also the default API offered by +users on *pysnmp.hlapi* sub-package import. + +Command Generator + +.. toctree:: + :maxdepth: 2 + + /docs/hlapi/asyncore/manager/cmdgen/getcmd + /docs/hlapi/asyncore/manager/cmdgen/setcmd + /docs/hlapi/asyncore/manager/cmdgen/nextcmd + /docs/hlapi/asyncore/manager/cmdgen/bulkcmd + +Notification Originator + +.. toctree:: + :maxdepth: 2 + + /docs/hlapi/asyncore/agent/ntforg/notification + +Transport configuration + +.. toctree:: + :maxdepth: 2 + + /docs/hlapi/asyncore/transport-configuration + +Most of SNMP operations involve packet exchange over network. PySNMP +is shipped with a set of bindings to popular asynchronous Python I/O +frameworks that let you run PySNMP in parallel with other tasks your +application may perform. + +Asynchronous: asyncore +---------------------- + +The :mod:`asyncore` module is in Python standard library since ancient +times. Main loop is built around :mod:`select` dispatcher, user +code is invoked through callback callables. + +.. toctree:: + :maxdepth: 2 + + /docs/hlapi/asyncore/manager/cmdgen/async-command-generator + /docs/hlapi/asyncore/agent/ntforg/async-notification-originator + +.. _asyncio: + +Asynchronous: asyncio +--------------------- + +The :mod:`asyncio` module first appeared in standard library since +Python 3.3 (in provisional basis). Its main design feature is that +it makes asynchronous code looking like synchronous one. That greately +simplifies development and maintanence. + +Command Generator + +.. toctree:: + :maxdepth: 2 + + /docs/hlapi/asyncio/manager/cmdgen/getcmd + /docs/hlapi/asyncio/manager/cmdgen/setcmd + /docs/hlapi/asyncio/manager/cmdgen/nextcmd + /docs/hlapi/asyncio/manager/cmdgen/bulkcmd + +Notification Originator + +.. toctree:: + :maxdepth: 2 + + /docs/hlapi/asyncio/agent/ntforg/notification + +Transport configuration + +.. toctree:: + :maxdepth: 2 + + /docs/hlapi/asyncio/transport-configuration + +.. _trollius: + +Asynchronous: trollius +---------------------- + +An almost compatible alternative to :ref:`asyncio` for pre-3.3 Python +is `Trollius <http://trollius.readthedocs.org>`_ module. PySNMP's +`asyncio` bindings automatically work with Trolleus. + +Please refer to :doc:`Trollius examples </examples/contents>` for +more information. + +.. _twisted: + +Asynchronous: Twisted +--------------------- + +`Twisted <http://twistedmatrix.org>`_ is one of the earliest and hugely +popular asynchronous I/O framework. It introduced a concept of +:class:`~twisted.internet.defer.Deferred` for representing work-in-progress +that is not blocking the rest of I/O operations. PySNMP provides Twisted +bindings. + +Command Generator + +.. toctree:: + :maxdepth: 2 + + /docs/hlapi/twisted/manager/cmdgen/getcmd + /docs/hlapi/twisted/manager/cmdgen/setcmd + /docs/hlapi/twisted/manager/cmdgen/nextcmd + /docs/hlapi/twisted/manager/cmdgen/bulkcmd + +Notification Originator + +.. toctree:: + :maxdepth: 2 + + /docs/hlapi/twisted/agent/ntforg/notification + +Transport configuration + +.. toctree:: + :maxdepth: 2 + + /docs/hlapi/twisted/transport-configuration + + +SNMP Engine +----------- + +SNMP Engine is a central, stateful object used by all SNMP v3 +substsems. Calls to high-level Applications API also consume SNMP +Engine object on input. + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.hlapi.SnmpEngine(snmpEngineID=None) + +Security Parameters +------------------- + +Calls to high-level Applications API consume Security Parameters +configuration object on input. The shortcut classes described in +this section convey configuration information to SNMP engine's +Local Configuration Datastore (:RFC:`2271#section-3.4.2`). +Once committed to LCD, SNMP engine saves its configuration for +the lifetime of SNMP engine object. + +Community-based ++++++++++++++++ + +Security Parameters object is Security Model specific. The +:py:class:`~pysnmp.hlapi.CommunityData` +class is used for configuring Community-Based Security Model of SNMPv1/SNMPv2c. + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.hlapi.CommunityData(communityIndex, communityName=None, mpModel=1, contextEngineId=None, contextName='', tag='') + +User-based +++++++++++ + +The :py:class:`~pysnmp.hlapi.UsmUserData` class provides SNMPv3 User-Based +Security Model configuration for SNMP v3 systems. + +.. autoclass:: pysnmp.hlapi.UsmUserData(userName, authKey=None, privKey=None, authProtocol=usmNoAuthProtocol, privProtocol=usmNoPrivProtocol, securityEngineId=None) + +Identification of Authentication and Privacy Protocols is done +via constant OIDs: + +.. autodata:: pysnmp.hlapi.usmNoAuthProtocol +.. autodata:: pysnmp.hlapi.usmHMACMD5AuthProtocol +.. autodata:: pysnmp.hlapi.usmHMACSHAAuthProtocol + +.. autodata:: pysnmp.hlapi.usmNoPrivProtocol +.. autodata:: pysnmp.hlapi.usmDESPrivProtocol +.. autodata:: pysnmp.hlapi.usm3DESEDEPrivProtocol +.. autodata:: pysnmp.hlapi.usmAesCfb128Protocol +.. autodata:: pysnmp.hlapi.usmAesCfb192Protocol +.. autodata:: pysnmp.hlapi.usmAesCfb256Protocol + +Transport configuration is I/O framework specific and is described in +respective sections. + +SNMP Context +------------ + +SNMP engine may serve several instances of the same MIB within +possibly multiple SNMP entities. SNMP context is a method to +unambiguously identify a collection of MIB variables behind +SNMP engine. See :RFC:`3411#section-3.3.1` for details. + +.. note:: + + SNMP context is only defined within SNMPv3 framework. For SNMPv1/v2c + architecture integration :RFC:`2576#section-5.1` introduces + interoperability aid which is available through + :py:class:`~pysnmp.hlapi.CommunityData`. + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.hlapi.ContextData + +.. _mib-services: + +MIB services +------------ + +.. _mib-variables: + +MIB Variables ++++++++++++++ + +SNMP MIB variable is identified by an OBJECT IDENTIFIER (OID) and is +accompanied by a value belonging to one of SNMP types (:RFC:`1902#section-2`). +This pair is collectively called a variable-binding in SNMP parlance. + +The :py:mod:`~pysnmp.smi.rfc1902` module implements :RFC:`1902#section-2` +MACRO definiitons. .. toctree:: - /docs/hlapi/contents + :maxdepth: 2 + +.. autoclass:: pysnmp.smi.rfc1902.ObjectIdentity + :members: + +.. autoclass:: pysnmp.smi.rfc1902.ObjectType + :members: + +.. _notification-types: -At the basic level, PySNMP offers a complete set of Standard SNMP -Applications to give you maximum flexibility with integration of SNMP -facilities into other applications, building special purpose SNMP Agents, -TRAP collectors, Proxy entities and all kinds of SNMP-related things. +MIB notification types +++++++++++++++++++++++ -Many user applications are built within some input/output framework. -PySNMP offers native bindings to some of these framework. +SNMP Notifications are enumerated and imply including certain +set of MIB variables. +Notification Originator applications refer to MIBs for MIB notifications +through *NOTIFICATION-TYPE* ASN.1 macro. It conveys a set of MIB variables to +be gathered and reported in SNMP Notification. The +:py:mod:`~pysnmp.smi.rfc1902` module implements :RFC:`1902#section-2` +macro definiitons. .. toctree:: -.. /docs/v3arch/asyncore/contents -.. /docs/v3arch/asyncio/contents -.. /docs/v3arch/trollius/contents -.. /docs/v3arch/twisted/contents + :maxdepth: 2 + +.. autoclass:: pysnmp.smi.rfc1902.NotificationType + :members: + +.. _snmp-types: + +SNMP base types +--------------- -At the other end of the complexity spectrum, PySNMP offers packet-level -ASN.1 data structures that let you build, parse and analyze SNMP messages -travelling over network. This extremely low-level programming interface is -explained by the SNMPv1/v2c example scripts. If your goal is to conduct -experiments on the protocol level or optimize for highest possible -performance - this is a way to go. +SNMP represents real-world objects it serves along with their +states in form of values. Those values each belong to one +of SNMP types (:RFC:`1902#section-2`) which, in turn, are based +on `ASN.1 <https://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One>`_ +data description language. PySNMP types are derived from +`Python ASN.1 types <http://pyasn1.sf.net>`_ implementation. .. toctree:: -.. /docs/v1arch/asyncore/contents + :maxdepth: 2 + +.. _integer32: + +Integer32 type +++++++++++++++ + +.. autoclass:: pysnmp.proto.rfc1902.Integer32(initializer) + :members: + +.. _integer: + +Integer type +++++++++++++ + +.. autoclass:: pysnmp.proto.rfc1902.Integer(initializer) + :members: + +.. _octetstring: + +OctetString type +++++++++++++++++ + +.. autoclass:: pysnmp.proto.rfc1902.OctetString(strValue=None, hexValue=None) + :members: + +.. _ipaddress: + +IpAddress type +++++++++++++++ + +.. autoclass:: pysnmp.proto.rfc1902.IpAddress(strValue=None, hexValue=None) + +ObjectIdentifier type ++++++++++++++++++++++ + +.. autoclass:: pysnmp.proto.rfc1902.ObjectIdentifier(initializer) + +Counter32 type +++++++++++++++ + +.. autoclass:: pysnmp.proto.rfc1902.Counter32(initializer) + +Gauge32 type +++++++++++++ + +.. autoclass:: pysnmp.proto.rfc1902.Gauge32(initializer) + +Unsigned32 type ++++++++++++++++ + +.. autoclass:: pysnmp.proto.rfc1902.Unsigned32(initializer) + +TimeTicks type +++++++++++++++ + +.. autoclass:: pysnmp.proto.rfc1902.TimeTicks(initializer) + +Opaque type ++++++++++++ -.. comment:: - MIB support - ----------- +.. autoclass:: pysnmp.proto.rfc1902.Opaque(initializer) - SNMP suite of standards defines a data model for objects being managed - (known as `SMI <http://en.wikipedia.org/wiki/Structure_of_Management_Information>`_), - it takes shape of `MIB <http://en.wikipedia.org/wiki/Management_information_base>`_ - files semi-formally listing and describing capabilities of a SNMP-managed - system. In PySNMP, MIB files are converted into Python code objects which - could be loaded and executed at run-time by both SNMP Manager (for purposes - of data presentation to human beings) and SNMP Agents (as a gateway to - backend systems like DBMS). +Counter64 type +++++++++++++++ - MIB conversion is handled automatically by `PySMI <http://pysmi.sf.net>`_ - library. Large collection of original MIB files is maintained at - `our MIB repository <http://mibs.snmplabs.com/asn1/>`_ . +.. autoclass:: pysnmp.proto.rfc1902.Counter64(initializer) - .. toctree:: - .. /docs/smi/contents +Bits type ++++++++++ +.. autoclass:: pysnmp.proto.rfc1902.Bits(initializer) + :members: |