Skip to content

Writing a profile ​

A profile is a JSON file, checked against profile.schema.json when it's loaded. Errors name the field at fault. Start the file with a $schema line, and your editor will autocomplete and check it as you type.

json
{
  "$schema": "./node_modules/net-netconf/profiles/profile.schema.json",
  "id": "acme-edge",
  "vendor": "Acme",
  "description": "Acme Edge routers, firmware 4.x",
  "status": "verified",
  "testedWith": [{ "model": "Edge 400", "version": "4.2.1" }],
  "notes": ["Rejects subtree filters below the second level."],

  "match": { "anyModule": ["acme-system"] },
  "connection": { "port": 830 },
  "quirks": { "subtreeFilter": "containers", "subtreeFilterDepth": 2 },
  "capabilities": { "add": [], "remove": [] },
  "workflow": {
    "editTarget": "candidate",
    "lock": true,
    "validate": true,
    "commit": true
  },
  "namespaces": { "acme-extra": "urn:acme:extra" },
  "paths": { "systemName": "/acme-system:system/name" },
  "operations": {
    "cli": {
      "description": "Run a CLI command and return its output",
      "mutates": false,
      "params": { "command": "string" },
      "request": "<cli xmlns=\"urn:acme:cli\"><cmd>{{command}}</cmd></cli>",
      "result": { "path": "output", "as": "text" }
    }
  }
}

Load it:

ts
import { loadDeviceProfile, loadDeviceProfiles } from '@node-net/netconf';

const profile = await loadDeviceProfile('./profiles/acme-edge.json');
// every profile in a directory
const all = await loadDeviceProfiles('./profiles');

Only id is required. Leave out anything the device doesn't need.

Fields ​

match ​

Rules for auto-detection, checked against the server's hello. If you give more than one group, they must all match.

anyCapabilityany of these capability URIs (the query part is ignored); a trailing * matches a prefix
anyModuleany of these YANG modules advertised
allModulesall of these YANG modules advertised

Prefer modules unique to the vendor or platform. If two profiles could match, make the more specific one extends the other.

connection ​

Defaults for ssh(): port, subsystem, command, keepaliveInterval, keepaliveCountMax and algorithms. These are needed before the hello, so they only take effect when the profile is named explicitly.

quirks ​

Named switches for the ways a device departs from the RFCs. See Quirks.

capabilities ​

add and remove correct a server that advertises too much or too little. Capability checks then use the corrected set.

workflow ​

How set(), remove() and configure() apply changes on this device:

editTargetrunning or candidate
locklock the target while editing
validate<validate> before committing (candidate only)
commit<commit> after editing (candidate only)

Anything left out comes from what the server advertises. See How changes are applied.

namespaces ​

Module name to namespace, for modules the server uses but doesn't advertise, or advertises with the wrong namespace. These beat the server's hello and YANG library, and connect({ namespaces }) beats these. See Where namespaces come from.

paths ​

Named YANG paths, usable as @name anywhere a path is accepted: client.content.readValue('@systemName').

A path may hold {{param}} placeholders, filled in as @name(value, param=value):

json
"paths": {
  "interface": "/ietf-interfaces:interfaces/interface[name={{ifName}}]",
  "portDesc": "/nokia-conf:configure/port[port-id=\"1/1/{{port}}\"]/description"
}
PlaceholderValueLeft out
a predicate's whole value: [name={{p}}], [name="{{p}}"], [.={{p}}]quoted for youa read drops the predicate and selects every entry; a change fails
part of a quoted value: [port-id="1/1/{{p}}"]inserted as is; may not hold that quotefails
anywhere else, such as a step's nameletters, digits, _, - and . onlyfails

Templates are checked when the profile loads. Names can't hold ( or ). See Named paths with parameters.

yang ​

Optional. YANG schemas for JSON conversion (format: 'json', and JSON config and filters):

json
"yang": { "modules": ["yang"], "requireSchema": true }

modules lists directories of YANG modules the server uses but can't serve with <get-schema>, relative to the profile file. They are used after any given to connect({ yang }) and before the bundled IETF modules. requireSchema refuses a schema-less conversion for this device, unless the connection or the call says otherwise. A profile that extends another replaces each field it gives.

operations ​

Vendor RPCs as XML templates. The name must be a valid identifier.

descriptionshown in tools such as the CLI
paramseach parameter's type: string, number or boolean, with ? for optional
requestthe operation element, with {{param}} placeholders
resultpath: /-separated element names, relative to <rpc-reply>. as: text, element, object or reply
mutatesfalse if the operation only reads

A template is parsed once, when the profile loads. A {{param}} can only be a whole text node or a whole attribute value, so values are always escaped and can't inject XML.

Mark read-only operations

An operation without "mutates": false counts as possibly changing state, so tools that protect read-only devices, such as nnc with a read-only target, refuse it. Set it on every operation that only reads.

An operation can't have the same name as a base operation, or as an operation from an enabled extension. connect() refuses a profile with such a clash.

Documentation fields ​

vendor, description, status (verified once tested against a real device), testedWith (model and version) and notes aren't used by the client, except that auto-detecting an unverified profile logs a warning. They tell the next person what was tested and what was found along the way.

Inheritance ​

extends names another profile to build on. Each section is merged key by key. In operations, a child operation with a request replaces the inherited one. Without a request, it changes only the fields it gives:

json
{
  "id": "nokia-sros-md-show-only",
  "extends": "nokia-sros-md",
  "quirks": { "subtreeFilter": "unsupported" },
  "operations": {
    "cli": { "description": "Run an MD-CLI show command", "mutates": false }
  }
}

Only mark an inherited operation "mutates": false if, for your users, it really can only read. Here, that's because the device's user profile only allows show commands.

When JSON isn't enough ​

The line sits at "templates plus extraction". An operation that needs real logic, such as several requests in sequence or post-processing, goes in a TypeScript profile made with defineDeviceProfile(), which can extend a JSON one. A behaviour no quirk covers needs a new quirk in the library: please open an issue with a capture of what the server sends.

Contributing a profile ​

  1. Test it against a real device, read-only first. Record the model and software version in testedWith, and set status to verified.
  2. Record in notes anything surprising: user permissions the device needs, filters it rejects, errors it gets wrong.
  3. Open a pull request that adds the file to profiles/.

Released under the MIT Licence.