Concepts
The layers
@node-net/netconf follows the four layers of RFC 6241: Network Configuration Protocol (NETCONF), and each layer only uses the one below it:
You'll usually work with NetconfClient, which sits on top of all of them and puts each call on the object for its layer e.g. client.ops.
| Layer | Function | On a connected client |
|---|---|---|
| Content | Configuration and state data | client.content: the YANG path API (read(), set(), configure()), and extensions' decoded readers |
| Operations | <get-config>, <edit-config>, <commit>, … | client.ops: getConfig() and friends, extensions' operations, and the device profile's own (device) |
| Messages | <hello>, <rpc>, <rpc-reply>, <notification> | client.session: message-ids, capabilities, raw RPCs, events |
| Transport | SSH or TLS, and framing | client.transport: the peer; ssh() and tls() open it |
So client.content.set() and client.ops.editConfig() say which level they work at. A call's layer is what you hand in and get back: raw XML, or an operation and its reply, is ops; paths, typed values and parsed objects are content. The layers below are there when you need them:
// from the server's <hello>
client.session.sessionId;
client.session.serverCapabilities.has(':candidate');
// any RPC, sent as is
await client.session.rpc('<get-chassis-inventory/>');Datastores
A datastore is a complete, named copy of a device's configuration. A NETCONF server can keep several, and every operation that reads or writes configuration names the one it works on: getConfig({ source: 'running' }), editConfig({ target: 'candidate' }), lock('startup').
Running, candidate and startup
RFC 6241 defines three, and the server's capabilities say which it has:
| Datastore | Capability | What it holds |
|---|---|---|
running | always there; writable with :writable-running | The configuration the device is using now |
candidate | :candidate | A scratch copy you edit without affecting the device. commit() makes it the running configuration, and discardChanges() puts it back to running |
startup | :startup | The configuration the device loads when it boots. Changes to running don't reach it until you copy them |
Most servers have either a candidate you commit, or a running datastore you write to directly, and some have both. With a separate startup, saving is a step of its own:
// make the running configuration survive a reboot
await client.ops.copyConfig({ source: 'running', target: 'startup' });Operations has each of these steps, and Transactions has withCandidate(), which locks, edits, validates and commits in the order RFC 6241 recommends. The path API chooses for you: client.content.set() and configure() edit the candidate and commit it when the server has :candidate, and write to running otherwise (see How changes are applied).
Configuration and state
A device also has state data: counters, operational status, learned routes, anything it reports rather than is told. State isn't in running, candidate or startup. getConfig() reads only configuration, from the datastore you name, while get() reads running's configuration together with the state.
NMDA: intended and operational
The Network Management Datastore Architecture (NMDA, RFC 8342) adds two read-only datastores that close that gap:
intendedis running after the device has applied its own processing, such as removing inactive configuration or expanding templates: the configuration it is trying to use.operationalis what the device is actually using, configuration and state together. Each node can be annotated with its origin: whether it came fromintended, was learned from a protocol, is adefault, and so on.
A server that supports NMDA can also have datastores beyond these five, such as factory-default. You read any of them with the nmda extension's getData(), and write the configuration datastores with its editData().
Which datastores and modules a device has
A device's datastores, and the YANG modules and features each one supports, can differ from what its <hello> shows. Under NMDA each datastore has a schema of its own: the configuration datastores always share one, but operational may differ. YANG 1.1 modules never appear in the hello at all, only in the server's YANG library (RFC 8525).
client.content.datastores() and client.content.modules() give you the full picture on any server, reading the YANG library where there is one and falling back to the hello where there isn't. See Device datastores and Device modules and features.
Client, session and device
- A
Sessionis the NETCONF session itself: the hello exchange, capabilities, numbering requests and matching replies, notifications, and closing. - A
NetconfClientputs each call on the object for the RFC 6241 layer it works at:client.transport(the peer),client.session(raw RPCs, capabilities, events),client.ops(base operations, opt-in extensions' operations, and the device profile's own underdevice) andclient.content(the path API, configure, and extensions' decoded readers). The device profile in use isclient.profile, and the options given toconnect()areclient.connectOptions. - A device profile describes how one kind of device differs from the RFCs, and what it offers beyond them. Profiles are JSON files. See Device profiles.
Promises for requests, events for everything else
The API has no callbacks:
Things you ask for (
connect,rpc,getConfig,commit,close) return promises. Each can be cancelled with anAbortSignaland given its owntimeout.Things that just happen (the session closing, warnings, notifications) arrive as typed events:
tsclient.session.on('notification', (n) => { console.log(n.eventTime, n.event?.name); }); client.session.on('closed', ({ cause }) => { if (cause) console.warn('session lost:', cause.message); });A subscription is an async iterable that you read with
for await, and that ends withawait using.
There is no 'error' event. In Node an 'error' event with no listener crashes the process, so failures come through rejected promises and the cause on 'closed' instead. See Errors.
Capabilities are checked before sending
Every operation knows which capabilities it needs. With the default capabilityCheck: 'strict', calling client.ops.commit() on a server without :candidate rejects with a CapabilityError, and nothing is sent. Use 'warn' to send it anyway with a logged warning, or 'off' to skip the check.
Operations as data
Every operation is also described as plain data: its name, its arguments and their types, the capabilities it needs, and whether it changes anything (mutates). client.ops.list lists everything the connected client can run, including extensions' operations and the device profile's operations. client.ops.run(name, args) runs any of them from plain arguments.
This is how the CLI gets its commands, help and read-only guard without any per-operation code. You can use the same descriptors to build forms, APIs or automation tools.