Skip to content

The session ​

Once connected, nnc shows what the server said in its hello, sends any operation you give it, and reports the server's errors field by field. The examples run against the lab device in the terminal at the bottom of the page.

What the server offers ​

status shows the session: the target, transport, session-id, the NETCONF base version agreed in the hello, the framing, the device profile, and any locks, confirmed commit, transaction or subscriptions open:

nnc
nnc lab> status

hello shows the server's <hello> as received, and capabilities lists its capability URIs, after any corrections the device profile makes:

nnc
nnc lab> hello
nnc lab> capabilities

The lab device offers base 1.0 and 1.1, so the session uses 1.1, with chunked framing. A device that offers only 1.0 gets end-of-message framing; see Watching the wire.

YANG modules and datastores ​

modules lists the YANG modules the device implements, with their revisions and the features it supports. On a server with a YANG library (RFC 8525) the list comes from there; otherwise from the hello. The first lines say which:

nnc
nnc lab> modules
nnc lab> modules ietf-system
nnc lab> datastores
Output
Source: YANG library
Datastore: running
Schema: complete

MODULE       REVISION    CONFORMANCE  FEATURES
───────────────────────────────────────────────────────────────────
ietf-system  2014-08-06  implement    authentication,dns-udp-tcp-port,…

modules --all-features reads each module's source and lists every feature it declares, supported or not. yang-library shows the YANG library itself; see Server data.

Any RPC ​

rpc sends any operation as XML. nnc adds the <rpc> wrapper and the message-id, and shows the reply:

nnc
nnc lab> rpc <get-config><source><running/></source></get-config>

Inline XML needs no quoting, and may span lines when pasted: the prompt keeps reading until its elements balance. rpc @get-system.xml reads it from a file. Every standard operation also has its own command, with options and Tab completion; see Configuration.

Errors ​

An <rpc-error> prints as a block on standard error, with only the fields the server sent: its error-type, error-tag, error-severity, error-app-tag, error-path, error-message and error-info. Creating a leaf that already exists, for example:

Output
nnc lab> edit-config candidate <system xmlns="urn:ietf:params:xml:ns:yang:ietf-system" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"><hostname nc:operation="create">x</hostname></system>
rpc-error: data-exists
  type      application
  severity  error
  path      /ietf-system:system/ietf-system:hostname
  message   leaf hostname can't be created: it already exists

A reply with several errors numbers them, rpc-error 1 of 2: …, and one that names the session holding a lock shows it in info:

Output
rpc-error 1 of 2: lock-denied
  type      protocol
  severity  error
  message   Lock failed, lock is already held
  info      session-id 7

show-last shows the last result or error again, and show-last --raw the reply exactly as received. A reply that succeeds with warnings (error-severity warning) shows the result, then each warning.

Checked before sending ​

An operation that needs a capability the server didn't advertise is refused before it's sent, naming the capability. The lab device can't copy a configuration to or from a URL:

Output
nnc lab> copy-config file:///tmp/backup.xml running
copy-config requires the :url capability, which the server didn't advertise; nothing was sent

A target's capabilityCheck changes this: "warn" sends it anyway with a warning, and "off" just sends it, to see what the server does.

Timeouts and cancelling ​

Every request takes --timeout <ms>. When it runs out, the request is abandoned, and the session stays open:

Output
nnc router1> get --timeout 2000
get: no reply within 2000 ms; the session is still open

Ctrl-C cancels the command in progress the same way. A target's timeouts sets the defaults for connect, hello, rpc and close.

Ending the session ​

disconnect sends <close-session> and closes the connection. If the server doesn't answer in time, nnc closes the connection anyway, and says so:

Output
nnc router1> disconnect
disconnected from router1 (no reply to <close-session> in time; the connection was closed anyway)

When the server ends the session, for another session's kill-session or a restart, nnc says so above the prompt, with the reason, and the prompt goes back to nnc>.

Messages between commands ​

A server can send at any time: notifications, and messages nnc can't match to a request. Each shows as a line above the prompt, and whatever you were typing is redrawn below it, still there:

Output
notification 4 · 2026-11-14T10:00:02Z · netconf-config-change
warning: Received an <rpc-reply> for unknown message-id "999999"
nnc router1> get-config runn

Next ​

Released under the MIT Licence.