Example scripts
***************

SNMP is not simple (PySNMP implementation takes over 15K lines of
Python code), but PySNMP tries to hide the complexities and let you
carry out typical SNMP operations in a quick and intuitive way.

PySNMP offers three groups of programming interfaces to deal with SNMP
protocol. In the order from most concise to most detailed those APIs
follow.


High-level SNMP
===============

The so called high-level API (hlapi) is designed to be simple, concise
and suitable for the most frequent operations. For that matter only
Command Generator and Notification Originator Applications are
currently wrapped into a nearly one-line Python expression.

It comes in several flavours: one synchronous and a bunch of bindings
to popular asynchronous I/O frameworks. Those varieties of APIs bring
subtile differences, mostly to better match particular I/O framework
customs. Unless you have a very specific task, the high-level API
might solve your SNMP needs.

* Synchronous SNMP

  * SNMP versions

  * Modifying variables

  * Walking operations

  * Table operations

  * MIB tweaks

  * Transport tweaks

  * Advanced Command Generator

  * Common notifications

  * SNMPv1 TRAP variants

  * Evaluating NOTIFICATION-TYPE

  * Advanced Notification Originator

* Asynchronous: asyncore

  * Various SNMP versions

  * Walking operations

  * Advanced Command Generator

  * Common notifications

  * Advanced Notification Originator

* Asynchronous: asyncio

  * Various SNMP versions

  * Walking operations

  * Advanced Command Generator

  * Common notifications

  * Advanced Notification Originator

* Asynchronous: trollius

  * Various SNMP versions

  * Walking operations

  * Common notifications

* Asynchronous: Twisted

  * Various SNMP versions

  * Walking operations

  * Transport tweaks

  * Advanced Command Generator

  * Common notifications

  * Advanced Notification Originator


Native SNMP API
===============

Complete implementation of all official Standard SNMP Applications. It
should let you implement any SNMP operation defined in the standard at
the cost of working at a somewhat low level.

This API also comes in several transport varieties depending on I/O
framework being used.

* Asynchronous: asyncore

  * Command Generator Applications

  * Command Responder Applications

  * Notification Originator Applications

  * Notification Receiver Applications

  * Proxy Forwarder Applications

* Asynchronous: asyncio

  * Command Responder Applications

  * Notification Receiver Applications

* Asynchronous: trollius

* Asynchronous: Twisted

  * Command Responder Applications

  * Notification Receiver Applications


Packet-level SNMP
=================

In cases where performance is your top priority and you only need to
work with SNMP v1 and v2c systems and you do not mind writing much
more code, then there is a low-level API to SNMP v1/v2c PDU and PySNMP
I/O engine. There's practically no SNMP engine or SMI infrastructure
involved in the operations of these almost wire-level interfaces.
Although MIB services can still be used separately.

A packet-level API-based application typically manages both SNMP
message building/parsing and network communication via one or more
transports. It's fully up to the application to handle failures on
message and transport levels.


Command Generator
-----------------

* Fetching variables

  * Fetch scalar MIB variables (SNMPv1)

* Modifying variables

  * SET string and integer scalars (SNMPv2c)

* MIB walking operations

  * Walk Agent MIB (SNMPv1)

  * Bulk walk Agent MIB (SNMPv2c)

* Transport tweaks

  * Spoof IPv4 source address

  * Broadcast SNMP message (IPv4)


Command Responder
-----------------

* Agent-side MIB implementations

  * Implementing scalar MIB objects


Notification Originator
-----------------------

* Transport tweaks

  * TRAP over multiple transports

  * INFORM over multiple transports


Notification Receiver
---------------------

* Transport tweaks

  * Listen for notifications at IPv4 & IPv6 interfaces


Low-level MIB access
====================

* Manager side

  * PDU var-binds to MIB objects

  * MIB objects to PDU var-binds

  * SNMP MIB browser

* Agent side

  * Implementing MIB objects

  * Agent operations on MIB


Using these examples
====================

Before doing cut&paste of the code below into your Python interpreter,
make sure to install pysnmp and its dependencies by running pip or
easy_install:

   # pip pysnmp

There's a public, multilingual SNMP Command Responder and Notification
Receiver configured at demo.snmplabs.com to let you run PySNMP
examples scripts in a cut&paste fashion. If you wish to use your own
SNMP Agent with these scripts, make sure to either configure your
local snmpd and/or snmptrapd or use a valid address and SNMP
credentials of your SNMP Agent in the examples to let them work.

Should you want to use a MIB to make SNMP operations more human-
friendly, you are welcome to search for it and possibly download one
from our public MIB repository. Alternatively, you can configure
PySNMP to fetch and cache required MIBs from there automatically.

If you find your PySNMP application behaving unexpectedly, try to
enable a /more or less verbose/ built-in PySNMP debugging by adding
the following snippet of code at the beginning of your application:

   from pysnmp import debug

   # use specific flags or 'all' for full debugging
   debug.setLogger(debug.Debug('dsp', 'msgproc', 'secmod'))

Then run your app and watch stderr. The Debug initializer enables
debugging for a particular PySNMP subsystem, 'all' enables full
debugging. More specific flags are:

* io

* dsp

* msgproc

* secmod

* mibbuild

* mibview

* mibinstrum

* acl

* proxy

* app

For more details on PySNMP programming model and interfaces, please
refer to library documentation.
