path: root/docs/source/docs/api-reference.rst

Library reference
=================

.. toctree::
   :maxdepth: 2

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

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.

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/sync/manager/cmdgen/getcmd
   /docs/hlapi/asyncore/sync/manager/cmdgen/setcmd
   /docs/hlapi/asyncore/sync/manager/cmdgen/nextcmd
   /docs/hlapi/asyncore/sync/manager/cmdgen/bulkcmd

Notification Originator

.. toctree::
   :maxdepth: 2

   /docs/hlapi/asyncore/sync/agent/ntforg/notification 

Transport configuration
+++++++++++++++++++++++

The following shortcut classes convey configuration information to
SNMP engine's Local Configuration Datastore (:RFC:`2271#section-3.4.2`)
as well as to underlying socket API. Once committed to LCD, SNMP engine
saves its configuration for the lifetime of SNMP engine object.

.. toctree::
   :maxdepth: 2

.. autoclass:: pysnmp.hlapi.UdpTransportTarget
   :members: setLocalAddress

.. autoclass:: pysnmp.hlapi.Udp6TransportTarget
   :members: setLocalAddress

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.

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

.. autoclass:: pysnmp.hlapi.asyncore.UdpTransportTarget
   :members: setLocalAddress

.. autoclass:: pysnmp.hlapi.asyncore.Udp6TransportTarget
   :members: setLocalAddress

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

.. autoclass:: pysnmp.hlapi.asyncio.UdpTransportTarget
   :members: setLocalAddress

.. autoclass:: pysnmp.hlapi.asyncio.Udp6TransportTarget
   :members: setLocalAddress

Asynchronous: trollius
----------------------

An almost compatible alternative to *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.

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

.. autoclass:: pysnmp.hlapi.twisted.UdpTransportTarget
   :members: setLocalAddress

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)

**Authentication protocol identifiers**

.. autodata:: pysnmp.hlapi.usmNoAuthProtocol
.. autodata:: pysnmp.hlapi.usmHMACMD5AuthProtocol
.. autodata:: pysnmp.hlapi.usmHMACSHAAuthProtocol
.. autodata:: pysnmp.hlapi.usmHMAC128SHA224AuthProtocol
.. autodata:: pysnmp.hlapi.usmHMAC192SHA256AuthProtocol
.. autodata:: pysnmp.hlapi.usmHMAC256SHA384AuthProtocol
.. autodata:: pysnmp.hlapi.usmHMAC384SHA512AuthProtocol

**Privacy (encryption) protocol identifiers**

.. autodata:: pysnmp.hlapi.usmNoPrivProtocol
.. autodata:: pysnmp.hlapi.usmDESPrivProtocol
.. autodata:: pysnmp.hlapi.usm3DESEDEPrivProtocol
.. autodata:: pysnmp.hlapi.usmAesCfb128Protocol
.. autodata:: pysnmp.hlapi.usmAesCfb192Protocol
.. autodata:: pysnmp.hlapi.usmAesCfb256Protocol
.. autodata:: pysnmp.hlapi.usmAesBlumenthalCfb192Protocol
.. autodata:: pysnmp.hlapi.usmAesBlumenthalCfb256Protocol

.. note::

   SNMP authentication and encryption keys must be at least *eight*
   octets long.

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 tool for
unambiguously identifying a collection of MIB variables behind the
SNMP engine. See :RFC:`3411#section-3.3.1` for details.

.. note::

   The SNMP context information is not tied to SNMPv3/USM user,
   but it is transferred in SNMPv3 message header.

   Legacy SNMPv1/v2c protocols do not accommodate the SNMP context
   information at all.

   To fit legacy SNMPv1/SNMPv2c systems into unified SNMPv3
   architecture, the mapping procedure is introduced by
   :RFC:`2576#section-5.1` which essentially lets you first configure
   and then supply the missing items (e.g. *contextName*,
   *contextEngineId* and other) to the upper layers of SNMP stack
   based on SNMPv1/v2c *communityName* and transport endpoint.

   The SNMP context information necessary for this mapping procedure
   to operate is supplied through the
   :py:class:`~pysnmp.hlapi.CommunityData` object.

.. 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::
   :maxdepth: 2

.. autoclass:: pysnmp.smi.rfc1902.ObjectIdentity
   :members:

.. autoclass:: pysnmp.smi.rfc1902.ObjectType
   :members:

.. _notification-types:

MIB notification types
++++++++++++++++++++++

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::
   :maxdepth: 2

.. autoclass:: pysnmp.smi.rfc1902.NotificationType
   :members:

.. _snmp-types:

SNMP base types
---------------

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://snmplabs.com/pyasn1/>`_ implementation.

.. toctree::
   :maxdepth: 2

.. _null:

Null type
+++++++++

.. autoclass:: pysnmp.proto.rfc1902.Null(initializer)
   :members:

.. note::

   The `NULL` type actually belongs to the base ASN.1 types. It is not defined
   in :RFC:`1902#section-2` as an SNMP type. The `Null` type is exposed through
   `rfc1902` module just for convenience.

.. _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
+++++++++++

.. autoclass:: pysnmp.proto.rfc1902.Opaque(initializer)

Counter64 type
++++++++++++++

.. autoclass:: pysnmp.proto.rfc1902.Counter64(initializer)

Bits type
+++++++++

.. autoclass:: pysnmp.proto.rfc1902.Bits(initializer)
   :members: