Skip to content

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:

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

ts
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 ​

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

ts
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 ​

ProfileDeviceStatus
nokia-7210-sasNokia 7210 SAS, classic CLIVerified read-only (TiMOS B-25.9.R5). See the profile's notes for the user access it needs.
nokia-sros-mdNokia SR OS, model-driven or mixed modeNot yet verified
sysrepo-netopeer2netopeer2 on sysrepoVerified
labThe docs site's lab device, behind its TypeScript and nnc terminalsNamed 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.

Released under the MIT Licence.