Expand description
§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
[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
- 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 asRpcReply; themessage-idmust match when present (a missing id is accepted). Error-severity<rpc-error>becomesNetconfClientError::Netconf. Warning-only replies succeed unlessConnection::set_warnings_as_errors. EOF after<commit>isNetconfClientError::CommitUnknown. Connection::close_sessionends 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.
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;sshpub use transport::ssh::JumpPool;sshpub use transport::ssh::JumpSession;sshpub use transport::ssh::SshAuth;sshpub use transport::ssh::SshConfig;sshpub use transport::ssh::SshJump;sshpub use transport::ssh::SshSessionOpts;sshpub use transport::ssh::SshTransport;ssh
Modules§
- connection
- NETCONF session: hello exchange, typed RPCs, and teardown.
- error
- Error type and
Resultalias 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.0capability (RFC6241 8.3).- CONFIRMED_
COMMIT_ 10_ CAP :confirmed-commit:1.0capability (RFC6241 8.4).- CONFIRMED_
COMMIT_ CAP :confirmed-commit:1.1capability (RFC6241 8.4).- DEFAULT_
NETCONF_ SSH_ PORT - Default NETCONF-over-SSH port (RFC6242).
- INTERLEAVE_
CAP :interleave:1.0capability — RPCs on a session with an active subscription (RFC5277).- NETCONF_
BASE_ 10_ CAP :base:1.0capability (RFC6241).- NETCONF_
BASE_ 11_ CAP :base:1.1capability; advertised by the server when chunked framing is supported (RFC6242).- NETCONF_
URN - XML namespace for NETCONF 1.0 messages (RFC6241).
- NOTIFICATION_
CAP :notification:1.0capability (RFC5277).- ROLLBACK_
ON_ ERROR_ CAP :rollback-on-error:1.0capability (RFC6241 8.5).- STARTUP_
CAP :startup:1.0capability (RFC6241 8.7).- URL_CAP
:url:1.0capability (RFC6241 8.8).- VALIDATE_
10_ CAP :validate:1.0capability (RFC6241 8.6).- VALIDATE_
CAP :validate:1.1capability (RFC6241 8.6).- WITH_
DEFAULTS_ CAP :with-defaults:1.0capability (RFC6243).- WRITABLE_
RUNNING_ CAP :writable-running:1.0capability (RFC6241 8.2).