Skip to main content

Crate netconf_async

Crate netconf_async 

Source
Expand description

§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

MethodOperation
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_sessionsession control
raw_rpccaller-supplied XML
create_subscription<create-subscription> (RFC 5277); session stays usable
recv_notification / drain_notificationspull buffered or next <notification>
notificationsubscribe + 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

FeatureDefaultPurpose
sshyesSshTransport over russh (implies tokio)
tokioyesTokio framer, RPC timeouts, notification streams

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

Re-exports§

pub use connection::Connection;
pub use error::NetconfClientError;
pub use error::NetconfClientResult;
pub use message::Datastore;
pub use message::Filter;
pub use message::RpcReply;
pub use transport::Transport;
pub use transport::ssh::HostKeyPolicy;ssh
pub use transport::ssh::JumpPool;ssh
pub use transport::ssh::JumpSession;ssh
pub use transport::ssh::SshAuth;ssh
pub use transport::ssh::SshConfig;ssh
pub use transport::ssh::SshJump;ssh
pub use transport::ssh::SshSessionOpts;ssh
pub use transport::ssh::SshTransport;ssh

Modules§

connection
NETCONF session: hello exchange, typed RPCs, and teardown.
error
Error type and Result alias for the client.
framer
NETCONF 1.0 end-of-message and 1.1 chunked framing (RFC6242).
message
NETCONF messages: <hello>, <rpc>, <rpc-reply>, and operation bodies.
transport
Byte transport under the framer (SSH today).

Constants§

CANDIDATE_CAP
:candidate:1.0 capability (RFC6241 8.3).
CONFIRMED_COMMIT_10_CAP
:confirmed-commit:1.0 capability (RFC6241 8.4).
CONFIRMED_COMMIT_CAP
:confirmed-commit:1.1 capability (RFC6241 8.4).
DEFAULT_NETCONF_SSH_PORT
Default NETCONF-over-SSH port (RFC6242).
INTERLEAVE_CAP
:interleave:1.0 capability — RPCs on a session with an active subscription (RFC5277).
NETCONF_BASE_10_CAP
:base:1.0 capability (RFC6241).
NETCONF_BASE_11_CAP
:base:1.1 capability; advertised by the server when chunked framing is supported (RFC6242).
NETCONF_URN
XML namespace for NETCONF 1.0 messages (RFC6241).
NOTIFICATION_CAP
:notification:1.0 capability (RFC5277).
ROLLBACK_ON_ERROR_CAP
:rollback-on-error:1.0 capability (RFC6241 8.5).
STARTUP_CAP
:startup:1.0 capability (RFC6241 8.7).
URL_CAP
:url:1.0 capability (RFC6241 8.8).
VALIDATE_10_CAP
:validate:1.0 capability (RFC6241 8.6).
VALIDATE_CAP
:validate:1.1 capability (RFC6241 8.6).
WITH_DEFAULTS_CAP
:with-defaults:1.0 capability (RFC6243).
WRITABLE_RUNNING_CAP
:writable-running:1.0 capability (RFC6241 8.2).