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.
{
"$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:
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.
anyCapability | any of these capability URIs (the query part is ignored); a trailing * matches a prefix |
anyModule | any of these YANG modules advertised |
allModules | all 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:
editTarget | running or candidate |
lock | lock 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):
"paths": {
"interface": "/ietf-interfaces:interfaces/interface[name={{ifName}}]",
"portDesc": "/nokia-conf:configure/port[port-id=\"1/1/{{port}}\"]/description"
}| Placeholder | Value | Left out |
|---|---|---|
a predicate's whole value: [name={{p}}], [name="{{p}}"], [.={{p}}] | quoted for you | a 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 quote | fails |
| anywhere else, such as a step's name | letters, digits, _, - and . only | fails |
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):
"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.
description | shown in tools such as the CLI |
params | each parameter's type: string, number or boolean, with ? for optional |
request | the operation element, with {{param}} placeholders |
result | path: /-separated element names, relative to <rpc-reply>. as: text, element, object or reply |
mutates | false 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:
{
"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
- Test it against a real device, read-only first. Record the model and software version in
testedWith, and setstatustoverified. - Record in
notesanything surprising: user permissions the device needs, filters it rejects, errors it gets wrong. - Open a pull request that adds the file to
profiles/.