Getting started
Install
npm install @node-net/netconf@node-net/netconf needs Node.js 22.12 or later. It's an ES module package:
import { connect, ssh } from '@node-net/netconf';But CommonJS code can load it too:
const { connect, ssh } = require('@node-net/netconf');TypeScript projects that compile to CommonJS need "module": "nodenext".
Two ways to work
@node-net/netconf follows the layers of RFC 6241, and a connected client gives you two of them to program against. Either one can achieve the same results, and this page introduces both.
client.content: the Content layer. This library's own higher-level abstraction over the configuration and state data. You name the data by YANG path (an RFC 7950 instance identifier, with module names as in RFC 7951) and the library works out the filters, edits and operation sequences, using library concepts such as the device profile to fit each kind of device.client.ops: the Operations layer. The NETCONF standard operations (<get-config>,<edit-config>,<lock>,<commit>, …), each as a function, as RFC 6241 defines them. You choose the operation, datastore and filter, and get the reply back. Data goes in and out as RFC 7951 JSON or as XML.
Which to start with:
- New to NETCONF, or want results quickly? Start with
client.content. You say what data you want, and the library handles the protocol. - Want to learn NETCONF itself, or need exact control over which operations are sent and in what order? Start with
client.ops.
They aren't exclusive. You can mix them on the same client, and use client.ops for anything client.content doesn't cover.
Run the examples in the lab
The lab is a terminal on this site, with a simulated device behind it, running in your browser. Through the guide, an example with a Run button types itself into the lab, ready for Enter to run it, so you can see what it does straight away. The Lab button in the header opens it on any page, as does Ctrl+`. See Try it in the lab for more.
Every example on this page runs there as written. In the lab, ssh() connects to the simulated device, whatever host you give it, and says so. In an example of several statements, each statement has its own Run button beside it, and the Run all button above the example runs them one after another, so you see what each one does.
Connect and read - Content Layer
Each example on this page reads the configuration of interface eth0, so you can compare the APIs side by side.
import { connect, ssh, knownHostsFile } from '@node-net/netconf';
const client = await connect({
transport: ssh({
host: 'router1.example.net',
username: 'admin',
// read only when connecting
password: () => process.env.ROUTER_PASSWORD!,
// or 'SHA256:…'; verification is mandatory
hostKey: knownHostsFile(),
}),
});
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';
// from running, as RFC 7951 JSON
const data = await client.content.read(IF);
console.log(data);
// {
// 'ietf-interfaces:interface': [
// {
// name: 'eth0',
// description: 'uplink to core1',
// type: 'iana-if-type:ethernetCsmacd',
// enabled: true,
// },
// ]
// }
// sends <close-session> and closes SSH
await client.close();connect() resolves once the hello exchange is complete. It returns a NetconfClient, which has the Content layer (the YANG path API) under content, a method for each base operation under ops, and the device profile, if one was chosen. For closing automatically, even after an error, see Closing.
You name the data by its path, and the library builds the filter. Writing is just as short: client.content.set(`${IF}/description`, 'uplink') locks, edits, validates, commits and unlocks in one call. See Content.
If the server doesn't advertise the module
The Content layer finds each module's namespace from the capabilities the server advertises in its hello. Some servers implement a YANG module but don't list it there. connect() still succeeds, but the first client.content call whose path names that module rejects with a PathError, before anything is sent:
PathError: Unknown YANG module "ietf-interfaces" in
"/ietf-interfaces:interfaces/interface[name=\"eth0\"]": the server did
not advertise it, and no profile or schema defines its namespaceOn such a server, read and write that module's data with client.ops and an XML filter instead.
Connect and read - Operations Layer
The same read with the standard operations: you choose the operation and build the filter yourself.
JSON filter
import { connect, ssh, knownHostsFile } from '@node-net/netconf';
const client = await connect({
transport: ssh({
host: 'router1.example.net',
username: 'admin',
password: () => process.env.ROUTER_PASSWORD!,
hostKey: knownHostsFile(),
}),
});
const data = await client.ops.getConfig({
// an RFC 7951 JSON subtree filter: the eth0 entry
filter: {
'ietf-interfaces:interfaces': {
interface: { name: 'eth0' },
},
},
// and an RFC 7951 JSON reply
format: 'json',
});
console.log(JSON.stringify(data, null, 2));
// {
// "ietf-interfaces:interfaces": {
// "interface": [
// {
// "name": "eth0",
// "description": "uplink to core1",
// "type": "iana-if-type:ethernetCsmacd",
// "enabled": true
// }
// ]
// }
// }
await client.close();The reply is the whole <data> tree, from the top-level container down, where the Content layer gave just the selected node. The JSON is typed by the server's YANG schema, both ways: see JSON and YANG.
XML filter
The same filter in XML, built with x() and subtree(). It names the module's namespace itself, so it works even when the server doesn't advertise the module. A JSON filter can't do that, because it has to look up the namespace from the module name.
import { connect, ssh, knownHostsFile, subtree, x } from '@node-net/netconf';
const client = await connect({
transport: ssh({
host: 'router1.example.net',
username: 'admin',
password: () => process.env.ROUTER_PASSWORD!,
hostKey: knownHostsFile(),
}),
});
const ns = 'urn:ietf:params:xml:ns:yang:ietf-interfaces';
// an XML subtree filter: the eth0 entry
const data = await client.ops.getConfig({
filter: subtree(
x('interfaces', { xmlns: ns },
x('interface', x('name', 'eth0')),
),
),
});
console.log(data);
// <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>
// <type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">
// ianaift:ethernetCsmacd</type>
// <enabled>true</enabled>
// </interface>
// </interfaces>
// </data>
await client.close();Without format: 'json', the reply is the <data> element as an XmlElement. Edits can be XML too. See Operations.
Next
- Try it in the lab: run the guide's examples in your browser
- Concepts: how the client, session and profile fit together
- Connecting: SSH keys and agents, jump hosts, TLS, timeouts
- Content: reading and writing by YANG path, comparing datastores
- Operations: every base operation, raw RPCs, events
- Device profiles: when a device doesn't behave like the RFC says