Skip to content

Watching the wire ​

nnc shows exactly what crosses the wire, at three levels, and lets you take over the protocol yourself when you want to see how a server answers something the library would never send.

Tracing ​

trace turns on one or more levels, and trace off turns them off. Tracing never changes what's sent.

LevelShows
bytesthe bytes of each read and write, framing included
frameseach message as it was framed: its size, and eom or chunked
xmleach message's XML, pretty-printed, with its kind and message-id
nnc
nnc lab> trace xml
nnc lab> lock running
nnc lab> unlock running
nnc lab> trace off
Output
nnc lab> lock running
>> 10:00:47.255 xml 153 B rpc message-id=47
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="47">
  <lock>
    <target>
      <running/>
    </target>
  </lock>
</rpc>
<< 10:00:47.255 xml 130 B rpc-reply message-id=47
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="47">
  <ok/>
</rpc-reply>
ok

>> is sent and << received. Levels combine, and bytes shows the chunk headers of base 1.1's chunked framing:

nnc
nnc lab> trace bytes frames
nnc lab> get-config running --filter xpath /ietf-system:system/hostname
nnc lab> trace off

A trace shows everything the library sends, not only your commands: the first JSON filter or edit of a session, for example, fetches the device's YANG modules with get-schema to convert it.

Secrets ​

A trace hides the values of password-like elements, so it can be shared:

nnc
nnc lab> trace xml
nnc lab> set /ietf-system:system/authentication/user[name="ops"]/password $0$pw
nnc lab> trace off
nnc lab> remove /ietf-system:system/authentication/user[name="ops"]

The edit-config that set sends shows the password as ***:

Output
        <authentication>
          <user>
            <name>ops</name>
            <password>***</password>
          </user>
        </authentication>

trace xml --no-redact shows them, and the prompt is marked [no-redact] for as long as it lasts.

To a file ​

trace … --file <path> writes the trace to a file as well; --quiet writes it only there. In a script, the trace goes to standard error, apart from the results on standard output.

Output
nnc router1> trace frames xml --file router1.trace --quiet

Framing ​

NETCONF over SSH frames each message one of two ways (RFC 6242): base 1.0 ends each with ]]>]]>, and base 1.1 sends it in chunks, each with its length in a header. The hello is always framed the base 1.0 way. Both sides switch to chunks after it if both offer base 1.1. status shows the framing in use: chunked on the lab device, eom on a device that offers only base 1.0.

A reply larger than the target's maxMessageBytes, or nested deeper or with more elements than its parseLimits allow, ends the session, so a broken or hostile server can't exhaust nnc's memory:

Output
get-config: Message exceeds maxMessageBytes (1000000)

Framed sessions ​

A framed session handles SSH and framing, and leaves everything else to you: the hello, message-ids, and the <rpc> wrapper. Use it to see how a server answers a message the library would never send, such as a malformed RPC or two requests at once.

nnc
nnc lab> disconnect
nnc> connect lab --framed
nnc lab [framed eom]> hello --base 1.1
nnc lab [framed eom]> framing chunked
nnc lab [framed chunked]> show
nnc lab [framed chunked]> disconnect
nnc> connect lab

The server's hello arrives as soon as the session opens. hello sends a standard client hello, and framing chunked switches to chunked framing. send frames and sends one message exactly as typed, and the server's reply arrives as a numbered message:

Output
nnc lab [framed chunked]> send <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><lock><target><running/></target></lock></rpc>
sent 126 bytes (framed, chunked)
message 2 · rpc-reply · 131 B
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
  <ok/>
</rpc-reply>
nnc lab [framed chunked]> show
1  10:00:34.908  3356 B  hello
2  10:00:34.913   131 B  rpc-reply

send @file sends a file's XML, and send --edit opens $EDITOR. server-hello shows the server's hello again, and show <n> any message. Send an RPC before the hello, and the server closes the session.

Raw sessions ​

A raw session leaves framing to you as well. nnc opens the SSH netconf subsystem, or the TLS stream, and writes exactly the bytes you give it:

nnc
nnc lab> disconnect
nnc> connect lab --raw
nnc lab [raw]> received
nnc lab [raw]> disconnect
nnc> connect lab

send writes text, with \n, \r, \t, \\ and \xHH escapes. send-hex writes bytes given in hex, and send-file a file's bytes, for reproducing a framing defect byte for byte. received shows everything received, and eof closes your side of the stream:

Output
nnc lab [raw]> send <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><capabilities><capability>urn:ietf:params:netconf:base:1.0</capability></capabilities></hello>]]>]]>
sent 155 bytes (raw)
nnc lab [raw]> send <rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><close-session/></rpc>]]>]]>
sent 96 bytes (raw)
<< 136 bytes
<?xml version="1.0" encoding="UTF-8"?><rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1"><ok/></rpc-reply>\n
]]>]]>
raw session to lab ended: the server closed the stream

nnc can't tell what you'll send in a framed or raw session, so a read-only target refuses both.

Next ​

Released under the MIT Licence.