Skip to content

Content ​

client.content implements the Content layer of NETCONF (RFC 6241 §1.2), which focuses attention on the configuration and state data itself, rather than the Operations layer protocol operations. Although the layer is specified in RFC 6241, its design is not, and so the Content layer presented here is this library's determination of a useful, high-level interface. If you want to work closer to the NETCONF protocol itself, see Operations instead.

The NETCONF layers Your code calls @node-net/netconf's Content layer with YANG paths, values and JSON. The Content layer turns paths and JSON into XML for the Operations layer, and turns the XML the Operations layer gets back into JSON. The Operations layer sends protocol operations as XML, the Messages layer sends each one as an rpc and matches its reply, and the Transport layer carries them over SSH or TLS, across the network, to the NETCONF server. Your codeYANG paths, values and JSON in; typed JSON (or XML) elements back@node-net/netconfContentclient.contentConfiguration and state data, named by YANG pathsread(), set(), configure(), and the steps of each changepath → XMLJSON → XMLXML → JSONOperationsclient.opsOne method per protocol operation<get-config>, <edit-config>, <lock>, <commit>, …Messagesclient.session<hello>, <rpc>, <rpc-reply> and <notification>message-ids, capabilities, <rpc-error> as exceptionsTransportclient.transportSSH or TLS, and message framingopened by ssh() and tls()NetworkTCP/IP

The highlighted steps are where the client changes the data's form: paths and JSON become XML on the way to the server, and the XML that comes back becomes JSON.

In this implementation, you name the data by the YANG path definition specified in RFC 7950 §9.13, and the library works out the filters, edits and sequences of operations from what the server advertises, adjusted by a device profile if you use one. You can read and write any YANG model the server advertises. You don't need schema files, generated code or XML.

ts
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';

// 'uplink', or undefined if not set
await client.content.readValue(`${IF}/description`);
// RFC 7951 JSON from running, typed by the YANG schema
await client.content.read(IF);
// config and state, with <get>
await client.content.read(IF, { source: 'config+state' });
// the matching XML elements, as the server sent them
await client.content.read(IF, { format: 'xml' });

// merge a value into the config
await client.content.set(`${IF}/description`, 'uplink');
// delete an entry; fine if it's already gone
await client.content.remove(
  '/ietf-interfaces:interfaces/interface[name="eth9"]',
);

Methods ​

MethodWhat it doesSends
read()the nodes a path selects, as XML or JSON<get-config> or <get>
readValue()the value of the first leaf a path selects<get-config> or <get>
set()sets one valuethe device's workflow
remove()deletes one node, if it existsthe device's workflow
configure()applies several edits in one <edit-config>the device's workflow
invoke()invokes the RPC or YANG 1.1 action a path names, with JSON input and outputthe RPC, or <action>
checkEdits()checks a configure() callback without applying itat most a YANG library read
compareDatastores()how two configuration datastores differtwo <get-config>
getCandidateChanges()what a commit would applytwo <get-config>
datastores()the datastores the server hasat most a YANG library read
modules()a datastore's YANG modules and featuresat most a YANG library read, and schema reads with declared
toJson()converts YANG data from XML to RFC 7951 JSONschema reads only
toXml()converts RFC 7951 JSON to XMLschema reads only
expandPath()the path a named path stands fornothing
resolvePath()a path's steps, with their namespacesnothing
toXPath()a path as an XPath filternothing
readFilter()the filter read() would sendnothing
namedPathTemplate()a named path's parametersnothing
moduleNamespace()a module's namespacenothing
moduleOf()a namespace's modulenothing
moduleNamespaces()every module the session knows, with its namespace, or one source's whole listnothing
moduleNamespacesInfo()the same, with where each namespace came from, or one source's whole listnothing
loadModules()learns module namespaces from the YANG librarya YANG library read, once per session

Extensions add their own readers under their id, such as client.content.monitoring: see Extensions' readers.

