README.md
1
2SNMP library for Python
3-----------------------
4[![PyPI](https://img.shields.io/pypi/v/pysnmp.svg?maxAge=2592000)](https://pypi.python.org/pypi/pysnmp)
5[![Python Versions](https://img.shields.io/pypi/pyversions/pysnmp.svg)](https://pypi.python.org/pypi/pysnmp/)
6[![Build status](https://travis-ci.org/etingof/pysnmp.svg?branch=master)](https://travis-ci.org/etingof/pysnmp)
7[![GitHub license](https://img.shields.io/badge/license-BSD-blue.svg)](https://raw.githubusercontent.com/etingof/pysnmp/master/LICENSE.rst)
8
9This is a pure-Python, open source and free implementation of v1/v2c/v3
10SNMP engine distributed under 2-clause [BSD license](http://snmplabs.com/pysnmp/license.html).
11
12The PySNMP project was initially sponsored by a [PSF](http://www.python.org/psf/) grant.
13Thank you!
14
15Features
16--------
17
18* Complete SNMPv1/v2c and SNMPv3 support
19* SMI framework for resolving MIB information and implementing SMI
20 Managed Objects
21* Complete SNMP entity implementation
22* USM Extended Security Options support (3DES, 192/256-bit AES encryption)
23* Extensible network transports framework (UDP/IPv4, UDP/IPv6)
24* Asynchronous socket-based IO API support
25* [Twisted](http://twistedmatrix.com), [Asyncio](https://docs.python.org/3/library/asyncio.html)
26 and [Trollius](http://trollius.readthedocs.org/index.html) integration
27* [PySMI](http://snmplabs.com/pysmi/) integration for dynamic MIB compilation
28* Built-in instrumentation exposing protocol engine operations
29* Python eggs and py2exe friendly
30* 100% Python, works with Python 2.4 though 3.7
31* MT-safe (if SnmpEngine is thread-local)
32
33Features, specific to SNMPv3 model include:
34
35* USM authentication (MD5/SHA-1/SHA-2) and privacy (DES/AES) protocols (RFC3414, RFC7860)
36* View-based access control to use with any SNMP model (RFC3415)
37* Built-in SNMP proxy PDU converter for building multi-lingual
38 SNMP entities (RFC2576)
39* Remote SNMP engine configuration
40* Optional SNMP engine discovery
41* Shipped with standard SNMP applications (RC3413)
42
43
44Download & Install
45------------------
46
47The PySNMP software is freely available for download from [PyPI](https://pypi.python.org/pypi/pysnmp)
48and [GitHub](https://github.com/etingof/pysnmp.git).
49
50Just run:
51
52```bash
53$ pip install pysnmp
54```
55
56to download and install PySNMP along with its dependencies:
57
58* [PyASN1](http://snmplabs.com/pyasn1/)
59* [PyCryptodomex](https://pycryptodome.readthedocs.io) (required only if SNMPv3 encryption is in use)
60* [PySMI](http://snmplabs.com/pysmi/) (required for MIB services only)
61
62Besides the library, command-line [SNMP utilities](https://github.com/etingof/snmpclitools)
63written in pure-Python could be installed via:
64
65```bash
66$ pip install snmpclitools
67```
68
69and used in the very similar manner as conventional Net-SNMP tools:
70
71```bash
72$ snmpget.py -v3 -l authPriv -u usr-md5-des -A authkey1 -X privkey1 demo.snmplabs.com sysDescr.0
73SNMPv2-MIB::sysDescr.0 = STRING: Linux zeus 4.8.6.5-smp #2 SMP Sun Nov 13 14:58:11 CDT 2016 i686
74```
75
76Examples
77--------
78
79PySNMP is designed in a layered fashion. Top-level and easiest to use API is known as
80*hlapi*. Here's a quick example on how to SNMP GET:
81
82```python
83from pysnmp.hlapi import *
84
85iterator = getCmd(SnmpEngine(),
86 CommunityData('public'),
87 UdpTransportTarget(('demo.snmplabs.com', 161)),
88 ContextData(),
89 ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0)))
90
91errorIndication, errorStatus, errorIndex, varBinds = next(iterator)
92
93if errorIndication: # SNMP engine errors
94 print(errorIndication)
95else:
96 if errorStatus: # SNMP agent errors
97 print('%s at %s' % (errorStatus.prettyPrint(), varBinds[int(errorIndex)-1] if errorIndex else '?'))
98 else:
99 for varBind in varBinds: # SNMP response contents
100 print(' = '.join([x.prettyPrint() for x in varBind]))
101```
102
103This is how to send SNMP TRAP:
104
105```python
106from pysnmp.hlapi import *
107
108errorIndication, errorStatus, errorIndex, varBinds = next(
109 sendNotification(
110 SnmpEngine(OctetString(hexValue='8000000001020304')),
111 UsmUserData('usr-sha-aes128', 'authkey1', 'privkey1',
112 authProtocol=usmHMACSHAAuthProtocol,
113 privProtocol=usmAesCfb128Protocol),
114 UdpTransportTarget(('demo.snmplabs.com', 162)),
115 ContextData(),
116 'trap',
117 NotificationType(ObjectIdentity('SNMPv2-MIB', 'authenticationFailure'))
118 )
119)
120
121if errorIndication:
122 print(errorIndication)
123```
124
125We maintain publicly available SNMP Agent and TRAP sink at
126[demo.snmplabs.com](http://snmplabs.com/snmpsim/public-snmp-agent-simulator.html). You are
127welcome to use it while experimenting with whatever SNMP software you deal with.
128
129```bash
130$ python3 examples/hlapi/asyncore/sync/manager/cmdgen/usm-sha-aes128.py
131SNMPv2-MIB::sysDescr.0 = SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m
132$
133$ python3 examples//hlapi/asyncore/sync/agent/ntforg/v3-inform.py
134SNMPv2-MIB::sysUpTime.0 = 0
135SNMPv2-MIB::snmpTrapOID.0 = SNMPv2-MIB::warmStart
136SNMPv2-MIB::sysName.0 = system name
137```
138
139Other than that, PySNMP is capable to automatically fetch and use required MIBs from HTTP, FTP sites
140or local directories. You could configure any MIB source available to you (including
141[this one](http://mibs.snmplabs.com/asn1/)) for that purpose.
142
143For more example scripts please refer to [examples section](http://snmplabs.com/pysnmp/examples/contents.html#high-level-snmp)
144at pysnmp web site.
145
146Documentation
147-------------
148
149Library documentation and examples can be found at the [pysnmp project site](http://snmplabs.com/pysnmp/).
150
151If something does not work as expected, please
152[open an issue](https://github.com/etingof/pysnmp/issues) at GitHub or
153post your question [on Stack Overflow](http://stackoverflow.com/questions/ask)
154or try browsing pysnmp
155[mailing list archives](https://sourceforge.net/p/pysnmp/mailman/pysnmp-users/).
156
157Bug reports and PRs are appreciated! ;-)
158
159Copyright (c) 2005-2019, [Ilya Etingof](mailto:etingof@gmail.com). All rights reserved.
160