Skip to content

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:

The NETCONF layers Your code calls @node-net/netconf, which has the four layers of RFC 6241, each on its own object of the client: Content (client.content), Operations (client.ops), Messages (client.session) and Transport (client.transport). Each layer uses only the one below it, and the Transport layer carries messages across the network to the NETCONF server. Your codecalls whichever layer it needs@node-net/netconfContentclient.contentConfiguration and state data, by YANG pathOperationsclient.ops<get-config>, <edit-config>, <commit>, …Messagesclient.session<hello>, <rpc>, <rpc-reply>, <notification>Transportclient.transportSSH or TLS, and framingNetworkTCP/IP

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.

LayerFunctionOn a connected client
ContentConfiguration and state dataclient.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
TransportSSH or TLS, and framingclient.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:

ts
// 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:

DatastoreCapabilityWhat it holds
runningalways there; writable with :writable-runningThe configuration the device is using now
candidate:candidateA scratch copy you edit without affecting the device. commit() makes it the running configuration, and discardChanges() puts it back to running
startup:startupThe 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:

ts
// 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:

  • intended is running after the device has applied its own processing, such as removing inactive configuration or expanding templates: the configuration it is trying to use.
  • operational is what the device is actually using, configuration and state together. Each node can be annotated with its origin: whether it came from intended, was learned from a protocol, is a default, 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 Session is the NETCONF session itself: the hello exchange, capabilities, numbering requests and matching replies, notifications, and closing.
  • A NetconfClient puts 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 under device) and client.content (the path API, configure, and extensions' decoded readers). The device profile in use is client.profile, and the options given to connect() are client.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 an AbortSignal and given its own timeout.

  • Things that just happen (the session closing, warnings, notifications) arrive as typed events:

    ts
    client.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 with await 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.

Released under the MIT Licence.