Each method that sends something also takes { timeout, signal }. The API reference has every method's full signature.

Paths ​

Path syntax ​

Paths are YANG instance identifiers (RFC 7950 §9.13), with module names in place of prefixes, as in YANG's JSON encoding (RFC 7951):

/ietf-interfaces:interfaces/interface[name="eth0"]/description
/nokia-conf:configure/port[port-id="1/1/2"]/description
/example:routes/route[prefix="10.0.0.0/8"][vrf="blue"]
  • A path is a series of steps separated by /, one for each node (RFC 7950 §9.13). The steps of /ietf-interfaces:interfaces/interface[name="eth0"]/description are ietf-interfaces:interfaces, interface[name="eth0"] and description.
  • The first step names its module before a colon: ietf-interfaces:interfaces is the interfaces node of the ietf-interfaces module. Later steps take the module from the step before them, unless they name another one, as an augmented node does: in /ietf-interfaces:interfaces/interface[name="eth0"]/ietf-ip:ipv4, interface comes from ietf-interfaces and ipv4 from ietf-ip. This is the JSON encoding's rule (RFC 7951 §6.11). The XML encoding puts a prefix on every step instead.
  • List entries are selected by their keys, in square brackets, with a predicate for each key (RFC 7950 §9.13). Write the keys in the order the YANG model gives them: the standard allows any order, but NETCONF's XML encoding sends keys in the model's order (RFC 7950 §7.8.5), and the client builds the XML in the order you write.
  • A path that starts with @ is a named path from the device profile: client.content.readValue('@systemName'). A named path can take parameters: @ifDescription(eth0). See Named paths with parameters. Named paths are this library's convention, not part of any RFC.

Syntax errors are reported with their position (PathError) before anything is sent.

Reading ​

read(path) resolves with the nodes the path selects, as JSON by default or, with format: 'xml', as every element selected (an empty array if none). readValue(path) resolves with the first one's value, or undefined if there is none.

How read() works The Content layer turns the YANG path into a subtree filter, resolving each module to its XML namespace. The Operations layer sends it in a get-config, which the Messages layer wraps in an rpc. The rpc-reply's data comes back to the Operations layer as XML. The Content layer converts it to JSON using the YANG schema, unless format xml was asked for, then selects the nodes the path names. Your coderead('/ietf-interfaces:interfaces/interface[name="eth0"]'){ 'ietf-interfaces:interface': [{ name: 'eth0', enabled: true, … } ] }Contentclient.contentpath → subtree filternamespaces: connect(), profile, hello, library<interfaces xmlns="…:ietf-interfaces"><interface><name>eth0</name></interface></interfaces>select the nodes the path namesin the JSON, or in the XML for format: 'xml'XML → JSON, typed by the YANG schemaskipped with format: 'xml'Operationsclient.opsgetConfig({ source: 'running',filter })the reply's <data>as XML, as the server sent itMessagesclient.session<rpc message-id="7"><get-config>…</get-config><rpc-reply message-id="7"><data>…</data>Transportclient.transportSSH or TLS, to and from the NETCONF server

source picks where the data comes from:

sourceReadsWith
'running' (default), 'candidate', 'startup'that configuration datastore<get-config>
'config+state'running configuration and state<get>

'operational' is refused with a TypeError. It names the NMDA <operational> datastore, which <get> doesn't read: use the nmda extension's getData() for it.

The other getConfig() options, such as the with-defaults extension's withDefaults, are passed on.

JSON ​

By default, read() resolves with the target node as RESTCONF returns it (RFC 8040), in RFC 7951 JSON typed by the server's YANG schema. The node's module-qualified name is the only member, and its value is the list's matching entries (as an array), the container (as an object), or the leaf's typed value. Nothing matching gives {}. readValue() resolves with the leaf's typed value:

ts
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';

await client.content.read(IF);
// { 'ietf-interfaces:interface': [{ name: 'eth0', enabled: true, … }] }
await client.content.read(`${IF}/enabled`);
// { 'ietf-interfaces:enabled': true }
// true, a boolean
await client.content.readValue(`${IF}/enabled`);

