Operations
client.ops implements the Operations layer of the NETCONF protocol (RFC 6241 §1.2): each protocol operation is a method that builds the <rpc>, checks the server advertises what it needs, sends it and resolves with the reply. If you want a higher-level interface that focusses more on the data itself, named by YANG paths, see Content instead.
Base operations
| Method | Operation | RFC 6241 section | Needs |
|---|---|---|---|
get() | <get> | §7.7 | |
getConfig() | <get-config> | §7.1 | :candidate or :startup to read those |
editConfig() | <edit-config> | §7.2 | :writable-running or :candidate for the target; some options need more |
copyConfig() | <copy-config> | §7.3 | :writable-running, :candidate, :startup or :url for the datastores used |
deleteConfig() | <delete-config> | §7.4 | :startup or :url |
lock() | <lock> | §7.5 | :candidate or :startup to lock those |
unlock() | <unlock> | §7.6 | as for lock() |
validate() | <validate> | §8.6.4.1 | :validate |
commit() | <commit> | §8.3.4.1, §8.4.5.1 | :candidate; :confirmed-commit for a confirmed commit |
cancelCommit() | <cancel-commit> | §8.4.4.1 | :confirmed-commit:1.1 |
discardChanges() | <discard-changes> | §8.3.4.2 | :candidate |
killSession() | <kill-session> | §7.9 | |
client.close() | <close-session> | §7.8 |
The Needs column lists the capabilities an operation depends on: optional features a server announces in its <hello>, written short, so :candidate is urn:ietf:params:netconf:capability:candidate:1.0. On a server that doesn't announce them, the call rejects with a CapabilityError before anything is sent (capability checks).
Each client.ops method also takes { timeout, signal }. The API reference has every method's full signature.
Read operations
get() reads configuration and state; getConfig() reads configuration from a datastore (source, default running). Both take an optional filter that selects what comes back, and a format for the reply. The nmda extension's getData() and compare() take the same filters, and getData() the same formats.
Filter selection
Without a filter the whole datastore comes back. RFC 6241 defines two forms of filter that can go to a NETCONF server: a subtree filter and an XPath filter. The library lets you write each of them in several ways.
The five examples below all build the same filter, which selects the eth0 entry of the ietf-interfaces interface list, so each one returns the same data. Only the way the filter is written changes.
1. Subtree
A subtree filter (RFC 6241 §6) is a pattern shaped like the data: an element with children returns only what matches inside it, an empty element returns that node whole, and an element with a value returns only the entries whose leaf has that value. Every server supports it.
1.1 Built with x()
subtree(...elements) takes one or more elements as separate arguments, each with its namespace, and makes them the top-level nodes of the filter. The same filter works for get() and getConfig():
import { subtree, x } from '@node-net/netconf';
const IF = 'urn:ietf:params:xml:ns:yang:ietf-interfaces';
// Subtree filter, built with x(): the eth0 entry of the interface list
const filter = subtree(
x('interfaces', { xmlns: IF },
x('interface',
x('name', 'eth0')
)
)
);
// configuration and state
await client.ops.get({ filter });
// configuration only, from running
await client.ops.getConfig({ filter });To select several subtrees, pass several elements: subtree(x('interfaces', …), x('system', …)).
1.2 From XML text
Parse XML text first: a plain string would be sent as escaped text, not XML.
import { parseXml, subtree } from '@node-net/netconf';
// Subtree filter, from XML text: the eth0 entry of the interface list
const filter = subtree(parseXml(`
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>eth0</name>
</interface>
</interfaces>`)
);
await client.ops.get({ filter });1.3 From JSON
A plain object as filter is a subtree filter written as RFC 7951 JSON.
// Subtree filter, from RFC 7951 JSON: the eth0 entry of the interface list
const filter = {
'ietf-interfaces:interfaces': {
interface: {
name: 'eth0'
}
}
};
await client.ops.get({ filter });The library converts it to XML with the server's YANG schema: {} selects a whole node, null a leaf, and a value matches entries. See JSON filters for the full mapping, and JSON and YANG for why the schema is needed. The filter's format doesn't change the reply's format.
2. XPath
An XPath filter (RFC 6241 §8.9) selects nodes with an XPath 1.0 expression, which can express conditions a subtree filter can't. Only servers that announce the :xpath capability in their hello accept one. Without it the call rejects with a CapabilityError, and nothing is sent (capability checks). Check with client.session.serverCapabilities.has(':xpath'), and use a subtree filter where it's missing.
2.1 Built with xpath()
xpath(expression, namespaces) takes the expression and a namespace for every prefix in it:
import { xpath } from '@node-net/netconf';
// XPath filter, built with xpath(): the eth0 entry of the interface list
const filter = xpath(
'/if:interfaces/if:interface[if:name="eth0"]',
{ if: 'urn:ietf:params:xml:ns:yang:ietf-interfaces' },
);
await client.ops.get({ filter });2.2 From a YANG path
The Content layer's toXPath() turns a YANG path, with module names rather than prefixes, into an XPath filter, declaring the namespaces for you:
// ietf-interfaces is YANG 1.1, listed in the YANG library, not the hello
await client.content.loadModules();
// XPath filter, from a YANG path: the eth0 entry of the interface list
const filter = client.content.toXPath(
'/ietf-interfaces:interfaces/interface[name="eth0"]',
);
await client.ops.get({ filter });toXPath() is synchronous, so for a module that only the server's YANG library lists, as YANG 1.1 modules usually are, read the library first with loadModules() (see Where namespaces come from).
Output format
The output format is totally independent of the input format, and can be either XML or JSON.
1. XML
By default, a read resolves with the reply's <data> element, an XmlElement:
import { subtree, x } from '@node-net/netconf';
const IF = 'urn:ietf:params:xml:ns:yang:ietf-interfaces';
// Each interface's name and description, as XML
const filter = subtree(
x('interfaces', { xmlns: IF },
x('interface', x('name'), x('description'))
)
);
const data = await client.ops.getConfig({ filter });
console.log(data);
const entries = data.path('interfaces')?.childrenNamed('interface') ?? [];
for (const entry of entries) {
console.log(entry.child('name')?.text());
}<data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>eth0</name>
<description>uplink to core1</description>
</interface>
<interface>
<name>eth1</name>
<description>spare</description>
</interface>
</interfaces>
</data>
eth0
eth1To look at a reply, console.log(data) prints it as indented XML. String(data) gives compact XML, and serializeXml(data, { indent: 2 }) gives the indented form as a string.
2. JSON
With format: 'json', a read resolves with the data as RFC 7951 JSON (YANG's JSON encoding, the one RESTCONF uses), typed by the server's YANG schema:
import { subtree, x } from '@node-net/netconf';
const IF = 'urn:ietf:params:xml:ns:yang:ietf-interfaces';
// The whole interface list, as RFC 7951 JSON
const filter = subtree(x('interfaces', { xmlns: IF }));
const data = await client.ops.getConfig({ filter, format: 'json' });
// The REPL, as Node's, shows nesting 2 deep; this shows it all
console.dir(data, { depth: null });{
'ietf-interfaces:interfaces': {
interface: [
{
name: 'eth0',
description: 'uplink to core1',
type: 'iana-if-type:ethernetCsmacd',
enabled: true
},
{
name: 'eth1',
description: 'spare',
type: 'iana-if-type:ethernetCsmacd',
enabled: false
}
]
}
}The TypeScript return type follows the option: YangJsonObject with format: 'json', and XmlElement without it. Lists are always arrays, numbers and booleans are typed, and identityref values are named by module. See Reading JSON for the full mapping, including RFC 7952 annotations.
Write operations
These take configuration to send: editConfig({ config }), copyConfig({ source: { config } }) and validate({ config }), and likewise nmda editData().
XML config
config is an element built with x(), or XML text parsed with parseXml(). The two examples below send the same edit, which sets the description of eth0.
1. Built with x()
import { x } from '@node-net/netconf';
const IF = 'urn:ietf:params:xml:ns:yang:ietf-interfaces';
// XML config, built with x(): eth0's description
const config = x('interfaces', { xmlns: IF },
x('interface',
x('name', 'eth0'),
x('description', 'uplink')
)
);
await client.ops.editConfig({ target: 'running', config });2. From XML text
Parse XML text first: a plain string would be sent as escaped text, not XML.
import { parseXml } from '@node-net/netconf';
// XML config, from XML text: eth0's description
const config = parseXml(`
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>eth0</name>
<description>uplink</description>
</interface>
</interfaces>`);
await client.ops.editConfig({ target: 'running', config });JSON config
A plain object as config is RFC 7951 JSON, so data read as JSON can be changed and sent straight back:
const IFS = 'ietf-interfaces:interfaces';
// Read eth0's configuration as RFC 7951 JSON
const filter = { [IFS]: { interface: { name: 'eth0' } } };
const config = await client.ops.getConfig({ filter, format: 'json' });
// The JSON isn't typed by the schema: say what this part holds
const ifs = config[IFS] as { interface: { description?: string }[] };
// Change its description, and send it back
ifs.interface[0].description = 'uplink';
await client.ops.editConfig({ target: 'running', config });The JSON is checked and converted with the server's YANG schema before sending: list keys go first, identityref values get their namespace prefixes declared, and data that doesn't match the schema is rejected without being sent. RFC 7952 metadata sets edit attributes such as nc:operation and yang:insert. See Writing JSON.
Edit options
editConfig() takes the <edit-config> parameters of RFC 6241 §7.2. Leave one out and the server uses its default.
| Option | Values | Needs |
|---|---|---|
target | 'running' or 'candidate' | :writable-running or :candidate |
defaultOperation | 'merge' (the server's default), 'replace' or 'none' | |
testOption | 'test-then-set' (the server's default), 'set' or 'test-only' | :validate; :validate:1.1 for 'test-only' |
errorOption | 'stop-on-error' (the server's default), 'continue-on-error' or 'rollback-on-error' | :rollback-on-error for 'rollback-on-error' |
url | a URL to load the configuration from, in place of config | :url |
Default operation
defaultOperation decides what happens to the nodes in config that have no operation attribute (nc:operation) of their own or above them. 'merge', the server's default, merges them in, and is what most edits want: the nodes you send are created or updated, and the rest stay as they are. 'replace' makes the config the whole datastore, deleting everything you didn't send, so use it only with a complete configuration. 'none' changes only the nodes that have an operation, such as delete or create; the rest only locate them. In JSON, an operation attribute is RFC 7952 metadata: see Writing JSON.
Testing and errors
testOption: 'test-only' checks an edit and changes nothing, and errorOption: 'rollback-on-error' applies it all or not at all. Give exactly one of config and url; otherwise the call throws a TypeError.
const config = {
'ietf-interfaces:interfaces': {
interface: [{ name: 'eth0', description: 'uplink' }],
},
};
// Check an edit without applying it
await client.ops.editConfig({
target: 'candidate',
config,
testOption: 'test-only',
});
// Apply it all or not at all
await client.ops.editConfig({
target: 'running',
config,
errorOption: 'rollback-on-error',
});Copying and deleting datastores
copyConfig({ source, target }) replaces the whole target with the source (RFC 6241 §7.3). Each one is a datastore name or a { url } (:url). The source can also be inline { config }, as XML or JSON, as for editConfig():
// save running as startup
await client.ops.copyConfig({ source: 'running', target: 'startup' });
// replace the whole candidate with configuration given inline:
// here, running's, read as JSON
const config = await client.ops.getConfig({ format: 'json' });
await client.ops.copyConfig({ source: { config }, target: 'candidate' });Writing to running needs :writable-running, and candidate and startup need their own capabilities. A URL source or target, such as { url: 'file:///backup.xml' }, needs :url, whose parameter lists the schemes the server accepts (?scheme=file,https). With the with-defaults extension, copyConfig() also takes a withDefaults option.
deleteConfig() deletes the startup datastore or a URL (RFC 6241 §7.4). running can never be deleted:
await client.ops.deleteConfig('startup');A URL is deleted the same way: deleteConfig({ url: 'file:///backup.xml' }).
Locks, validation and commits
These are the steps of a careful change. withCandidate() runs them in the right order and cleans up when one fails, so use it unless you need the steps one at a time.
Locking
lock(datastore) takes a global lock on running, candidate or startup, so that no other session can change it, and unlock(datastore) releases the lock (RFC 6241 §7.5). The server releases a session's locks when the session ends.
const config = {
'ietf-interfaces:interfaces': {
interface: [{ name: 'eth0', description: 'uplink' }],
},
};
await client.ops.lock('running');
try {
await client.ops.editConfig({ target: 'running', config });
} finally {
await client.ops.unlock('running');
}When another session holds the lock, lock() rejects with an RpcError whose tag is lock-denied (see Errors). The monitoring extension's client.content.monitoring.datastores() tells you which session holds it.
Validating
validate(source) checks a configuration and changes nothing (RFC 6241 §8.6). The source is a datastore name, a { url } or inline { config }:
await client.ops.validate('candidate');
// Inline configuration, XML or JSON as for editConfig(), is
// checked as a whole datastore: here, running's, read as JSON
const config = await client.ops.getConfig({ format: 'json' });
await client.ops.validate({ config });Inline configuration is checked as a complete datastore, not as an edit, so a fragment fails on whatever it leaves out, such as a mandatory leaf. Invalid configuration rejects with an RpcError that lists every problem the server found.
Committing the candidate
On a server with :candidate, edits go to the candidate datastore, and commit() makes them the running configuration (RFC 6241 §8.3). discardChanges() drops uncommitted edits, putting the candidate back to the running configuration. Done one step at a time, in the order RFC 6241 Appendix E.1 gives:
const config = {
'ietf-interfaces:interfaces': {
interface: [{ name: 'eth0', description: 'uplink' }],
},
};
await client.ops.lock('running');
await client.ops.lock('candidate');
try {
// drop edits another session left
await client.ops.discardChanges();
await client.ops.editConfig({ target: 'candidate', config });
await client.ops.validate('candidate');
await client.ops.commit();
} catch (err) {
await client.ops.discardChanges();
throw err;
} finally {
await client.ops.unlock('candidate');
await client.ops.unlock('running');
}withCandidate() does the same, and also collects any errors from the cleanup instead of letting them hide the first error.
Confirmed commits
A confirmed commit (RFC 6241 §8.4) is rolled back by the server unless it's confirmed in time. That's useful for a change that might cut you off from the device. It needs :confirmed-commit:
// timeout in seconds; the server's default is 600
await client.ops.commit({ confirmed: true, confirmTimeout: 120 });
// ...check that you can still reach the device...
// confirm: the change is now permanent
await client.ops.commit();
// or, to roll it back now: await client.ops.cancelCommit();A confirmed commit with no confirmation is also rolled back if the session ends. Another confirmed commit before the timeout resets the timer. cancelCommit() needs :confirmed-commit:1.1.
confirmTimeout and persist only go with confirmed: true, as in RFC 6241. Without it, commit() throws a TypeError and sends nothing. persistId on its own is the confirming commit.
With persist, the pending commit survives the session ending (:confirmed-commit:1.1). Any session can then confirm it with persistId or cancel it, which matters when the change drops the connection and you have to reconnect (see Reconnecting):
await client.ops.commit({
confirmed: true,
confirmTimeout: 300,
persist: 'change-42',
});
// later, from a new session, confirm
await client.ops.commit({ persistId: 'change-42' });
// or roll back: await client.ops.cancelCommit({ persistId: 'change-42' });In a transaction, the confirmed option gives you a PendingCommit handle with confirm() and cancel().
Sessions
killSession(sessionId) forces another session to close (RFC 6241 §7.9). The server stops that session's operations, releases its locks and rolls back its unconfirmed confirmed commit. It's typically used to free a lock that a stale session still holds:
// Needs the monitoring extension
const ds = await client.content.monitoring.datastores();
const holder = ds.find((d) => d.name === 'candidate')?.globalLock?.sessionId;
if (holder) await client.ops.killSession(holder);A sessionId that isn't a positive integer throws a RangeError. The server refuses to kill your own session.
To close your own session, call client.close(). It sends <close-session> (RFC 6241 §7.8) and then closes the connection. See Closing.
Actions and RPCs by path
A YANG 1.1 action (RFC 7950 §7.15) is an operation on a data node, such as resetting one interface. client.content.invoke() names the action by its path, with the list keys of the node it acts on, and takes the input as RFC 7951 JSON. It resolves with the output, typed by the server's schema:
// ex:servers/server is a list keyed by name, and reset an action on it
const path = '/ex:servers/server[name="a"]/reset';
// { 'finished-at': '2026-11-15T04:40:00Z', attempts: 2 }
await client.content.invoke(path, { delay: 3 });The input and output members are named as they are inside the action, so a parameter from the action's own module has no prefix. With no output, invoke() resolves with {}, and with format: 'xml' it resolves with the output elements instead. Input can be XML elements too.
A path of one step names an RPC, which is called the same way:
// { when: 'now' }
await client.content.invoke('/ex:restart', { after: 10 });Paths work as in read(): a module the server lists only in its YANG library is found, and a device profile's named paths can be used. The last step names the action, so it can't have a predicate (TypeError). JSON follows the same rules as JSON reads and writes: input that doesn't match the schema rejects before anything is sent, and output without a schema falls back to schema-less conversion with a warning unless you set requireSchema. An <rpc-error> rejects with an RpcError; an action on a list entry that doesn't exist is usually data-missing.
On the Operations layer, client.ops.action() sends the <action> element for a data-node tree you build, from the top-level node down to the action, with the input inside. The tree can be XML or JSON. The reply's output holds the action's output elements:
const reply = await client.ops.action({
'ex:servers': { server: [{ name: 'a', reset: { delay: 3 } }] },
});
// [<finished-at>…</finished-at>, <attempts>2</attempts>]
reply.output;action is in client.ops.list as an operation that changes state, so client.ops.run('action', { target }) works, and a read-only nnc target refuses it.
Any other RPC
Vendor RPCs, and any other RPC without a method, go through client.session.rpc(). See Vendor RPCs. An RPC that a YANG module the server lists defines can be called by path instead, as above.
Errors
A failed operation rejects with a NetconfError. When the server replies with <rpc-error>, it's an RpcError holding every error in the reply; an operation the server didn't advertise is a CapabilityError. See Errors for every error class, by layer, and how to handle them.
Events and pipelining
Events, such as notifications and the session closing, and how requests are pipelined belong to the messages layer. See Messages.