Device profiles
Real devices differ from the RFCs, and from each other. They may need a different port, advertise the wrong capabilities, mishandle some filters, or have vendor RPCs you'll want to call. The @node-net/netconf solution to this is to store these differences in device profiles, which are JSON files, not code. Device profiles are a construct of this library, not an RFC concept.
A profile can give:
- detection rules, so the right profile is chosen from the server's hello,
- connection defaults, such as the port,
- quirks: named switches for known deviations from the RFCs,
- capability corrections, for servers that advertise too much or too little,
- the workflow for applying configuration: which datastore, and whether to lock, validate and commit,
- named paths, such as
@systemName, - device operations: the device's own RPCs, as XML templates you can call by name.
Choosing a profile
Name one explicitly, or let the client choose after the hello:
import {
connect, autoDetect, builtinDeviceProfiles, loadDeviceProfiles,
} from '@node-net/netconf';
// Auto-detect among your own profiles and the built-in ones
const profile = autoDetect([
...(await loadDeviceProfiles('./my-profiles')),
...(await builtinDeviceProfiles()),
]);
const client = await connect({ transport, profile });
// which one was chosen
client.profile.id;
// { type: 'builtin' | 'file' | 'inline', file? }
client.profile.source;When auto-detection chooses a profile whose status is unverified, such as the built-in nokia-sros-md, the client still uses it, but logs a warning naming it, since nobody has tested it against a device yet. Naming a profile explicitly logs nothing: you chose it knowingly.
Settings needed before the hello, such as the port, or a quirk like forceBaseVersion, only take effect when you name the profile explicitly:
const [nokia] = (await builtinDeviceProfiles())
.filter((p) => p.id === 'nokia-7210-sas');
const transport = ssh({
...nokia.connection, host, username, password, hostKey,
});
const client = await connect({ transport, profile: nokia });Using a profile
// a named path
await client.content.readValue('@systemName');
// a named path with a parameter
await client.content.readValue('@ifDescription(eth0)');
// a device operation
await client.ops.device.call('cli', { command: 'show version' });
// the same, by descriptor
await client.ops.run('cli', { command: 'show version' });
// follows the profile's workflow
await client.content.set('@systemName', 'router1');A profile's operations also appear in client.ops.list, after the base and extension operations, so tools built on descriptors, such as the CLI, list them automatically.
Inspecting a profile
A profile loaded from JSON keeps the definition it was compiled from as profile.definition. This is the effective definition: in the profile file format, with extends already merged. It includes each operation's request template and result rule, so you can show exactly what an operation sends without running it. The definition is read-only. A profile written in code with defineDeviceProfile() has none.
client.profile.definition?.operations?.cli;
// {
// description: 'Run an MD-CLI command…',
// params: { command: 'string' },
// request: '<md-cli-raw-command …>',
// result: { path: 'md-cli-output-block', as: 'text' },
// }
// the whole effective profile
JSON.stringify(client.profile.definition, null, 2);Built-in profiles
| Profile | Device | Status |
|---|---|---|
nokia-7210-sas | Nokia 7210 SAS, classic CLI | Verified read-only (TiMOS B-25.9.R5). See the profile's notes for the user access it needs. |
nokia-sros-md | Nokia SR OS, model-driven or mixed mode | Not yet verified |
sysrepo-netopeer2 | netopeer2 on sysrepo | Verified |
lab | The docs site's lab device, behind its TypeScript and nnc terminals | Named paths only, for the examples; never auto-detected |
The built-in profiles are in the package's profiles/ directory. Each has notes recording what was tested, and anything odd found along the way.
Have a device that isn't listed? Write a profile. If it works, please contribute it, along with the model and software version you tested.