This is the Content layer's default. The Operations layer's reads (client.ops.get(), getConfig()) default to XML, because they return what the server sent.

Key predicates match a key by its value, whatever its JSON type: [mtu="1500"] matches the number 1500. The conversion rules, where the schema comes from and what happens without one are in JSON and YANG.

Without a schema ​

Turning a path into a request needs no schema, but turning the server's XML reply into typed JSON does. The library takes each module's text from connect({ yang: { modules } }), the device profile, the IETF modules it bundles, or the server's <get-schema>. When none of them has a module the data needs (on a device without <get-schema>, for example), the JSON is converted schema-less. It then differs from typed JSON: for example, values are text, and a list with one entry is not an array. A warning event says so, and suggests supplying the modules with yang.modules. Why the schema matters explains what a schema-less conversion can't tell you, and Where the schema comes from how to supply one.

format: 'xml' reads the data as the server sent it, which needs no schema at all. Values are text, and readValue() gives the trimmed text:

ts
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';

// the <description> element(s)
await client.content.read(`${IF}/description`, { format: 'xml' });
// 'true', a string
await client.content.readValue(`${IF}/enabled`, { format: 'xml' });

With requireSchema, a read that can't be typed rejects instead, and its error suggests format: 'xml'.

Reading on devices that filter badly ​

read() sends a subtree filter built from the path, then selects the matching elements locally. Some devices can't handle subtree filters, or only some of them. A profile's subtreeFilter quirk changes what read() sends, while the result stays the same. client.content.readFilter(path) shows the filter read() would send, without sending it.

Writing ​

set(path, value) merges one value into the configuration, and remove(path) deletes one node, doing nothing if it's already gone. Each is a one-edit configure(), and takes the same options.

How configure() works The Content layer turns path edits into XML, resolving each module to its XML namespace, and JSON edits into XML using the edit target's YANG schema, and puts them in one config. The Operations layer sends it in an edit-config, which the Messages layer wraps in an rpc. The server's ok reply comes back up, and configure() resolves. Your codeconfigure((txn) => {txn.set(`${IF}/description`, 'uplink');txn.merge({ 'ietf-netconf-acm:nacm': … });})resolvesan <rpc-error> rejects insteadContentclient.contentpath edits → XMLmodules → namespacesJSON edits → XMLedit target's YANG schemaone <config>: the path edits, then the JSONOperationsclient.opseditConfig({ target: 'candidate',config })Messagesclient.session<rpc message-id="8"><edit-config>…</edit-config><rpc-reply message-id="8"><ok/>Transportclient.transportSSH or TLS, to and from the NETCONF server

A single change ​

set() sets one value, merging it into the configuration:

ts
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';

await client.content.set(`${IF}/description`, 'uplink');

Running it again changes nothing: a merge of the value already there succeeds.

Several changes at once ​

configure() collects edits and applies them as one <edit-config>:

ts
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';
const ETH1 = '/ietf-interfaces:interfaces/interface[name="eth1"]';

await client.content.configure((txn) => {
  // merge
  txn.set(`${IF}/description`, 'uplink');
  // replace the node and everything below it
  txn.replace(`${ETH1}/enabled`, true);
  // fails if it exists
  txn.create('/ietf-system:system/location', 'rack 1');
  // fails if it's missing
  txn.delete(`${ETH1}/description`);
  // fine if it's missing
  txn.remove('/ietf-interfaces:interfaces/interface[name="eth9"]');
});

Run it a second time and it fails, as it should: location now exists, and eth1 has no description left to delete.

A value can be a string, number or boolean (it becomes text), an XmlElement or array of them (they become children), or null (an empty element).

Inside the callback the edit methods check only path syntax. An unknown module rejects configure() itself, before anything is sent. A callback that makes no edits sends nothing.

JSON edits ​

