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.
Files changed (63) hide show
  1. snmpify-0.1.0/.gitignore +21 -0
  2. snmpify-0.1.0/CHANGELOG.md +165 -0
  3. snmpify-0.1.0/CODE_OF_CONDUCT.md +15 -0
  4. snmpify-0.1.0/COMPARISON.md +129 -0
  5. snmpify-0.1.0/CONTRIBUTING.md +38 -0
  6. snmpify-0.1.0/Cargo.lock +468 -0
  7. snmpify-0.1.0/Cargo.toml +78 -0
  8. snmpify-0.1.0/LICENSE +21 -0
  9. snmpify-0.1.0/PKG-INFO +103 -0
  10. snmpify-0.1.0/README.md +320 -0
  11. snmpify-0.1.0/ROADMAP.md +21 -0
  12. snmpify-0.1.0/SECURITY.md +18 -0
  13. snmpify-0.1.0/examples/codec_bench.rs +150 -0
  14. snmpify-0.1.0/examples/gen_builtin_mibs.rs +163 -0
  15. snmpify-0.1.0/examples/walk.rs +26 -0
  16. snmpify-0.1.0/pyproject.toml +44 -0
  17. snmpify-0.1.0/python/.gitignore +5 -0
  18. snmpify-0.1.0/python/Cargo.toml +19 -0
  19. snmpify-0.1.0/python/README.md +77 -0
  20. snmpify-0.1.0/python/requirements-ci.in +5 -0
  21. snmpify-0.1.0/python/requirements-ci.txt +48 -0
  22. snmpify-0.1.0/python/snmpify/__init__.py +41 -0
  23. snmpify-0.1.0/python/snmpify/_snmpify.pyi +166 -0
  24. snmpify-0.1.0/python/snmpify/_types.py +92 -0
  25. snmpify-0.1.0/python/snmpify/exceptions.py +37 -0
  26. snmpify-0.1.0/python/snmpify/py.typed +0 -0
  27. snmpify-0.1.0/python/src/lib.rs +1434 -0
  28. snmpify-0.1.0/python/tests/test_snmpify.py +288 -0
  29. snmpify-0.1.0/src/agent.rs +682 -0
  30. snmpify-0.1.0/src/agentx.rs +970 -0
  31. snmpify-0.1.0/src/ber.rs +518 -0
  32. snmpify-0.1.0/src/blocking.rs +353 -0
  33. snmpify-0.1.0/src/client.rs +1984 -0
  34. snmpify-0.1.0/src/engine/tests.rs +267 -0
  35. snmpify-0.1.0/src/engine.rs +489 -0
  36. snmpify-0.1.0/src/error.rs +151 -0
  37. snmpify-0.1.0/src/lib.rs +70 -0
  38. snmpify-0.1.0/src/mib/builtin.rs +40431 -0
  39. snmpify-0.1.0/src/mib/hint.rs +193 -0
  40. snmpify-0.1.0/src/mib/mod.rs +700 -0
  41. snmpify-0.1.0/src/mib/parse.rs +654 -0
  42. snmpify-0.1.0/src/mib/tests.rs +468 -0
  43. snmpify-0.1.0/src/notification.rs +370 -0
  44. snmpify-0.1.0/src/oid.rs +335 -0
  45. snmpify-0.1.0/src/pdu.rs +655 -0
  46. snmpify-0.1.0/src/tcp.rs +83 -0
  47. snmpify-0.1.0/src/usm/tests.rs +495 -0
  48. snmpify-0.1.0/src/usm.rs +769 -0
  49. snmpify-0.1.0/src/v3.rs +659 -0
  50. snmpify-0.1.0/src/value.rs +438 -0
  51. snmpify-0.1.0/src/view.rs +446 -0
  52. snmpify-0.1.0/tests/agent.rs +490 -0
  53. snmpify-0.1.0/tests/client_fake_agent.rs +587 -0
  54. snmpify-0.1.0/tests/decode_robustness.rs +177 -0
  55. snmpify-0.1.0/tests/netsnmp.rs +612 -0
  56. snmpify-0.1.0/tests/netsnmp_agent.rs +306 -0
  57. snmpify-0.1.0/tests/netsnmp_notifications.rs +225 -0
  58. snmpify-0.1.0/tests/notifications.rs +277 -0
  59. snmpify-0.1.0/tests/v3_fake_agent.rs +640 -0
  60. snmpify-0.1.0/tools/mibs/fetch.py +105 -0
  61. snmpify-0.1.0/tools/snmpd/Dockerfile +20 -0
  62. snmpify-0.1.0/tools/snmpd/snmpd.conf +83 -0
  63. snmpify-0.1.0/tools/snmpd/snmptrapd.conf +9 -0
@@ -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.