haraldwolff
/
pysnmp-sky
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

documentation reworked and converted to Sphinx (in NumPy style)

pull/45/head
elie 2015-09-14 05:39:35 +00:00
parent ddc989155d
commit c0afe7276d
18 changed files with 1300 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
MANIFEST.in
View File

@ -1,3 +1,3 @@
include *.txt
recursive-include examples *.py
recursive-include docs *.txt *.html *.gif *.conf
recursive-include docs *.txt *.rst *.conf Makefile

11
docs/README.txt 100644
View File

@ -0,0 +1,11 @@
You need Sphinx too build this documentation. Or you can read it in ASCII. ;)
Better run:
# pip sphinx
and once Sphinx is installed on your system, run:
$ make html
To build a copy of HTML'ed PySNMP documentation.

10
docs/source/.static/css/rtdimproved.css 100644
View File

@ -0,0 +1,10 @@
@import url("../pygments.css");
@import url("theme.css");
/* fix horizontal padding to accomodate adsense banners */
.wy-nav-content {
padding: 1.618em 2.236em;
height: 100%;
/* max-width: 800px; */
margin: auto;
}

185
docs/source/.templates/layout.html 100644
View File

@ -0,0 +1,185 @@
{# TEMPLATE VAR SETTINGS #}
{%- set url_root = pathto('', 1) %}
{%- if url_root == '#' %}{% set url_root = '' %}{% endif %}
{%- if not embedded and docstitle %}
{%- set titlesuffix = " — "|safe + docstitle|e %}
{%- else %}
{%- set titlesuffix = "" %}
{%- endif %}
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
{{ metatags }}
<meta name="viewport" content="width=device-width, initial-scale=1.0">
{% block htmltitle %}
<title>{{ title|striptags|e }}{{ titlesuffix }}</title>
{% endblock %}
{# FAVICON #}
{% if favicon %}
<link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
{% endif %}
{# CSS #}
{# OPENSEARCH #}
{% if not embedded %}
{% if use_opensearch %}
<link rel="search" type="application/opensearchdescription+xml" title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}" href="{{ pathto('_static/opensearch.xml', 1) }}"/>
{% endif %}
{% endif %}
{# RTD hosts this file, so just load on non RTD builds #}
{% if not READTHEDOCS %}
<link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
{% endif %}
{% for cssfile in css_files %}
<link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
{% endfor %}
{% for cssfile in extra_css_files %}
<link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
{% endfor %}
{%- block linktags %}
{%- if hasdoc('about') %}
<link rel="author" title="{{ _('About these documents') }}"
href="{{ pathto('about') }}"/>
{%- endif %}
{%- if hasdoc('genindex') %}
<link rel="index" title="{{ _('Index') }}"
href="{{ pathto('genindex') }}"/>
{%- endif %}
{%- if hasdoc('search') %}
<link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}"/>
{%- endif %}
{%- if hasdoc('copyright') %}
<link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}"/>
{%- endif %}
<link rel="top" title="{{ docstitle|e }}" href="{{ pathto('index') }}"/>
{%- if parents %}
<link rel="up" title="{{ parents[-1].title|striptags|e }}" href="{{ parents[-1].link|e }}"/>
{%- endif %}
{%- if next %}
<link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}"/>
{%- endif %}
{%- if prev %}
<link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}"/>
{%- endif %}
{%- endblock %}
{%- block extrahead %} {% endblock %}
{# Keep modernizr in head - http://modernizr.com/docs/#installing #}
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
{# SIDE NAV, TOGGLES ON MOBILE #}
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
{% block sidebartitle %}
{% if logo and theme_logo_only %}
<a href="{{ pathto(master_doc) }}">
{% else %}
<a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
{% endif %}
{% if logo %}
{# Not strictly valid HTML, but it's the only way to display/scale it properly, without weird scripting or heaps of work #}
<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" />
{% endif %}
</a>
{% include "searchbox.html" %}
{% endblock %}
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
{% block menu %}
{% set toctree = toctree(maxdepth=4, collapse=True, includehidden=True) %}
{% if toctree %}
{{ toctree }}
{% else %}
<!-- Local TOC -->
<div class="local-toc">{{ toc }}</div>
{% endif %}
{% endblock %}
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
{# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #}
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="{{ pathto(master_doc) }}">{{ project }}</a>
</nav>
{# PAGE CONTENT #}
<div class="wy-nav-content">
<div class="rst-content">
{% include "breadcrumbs.html" %}
<div role="main" class="document">
{% include "top.html" %}
{% block body %}{% endblock %}
{% include "bottom.html" %}
{% include "analytics.html" %}
<hr/>
</div>
{% include "footer.html" %}
</div>
</div>
</section>
</div>
{% include "versions.html" %}
{% if not embedded %}
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'{{ url_root }}',
VERSION:'{{ release|e }}',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}',
HAS_SOURCE: {{ has_source|lower }}
};
</script>
{%- for scriptfile in script_files %}
<script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
{%- endfor %}
{% endif %}
{# RTD hosts this file, so just load on non RTD builds #}
{% if not READTHEDOCS %}
<script type="text/javascript" src="{{ pathto('_static/js/theme.js', 1) }}"></script>
{% endif %}
{# STICKY NAVIGATION #}
{% if theme_sticky_navigation %}
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
{% endif %}
{%- block footer %} {% endblock %}
</body>
</html>

6
docs/source/changelog.rst 100644
View File

@ -0,0 +1,6 @@
Changelog
=========
.. include:: ../../CHANGES.txt

314
docs/source/conf.py 100644
View File

@ -0,0 +1,314 @@
# -*- coding: utf-8 -*-
#
# PySNMP documentation build configuration file, created by
# sphinx-quickstart on Sat Jun 27 23:15:54 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
import shlex
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo'
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['.templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'contents'
# General information about the project.
project = u'PySNMP'
copyright = u'2015, Ilya Etingof <ilya@glas.net>'
author = u'Ilya Etingof <ilya@glas.net>'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '4.3'
# The full version, including alpha/beta/rc tags.
release = '4.3'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['.static']
# Custom CSS theme
html_style = 'css/rtdimproved.css'
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
html_show_sourcelink = False
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
#html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'PySNMPdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment
#'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'PySNMP.tex', u'PySNMP Documentation',
u'Ilya Etingof \\textless{}ilya@glas.net\\textgreater{}', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'pysnmp', u'PySNMP Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'PySNMP', u'PySNMP Documentation',
author, 'PySNMP', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = { 'python': ('https://docs.python.org/', None),
'pysmi': ('http://pysmi.sf.net/', None) }
# this merges constructor docstring with class docstring
autoclass_content = 'both'
# Napoleon settings
napoleon_google_docstring = False
napoleon_numpy_docstring = True
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = False
napoleon_use_rtype = False

114
docs/source/contents.rst 100644
View File

@ -0,0 +1,114 @@
SNMP library for Python
=======================
.. toctree::
:maxdepth: 2
PySNMP is a cross-platform, pure-`Python <http://www.python.org/>`_
`SNMP <http://en.wikipedia.org/wiki/Simple_Network_Management_Protocol>`_
engine implementation. It features fully-functional SNMP engine capable
to act in Agent/Manager/Proxy roles, talking SNMP v1/v2c/v3 protocol
versions over IPv4/IPv6 and other network transports.
Despite its name, SNMP is not a really simple protocol. For instance its
third version introduces complex and open-ended security framework,
multilingual capabilities, remote configuration and other features.
PySNMP implementation closely follows intricate system details and features
bringing most possible power and flexibility to its users.
Current PySNMP stable version is 4.3.0. It runs with Python 2.4 through 3.5
and is recommended for new applications as well as for migration from older,
now obsolete, PySNMP releases. All site documentation and examples are written
for the 4.3.0 and later versions in mind. Older materials are still
available under the obsolete section.
Besides the libraries, a set of pure-Python command-line tools are shipped
along with the system. Those tools mimic the interface and behaviour of
popular Net-SNMP snmpget/snmpset/snmpwalk utilities. They may be useful
in a cross-platform situations as well as a testing and prototyping
instrument for pysnmp users.
PySNMP software is free and open-source. It's being distributed under a
liberal BSD-style license. PySNMP development has been initially sponsored
by a `PSF <http://www.python.org/psf/>`_ grant.
Quick start
-----------
You already know something about SNMP and have no courage to dive into
this implementation? Try out quick start page!
.. toctree::
:maxdepth: 2
/quick-start
Documentation
-------------
This is so boring to read... Now imagine how boring it was to write this! ;-)
.. toctree::
:maxdepth: 2
/snmp-overview
/docs/contents
Examples
--------
.. toctree::
:maxdepth: 2
/examples/contents
Download
--------
Best way is usually to
.. code-block:: bash
# pip install pysnmp
If that does not work for you for some reason, you might need to read the
following page.
.. toctree::
:maxdepth: 2
/download
FAQ
---
.. toctree::
:maxdepth: 2
/faq
Development
-----------
We fanatically document all fixes, changes and new features in changelog.
There you could also download the latest unreleased pysnmp tarball
containing the latest fixes and improvements.
.. toctree::
:maxdepth: 1
/changelog
Our development plans and new features we consider for eventual implementation
are collected in the following section.
.. toctree::
:maxdepth: 2
/development
License
-------
.. include:: ../../LICENSE.txt

100
docs/source/development.rst 100644
View File

@ -0,0 +1,100 @@
Further development
-------------------
Although PySNMP is already a mature software and it is being used at many
places, the ultimate goal of the project is to implement most of the useful
features that SNMP standards can offer. What follows is a list of most
prominent missing features that PySNMP developers are planning to put their
hands on in the future.
PySNMP library
++++++++++++++
#. Built-in MIB parser. PySNMP uses a data model of its own to work with
information contained in MIB files. To convert ASN.1-based MIB texts
into Python modules, an off-line, third-party tool is employed. As it
turns out, this approach has two major drawback: one is that PySNMP
users may need to pre-process MIB texts to use them with their
PySNMP-based applications. Another is that LibSMI's Python driver
seems to miss some information carried by MIBs. Thus the solution would
be to write another MIB parser and code generator which would produce
PySNMP compliant Python code right from MIB text files all by itself.
**Done:** see `PySMI project <http://pysmi.sf.net>`_ in conjuction with the latest PySNMP codebase.
#. Reverse MIB index. The variable-bindings received by the system whilst
in Manager role could be post-processed using the information kept in
MIB files to include human-friendly OIDs names, tables indices and
values representation. However, there is currently no provisioning in
the PySNMP system for locating and loading up MIB files containing
additional information on arbitrary OIDs. So the idea is to maintain
an OID-to-MIB index to let PySNMP load relevant MIB automatically on
demand.
#. Stream sockets support. Currently, PySNMP transport subsystem only
supports datagram-type network sockets. That covers UDP-over-IPv4 and
UDP-over-IPv6. However, SNMP engine can potentially run over
stream-oriented protocols what would let it support TCP-over-IPv4,
TCP-over-IPv6 and SSL/TSL transports. Neither of these is currently
implemented with PySNMP.
#. AgentX implementation. We anticipate many uses of this. For instance,
having AgentX protocol support in pure-Python would let us write AgentX
modules in pure-Python and attach them to high-performance Net-SNMP
Agent. Or we could build and maintain a fully-featured, stand-alone
PySNMP-based Agent so that users would write their own AgentX extensions
what would comprise a complete SNMP Agent solution at lesser effort.
#. A DBMS-based SMI. Currently implemented SMI takes shape of live Python
objects that let user hook up his own handler on any existing Managed
Object Instance. That's flexible and working approach in many cases,
however sometimes, for instance when Management Instrumentation is
inherently DBMS-based, it may be more efficient to move the entire
SMI/MIB subsystem into a database. PySNMP engine would talk to it
through its simple and well defined SMI API.
Stand-alone PySNMP-based tools
++++++++++++++++++++++++++++++
#. SNMP Proxy Forwarder. That would be a stand-alone, application-level
proxy service supporting all SNMP versions, multiple network transports,
Command and Notification SNMP message types. Its anticipated features
include extensive configuration facilities, fine-graned access
control and logging.
**Done:** see `SNMP Proxy Forwarder <http://snmpfwd.sf.net>`_.
#. SNMP Trap Receiver. We see this application as a simple yet flexible
SNMP TRAP collector. It would listen on network sockets of different
types receiving SNMP TRAP/INFORM notifications over any SNMP version
and putting all the details into a database and possibly triggering
external events.
#. Database backend for SNMP Simulator. We have already built a tool for
simulating SNMP Agents based on a snapshot of their Management
Instrumentation state. Current implementation uses a plain-text file
for keeping and possibly managing the snapshot. Many users of the
Simulator software requested a value variation feature to be supported
so that simulated Agents would look live, not static. We consider this
variation and also dependencies features would be best implemented as
a relational database application. So we are planning to put some more
efforts into the Simulator project as time permits.
**Done:** since `snmpsim-0.2.4 <http://snmpsim.sf.net>`_
If you need some particular feature - please,
`drop us a note <http://pysnmp.sourceforge.net/contact.html>`_ . Once we
see a greater demand in particular area, we would re-arrange our
development resources to meet it sooner.
You could greater speed up the development of particular feature by
sponsoring it. Please get back to us to discuss details.
Contributions to the PySNMP source code is greatly appreciated as well.
We require contributed code to run with Python 2.4 through the latest
Python version (which is 3.3 at the time of this writing). Contributed
code will be redistributed under the terms of the same
`license <http://pysnmp.sourceforge.net/license.html>`_ as PySNMP is.

62
docs/source/docs/contents.rst 100644
View File

@ -0,0 +1,62 @@
Library reference
=================
.. toctree::
:maxdepth: 2
As dealing with
many features may 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.
.. toctree::
/docs/v3arch/asyncore/oneliner/contents
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.
Many user applications are built within some input/output framework.
PySNMP offers native bindings to some of these framework.
.. toctree::
.. /docs/v3arch/asyncore/contents
.. /docs/v3arch/asyncio/contents
.. /docs/v3arch/trollius/contents
.. /docs/v3arch/twisted/contents
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.
.. toctree::
.. /docs/v1arch/asyncore/contents
.. comment::
MIB support
-----------
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).
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/>`_ .
.. toctree::
.. /docs/smi/contents

8
docs/source/docs/hlapi/asyncore/sync/agent/ntforg/notification.rst 100644
View File

@ -0,0 +1,8 @@
Notification Originator
=======================
.. toctree::
:maxdepth: 2
.. autofunction:: pysnmp.entity.rfc3413.oneliner.ntforg.sendNotification

8
docs/source/docs/hlapi/asyncore/sync/manager/cmdgen/bulkcmd.rst 100644
View File

@ -0,0 +1,8 @@
GETBULK Command Generator
=========================
.. toctree::
:maxdepth: 2
.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.bulkCmd

8
docs/source/docs/hlapi/asyncore/sync/manager/cmdgen/getcmd.rst 100644
View File

@ -0,0 +1,8 @@
GET Command Generator
=====================
.. toctree::
:maxdepth: 2
.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.getCmd

8
docs/source/docs/hlapi/asyncore/sync/manager/cmdgen/nextcmd.rst 100644
View File

@ -0,0 +1,8 @@
GETNEXT Command Generator
=========================
.. toctree::
:maxdepth: 2
.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.nextCmd

8
docs/source/docs/hlapi/asyncore/sync/manager/cmdgen/setcmd.rst 100644
View File

@ -0,0 +1,8 @@
SET Command Generator
=====================
.. toctree::
:maxdepth: 2
.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.setCmd

74
docs/source/download.rst 100644
View File

@ -0,0 +1,74 @@
Download PySNMP
===============
.. toctree::
:maxdepth: 2
The PySNMP software is provided under terms and conditions of BSD-style
license, and can be freely downloaded from Source Forge
`download servers <http://sourceforge.net/projects/pysnmp/files/>`_ or
`PyPI <http://pypi.python.org/pypi/pysnmp/>`_.
Please, note that there are frequently release candidate versions (marked rc)
also available for download. These are potentially less stable in terms of
implementation and public interfaces. However they are first to contain
fixes to the issues, discovered in latest stable branch.
But the simplest way to obtain PySNMP is to run:
.. code-block:: bash
$ easy_install pysnmp
or
.. code-block:: bash
$ pip install pysnmp
Those Python package managers will download PySNMP along with all its
dependencies and install them all on your system.
In case you do not have the easy_install command on your system but still
would like to use the on-line package installation method, please install
`setuptools <http://pypi.python.org/pypi/setuptools>`_ package by
downloading and running `ez_setup.pz <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_ bootstrap:
.. code-block:: bash
# wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
# python ez_setup.py
In case you are installing PySNMP on an off-line system, the following
packages need to be downloaded and installed for PySNMP to become
operational:
* `PyASN1 <http://pypi.python.org/packages/source/p/pyasn1/>`_,
used for handling ASN.1 objects
* `PySNMP <http://pypi.python.org/packages/source/p/pysnmp/>`_,
SNMP engine implementation
Optional, but recommended:
* `PyCrypto <http://pypi.python.org/packages/source/p/pycrypto/>`_,
used by SNMPv3 crypto features (Windows users need
`precompiled version <http://www.voidspace.org.uk/python/modules.shtml>`_)
* `PySMI <http://pypi.python.org/packages/source/p/pysmi/>`_ for automatic
MIB download and compilation. That helps visualizing more SNMP objects
* `Ply <http://pypi.python.org/packages/source/p/ply/>`_, parser generator
required by PySMI
The installation procedure for all the above packages is as follows
(on UNIX-based systems):
.. code-block:: bash
$ tar zxf package-X.X.X.tar.gz
$ cd package-X.X.X
# python setup.py install
# cd ..
# rm -rf package-X.X.X
In case of any issues, please `let us know <http://pysnmp.sourceforge.net/contact.html>`_ so we could try to help out.

17
docs/source/faq.rst 100644
View File

@ -0,0 +1,17 @@
FAQ
===
Here we have an ever-growing list of frequently asked questions regarding
PySNMP usage issues. If you got an issue that you think is worth noting
here, please `drop us a note <http://pysnmp.sourceforge.net/contact.html>`_.
Keep in mind that some the answers below may not be universally applicable
to any PySNMP revision.
.. toctree::
:maxdepth: 2
:glob:
/faq/*

53
docs/source/quick-start.rst 100644
View File

@ -0,0 +1,53 @@
Quick start
===========
.. toctree::
:maxdepth: 2
Once you downloaded and installed PySNMP library on your Linux/Windows/OS-X
system, you should be able to solve the very basic SNMP task right from
your Python prompt - fetch some data from a remote SNMP Agent (you'd need
at least version 4.3.0 to run code from this page).
Fetch SNMP variable
-------------------
So just cut&paste the following code right into your Python prompt. The
code will performs SNMP GET operation for a sysDescr.0 object at a
publically available SNMP Agent at **demo.snmplabs.com**:
.. literalinclude:: /../../examples/v3arch/asyncore/oneliner/manager/cmdgen/get-v1.py
:start-after: """#
:language: python
:download:`Download</../../examples/v3arch/asyncore/oneliner/manager/cmdgen/get-v1.py>` script.
If everything works as it should you will get:
.. code-block:: python
...
SNMPv2-MIB::sysDescr."0" = SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m
>>>
on your console.
Send SNMP TRAP
--------------
To send a trivial TRAP message to your local Notification Receiver
just cut&paste the following code into your interactive Python session:
.. literalinclude:: /../../examples/v3arch/asyncore/oneliner/agent/ntforg/trap-v2c-with-mib-lookup.py
:start-after: """#
:language: python
:download:`Download</../../examples/v3arch/asyncore/oneliner/agent/ntforg/trap-v2c-with-mib-lookup.py>` script.
For more sophisticated examples and uses cases please refer to the examples
and documentation pages.

313
docs/source/snmp-overview.rst 100644
View File

@ -0,0 +1,313 @@
.. toctree::
:maxdepth: 2
SNMP overview
=============
As networks become more complex, in terms of device population, topology
and distances, it has been getting more and more important for network
administrators to have some easy and convenient way for controlling all
pieces of the whole network.
Basic features of a network management system include device information
retrieval and device remote control. Former often takes shape of gathering
device operation statistics, while latter can be seen in device remote
configuration facilities.
For any information to be exchanged between entities, some agreement on
information format and transmission procedure needs to be settled
beforehand. This is what is conventionally called a Protocol.
Large networks nowdays, may host thousands of different devices. To benefit
network manager's interoperability and simplicity, any device on the
network should carry out most common and important management operations in
a well known, unified way. Therefore, an important feature of a network
management system would be a Convention on management information naming
and presentation.
Sometimes, management operations should be performed on large number of
managed devices. For a network manager to complete such a management round
in a reasonably short period of time, an important feature of a network
management software would be Performance.
Some of network devices may run on severely limited resources what invokes
another property of a proper network management facility: Low resource
consumption.
In practice, the latter requirement translates into low CPU cycles and
memory footprint for management software aboard device being managed.
As networking becomes a more crucial part of our daily lives, security
issues have become more apparent. As a side note, even Internet
technologies, having military roots, did not pay much attention to security
initially. So, the last key feature of network management appears to be
Security.
Data passed back and forth through the course of management operations
should be at least authentic and sometimes hidden from possible observers.
All these problems were approached many times through about three decades
of networking history. Some solutions collapsed over time for one reason or
another, while others, such as Simple Network Management Protocol (SNMP),
evolve into an industry standard.
SNMP management architecture
----------------------------
The SNMP management model includes three distinct entities -- Agent,
Manager and Proxy talking to each other over network.
Agent entity is basically a software running somewhere in a networked
device and having the following distinguishing properties:
* SNMP protocol support
* Access to managed device's internals
The latter feature is a source of management information for Agent, as well
as a target for remote control operations.
Modern SNMP standards suggest splitting Agent functionality on two parts.
Such Agents may run SNMP for local processes called Subagents, which
interface with managed devices internals. Communication between Master
Agent and its Subagents is performed using a simplified version of original
SNMP protocol, known as AgentX, which is designed to run only within a
single host.
Manager entity is usually an application used by humans (or daemons) for
performing various network management tasks, such as device statistics
retrieval or remote control.
Sometimes, Agents and Managers may run peer-to-peer within a single entity
that is called Proxy. Proxies can often be seen in application-level
firewalling or may serve as SNMP protocol translators between otherwise
SNMP version-incompatible Managers and Agents.
For Manager to request Agent for an operation on a particular part of
managed device, some convention on device's components naming is needed.
Once some components are identified, Manager and Agent would have to agree
upon possible components' states and their semantics.
SNMP approach to both problems is to represent each component of a device
as a named object, similar to named variables seen in programming
languages, and state of a component maps to a value associated with this
imaginary variable. These are called Managed Objects in SNMP.
For representing a group of similar components of a device, such as network
interfaces, Managed Objects can be organized into a so-called conceptual
table.
Manager talks to Agent by sending it messages of several types. Message
type implies certain action to be taken. For example, GET message instructs
Agent to report back values of Managed Objects whose names are indicated in
message.
There's also a way for Agent to notify Manager of an event occurred to
Agent. This is done through so-called Trap messages. Trap message also
carries Managed Objects and possibly Values, but besides that it has an ID
of event in form of integer number or a Managed Object.
For naming Managed Objects, SNMP uses the concept of Object Identifier. As
an example of Managed Object,
.iso.org.dod.internet.mgmt.mib-2.system.sysName.0 represents human-readable
name of a device where Agent is running.
Managed Objects values are always instances of ASN.1 types (such as
Integer) or SNMP-specific subtypes (such as IpAddress). As in programming
languages, type has an effect of restricting possible set of states Managed
Object may ever enter.
Whenever SNMP entities talk to each other, they refer to Managed Objects
whose semantics (and value type) must be known in advance by both parties.
SNMP Agent may be seen as a primary source of information on Managed
Objects, as they are implemented by Agent. In this model, Manager should
have a map of Managed Objects contained within each Agent to talk to.
SNMP standard introduces a set of ASN.1 language constructs (such as ASN.1
subtypes and MACROs) which is called Structure of Management Information
(SMI). Collections of related Managed Objects described in terms of SMI
comprise Management Information Base (MIB) modules.
Commonly used Managed Objects form core MIBs that become part of SNMP
standard. The rest of MIBs are normally created by vendors who build SNMP
Agents into their products.
More often then not, Manager implementations could parse MIB files and use
Managed Objects information for names resolution, value type determination,
pretty printing and so on. This feature is known as MIB parser support.
The history of SNMP
-------------------
First SNMP version dates back to 1988 when a set of IETF RFC's were first
published (`RFC1065 <http://www.ietf.org/rfc/rfc1065.txt>`_ ,
`RFC1066 <http://www.ietf.org/rfc/rfc1066.txt>`_ ,
`RFC1067 <http://www.ietf.org/rfc/rfc1067.txt>`_ ).
These documents describe protocol operations (in terms of message syntax
and semantics), SMI and a few core MIBs. The first version appears to
be lightweight and easy to implement.
Although, its poor security became notorious over years *(Security?
Not My Problem!)*, because cleartext password used for authentication (AKA
Community String) is extremely easy to eavesdrop and replay, even after
almost 20 years, slightly refined standard (
`RFC1155 <http://www.ietf.org/rfc/rfc1155.txt>`_ ,
`RFC1157 <http://www.ietf.org/rfc/rfc1157.txt>`_ ,
`RFC1212 <http://www.ietf.org/rfc/rfc1212.txt>`_ )
still seems to be the most frequent encounter in modern SNMP devices.
In effort to fix security issues of SNMPv1 and to make protocol faster for
operations on large number of Managed Objects, SNMP Working Group at IETF
came up with SNMPv2. This new protocol offers bulk transfers of Managed
Objects information (by means of new, GETBULK message payload), improved
security and re-worked SMI. But its new party-based security system turned
out to be too complicated. In the end, security part of SNMPv2 has been
dropped in favor of community-based authentication system used in SNMPv1.
The result of this compromise is known as SNMPv2c (where "c" stands for
community) and is still widely supported without being a standard (
`RFC1902 <http://www.ietf.org/rfc/rfc1902.txt>`_,
`RFC1903 <http://www.ietf.org/rfc/rfc1903.txt>`_,
`RFC1904 <http://www.ietf.org/rfc/rfc1904.txt>`_,
`RFC1905 <http://www.ietf.org/rfc/rfc1905.txt>`_,
`RFC1906 <http://www.ietf.org/rfc/rfc1906.txt>`_,
`RFC1907 <http://www.ietf.org/rfc/rfc1907.txt>`_,
`RFC1908 <http://www.ietf.org/rfc/rfc1908.txt>`_ ).
The other compromise targeted at offering greater security than SNMPv1,
without falling into complexities of SNMPv2, has been attempted by
replacing SNMPv2 party-based security system with newly developed
user-based security model. This variant of protocol is known as SNMPv2u.
Although neither widely implemented nor standardized, User Based Security
Model (USM) of SNMPv2u got eventually adopted as one of possibly many
SNMPv3 security models.
As of this writing, SNMPv3 is current standard for SNMP. Although it's
based heavily on previous SNMP specifications, SNMPv3 offers many
innovations but also brings significant complexity. Additions to version 3
are mostly about protocol operations. SMI part of standard is inherited
intact from SNMPv2.
SNMPv3 system is designed as a framework that consists of a core, known as
Message and PDU Dispatcher, and several abstract subsystems: Message
Processing Subsystem (MP), responsible for SNMP message handling, Transport
Dispatcher, used for carrying over messages, and Security Subsystem, which
deals with message authentication and encryption issues. The framework
defines subsystems interfaces to let feature-specific modules to be plugged
into SNMPv3 core thus forming particular feature-set of SNMP system.
Typical use of this modularity feature could be seen in multiprotocol
systems -- legacy SNMP protocols are implemented as version-specific MP and
security modules. Native SNMPv3 functionality relies upon v3 message
processing and User-Based Security modules.
Besides highly detailed SNMP system specification, SNMPv3 standard also
defines a typical set of SNMP applications and their behavior. These
applications are Manager, Agent and Proxy (
`RFC3411 <http://www.ietf.org/rfc/rfc3411.txt>`_,
`RFC3412 <http://www.ietf.org/rfc/rfc3412.txt>`_,
`RFC3413 <http://www.ietf.org/rfc/rfc3413.txt>`_,
`RFC3414 <http://www.ietf.org/rfc/rfc3414.txt>`_,
`RFC3415 <http://www.ietf.org/rfc/rfc3415.txt>`_,
`RFC3416 <http://www.ietf.org/rfc/rfc3416.txt>`_,
`RFC3417 <http://www.ietf.org/rfc/rfc3417.txt>`_,
`RFC3418 <http://www.ietf.org/rfc/rfc3418.txt>`_ ).
PySNMP architecture
-------------------
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.