PySNMP is a pure-Python SNMP engine implementation. This software deals with the darkest corners of SNMP specifications all in Python programming language.
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.
From Programmer's point of view, the layout of PySNMP software reflects SNMP protocol evolution. It has been written from ground up, from trivial SNMPv1 up to fully featured SNMPv3. Therefore, several levels of API to SNMP functionality are available:
The most ancient and low-level is SNMPv1/v2c protocol scope. Here programmer is supposed to build/parse SNMP messages and their payload -- Protocol Data Unit (PDU), handle protocol-level errors, transport issues and so on.
Although considered rather complex to deal with, this API probably gives best performance, memory footprint and flexibility, unless MIB access and/or SNMPv3 support is needed.
Parts of SNMPv3 standard is expressed in terms of some abstract API to SNMP engine and its components. PySNMP implementation adopts this abstract API to a great extent, so it's available at Programmer's disposal. As a side effect, SNMP RFCs could be referenced for API semantics when programming PySNMP at this level.
This API is much more higher-level than previous; here Programmer would have to manage two major issues: setting up Local Configuration Datastore (LCD) of SNMP engine and build/parse PDUs. PySNMP system is shipped multi-lingual, thus at this level all SNMPv1, SNMPv2c and SNMPv3 features are available.
At last, the highest-level API to SNMP functionality is available through the use of standard SNMPv3 applications. These applications cover the most frequent needs. That's why this API is expected to be the first to start with.
The Applications API further simplifies Programmer's job by hiding LCD management issues (contrary to SNMPv3 engine level). This API could be exploited in a oneliner fashion, for quick and simple prototyping.
As for its internal structure, PySNMP consists of a handful of large, dedicated components. They normally take shape of classes which turn into linked objects at runtime. So here are the main components:
SNMP Engine is an object holding references to all other components of the SNMP system. Typical user application has a single instance of SNMP Engine class possibly shared by many SNMP Applications of all kinds. As the other linked-in components tend to buildup various configuration and housekeeping information in runtime, SNMP Engine object appears to be expensive to configure to a usable state.
Transport subsystem is used for sending SNMP messages to and accepting them from network. The I/O subsystem consists of an abstract Dispatcher and one or more abstract Transport classes. Concrete Dispatcher implementation is I/O method-specific, consider BSD sockets for example. Concrete Transport classes are transport domain-specific. SNMP frequently uses UDP Transport but others are also possible. Transport Dispatcher interfaces are mostly used by Message And PDU Dispatcher. However, when using the SNMPv1/v2c-native API (the lowest-level one), these interfaces would be invoked directly.
Message And PDU Dispatcher is a heart of SNMP system. Its main responsibilities include dispatching PDUs from SNMP Applications through various subsystems all the way down to Transport Dispatcher, and passing SNMP messages coming from network up to SNMP Applications. It maintains logical connection with Management Instrumentation Controller which carries out operations on Managed Objects, here for the purpose of LCD access.
Message Processing Modules handle message-level protocol operations for present and possibly future versions of SNMP protocol. Most importantly, these include message parsing/building and possibly invoking security services whenever required. All MP Modules share standard API used by Message And PDU Dispatcher.
Message Security Modules perform message authentication and/or encryption. As of this writing, User-Based (for v3) and Community (for v1/2c) modules are implemented in PySNMP. All Security Modules share standard API used by Message Processing subsystem.
Access Control subsystem uses LCD information to authorize remote access to Managed Objects. This is used when serving Agent Applications or Trap receiver in Manager Applications.
A collection of dedicated Managed Objects Instances are used by PySNMP for its internal purposes. They are collectively called Local Configuration Datastore (LCD). In PySNMP, all SNMP engine configuration and statistics is kept in LCD. LCD Configurator is a wrapper aimed at simplifying LCD operations.
In most cases user is expected to only deal with the high-level, oneliner API to all these PySNMP components. However implementing SNMP Agents, Proxies and some other fine features of Managers require using the Standard Applications API. In those cases general understanding of SNMP operations and SNMP Engine components would be helpful.