txn.merge(json) and txn.replace(json) add whole subtrees as RFC 7951 JSON, in the same <edit-config> as the path edits. replace marks each top-level member with the NETCONF replace operation:

ts
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';

await client.content.configure((txn) => {
  txn.set(`${IF}/description`, 'uplink');
  txn.merge({
    'ietf-system:system': {
      contact: 'noc@example.net',
      location: 'rack 2',
    },
  });
});

The JSON is converted with the schema of the workflow's edit target, by the rules in Writing JSON, including RFC 7952 metadata for deletes and inserts. A conversion problem rejects configure() (and checkEdits()) before anything is locked or sent. Several merge() calls on the same top-level member are combined, but one top-level node can't be edited both by a path and as JSON, or both merged and replaced. The json option of configure() takes the same settings as json on editConfig().

Checking edits first ​

checkEdits() takes the same callback as configure() and runs every check configure() makes before sending: path syntax, unknown modules and named paths, two edits to the same node, a value given to remove, and the JSON conversion. It rejects as configure() would, but sends no edit and takes no lock. It may read the YANG library once, to resolve a module only the library lists (see Where namespaces come from).

ts
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';

await client.content.checkEdits((txn) => {
  txn.set(`${IF}/description`, 'uplink');
});

It takes editTarget and json, which pick the schema for JSON edits.

Edits the target can't hold ​

Under NMDA each datastore has its own schema, and a module can be in one but not another: a state module only operational implements, for example. A path through such a module can't be written to running or the candidate. When the session has read a YANG library that lists datastores, configure(), set(), remove() and checkEdits() reject a path whose module the library implements in another datastore's schema but not in the edit target's, with a PathError, before anything is locked or sent:

Other device
await client.content.set('/acme-state:counters/reset', true);
// PathError: configure: /acme-state:counters/reset is in module
// acme-state, which the server's YANG library implements in
// operational but not in running, the datastore this edit goes to

Only that evidence counts. A module the library doesn't implement in any datastore, such as one you or the device profile name for a device whose library is incomplete, is left for the server to accept or refuse. The check follows capabilityCheck: with 'warn' the edit is sent with a warning event, and with 'off' there's no check.

How changes are applied ​

set(), remove() and configure() follow the device's workflow. Each part comes from the call's options, then the device profile, then what the server advertises:

Default
editTargetcandidate if the server has :candidate, otherwise running
locktrue
validatetrue on candidate if the server has :validate
committrue on candidate

On a candidate workflow the steps are lock, discard stale changes, edit, validate, commit and unlock, using withCandidate(). If anything fails, the candidate is discarded and the locks released, and the call rejects with a TransactionError naming the failed step. If another session holds a lock, you get a LockDeniedError with the holder's session-id.

ts
const pending = await client.content.set(
  '/ietf-system:system/contact',
  'noc@example.net',
  {
    // each request as it succeeds
    onStep: (step) => console.log(step.operation, step.datastore),
    // a confirmed commit; see Transactions
    confirmed: { timeout: 120 },
  },
);
// make the change permanent (set() gives a PendingCommit
// only with confirmed)
await pending?.confirm();

With confirmed, the call resolves with a PendingCommit to confirm or cancel. confirmed needs a candidate workflow that commits.

Advanced paths ​

Named paths with parameters ​

A device profile's named paths may hold {{parameter}} placeholders, so one name covers every entry of a list. The lab device's built-in lab profile has these, so the examples below run in the REPL:

json
"paths": {
  "interface":
    "/ietf-interfaces:interfaces/interface[name={{ifName}}]",
  "ifDescription":
    "/ietf-interfaces:interfaces/interface[name={{ifName}}]/description"
}

Give values by position (in the order the parameters first appear) or by name. namedPath() builds the reference, quoting the values for you:

ts
import { namedPath } from '@node-net/netconf';

