netconf-async 0.1.0

Async NETCONF client (RFC 6241) over SSH
Documentation

netconf-async

Async NETCONF client for Rust.

crates.io docs.rs License: MIT

Talk to routers and switches over SSH using the netconf subsystem. The crate handles the <hello> exchange, base 1.0 / 1.1 framing, and typed RPCs.

Install

[dependencies]
netconf-async = "0.1"

Requires rustc 1.85+ (edition 2024).

Default features pull in Tokio and SSH (russh, pure Rust).

Example

use netconf_async::{Connection, Datastore, Filter, HostKeyPolicy, SshAuth, SshConfig, SshTransport};

#[tokio::main]
async fn main() -> netconf_async::NetconfClientResult<()> {
    let transport = SshTransport::connect(
        SshConfig::new("192.0.2.10", 830, "netconf", SshAuth::password("secret"))
            .host_key(HostKeyPolicy::Fingerprint("SHA256:base64fingerprint".into())),
    ).await?;
    let mut conn = Connection::new(transport).await?;

    let running = conn.get_config(Datastore::Running, None, None).await?;
    println!("{running}");

    let filter = Filter::subtree(
        r#"<system xmlns="urn:ietf:params:xml:ns:yang:ietf-system"/>"#,
    );
    let filtered = conn.get(Some(filter), None).await?;
    println!("{filtered}");

    conn.close_session().await?;
    Ok(())
}

[Connection::new] performs the <hello> exchange and upgrades the framer when the server advertises [NETCONF_BASE_11_CAP]. Call [Connection::close_session] when you are done: a clean shutdown has to await I/O, which [Drop] cannot do, so dropping an open session only logs a warning.

[SshTransport::connect] takes [SshAuth] (password, agent, or key file) and an optional ProxyJump chain. Host-key policy defaults to [HostKeyPolicy::RejectAll]; pin a fingerprint with [HostKeyPolicy::Fingerprint] or an OpenSSH file with [HostKeyPolicy::KnownHosts] / [HostKeyPolicy::AcceptNew]. Share a [JumpPool] when many devices use the same hops.

A custom byte pipe implements [Transport] and is passed to [Connection::new] the same way.

Session flow

  1. SSH connect, request subsystem netconf.
  2. Exchange <hello> with 1.0 framing (]]>]]>).
  3. If the server advertises :base:1.1, call transport.upgrade() → chunked framing (\n#N\n...\n##\n, RFC 6242).
  4. Each RPC is write then loop receive. A <notification> is buffered and the wait continues. The reply is parsed as [RpcReply]; the message-id must match when present (a missing id is accepted). Error-severity <rpc-error> becomes [NetconfClientError::Netconf]. Warning-only replies succeed unless [Connection::set_warnings_as_errors]. EOF after <commit> is [NetconfClientError::CommitUnknown].
  5. [Connection::close_session] ends the session and tears the transport down.

[Connection::set_parse_replies] (false) returns the device's XML untouched and stops <rpc-error> from becoming an error. [Connection::set_timeout] bounds a single RPC; a timed-out session is marked unusable, because a late reply would be read as the answer to the next request.

Default NETCONF-over-SSH port is 830.

RPCs

Method Operation
get <get>
get_config <get-config>
edit_config <edit-config>
copy_config <copy-config>
delete_config <delete-config>
lock / unlock <lock> / <unlock>
validate <validate>
commit / confirmed_commit / confirm_commit / cancel_commit <commit> family
discard_changes <discard-changes>
close_session / kill_session session control
raw_rpc caller-supplied XML
create_subscription <create-subscription> (RFC 5277); session stays usable
recv_notification / drain_notifications pull buffered or next <notification>
notification subscribe + exclusive listen loop (holds &mut self)

Subtree filters and with-defaults (RFC 6243) are supported on get / get-config. has_capability reflects the server <hello> (query string ignored).

Filter and <config> payloads reach the device byte for byte; everything the crate generates around them stays XML-escaped. [RpcReply::errors] exposes each <rpc-error>, including vendor tags outside RFC 6241.

Logging

The crate uses the log facade.

  • warn / error: host-key policy, dropped session, unknown SSH algorithms
  • debug: ProxyJump hops, transport teardown
  • trace: full <hello> / RPC XML, framer writes, ssh-agent identity probes

Wire dumps are trace, not debug. RUST_LOG=netconf_async=debug is session diagnostics; RUST_LOG=netconf_async=trace is the wire.

Crate features

Feature Default Purpose
ssh yes SshTransport over russh (implies tokio)
tokio yes Tokio framer, RPC timeouts, notification streams

Related

A CLI that fans these operations out to one or more hosts lives in the same repository: netconf-cli.