snmpify 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- snmpify-0.1.0/.gitignore +21 -0
- snmpify-0.1.0/CHANGELOG.md +165 -0
- snmpify-0.1.0/CODE_OF_CONDUCT.md +15 -0
- snmpify-0.1.0/COMPARISON.md +129 -0
- snmpify-0.1.0/CONTRIBUTING.md +38 -0
- snmpify-0.1.0/Cargo.lock +468 -0
- snmpify-0.1.0/Cargo.toml +78 -0
- snmpify-0.1.0/LICENSE +21 -0
- snmpify-0.1.0/PKG-INFO +103 -0
- snmpify-0.1.0/README.md +320 -0
- snmpify-0.1.0/ROADMAP.md +21 -0
- snmpify-0.1.0/SECURITY.md +18 -0
- snmpify-0.1.0/examples/codec_bench.rs +150 -0
- snmpify-0.1.0/examples/gen_builtin_mibs.rs +163 -0
- snmpify-0.1.0/examples/walk.rs +26 -0
- snmpify-0.1.0/pyproject.toml +44 -0
- snmpify-0.1.0/python/.gitignore +5 -0
- snmpify-0.1.0/python/Cargo.toml +19 -0
- snmpify-0.1.0/python/README.md +77 -0
- snmpify-0.1.0/python/requirements-ci.in +5 -0
- snmpify-0.1.0/python/requirements-ci.txt +48 -0
- snmpify-0.1.0/python/snmpify/__init__.py +41 -0
- snmpify-0.1.0/python/snmpify/_snmpify.pyi +166 -0
- snmpify-0.1.0/python/snmpify/_types.py +92 -0
- snmpify-0.1.0/python/snmpify/exceptions.py +37 -0
- snmpify-0.1.0/python/snmpify/py.typed +0 -0
- snmpify-0.1.0/python/src/lib.rs +1434 -0
- snmpify-0.1.0/python/tests/test_snmpify.py +288 -0
- snmpify-0.1.0/src/agent.rs +682 -0
- snmpify-0.1.0/src/agentx.rs +970 -0
- snmpify-0.1.0/src/ber.rs +518 -0
- snmpify-0.1.0/src/blocking.rs +353 -0
- snmpify-0.1.0/src/client.rs +1984 -0
- snmpify-0.1.0/src/engine/tests.rs +267 -0
- snmpify-0.1.0/src/engine.rs +489 -0
- snmpify-0.1.0/src/error.rs +151 -0
- snmpify-0.1.0/src/lib.rs +70 -0
- snmpify-0.1.0/src/mib/builtin.rs +40431 -0
- snmpify-0.1.0/src/mib/hint.rs +193 -0
- snmpify-0.1.0/src/mib/mod.rs +700 -0
- snmpify-0.1.0/src/mib/parse.rs +654 -0
- snmpify-0.1.0/src/mib/tests.rs +468 -0
- snmpify-0.1.0/src/notification.rs +370 -0
- snmpify-0.1.0/src/oid.rs +335 -0
- snmpify-0.1.0/src/pdu.rs +655 -0
- snmpify-0.1.0/src/tcp.rs +83 -0
- snmpify-0.1.0/src/usm/tests.rs +495 -0
- snmpify-0.1.0/src/usm.rs +769 -0
- snmpify-0.1.0/src/v3.rs +659 -0
- snmpify-0.1.0/src/value.rs +438 -0
- snmpify-0.1.0/src/view.rs +446 -0
- snmpify-0.1.0/tests/agent.rs +490 -0
- snmpify-0.1.0/tests/client_fake_agent.rs +587 -0
- snmpify-0.1.0/tests/decode_robustness.rs +177 -0
- snmpify-0.1.0/tests/netsnmp.rs +612 -0
- snmpify-0.1.0/tests/netsnmp_agent.rs +306 -0
- snmpify-0.1.0/tests/netsnmp_notifications.rs +225 -0
- snmpify-0.1.0/tests/notifications.rs +277 -0
- snmpify-0.1.0/tests/v3_fake_agent.rs +640 -0
- snmpify-0.1.0/tools/mibs/fetch.py +105 -0
- snmpify-0.1.0/tools/snmpd/Dockerfile +20 -0
- snmpify-0.1.0/tools/snmpd/snmpd.conf +83 -0
- snmpify-0.1.0/tools/snmpd/snmptrapd.conf +9 -0
snmpify-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Generated by Cargo
|
|
2
|
+
# will have compiled files and executables
|
|
3
|
+
debug/
|
|
4
|
+
target/
|
|
5
|
+
|
|
6
|
+
# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
|
|
7
|
+
# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
|
|
8
|
+
Cargo.lock
|
|
9
|
+
|
|
10
|
+
# These are backup files generated by rustfmt
|
|
11
|
+
**/*.rs.bk
|
|
12
|
+
|
|
13
|
+
# MSVC Windows builds of rustc generate these, which store debugging information
|
|
14
|
+
*.pdb
|
|
15
|
+
|
|
16
|
+
# RustRover
|
|
17
|
+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
|
|
18
|
+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
|
|
19
|
+
# and can be added to the global gitignore or merged into this file. For a more nuclear
|
|
20
|
+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
|
|
21
|
+
#.idea/
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.2.0 — 2026-11-22
|
|
4
|
+
|
|
5
|
+
### Performance
|
|
6
|
+
- The client reads its socket from the waiting request (no receive task;
|
|
7
|
+
no hand-off when nobody else waits), with one shared deadline sleep per
|
|
8
|
+
socket instead of a timer per request, header-only answer matching,
|
|
9
|
+
answers decoded where they lie, connected sockets for single-agent
|
|
10
|
+
clients, and an atomic in-flight counter. Decoding sizes vectors once and
|
|
11
|
+
parses one-byte OID arcs directly. A walk of 200 000 objects: 67 → 43 ms
|
|
12
|
+
CPU (in place), 47 ms (owned); now level with snmp2 and ahead of
|
|
13
|
+
net-snmp's C library.
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
- SNMPv3 privacy `PrivProtocol::Des3`: CBC-3DES-EDE
|
|
17
|
+
(draft-reeder-snmpv3-usm-3desede-00), checked against pysnmp's keys
|
|
18
|
+
and traps (`"3DES"` in Python and C).
|
|
19
|
+
- Benchmarks for every operation: GetNext, GetBulk, Set, traps and
|
|
20
|
+
informs, in all compared libraries.
|
|
21
|
+
- `snmpify::view`: zero-copy views (`VarBindRef`, `ValueRef`, `OidRef`,
|
|
22
|
+
`Varbinds`, `community_pdu`) and `Client::walk_with`, a walk handing
|
|
23
|
+
each binding over in place.
|
|
24
|
+
- SNMP over TCP (RFC 3430): `Client::connect_tcp` (no retransmissions;
|
|
25
|
+
a closed connection fails pending requests with `Error::Io`),
|
|
26
|
+
`Agent::run_tcp`, `blocking::Client::connect_tcp`, Python
|
|
27
|
+
`Client(..., tcp=True)`, C `snmpify_client_new_tcp` /
|
|
28
|
+
`snmpify_client_new_v3_tcp`. Tested against snmpd over TCP and with
|
|
29
|
+
net-snmp's snmpget / snmpbulkwalk against the agent over TCP.
|
|
30
|
+
- SNMPv3 privacy `PrivProtocol::Aes192Cisco` / `Aes256Cisco`: AES-192/256
|
|
31
|
+
with Cisco's key extension (draft-reeder; net-snmp's `AES-192-C`,
|
|
32
|
+
pysnmp's `usmAesCfb192Protocol`). Checked against pysnmp's keys and with
|
|
33
|
+
traps pysnmp encrypts that way. Python and C accept `"AES-192-C"`,
|
|
34
|
+
`"AES-256-C"`.
|
|
35
|
+
- Benchmarks (`benchmarks/`): snmpify (Rust and Python) against snmp2,
|
|
36
|
+
async-snmp, csnmp, net-snmp's C library, pysnmp and ezsnmp: walks
|
|
37
|
+
(v2c and v3), GetRequest latency, mass polling, CPU and memory, with
|
|
38
|
+
the programs and `run.py` to reproduce them.
|
|
39
|
+
- Python: `snmpify.Manager` (many agents over one socket; `client()` /
|
|
40
|
+
`blocking_client()`).
|
|
41
|
+
- `Manager::with_max_in_flight` and `client::DEFAULT_MAX_IN_FLIGHT` (64).
|
|
42
|
+
- C and C++ API (`capi/`, `libsnmpify`): `include/snmpify.h` (clients
|
|
43
|
+
v1/v2c/v3, get / get-next / get-bulk / set / walks, traps and informs,
|
|
44
|
+
notification receiver, agent with values and callbacks, MIBs) and the
|
|
45
|
+
header-only C++17 `include/snmpify.hpp` (RAII, exceptions). CMake
|
|
46
|
+
package and pkg-config file (Linux, macOS, Windows), shared and static
|
|
47
|
+
libraries, examples (`get.c`, `walk.cpp`, `trapd.c`). Tested with C and
|
|
48
|
+
C++ programs (CTest on Linux, macOS and Windows; against net-snmp on
|
|
49
|
+
Linux; clean under ASan/UBSan/LSan); prebuilt archives on `c-v*` tags.
|
|
50
|
+
- Python bindings (`python/`, PyPI `snmpify`, PyO3, abi3 wheels for
|
|
51
|
+
Python 3.9+ on Linux, macOS and Windows): `Client` (blocking, GIL
|
|
52
|
+
released) and `AsyncClient` (asyncio) with get / get_many / get_next /
|
|
53
|
+
get_bulk / set / walk / trap / inform, v1, v2c and v3 (`UsmUser`);
|
|
54
|
+
values typed (`Counter32`, `Gauge32`, `TimeTicks`, `Counter64`,
|
|
55
|
+
`IpAddress`, `ObjectId`, `Opaque` keep their SNMP type through
|
|
56
|
+
Python); exceptions (`SnmpTimeout`, `AgentError`, `ReportError`,
|
|
57
|
+
`InvalidArgument`); `NotificationReceiver` (blocking, async
|
|
58
|
+
iteration); `Agent` with fixed, writable and callback values; `Mib`.
|
|
59
|
+
Type stubs. Tested against an in-process agent and net-snmp's snmpd in
|
|
60
|
+
CI; wheels are built and published on `py-v*` tags.
|
|
61
|
+
- `snmpify::blocking`: `Client` (with `Walk` as an iterator),
|
|
62
|
+
`NotificationReceiver`, `RunningAgent`, on a shared runtime.
|
|
63
|
+
- MIBs (`snmpify::mib`): a tolerant SMIv1/SMIv2 parser (OBJECT-TYPE,
|
|
64
|
+
OBJECT-IDENTITY, MODULE-IDENTITY, NOTIFICATION-TYPE, TRAP-TYPE, groups,
|
|
65
|
+
compliances, textual conventions, imports, modules in any order);
|
|
66
|
+
`Mib::standard()` with 55 standard modules built in as a table of
|
|
67
|
+
facts (names, OIDs, kinds, types, access, enumerations, display hints:
|
|
68
|
+
no module text), generated by `examples/gen_builtin_mibs.rs` from the
|
|
69
|
+
RFCs, IANA registries and net-snmp MIBs (`tools/mibs/fetch.py`);
|
|
70
|
+
`resolve` / `name` / `lookup` / `object`, and `format` with enum labels,
|
|
71
|
+
named bits and RFC 2579 display hints (`format_octets`,
|
|
72
|
+
`format_integer`). Checked by walking all of snmpd: every object it
|
|
73
|
+
serves has a name.
|
|
74
|
+
- Agent (`snmpify::agent`): `Agent` answers Get, GetNext, GetBulk and Set
|
|
75
|
+
over SNMPv1, v2c and v3 from `MibHandler`s registered under subtrees
|
|
76
|
+
(deepest registration wins); `MibTree` holds fixed, writable and
|
|
77
|
+
computed values and the MIB-II system group. Two-phase sets, v1 error
|
|
78
|
+
mapping and Counter64 skipping (RFC 3584), tooBig and GetBulk
|
|
79
|
+
truncation by message size, read-only / read-write communities, per
|
|
80
|
+
user access and minimum level (authorizationError below it), unknown
|
|
81
|
+
contexts reported.
|
|
82
|
+
- AgentX subagent (`snmpify::agentx`, RFC 2741): the same handlers under
|
|
83
|
+
a master agent (TCP or Unix socket): Open, Register, Get, GetNext,
|
|
84
|
+
GetBulk, TestSet/CommitSet/UndoSet/CleanupSet, Notify, both byte
|
|
85
|
+
orders.
|
|
86
|
+
- Tests: the client against the agent in every version; net-snmp's
|
|
87
|
+
snmpget/snmpbulkwalk/snmpset against the agent (v2c and v3 authPriv);
|
|
88
|
+
snmpify as an AgentX subagent of snmpd (get, walk, set, notify).
|
|
89
|
+
- Notifications (`snmpify::notification`): `NotificationReceiver` takes
|
|
90
|
+
traps (v1, v2c, v3) and informs (v2c, v3, acknowledged), filtered by
|
|
91
|
+
community and SNMPv3 user, and hands them over in SNMPv2 form
|
|
92
|
+
(`Notification`: trap OID, uptime, bindings; v1 traps translated as in
|
|
93
|
+
RFC 3584). Sending: `Client::trap`, `Client::inform` (waits for the
|
|
94
|
+
acknowledgement, retries) and `Client::trap_v1`; `Usm::with_engine_id`
|
|
95
|
+
sets the engine id of SNMPv3 traps.
|
|
96
|
+
- `snmpify::engine::LocalEngine`: the authoritative side of USM (RFC 3414
|
|
97
|
+
§3.2): engine discovery reports, unknown user / wrong digest /
|
|
98
|
+
decryption / security level / time window reports, usmStats
|
|
99
|
+
counters, traps from other engines with replay protection, responses
|
|
100
|
+
at the request's level. `LocalizedUser::seal_with_level`.
|
|
101
|
+
- Tests against net-snmp both ways: snmpify → snmptrapd and snmptrap /
|
|
102
|
+
snmpinform → snmpify, v1, v2c and v3; the robustness test also feeds
|
|
103
|
+
the engine.
|
|
104
|
+
|
|
105
|
+
### Fixed
|
|
106
|
+
- Mass polling: requests in flight per socket are capped (64 by default).
|
|
107
|
+
1000 agents answering at once overflowed the socket's receive buffer;
|
|
108
|
+
the dropped answers were retried a timeout later (1000 agents: 2 s,
|
|
109
|
+
now 9 ms).
|
|
110
|
+
|
|
111
|
+
## 0.1.0 — 2026-11-22
|
|
112
|
+
|
|
113
|
+
First code: the SNMP wire format and an async v1/v2c/v3 client.
|
|
114
|
+
|
|
115
|
+
### Added
|
|
116
|
+
- SNMPv3 with the User-based Security Model.
|
|
117
|
+
- `snmpify::v3` (always available): `V3Message`, `UsmParams`,
|
|
118
|
+
`ScopedPdu`, `Message` (any version), `ReportKind` (usmStats and
|
|
119
|
+
snmpMPDStats reports).
|
|
120
|
+
- `snmpify::usm` (feature `v3`, on with `client`): `UsmUser` (master
|
|
121
|
+
keys hashed once from the passwords), `LocalizedUser::seal` / `open`.
|
|
122
|
+
Authentication HMAC-MD5-96, HMAC-SHA-96, HMAC-SHA-224/256/384/512
|
|
123
|
+
(RFC 3414, 7860); privacy DES, AES-128, AES-192/256 (RFC 3414, 3826,
|
|
124
|
+
the Blumenthal key extension as in net-snmp). Constant-time MAC check;
|
|
125
|
+
keys never in `Debug`.
|
|
126
|
+
- The client takes a `UsmUser` (or `Usm` with a context) wherever it
|
|
127
|
+
took a `Community`. Engine discovery once per agent for all clones,
|
|
128
|
+
time synchronisation and resync on notInTimeWindow, rediscovery when
|
|
129
|
+
the engine id changes. Answers are accepted only at the request's
|
|
130
|
+
security level, for its engine, within the time window: forged,
|
|
131
|
+
replayed, downgraded and altered answers are ignored. Reports become
|
|
132
|
+
`Error::Report`.
|
|
133
|
+
- Tested: RFC 3414 key vectors, HMAC/AES/DES known answers, every
|
|
134
|
+
protocol combination sealed and opened, tampering, a scripted v3 agent
|
|
135
|
+
(discovery, resync, reboot, engine change, forged answers, contexts,
|
|
136
|
+
40 agents over one socket), the robustness test and the fuzz target
|
|
137
|
+
on v3 input, and all 31 combinations against net-snmp's snmpd.
|
|
138
|
+
- `examples/codec_bench.rs` times seal/open per protocol and key
|
|
139
|
+
derivation.
|
|
140
|
+
- CI: tests with `--no-default-features` (wire format only) and
|
|
141
|
+
`--features v3`; a coverage job (cargo-llvm-cov with the snmpd tests,
|
|
142
|
+
summary in the run, lcov as an artifact).
|
|
143
|
+
- Minimum supported Rust version 1.85 (tokio needs it), checked in CI.
|
|
144
|
+
- `client` (feature `client`, on by default; tokio): `Client` with `get`,
|
|
145
|
+
`get_one`, `get_next`, `get_bulk`, `set`, `walk` (GetBulk in v2c, GetNext
|
|
146
|
+
in v1, stops at the end of the subtree, fails instead of looping on an
|
|
147
|
+
agent whose OIDs do not increase), `walk_all` and raw `request`;
|
|
148
|
+
`Manager`: many clients over one UDP socket and receive task, responses
|
|
149
|
+
matched by request id, source address, version and community;
|
|
150
|
+
retransmission (`Options`: timeout, retries, max-repetitions);
|
|
151
|
+
cancellation-safe. Tested against a scripted agent (loss, timeouts,
|
|
152
|
+
spoofed/stray/garbage answers, 500 concurrent requests, broken walks) and
|
|
153
|
+
against net-snmp. `examples/walk.rs`.
|
|
154
|
+
- BER codec (`snmpify::ber`): zero-copy `Reader`, back-to-front `Writer`
|
|
155
|
+
(nested values are never copied to prepend their length), definite
|
|
156
|
+
lengths only, strict about malformed input.
|
|
157
|
+
- `Oid`: up to 15 arcs inline without allocation, parsing, display,
|
|
158
|
+
MIB-tree ordering, `starts_with`, `child`.
|
|
159
|
+
- `Value`: every SMIv2 type and the v2 exceptions; `VarBind`.
|
|
160
|
+
- Every PDU (Get, GetNext, GetBulk, Set, Response, Inform, TrapV2, Report,
|
|
161
|
+
v1 Trap), `ErrorStatus`, and `CommunityMessage` (SNMPv1 and v2c).
|
|
162
|
+
- Tests: unit tests with known encodings, a robustness test on 70 000
|
|
163
|
+
random and mutated messages, a cargo-fuzz target, and interoperability
|
|
164
|
+
tests against net-snmp's snmpd (Get/GetNext/GetBulk/Set, v1 and v2c,
|
|
165
|
+
a full walk of the agent).
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Code of conduct
|
|
2
|
+
|
|
3
|
+
This project adopts the
|
|
4
|
+
[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
|
|
5
|
+
|
|
6
|
+
In short: be respectful and constructive, assume good intent, and keep
|
|
7
|
+
discussion about the work. Harassment, insults and personal attacks are not
|
|
8
|
+
accepted in issues, pull requests or any other project space.
|
|
9
|
+
|
|
10
|
+
## Reporting
|
|
11
|
+
|
|
12
|
+
Report unacceptable behavior privately to the maintainer through
|
|
13
|
+
[GitHub](https://github.com/sameteraslan). Reports are handled confidentially.
|
|
14
|
+
Maintainers may remove comments, close threads or block participants who
|
|
15
|
+
break these rules.
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# snmpify compared with other SNMP libraries
|
|
2
|
+
|
|
3
|
+
Every SNMP function, library by library, and what each costs. The
|
|
4
|
+
features come from each library's source code (the versions in
|
|
5
|
+
[benchmarks/results.md](benchmarks/results.md)). The numbers come from
|
|
6
|
+
[benchmarks/](benchmarks/README.md): every client against the same local
|
|
7
|
+
agent, medians of 5 runs.
|
|
8
|
+
|
|
9
|
+
✓ = supported, — = not supported.
|
|
10
|
+
|
|
11
|
+
## Functions
|
|
12
|
+
|
|
13
|
+
| | **snmpify** | async-snmp | snmp2 | csnmp | net-snmp (C) | pysnmp | ezsnmp |
|
|
14
|
+
|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|
|
15
|
+
| Language | Rust, Python, C, C++ | Rust | Rust | Rust | C | Python | Python (net-snmp) |
|
|
16
|
+
| **Requests** | | | | | | | |
|
|
17
|
+
| Get | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
18
|
+
| GetNext | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
19
|
+
| GetBulk | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
20
|
+
| Set | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
21
|
+
| Walk (GetNext / GetBulk) | ✓ | ✓ | — | ✓ | applications only¹ | ✓ | ✓ |
|
|
22
|
+
| Walk decoded in place (zero-copy) | ✓ | — | lazy decoding, no walk | — | — | — | — |
|
|
23
|
+
| **Notifications** | | | | | | | |
|
|
24
|
+
| Send SNMPv1 traps | ✓ | ✓ | — | — | ✓ | ✓ | `snmptrap` wrapper² |
|
|
25
|
+
| Send v2c / v3 traps | ✓ | ✓ | — | v2c | ✓ | ✓ | `snmptrap` wrapper² |
|
|
26
|
+
| Send informs (acknowledged) | ✓ | ✓ | — | v2c | ✓ | ✓ | `snmptrap` wrapper² |
|
|
27
|
+
| Receive traps and informs | ✓ | ✓ | parse only | — | ✓ (snmptrapd) | ✓ | — |
|
|
28
|
+
| **Agent** | | | | | | | |
|
|
29
|
+
| Agent (command responder) | ✓ | ✓ | — | — | ✓ (snmpd) | ✓ | — |
|
|
30
|
+
| Access control | per community / user, read or read-write | VACM | — | — | VACM | VACM | — |
|
|
31
|
+
| AgentX subagent (RFC 2741) | ✓ (TCP, Unix socket) | — | — | — | ✓ | — | — |
|
|
32
|
+
| AgentX master | — | — | — | — | ✓ | — | — |
|
|
33
|
+
| **Versions and security** | | | | | | | |
|
|
34
|
+
| SNMPv1 / v2c | ✓ | ✓ | ✓ | v2c | ✓ | ✓ | ✓ |
|
|
35
|
+
| SNMPv3 (USM, engine discovery) | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ |
|
|
36
|
+
| Authentication: MD5, SHA-1, SHA-224/256/384/512 | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ |
|
|
37
|
+
| Privacy: DES, AES-128 | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ |
|
|
38
|
+
| Privacy: AES-192/256 (Blumenthal) | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ |
|
|
39
|
+
| Privacy: AES-192/256, Cisco's key extension (Reeder) | ✓ | ✓ | ✓ | — | build option | ✓ | as net-snmp |
|
|
40
|
+
| Privacy: 3DES-EDE | ✓ | ✓ | — | — | — | ✓ | — |
|
|
41
|
+
| TLS / DTLS (RFC 6353) | — | — | — | — | build option | — | — |
|
|
42
|
+
| **Transports** | | | | | | | |
|
|
43
|
+
| UDP over IPv4 and IPv6 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
44
|
+
| TCP (RFC 3430) | ✓ (client and agent) | ✓ | — | — | ✓ | — in the high-level API | ✓ |
|
|
45
|
+
| Many agents over one socket | ✓ | ✓ | — | — | — (a socket per session) | ✓ | — |
|
|
46
|
+
| **APIs** | | | | | | | |
|
|
47
|
+
| Async | ✓ (tokio; Python asyncio) | ✓ (tokio) | ✓ (tokio) | ✓ (tokio) | callbacks | ✓ (asyncio) | — |
|
|
48
|
+
| Blocking | ✓ (Rust, Python, C) | example wrapper | ✓ | — | ✓ | — | ✓ |
|
|
49
|
+
| Timeouts and retries | ✓ | ✓ | timeout (blocking API) | ✓ | ✓ | ✓ | ✓ |
|
|
50
|
+
| MIB names and files | ✓ (built-in modules, MIB parser) | ✓ (mib-rs) | via libnetsnmp | — | ✓ | ✓ (pysmi) | ✓ |
|
|
51
|
+
| Memory-safe | ✓ (no `unsafe`) | ✓ | ✓ | ✓ | — | ✓ | — (C underneath) |
|
|
52
|
+
|
|
53
|
+
1. net-snmp's library has no walk call; its `snmpwalk` and
|
|
54
|
+
`snmpbulkwalk` applications loop over GetNext or GetBulk.
|
|
55
|
+
2. ezsnmp's `Session` has no notification API. `ezsnmp.netsnmp.snmptrap`
|
|
56
|
+
runs net-snmp's `snmptrap` command inside the process, taking
|
|
57
|
+
command-line arguments and opening a new session on every call.
|
|
58
|
+
|
|
59
|
+
## What each function costs
|
|
60
|
+
|
|
61
|
+
**CPU time of the work (startup subtracted); lower is better**
|
|
62
|
+
|
|
63
|
+
| | snmpify | async-snmp | snmp2 | csnmp | net-snmp (C) | snmpify (Python) | pysnmp (Python) | ezsnmp (Python) |
|
|
64
|
+
|---|---:|---:|---:|---:|---:|---:|---:|---:|
|
|
65
|
+
| Walk, 200 000 objects (v2c) | **42 ms** | 85 ms | 48 ms | 348 ms | 50 ms | **177 ms** | 18284 ms | 2303 ms |
|
|
66
|
+
| Walk over SNMPv3 (SHA, AES-128) | 74 ms | 117 ms | **72 ms** | — | 110 ms | **192 ms** | 20825 ms | 2458 ms |
|
|
67
|
+
| 5000 Get | 27 ms | 35 ms | 23 ms | 41 ms | **20 ms** | **49 ms** | 1782 ms | 101 ms |
|
|
68
|
+
| 2000 GetNext | 13 ms | 19 ms | **10 ms** | 23 ms | ≤ 10 ms | **24 ms** | 729 ms | 41 ms |
|
|
69
|
+
| 2000 GetBulk × 50 rows | 17 ms | 25 ms | **13 ms** | 125 ms | ≤ 10 ms | **53 ms** | 8295 ms | 210 ms |
|
|
70
|
+
| 2000 Set | 13 ms | 20 ms | **12 ms** | 25 ms | ≤ 10 ms | **25 ms** | 791 ms | 46 ms |
|
|
71
|
+
| 2000 traps sent | **7 ms** | **7 ms** | — | 17 ms | ≤ 10 ms | **14 ms** | 534 ms | 222 ms |
|
|
72
|
+
| 2000 informs (acknowledged) | **15 ms** | 21 ms | — | 33 ms | ≤ 10 ms | **27 ms** | 1373 ms | 246 ms |
|
|
73
|
+
| 1000 agents polled at once | **9 ms** | 32 ms | 85 ms | 26 ms | ≤ 10 ms | **61 ms** | 1454 ms | 167 ms |
|
|
74
|
+
|
|
75
|
+
**Wall-clock time; lower is better**
|
|
76
|
+
|
|
77
|
+
| | snmpify | async-snmp | snmp2 | csnmp | net-snmp (C) | snmpify (Python) | pysnmp (Python) | ezsnmp (Python) |
|
|
78
|
+
|---|---:|---:|---:|---:|---:|---:|---:|---:|
|
|
79
|
+
| Walk, 200 000 objects (v2c) | **140 ms** | 185 ms | 141 ms | 457 ms | 158 ms | **275 ms** | 19794 ms | 2444 ms |
|
|
80
|
+
| Walk over SNMPv3 (SHA, AES-128) | 193 ms | 237 ms | **190 ms** | — | 238 ms | **324 ms** | 22474 ms | 2653 ms |
|
|
81
|
+
| 5000 Get | 46 ms | 55 ms | **44 ms** | 61 ms | 47 ms | **60 ms** | 2252 ms | 125 ms |
|
|
82
|
+
| 2000 GetNext | 22 ms | 30 ms | 21 ms | 31 ms | **19 ms** | **29 ms** | 908 ms | 51 ms |
|
|
83
|
+
| 2000 GetBulk × 50 rows | 58 ms | 65 ms | **52 ms** | 169 ms | 59 ms | **84 ms** | 8728 ms | 257 ms |
|
|
84
|
+
| 2000 Set | 23 ms | 31 ms | 22 ms | 33 ms | **20 ms** | **27 ms** | 987 ms | 57 ms |
|
|
85
|
+
| 2000 traps sent | 7 ms | 8 ms | — | 16 ms | **6 ms** | **8 ms** | 535 ms | 224 ms |
|
|
86
|
+
| 2000 informs (acknowledged) | 24 ms | 30 ms | — | 41 ms | **21 ms** | **30 ms** | 1591 ms | 268 ms |
|
|
87
|
+
| 1000 agents polled at once | **9 ms** | 4023 ms | 85 ms | 24 ms | 12 ms | **29 ms** | 4275 ms | 176 ms |
|
|
88
|
+
|
|
89
|
+
**Latency per request, median (p50)**
|
|
90
|
+
|
|
91
|
+
| | snmpify | async-snmp | snmp2 | csnmp | net-snmp (C) | snmpify (Python) | pysnmp (Python) | ezsnmp (Python) |
|
|
92
|
+
|---|---:|---:|---:|---:|---:|---:|---:|---:|
|
|
93
|
+
| 5000 Get | 8 µs | 10 µs | 8 µs | 10 µs | 9 µs | 10 µs | 431 µs | 24 µs |
|
|
94
|
+
| 2000 GetNext | 8 µs | 11 µs | 8 µs | 11 µs | 9 µs | 11 µs | 433 µs | 24 µs |
|
|
95
|
+
| 2000 GetBulk × 50 rows | 24 µs | 28 µs | 23 µs | 75 µs | 28 µs | 39 µs | 4304 µs | 117 µs |
|
|
96
|
+
| 2000 Set | 8 µs | 11 µs | 9 µs | 12 µs | 10 µs | 11 µs | 464 µs | 26 µs |
|
|
97
|
+
| 2000 traps sent | 2 µs | 3 µs | — | 6 µs | 3 µs | 3 µs | 256 µs | 106 µs |
|
|
98
|
+
| 2000 informs (acknowledged) | 8 µs | 11 µs | — | 16 µs | 10 µs | 12 µs | 741 µs | 118 µs |
|
|
99
|
+
|
|
100
|
+
Bold: the lowest among the Rust and C libraries, and among the Python
|
|
101
|
+
ones. net-snmp runs in a container whose `time` measures CPU only to
|
|
102
|
+
10 ms: its small CPU figures read "≤ 10 ms" and are not ranked. snmpify's walk
|
|
103
|
+
reads the answers in place (`Client::walk_with`); with owned values
|
|
104
|
+
(`walk_all`) it uses 54 ms (v2c) and 72 ms (v3). snmp2 has no
|
|
105
|
+
notification API, and ezsnmp sends notifications only through its
|
|
106
|
+
`snmptrap` command wrapper. Full tables, with p99 latencies and memory:
|
|
107
|
+
[benchmarks/results.md](benchmarks/results.md).
|
|
108
|
+
|
|
109
|
+
## Summary
|
|
110
|
+
|
|
111
|
+
- **Functions**: net-snmp is the reference, with everything (including
|
|
112
|
+
an AgentX master and TLS) but none of the memory safety. Among the
|
|
113
|
+
memory-safe libraries, snmpify and async-snmp cover the most: every
|
|
114
|
+
request, sending and receiving notifications, an agent, all SNMPv3
|
|
115
|
+
protocols and TCP. On top of that, snmpify has an AgentX subagent,
|
|
116
|
+
Python and C/C++ bindings, a zero-copy walk and mass polling over one
|
|
117
|
+
socket. async-snmp has full VACM. pysnmp is the most complete in
|
|
118
|
+
Python. snmp2 is a client without walks or notifications. csnmp is a
|
|
119
|
+
v2c-only client. ezsnmp is a client over net-snmp.
|
|
120
|
+
- **Speed**: snmpify, snmp2 and net-snmp are close for single requests
|
|
121
|
+
(8–10 µs, mostly the kernel's UDP work). snmpify and snmp2 walk with
|
|
122
|
+
the least CPU, ahead of net-snmp. snmpify polls 1000 agents in 9 ms
|
|
123
|
+
(snmp2 85 ms, async-snmp 4 s). async-snmp uses about 40% more CPU
|
|
124
|
+
than snmpify per request and twice as much per walk (the same for
|
|
125
|
+
traps). csnmp is the slowest Rust client for bulk data.
|
|
126
|
+
- **Python**: snmpify's package is the fastest in every operation. It is
|
|
127
|
+
2–9 times faster than ezsnmp for requests and walks (28 times for
|
|
128
|
+
traps, which ezsnmp sends through a command wrapper), and 40–100 times
|
|
129
|
+
faster than pysnmp.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Contributing to snmpify
|
|
2
|
+
|
|
3
|
+
Bug reports, interoperability reports and pull requests are welcome.
|
|
4
|
+
|
|
5
|
+
## Reporting a bug
|
|
6
|
+
|
|
7
|
+
Open an [issue](https://github.com/snmp-rs/snmpify/issues/new/choose) with
|
|
8
|
+
the smallest code that shows the problem and the agent involved (vendor,
|
|
9
|
+
model, firmware). For decoding problems, the packet bytes in hex (from
|
|
10
|
+
Wireshark or `tcpdump -X`) are the most useful thing you can send.
|
|
11
|
+
|
|
12
|
+
## Pull requests
|
|
13
|
+
|
|
14
|
+
`main` is protected: every change goes through a pull request from a fork,
|
|
15
|
+
and the CI checks must pass before it is merged.
|
|
16
|
+
|
|
17
|
+
1. Fork the repository and create a branch.
|
|
18
|
+
2. Make the change, with a test for it.
|
|
19
|
+
3. Run:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
cargo fmt --all
|
|
23
|
+
cargo clippy --all-targets -- -D warnings
|
|
24
|
+
cargo test
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
4. For anything that goes on the wire, also run the tests against net-snmp:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
docker build -t snmpify-snmpd tools/snmpd
|
|
31
|
+
docker run -d --rm --name snmpify-snmpd -p 127.0.0.1:1161:161/udp snmpify-snmpd
|
|
32
|
+
SNMPIFY_AGENT=127.0.0.1:1161 cargo test --test netsnmp
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
and, for decoder changes, fuzz for a while:
|
|
36
|
+
`cargo +nightly fuzz run decode_message`.
|
|
37
|
+
5. Add a line to `CHANGELOG.md` for user-visible changes, and open the
|
|
38
|
+
pull request.
|