netconf-async
Async NETCONF client for Rust.
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
[]
= "0.1"
Requires rustc 1.85+ (edition 2024).
Default features pull in Tokio and SSH (russh, pure Rust).
Example
use ;
async
[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
- SSH connect, request subsystem
netconf. - Exchange
<hello>with 1.0 framing (]]>]]>). - If the server advertises
:base:1.1, calltransport.upgrade()→ chunked framing (\n#N\n...\n##\n, RFC 6242). - Each RPC is write then loop receive. A
<notification>is buffered and the wait continues. The reply is parsed as [RpcReply]; themessage-idmust 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]. - [
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 algorithmsdebug: ProxyJump hops, transport teardowntrace: 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.