async-snmp

An asynchronous SNMP library for Rust that uses Tokio.

Status

This crate is pre-1.0, so its API can change between releases. This README describes the main branch, which can differ from published crate versions. For version-specific API documentation, see async-snmp on docs.rs.

Supported operations

• SNMPv1, SNMPv2c, and SNMPv3 USM clients
• GET, GETNEXT, GETBULK, SET, WALK, and BULKWALK
• Trap and inform sending and receiving
• UDP, shared UDP, and TCP transports
• An optional SNMP agent with asynchronous handlers, two-phase SET processing, and View-based Access Control Model (VACM) support
• Optional MIB parsing, OID resolution, and value formatting through mib-rs
• Automatic tooBig recovery for GET and GETNEXT batches

GETBULK, BULKWALK, and informs require SNMPv2c or SNMPv3. SNMPv3 supports MD5, SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 authentication. It supports DES, 3DES, and AES-128/192/256 privacy. The available algorithms depend on the enabled cryptographic backend.

Installation

Install the published release:

cargo add async-snmp
cargo add tokio --features macros,rt

To use the API documented in this README, install the main branch:

cargo add async-snmp --git https://github.com/lukeod/async-snmp
cargo add tokio --features macros,rt

Example

use async_snmp::{Auth, Client, oid};

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder(("192.168.1.1", 161), Auth::v2c("public"))
        .connect()
        .await?;

    let response = client
        .get(&oid!(1, 3, 6, 1, 2, 1, 1, 1, 0))
        .await?;

    for varbind in response.varbinds {
        println!("{}: {:?}", varbind.oid, varbind.value);
    }

    Ok(())
}

get, get_next, and set preserve received bindings in varbinds and report response-shape issues in anomalies. Use single() when one unambiguous binding is required.

The repository contains these examples:

• basic client operations
• walking a subtree
• SNMPv3
• shared UDP transport
• TCP
• runtime transport selection
• a lightweight single-threaded runtime
• value extraction
• trap and inform sending and receiving
• an agent with writable objects
• calling the library from synchronous code
• MIB-backed queries, walks, and table index decoding

Command-line tools

The cli feature provides the asnmp-get, asnmp-walk, and asnmp-set commands:

cargo install --locked --git https://github.com/lukeod/async-snmp --features cli
asnmp-get -v 2c -c public 192.0.2.10 sysDescr.0
asnmp-walk -v 2c -c public 192.0.2.10 1.3.6.1.2.1.1
asnmp-set -v 2c -c private 192.0.2.10 sysLocation.0 s rack-7

Run each command with --help for its options.

Feature flags

SNMPv1, SNMPv2c, and SNMPv3 noAuthNoPriv work without a cryptographic backend. Cargo features are additive. When you enable both backends, RustCrypto is the default unless you select AWS-LC FIPS in the USM configuration.

Documentation

Docs.rs hosts API documentation for published versions. To build and open documentation for the main branch, run:

cargo doc --all-features --open

Minimum supported Rust version

Rust 1.88 or later is required.

License

You can use async-snmp under either the Apache License 2.0 or the MIT License.

Contributing

See the contribution guide.