1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
=======
Ez SNMP
=======
|Python Code Style| |Black| |Pull Request Sphinx Docs Check| |PyPI Distributions| |TestPyPI Distributions| |Tests| |License|
.. |Python Code Style| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
.. |Black| image:: https://github.com/carlkidcrypto/ezsnmp/actions/workflows/black.yml/badge.svg
:target: https://github.com/carlkidcrypto/ezsnmp/actions/workflows/black.yml
.. |Pull Request Sphinx Docs Check| image:: https://github.com/carlkidcrypto/ezsnmp/actions/workflows/sphinx_build.yml/badge.svg
:target: https://github.com/carlkidcrypto/ezsnmp/actions/workflows/sphinx_build.yml
.. |PyPI Distributions| image:: https://github.com/carlkidcrypto/ezsnmp/actions/workflows/build_and_publish_to_pypi.yml/badge.svg
:target: https://github.com/carlkidcrypto/ezsnmp/actions/workflows/build_and_publish_to_pypi.yml
.. |TestPyPI Distributions| image:: https://github.com/carlkidcrypto/ezsnmp/actions/workflows/build_and_publish_to_test_pypi.yml/badge.svg
:target: https://github.com/carlkidcrypto/ezsnmp/actions/workflows/build_and_publish_to_test_pypi.yml
.. |Tests| image:: https://github.com/carlkidcrypto/ezsnmp/actions/workflows/tests.yml/badge.svg
:target: https://github.com/carlkidcrypto/ezsnmp/actions/workflows/tests.yml
.. |License| image:: https://img.shields.io/badge/license-BSD-blue.svg
:target: https://github.com/carlkidcrypto/ezsnmp/blob/master/LICENSE
.. image:: https://github.com/carlkidcrypto/ezsnmp/blob/main/images/ezsnmp_logo.jpeg
:alt: Ez SNMP Logo
Introduction
------------
Ez SNMP is a fork of `Easy SNMP <http://net-snmp.sourceforge.net/wiki/index.php/Python_Bindings>`__
Why Another Library?
--------------------
- Simple, because the maintainer of `Easy SNMP` seems to have abandoned the project and or isn't actively working on it.
- This version (Ez SNMP) will attempt to remain up to date with Python versions that are supported by `Python <https://devguide.python.org/versions/>`__
and net-snmp versions that are supported by `Net-SNMP <http://www.net-snmp.org/download.html>`__
How to Support This Project?
----------------------------
.. image:: https://github.com/carlkidcrypto/ezsnmp/blob/main/images/buy_me_a_coffee.png
:alt: Buy Me A Coffee.
`Use this link to buy me a coffee! <https://www.buymeacoffee.com/carlkidcrypto>`__
Quick Start
-----------
There are primarily two ways you can use the Ez SNMP library:
1. By using a Session object which is most suitable
when you want to request multiple pieces of SNMP data from a
source:
.. code:: python
from ezsnmp import Session
# Create an SNMP session to be used for all our requests
session = Session(hostname='localhost', community='public', version=2)
# You may retrieve an individual OID using an SNMP GET
location = session.get('sysLocation.0')
# You may also specify the OID as a tuple (name, index)
# Note: the index is specified as a string as it can be of other types than
# just a regular integer
contact = session.get(('sysContact', '0'))
# And of course, you may use the numeric OID too
description = session.get('.1.3.6.1.2.1.1.1.0')
# Set a variable using an SNMP SET
session.set('sysLocation.0', 'The SNMP Lab')
# Perform an SNMP walk
system_items = session.walk('system')
# Each returned item can be used normally as its related type (str or int)
# but also has several extended attributes with SNMP-specific information
for item in system_items:
print '{oid}.{oid_index} {snmp_type} = {value}'.format(
oid=item.oid,
oid_index=item.oid_index,
snmp_type=item.snmp_type,
value=item.value
)
2. By using Ez SNMP via its simple interface which is intended
for one-off operations (where you wish to specify all details in the
request):
.. code:: python
from ezsnmp import snmp_get, snmp_set, snmp_walk
# Grab a single piece of information using an SNMP GET
snmp_get('sysDescr.0', hostname='localhost', community='public', version=1)
# Perform an SNMP SET to update data
snmp_set(
'sysLocation.0', 'My Cool Place',
hostname='localhost', community='public', version=1
)
# Perform an SNMP walk
snmp_walk('system', hostname='localhost', community='public', version=1)
Documentation
-------------
Please check out the `Ez SNMP documentation at <http://carlkidcrypto.github.io/ezsnmp/>`_. This includes installation
instructions for various operating systems.
You may generate the documentation as follows:
.. code:: bash
# Install Sphinx
# See this website for install instructions https://www.sphinx-doc.org/en/master/usage/installation.html
# Build the documentation into static HTML pages
cd sphinx_docs_build
make html
Acknowledgments
---------------
I'd like to say thanks to the following folks who have made this project
possible:
- **Giovanni Marzot**: the original author
- **ScienceLogic, LLC**: sponsored the initial development of this
module
- **Wes Hardaker and the net-snmp-coders**: for their hard work and
dedication
- **fgimian and nnathan**: the original contributors to this codebase
- **Kent Coble**: who was the most recent maintainer. `Easy SNMP <https://github.com/easysnmp/easysnmp>`_
Running Tests
-------------
Tests use `Pytest <https://github.com/pytest-dev/pytest>`_. You can run
them with the following on Linux:
.. code:: bash
git clone https://github.com/ezsnmp/ezsnmp.git;
cd ezsnmp;
sudo apt update && sudo apt upgrade -y;
sudo apt install -y snmp snmpd libsnmp-dev libperl-dev snmp-mibs-downloader valgrind;
sudo apt install -y python3-pip python3-dev python3-setuptools gdb -y;
sudo systemctl stop snmpd;
sudo mv /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.orig;
sudo cp tests/snmpd.conf /etc/snmp/snmpd.conf;
sudo download-mibs;
mkdir -p -m 0755 ~/.snmp;
echo 'mibs +ALL' > ~/.snmp/snmp.conf;
sudo systemctl start snmpd;
rm -drf build/ dist/ ezsnmp.egg-info;
python3 -m pip install -r requirements.txt;
python3 setup.py build && python3 -m pip install -e . && python3 -m pytest .;
# Bottom one for debug. Replace the top one with it if needed.
# python3 setup.py build && python3 -m pip install -e . && gdb -ex run -ex bt -ex quit --args python3 -m pytest .;
# Bottom one for valgrind. Replace the top one with it if needed.
# python3 setup.py build && python3 -m pip install -e . && valgrind --tool=memcheck --leak-check=full --show-leak-kinds=definite,indirect,possible python3 -m pytest .
# Bottom one for valgrind using helgrind. Replace the top one with it if needed.
# python3 setup.py build && python3 -m pip install -e . && valgrind --tool=helgrind --free-is-write=yes python3 -m pytest .
On MacOS
.. code:: bash
git clone https://github.com/ezsnmp/ezsnmp.git;
cd ezsnmp;
sudo mv /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.orig;
sudo cp tests/snmpd.conf /etc/snmp/snmpd.conf;
sudo launchctl unload /System/Library/LaunchDaemons/org.net-snmp.snmpd.plist;
sudo launchctl load -w /System/Library/LaunchDaemons/org.net-snmp.snmpd.plist;
rm -drf build/ dist/ ezsnmp.egg-info;
python3 setup.py build && python3 -m pip install -e . && python3 -m pytest .;
Running cibuildwheels
---------------------
For Linux builds on a Linux machine
.. code:: bash
clear && rm -drf wheelhouse/ build/ ezsnmp.egg-info/ && python3 -m cibuildwheel --output-dir wheelhouse --platform linux
For MacOS builds on a MacOS machine
.. code:: bash
clear && rm -drf wheelhouse/ build/ ezsnmp.egg-info/ && python3 -m cibuildwheel --output-dir wheelhouse --platform macos
License
-------
Ez SNMP is released under the **BSD** license. Please see the
`LICENSE <https://github.com/ezsnmp/ezsnmp/blob/master/LICENSE>`_
file for more details.
Copyright
---------
The original version of this library is copyright (c) 2006 G. S. Marzot.
All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Net-SNMP itself.
Copyright (c) 2006 SPARTA, Inc. All Rights Reserved. This program is
free software; you can redistribute it and/or modify it under the same
terms as Net-SNMP itself.
Copyright (c) 2024 carlkidcrypto All Rights Reserved. This program is
free software; you can redistribute it and/or modify it under the same
terms as Net-SNMP itself.
|