await client.content.readValue('@ifDescription(eth0)');
await client.content.readValue('@ifDescription(ifName=eth0)');
// '@ifDescription(ifName="eth0")'
const ref = namedPath('ifDescription', { ifName: 'eth0' });
await client.content.readValue(ref);

With several parameters, position follows the order they first appear in the template. On a device whose profile has "route": "/example:routes/route[prefix=][next-hop=]":

Other device
import { namedPath } from '@node-net/netconf';

await client.content.read('@route(10.0.0.0/8, 192.0.2.1)');
// quoting done for you: the prefix holds a /
const route = namedPath('route', {
  prefix: '10.0.0.0/8',
  nextHop: '192.0.2.1',
});
await client.content.read(route);
// every next hop for that prefix (see below)
await client.content.read('@route(10.0.0.0/8)');

A read may leave out a parameter that is a predicate's whole value. The predicate is dropped, so the path selects every entry:

ts
// every interface
await client.content.read('@interface');
// every interface's description
await client.content.read('@ifDescription');

set(), remove() and configure() need every parameter: an edit without its list keys isn't the edit you meant, so it fails with a PathError before anything is sent.

More of the path can follow a reference, so one named path for a list entry covers everything under it:

ts
await client.content.set('@interface(eth0)/description', 'uplink');
await client.content.read('@interface(eth0)/enabled');
// every interface's description
await client.content.read('@interface/description');

The rest of the path starts with /, and its steps take their module from the step before, as in any path. With namedPath(), append it to the result:

ts
import { namedPath } from '@node-net/netconf';

const ifPath = namedPath('interface', { ifName: 'eth0' });
await client.content.read(`${ifPath}/description`);

This is also why a named path's name can't hold /, and it can't start with @ either. namedPath() accepts the name with or without its @.

A placeholder written anywhere else must always be given, even on a read. That covers part of a quoted value, or a step's name, as in these two of the lab profile's paths:

json
"paths": {
  "port":
    "/openconfig-platform:components/component[name=\"port-{{port}}\"]",
  "systemLeaf": "/ietf-system:system/{{leaf}}"
}
ts
// name="port-eth0"
await client.content.read('@port(eth0)/config');
// /ietf-system:system/hostname
await client.content.readValue('@systemLeaf(hostname)');
// a PathError: '@port needs port: …'
await client.content.read('@port').catch((err) => err.message);

Where namespaces come from ​

A YANG path names YANG modules, but the underlying NETCONF protocol needs XML namespaces. The client looks a module up in this order:

  1. the namespaces parameter on the connect connect({ namespaces: { 'my-module': 'urn:…' } }),
  2. the device profile's namespaces,
  3. the server's <hello> capabilities,
  4. a cache of the server's YANG library (RFC 8525, or the older RFC 7895), if the session has already read it,
  5. the server's YANG library, fetched now if no step above knows the module. The session caches what it fetches, so from then on step 4 answers.

What you set beats what the device profile sets, which beats what the server says, so you can correct a server that gives a module the wrong namespace. A namespace you or the profile give that differs from the server's is logged at debug level.

Steps 1 to 3 are known when the session opens, and the YANG library only answers modules none of them knows. Reading the library therefore never changes a namespace the client has already used. It only adds modules that were unknown before.

YANG 1.1 modules aren't listed in the hello (RFC 7950 §5.6.4), though some servers list them anyway, so the YANG library is usually how they're found. client.content.moduleNamespace(name) does steps 1 to 4, and the JSON conversion uses the same order. client.content.moduleOf(namespace) looks the other way, from a namespace to its module, which is how identities and paths are named.

read(), set(), remove(), configure() and checkEdits() read the YANG library by themselves when they need it. The methods in Path tools are synchronous, so for a module only the library lists, call await client.content.loadModules() first. It resolves with moduleNamespaces() (below), and sends nothing on a server without a YANG library. The library is read once per session, shared with datastores(), modules() and the yang-library extension. loadModules({ refresh: true }) reads it again.

Seeing every namespace ​

