Library reference
*****************

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

* GET command

* SET command

* GETNEXT command

* GETBULK command

Notification Originator

* TRAP/INFORM 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.


Asynchronous: asyncore
======================

The "asyncore" module is in Python standard library since ancient
times. Main loop is built around "select" dispatcher, user code is
invoked through callback callables.

Command Generator

* GET command

* SET command

* GETNEXT command

* GETBULK command

Notification Originator

* TRAP/INFORM notification


Transport configuration
-----------------------


Asynchronous: asyncio
=====================

The "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

* GET command

* SET command

* GETNEXT command

* GETBULK command

Notification Originator

* TRAP/INFORM notification


Transport configuration
-----------------------


Asynchronous: trollius
======================

An almost compatible alternative to *asyncio* for pre-3.3 Python is
Trollius module. PySNMP's *asyncio* bindings automatically work with
Trolleus.

Please refer to Trollius examples for more information.


Asynchronous: Twisted
=====================

Twisted is one of the earliest and hugely popular asynchronous I/O
framework. It introduced a concept of "Deferred" for representing
work-in-progress that is not blocking the rest of I/O operations.
PySNMP provides Twisted bindings.

Command Generator

* GET command

* SET command

* GETNEXT command

* GETBULK command

Notification Originator

* TRAP/INFORM notification


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.


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
"CommunityData" class is used for configuring Community-Based Security
Model of SNMPv1/SNMPv2c.


User-based
----------

The "UsmUserData" class provides SNMPv3 User-Based Security Model
configuration for SNMP v3 systems.

**Authentication protocol identifiers**

**Privacy (encryption) protocol identifiers**

**Key material types**

Note: SNMP authentication and encryption keys must be at least *8*
  and at most *32* 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
  "CommunityData" object.


MIB services
============


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 "rfc1902" module implements **RFC 1902#section-2** MACRO
definiitons.


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 "rfc1902" module implements **RFC 1902#section-2**
macro definiitons.


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 data
description language. PySNMP types are derived from Python ASN.1 types
implementation.


Null type
---------

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


Integer type
------------


OctetString type
----------------


IpAddress type
--------------


ObjectIdentifier type
---------------------


Counter32 type
--------------


Gauge32 type
------------


Unsigned32 type
---------------


TimeTicks type
--------------


Opaque type
-----------


Counter64 type
--------------


Bits type
---------
