diff options
Diffstat (limited to 'docs/source')
33 files changed, 1592 insertions, 0 deletions
diff --git a/docs/source/.static/css/rtdimproved.css b/docs/source/.static/css/rtdimproved.css new file mode 100644 index 0000000..981f84e --- /dev/null +++ b/docs/source/.static/css/rtdimproved.css @@ -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; +} diff --git a/docs/source/.templates/analytics.html b/docs/source/.templates/analytics.html new file mode 100644 index 0000000..72b6a40 --- /dev/null +++ b/docs/source/.templates/analytics.html @@ -0,0 +1,10 @@ +<script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-34689015-5', 'auto'); + ga('send', 'pageview'); + +</script> diff --git a/docs/source/.templates/bottom.html b/docs/source/.templates/bottom.html new file mode 100644 index 0000000..377e758 --- /dev/null +++ b/docs/source/.templates/bottom.html @@ -0,0 +1,10 @@ +<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script> +<!-- _pysmi bottom --> +<ins class="adsbygoogle" + style="display:block" + data-ad-client="ca-pub-9731411670727851" + data-ad-slot="5936755463" + data-ad-format="auto"></ins> +<script> +(adsbygoogle = window.adsbygoogle || []).push({}); +</script> diff --git a/docs/source/.templates/layout.html b/docs/source/.templates/layout.html new file mode 100644 index 0000000..0f25e0e --- /dev/null +++ b/docs/source/.templates/layout.html @@ -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> + + </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> diff --git a/docs/source/.templates/top.html b/docs/source/.templates/top.html new file mode 100644 index 0000000..384b5b6 --- /dev/null +++ b/docs/source/.templates/top.html @@ -0,0 +1,11 @@ +<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script> +<!-- _pysmi top --> +<ins class="adsbygoogle" + style="display:block" + data-ad-client="ca-pub-9731411670727851" + data-ad-slot="7553089460" + data-ad-format="auto"></ins> +<script> +(adsbygoogle = window.adsbygoogle || []).push({}); +</script> +<hr/> diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 0000000..b67b1a6 --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1,6 @@ + +Changelog +========= + +.. include:: ../../CHANGES.txt + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..ecabef1 --- /dev/null +++ b/docs/source/conf.py @@ -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 diff --git a/docs/source/contents.rst b/docs/source/contents.rst new file mode 100644 index 0000000..e17fcc4 --- /dev/null +++ b/docs/source/contents.rst @@ -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 diff --git a/docs/source/development.rst b/docs/source/development.rst new file mode 100644 index 0000000..abe9cba --- /dev/null +++ b/docs/source/development.rst @@ -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. + diff --git a/docs/source/docs/contents.rst b/docs/source/docs/contents.rst new file mode 100644 index 0000000..12568a9 --- /dev/null +++ b/docs/source/docs/contents.rst @@ -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 + diff --git a/docs/source/docs/smi/contents.rst b/docs/source/docs/smi/contents.rst new file mode 100644 index 0000000..0e2ee9f --- /dev/null +++ b/docs/source/docs/smi/contents.rst @@ -0,0 +1,20 @@ + +Oneliner MIB lookup service +=========================== + +PySNMP MIB architecture +======================= + +MIB types and objects +--------------------- + +MIB Builder +----------- + +MIB View Controller +------------------- + +MIB Instrumentation Controller +------------------------------ + + diff --git a/docs/source/docs/smi/mib-notification-types.rst b/docs/source/docs/smi/mib-notification-types.rst new file mode 100644 index 0000000..118c615 --- /dev/null +++ b/docs/source/docs/smi/mib-notification-types.rst @@ -0,0 +1,14 @@ + +MIB notification types +====================== + +ASN.1 macro definition -- NOTIFICATION-TYPE conveys 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: diff --git a/docs/source/docs/smi/mib-variables.rst b/docs/source/docs/smi/mib-variables.rst new file mode 100644 index 0000000..3d6cb4a --- /dev/null +++ b/docs/source/docs/smi/mib-variables.rst @@ -0,0 +1,19 @@ + +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: diff --git a/docs/source/docs/v1arch/asyncore/contents.rst b/docs/source/docs/v1arch/asyncore/contents.rst new file mode 100644 index 0000000..e803a1d --- /dev/null +++ b/docs/source/docs/v1arch/asyncore/contents.rst @@ -0,0 +1,3 @@ +Packet-level SNMP with Asyncore +=============================== + diff --git a/docs/source/docs/v3arch/asyncore/contents.rst b/docs/source/docs/v3arch/asyncore/contents.rst new file mode 100644 index 0000000..b385865 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/contents.rst @@ -0,0 +1,2 @@ +Standard SNMP Apps with Asyncore +================================ diff --git a/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/contents.rst b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/contents.rst new file mode 100644 index 0000000..80966d7 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/contents.rst @@ -0,0 +1,12 @@ + +Synchronous Notification Originator +=================================== + +Functions dscribed in this section return generators that perform +blocking SNMP queries. See :RFC:`3413#section-3.2` for more information +on the Notification Originator Applications. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/agent/ntforg/notification diff --git a/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/notification.rst b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/notification.rst new file mode 100644 index 0000000..b6061ad --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/notification.rst @@ -0,0 +1,8 @@ + +Notification Originator +======================= + +.. toctree:: + :maxdepth: 2 + +.. autofunction:: pysnmp.entity.rfc3413.oneliner.ntforg.sendNotification diff --git a/docs/source/docs/v3arch/asyncore/oneliner/contents.rst b/docs/source/docs/v3arch/asyncore/oneliner/contents.rst new file mode 100644 index 0000000..5bd2df3 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/contents.rst @@ -0,0 +1,95 @@ + +High-level SNMP +=============== + +There are a handful of most basic SNMP Applications defined by RFC3413 and +called Standard Applications. Those implementing Manager side of the system +(:RFC:`3411#section-3.1.3.1`) are Command Generator (initiating GET, SET, +GETNEXT, GETBULK operations) and Notification Receiver (handling arrived +notifications). On Agent side (:RFC:`3411#section-3.1.3.2`) there are +Command Responder (handling GET, SET, GETNEXT, GETBULK operations) and +Notification Originator (issuing TRAP and INFORM notifications). In +PySNMP Standard Applications are implemented on top of SNMPv3 framework. + +There're two kinds of high-level programming interfaces to Standard SNMP +Applications: synchronous and asynchronous. They are similar in terms of +call signatures but differ in behaviour. Synchronous calls block the whole +application till requested operation is finished. Asynchronous interface +breaks its synchronous version apart - at first required data are prepared +and put on the outgoing queue. The the application is free to deal with +other tasks till pending message is sent out (by I/O dispacher) and +response is arrived. At that point a previously supplied callback function +will be invoked and response data will be passed along. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/manager/cmdgen/contents + /docs/v3arch/asyncore/oneliner/agent/ntforg/contents + +The asynchronous version is best suited for massively parallel SNMP +messaging possibly handling other I/O activities in the same time. The +synchronous version is advised to employ for singular and blocking +operations as well as for rapid prototyping. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/manager/cmdgen/async.rst + /docs/v3arch/asyncore/oneliner/agent/ntforg/async.rst + +SNMP security configuration is conveyed to SNMP engine via +:py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityName` +and :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` +classes: + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/security-configuration + +Type of network transport SNMP engine uses along with transport +options is summarized by +:py:class:`~pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget` +and +:py:class:`~pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget` +container classes: + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/transport-configuration + +SNMP engine may serve several instances of the same MIB within +possibly multiple SNMP entities. SNMP context is a method to +unambiguously identify a collection of MIB variables behind +SNMP engine. +See :RFC:`3411#section-3.3.1` for details. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/snmp-context + +MIB variables represent a collection of managed objects, +residing in MIBs. Command Generator applications refer +to MIB variables and their values using +:py:class:`~pysnmp.smi.rfc1902.ObjectType` and +:py:class:`~pysnmp.smi.rfc1902.ObjectIdentity` classes. + +.. toctree:: + :maxdepth: 2 + + /docs/smi/mib-variables + +SNMP Notifications are enumerated and imply including certain +set of MIB variables. +Notification Originator applications refer to MIBs for MIB notifications +that are represented by +:py:class:`~pysnmp.smi.rfc1902.NotificationType` class instances. + +.. toctree:: + :maxdepth: 2 + + /docs/smi/mib-notification-types + diff --git a/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/bulkcmd.rst b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/bulkcmd.rst new file mode 100644 index 0000000..5882ca3 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/bulkcmd.rst @@ -0,0 +1,8 @@ + +GETBULK Command Generator +========================= + +.. toctree:: + :maxdepth: 2 + +.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.bulkCmd diff --git a/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/contents.rst b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/contents.rst new file mode 100644 index 0000000..a72c8da --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/contents.rst @@ -0,0 +1,15 @@ + +Synchronous Command Generator +============================= + +Functions dscribed in this section return generators that perform +blocking SNMP queries. See :RFC:`3413#section-3.1` for more information +on the Command Generator Applications. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/manager/cmdgen/getcmd + /docs/v3arch/asyncore/oneliner/manager/cmdgen/setcmd + /docs/v3arch/asyncore/oneliner/manager/cmdgen/nextcmd + /docs/v3arch/asyncore/oneliner/manager/cmdgen/bulkcmd diff --git a/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/getcmd.rst b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/getcmd.rst new file mode 100644 index 0000000..cf97515 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/getcmd.rst @@ -0,0 +1,8 @@ + +GET Command Generator +===================== + +.. toctree:: + :maxdepth: 2 + +.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.getCmd diff --git a/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/nextcmd.rst b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/nextcmd.rst new file mode 100644 index 0000000..626ff48 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/nextcmd.rst @@ -0,0 +1,8 @@ + +GETNEXT Command Generator +========================= + +.. toctree:: + :maxdepth: 2 + +.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.nextCmd diff --git a/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/setcmd.rst b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/setcmd.rst new file mode 100644 index 0000000..e458c9f --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/manager/cmdgen/setcmd.rst @@ -0,0 +1,8 @@ + +SET Command Generator +===================== + +.. toctree:: + :maxdepth: 2 + +.. autofunction:: pysnmp.entity.rfc3413.oneliner.cmdgen.setCmd diff --git a/docs/source/docs/v3arch/asyncore/oneliner/security-configuration.rst b/docs/source/docs/v3arch/asyncore/oneliner/security-configuration.rst new file mode 100644 index 0000000..86bee25 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/security-configuration.rst @@ -0,0 +1,39 @@ + +Security Parameters +=================== + +Calls to oneliner 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. + +Security Parameters object is Security Model specific. +:py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` class +serves SNMPv3 User-Based Security Model configuration, while +:py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData` +class is used for Community-Based Security Model of SNMPv1/SNMPv2c. + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.auth.CommunityData(communityIndex, communityName=None, mpModel=1, contextEngineId=None, contextName='', tag='') + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.auth.UsmUserData(userName, authKey=None, privKey=None, authProtocol=usmNoAuthProtocol, privProtocol=usmNoPrivProtocol, securityEngineId=None) + +Identification of Authentication and Privacy Protocols is done +via constant OIDs: + +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmNoAuthProtocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmHMACMD5AuthProtocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmHMACSHAAuthProtocol + +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmNoPrivProtocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmDESPrivProtocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usm3DESEDEPrivProtocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmAesCfb128Protocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmAesCfb192Protocol +.. autodata:: pysnmp.entity.rfc3413.oneliner.auth.usmAesCfb256Protocol + + diff --git a/docs/source/docs/v3arch/asyncore/oneliner/snmp-context.rst b/docs/source/docs/v3arch/asyncore/oneliner/snmp-context.rst new file mode 100644 index 0000000..04fb5f1 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/snmp-context.rst @@ -0,0 +1,23 @@ + +SNMP Context +============ + +Calls to oneliner Applications API consume SNMP Context +configuration object on input. The shortcut class described in +this section convey this MIB instance identification information +to SNMP PDU for further communication to peer SNMP engine +(:RFC:`3411#section-4.1`). + +.. note:: + + SNMP context is only defined within SNMPv3 framework. For SNMPv1/v2c + architecture integration :RFC:`2576#section-5.1` introduces + interoperability aid which is available through + :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData`. + + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.ctx.ContextData + diff --git a/docs/source/docs/v3arch/asyncore/oneliner/transport-configuration.rst b/docs/source/docs/v3arch/asyncore/oneliner/transport-configuration.rst new file mode 100644 index 0000000..3aff429 --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/transport-configuration.rst @@ -0,0 +1,25 @@ + +Transport configuration +======================= + +Calls to oneliner Applications API consume Transport configuration +object on input. 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. + +Transport configuration is specific to Transport domain - +:py:class:`~pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget` +class represents remote network endpoint of a UDP-over-IPv4 transport, +whereas +:py:class:`~pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget` +is specific to UDP-over-IPv6 communication. + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget + diff --git a/docs/source/docs/v3arch/asynio/contents.rst b/docs/source/docs/v3arch/asynio/contents.rst new file mode 100644 index 0000000..4a416e0 --- /dev/null +++ b/docs/source/docs/v3arch/asynio/contents.rst @@ -0,0 +1,2 @@ +Standard SNMP Apps with Asyncio +=============================== diff --git a/docs/source/docs/v3arch/trollius/contents.rst b/docs/source/docs/v3arch/trollius/contents.rst new file mode 100644 index 0000000..a7e650b --- /dev/null +++ b/docs/source/docs/v3arch/trollius/contents.rst @@ -0,0 +1,2 @@ +Standard SNMP Apps with Trollius +================================ diff --git a/docs/source/docs/v3arch/twisted/contents.rst b/docs/source/docs/v3arch/twisted/contents.rst new file mode 100644 index 0000000..885aac3 --- /dev/null +++ b/docs/source/docs/v3arch/twisted/contents.rst @@ -0,0 +1,2 @@ +Standard SNMP Apps with Twisted +=============================== diff --git a/docs/source/download.rst b/docs/source/download.rst new file mode 100644 index 0000000..44dd72a --- /dev/null +++ b/docs/source/download.rst @@ -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. + + diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 0000000..18ce967 --- /dev/null +++ b/docs/source/faq.rst @@ -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/* + diff --git a/docs/source/quick-start.rst b/docs/source/quick-start.rst new file mode 100644 index 0000000..8bcf6bb --- /dev/null +++ b/docs/source/quick-start.rst @@ -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. + + + + diff --git a/docs/source/snmp-overview.rst b/docs/source/snmp-overview.rst new file mode 100644 index 0000000..b532f66 --- /dev/null +++ b/docs/source/snmp-overview.rst @@ -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. |