moduleNamespaces() is every module the session knows, mapped to the namespace moduleNamespace() gives it. It sends nothing. Modules from steps 1 to 3 come first, then the ones only the YANG library lists, once the session has read it:

ts
client.content.moduleNamespaces();
// FrozenMap(17) [Map] {
//   'iana-if-type' => 'urn:ietf:params:xml:ns:yang:iana-if-type',
//   'ietf-netconf' => 'urn:ietf:params:xml:ns:netconf:base:1.0',
//   …
// }

On the lab device that's 17 modules from the hello. Its YANG 1.1 modules, such as ietf-interfaces, join them once the session reads the YANG library.

moduleNamespacesInfo() adds where each namespace came from (given, profile, hello or library, for steps 1 to 4):

ts
await client.content.loadModules();
client.content.moduleNamespacesInfo().get('ietf-interfaces');
// {
//   namespace: 'urn:ietf:params:xml:ns:yang:ietf-interfaces',
//   source: 'library'
// }

When a later source gave the module a different namespace, overrides lists it, so you can see what you or the device profile corrected. On a device whose profile corrects the namespace its hello gives acme-system:

Other device
client.content.moduleNamespacesInfo().get('acme-system');
// {
//   namespace: 'urn:acme:system',
//   source: 'profile',
//   overrides: [{ source: 'hello', namespace: 'urn:acme:sys' }],
// }

With source, moduleNamespacesInfo() gives that source's whole list instead: every module it names, with the namespace it gives, whether or not an earlier source beats it. These are the lists for the five steps:

ts
const ns = client.content;
// 1. connect({ namespaces })
ns.moduleNamespacesInfo({ source: 'given' });
// 2. the device profile's namespaces
ns.moduleNamespacesInfo({ source: 'profile' });
// 3. the server's hello
ns.moduleNamespacesInfo({ source: 'hello' });
// 4. the YANG library, if the session has read it; empty if not
ns.moduleNamespacesInfo({ source: 'library' });
// 5. read the library now, then as step 4
await ns.loadModules();
ns.moduleNamespacesInfo({ source: 'library' });

The hello's entry for acme-system above is { namespace: 'urn:acme:sys', source: 'hello' }, though the profile's namespace is the one used. In a source's own list, overrides lists only where the source disagrees with itself, such as two YANG library module sets giving a module different namespaces.

moduleNamespaces({ source }) gives the same list without the sources, mapping each module to the namespace that source gives it.

Namespaces span every datastore ​

None of these methods takes a datastore. A module's namespace belongs to the module, so it's the same in every schema the module is in, and one lookup serves every datastore. The YANG library's entries come from every datastore's schema and module set, so moduleNamespaces() can list a module that only operational has. To see which modules one datastore has, use modules({ datastore }).

Whether a datastore has a module matters when you write to it. set(), remove(), configure() and checkEdits() check each path against the edit target's schema: see Edits the target can't hold.

Path tools ​

These methods send nothing. They throw a PathError for a malformed path, an unknown module or an unknown name.

expandPath() shows the path a reference stands for, filling in its parameters as a read does:

ts
client.content.expandPath('@ifDescription(eth0)');
// '/ietf-interfaces:interfaces/interface[name="eth0"]/description'
client.content.expandPath('@ifDescription');
// '/ietf-interfaces:interfaces/interface/description'

toXPath() turns a path into an XPath filter, declaring the namespaces for you. Use it as a filter for get(), or anywhere else that takes XPath, such as a partial-lock select:

ts
// ietf-interfaces is YANG 1.1: read the library first (see above)
await client.content.loadModules();
client.content.toXPath(
  '/ietf-interfaces:interfaces/interface[name="eth0"]',
);
// {
//   type: 'xpath',
//   select: "/ietf-interfaces:interfaces/ietf-interfaces:interface"
//     + "[ietf-interfaces:name='eth0']",
//   namespaces: {
//     'ietf-interfaces': 'urn:ietf:params:xml:ns:yang:ietf-interfaces'
//   }
// }

resolvePath() parses a path and resolves each step's module, for code that works with paths itself:

ts
await client.content.loadModules();
client.content.resolvePath(
  '/ietf-interfaces:interfaces/interface[name="eth0"]/description',
);
// [
//   { name: 'interfaces', moduleName: 'ietf-interfaces', ns: '…', … },
//   { name: 'interface', keys: [{ name: 'name', value: 'eth0' }], … },
//   { name: 'description', moduleName: 'ietf-interfaces', … },
// ]

Each step has its name, its moduleName and namespace (ns), whether written on the step or taken from the one before, and its list keys.

namedPathTemplate(name) returns a named path's template from the profile, or undefined when there is none. Its params are the parameter names, in the order they first appear, and optional holds the ones a read may leave out. The CLI uses it to complete and check named paths.

The same parsing is available without a client: parsePath() parses a path's syntax, pathXPath() turns resolved steps into an XPath filter, and compileNamedPath() checks a named-path template.

Comparing datastores ​

compareDatastores({ source, target }) lists how two of running, candidate and startup differ: the changes that turn source into target. getCandidateChanges() is the same comparison from running to the candidate, so it lists what a commit would apply.

ts
await client.content.set('/ietf-system:system/location', 'rack 2');

// what a reboot would lose
const unsaved = await client.content.compareDatastores({
  source: 'startup',
  target: 'running',
});
for (const c of unsaved) {
  console.log(c.operation, c.path, c.previous, '→', c.value);
}
// on a fresh lab device, whose startup matches running:
// create /ietf-system:system/location undefined → rack 2

Each change has:

  • operation: create (only in the target), delete (only in the source), replace (a leaf's value changed) or move (an entry of an ordered-by-user list or leaf-list changed place)
  • path: the node's RFC 7951 data path, with list entries named by their keys
  • value: the node as it is in the target, and previous: as it is in the source, as RFC 7951 JSON (a leaf's typed value, or an object for a container or list entry)
  • position, for a created or moved entry of an ordered-by-user list: { where: 'first' } or { where: 'after', anchor }, where anchor is the path of the entry before it

List entries are matched by their keys, so adding one interface is one create, whatever its position. Nothing inside a created or deleted node is listed separately. filter limits the comparison to part of the configuration, as on getConfig().

Both datastores are read with <get-config> and compared by the client, so this works on any server, with no RFC 9144 compare support needed. It needs the server's YANG schema to match list entries: when the data can't be typed, it rejects with a SchemaUnavailableError rather than guessing (see Where the schema comes from). A datastore the server doesn't advertise is refused with a CapabilityError.

Another session can change either datastore between the reads. To compare under locks before committing, use txn.getCandidateChanges() inside withCandidate().

Device information ​

Device datastores ​

client.content.datastores() lists the datastores the server has, whether or not it supports NMDA:

ts
await client.content.datastores();
// {
//   source: 'yang-library',
//   datastores: [
//     { name: 'ietf-datastores:running', schema: 'complete' },
//     { name: 'ietf-datastores:candidate', schema: 'complete' },
//     { name: 'ietf-datastores:startup', schema: 'complete' },
//     { name: 'ietf-datastores:intended', schema: 'complete' },
//     { name: 'ietf-datastores:operational', schema: 'complete' }
//   ]
// }

The list always comes from one source, and source says which:

sourceWhenThe list
'yang-library'The server advertises :yang-library:1.1 (NMDA, RFC 8525)Its /yang-library/datastore entries, in its order, each with the schema it uses. These can include datastores beyond the standard five, such as factory-default
'capabilities'Any other server (no YANG library, or only :yang-library:1.0), or one whose library lists no datastoresrunning, then candidate with :candidate, then startup with :startup (RFC 6241). Nothing is sent

Both use the capabilities after the device profile's corrections. The library is read once per session, the same read the path API and the yang-library extension use. refresh: true reads it again.

Device modules and features ​

client.content.modules() lists the YANG modules the server has for a datastore (default running), with the features it supports:

ts
const { source, schema, modules } = await client.content.modules({
  module: 'ietf-netconf',
});
console.dir(modules, { depth: null });
// source: 'yang-library', schema: 'complete'
// [{
//   name: 'ietf-netconf', revision: '2011-06-01',
//   namespace: 'urn:ietf:params:xml:ns:netconf:base:1.0',
//   conformance: 'implement',
//   features: ['candidate', 'confirmed-commit', …, 'xpath'],
//   deviations: [], submodules: [], locations: []
// }]

A feature belongs to its module: xpath in ietf-netconf and xpath in ietf-subscribed-notifications are different features. Which features a server supports can differ between datastores, because under NMDA each datastore has a schema of its own (the configuration datastores always share one; operational may differ). Pass datastore for another datastore, or schema to name a YANG library schema directly. module keeps one module by name.

As with datastores(), the list comes from one source and is never merged:

sourceWhenThe list
'yang-library'The server advertises :yang-library:1.1 or :yang-library:1.0The modules of the datastore's schema. A library without datastores (RFC 7895, or a 1.1 library listing none) has one schema, which serves every datastore. A datastore or schema the library doesn't list is rejected
'capabilities'Any other server, or one whose library lists no modulesThe module capabilities in the hello. Nothing is sent

On a server with a YANG library, the module capabilities in its hello are ignored: YANG 1.1 modules never appear there, so the library is the complete list. The hello stays the authority for protocol capabilities such as :candidate.

Implemented modules come first, then the import-only ones (conformance: 'import'), whose definitions are used only by modules that import them.

Features a server doesn't support ​

A server only reports the features it supports. To also see the ones it doesn't, the module's YANG source is needed. declared: true reads it (from the schema sources the JSON conversion uses, <get-schema> included), compiles it, and adds every feature it declares:

ts
const { modules } = await client.content.modules({
  module: 'ietf-netconf',
  declared: true,
});
const [netconf] = modules;
console.log(netconf.declared);
// [
//   { name: 'writable-running', supported: true },
//   …,
//   { name: 'url', supported: false },
//   { name: 'xpath', supported: true }
// ]

// features the server reports but the source doesn't declare
netconf.undeclared;
// []

This reads and compiles source, so it costs more than the list itself. A module whose source can't be found has no declared, and a session warning names it.

Converting between XML and JSON ​

toJson() and toXml() convert YANG data by the same rules and schemas as JSON reads and JSON config, for data that didn't come from (or isn't going to) a read or edit:

  • toJson(element, { datastore, scope }) converts any element holding YANG data to JSON: the result of client.session.rpc(), a transaction's getConfig(), or a notification's content. datastore (default 'operational') picks the schema. A parsed element carries the prefixes declared above it, so scope is only for an element built with x() whose values use prefixes declared elsewhere.
  • toXml(json, { datastore, filter }) returns the elements an edit would send, or with filter: true, subtree-filter content. datastore defaults to 'running'. Extensions get it as ctx.toXml.
ts
import { NETCONF_NS, x } from '@node-net/netconf';

const reply = await client.session.rpc(x('get', { xmlns: NETCONF_NS }));
const json = await client.content.toJson(reply.data!);

Neither sends anything except the schema reads it needs. The rules are in JSON and YANG.

Extensions' readers ​

An extension that decodes data puts its readers under its id: client.content.monitoring.sessions(), client.content.yangLibrary.load(), client.content.withDefaults.basicMode and others. Each is listed with its extension, and Reads as operations shows how they are also run by name.

Errors ​

A path that can't be parsed, names an unknown module or named path, or is missing a parameter rejects with a PathError before anything is sent. Edits that the server refuses reject with a TransactionError, and JSON that doesn't match the schema with a YangDataError. The errors of the operations underneath, such as RpcError and TimeoutError, come through unchanged. See Errors.

Released under the MIT Licence.