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.
| Level | Shows |
|---|---|
bytes | the bytes of each read and write, framing included |
frames | each message as it was framed: its size, and eom or chunked |
xml | each message's XML, pretty-printed, with its kind and message-id |
nnc lab> trace xml
nnc lab> lock running
nnc lab> unlock running
nnc lab> trace offnnc 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 lab> trace bytes frames
nnc lab> get-config running --filter xpath /ietf-system:system/hostname
nnc lab> trace offA 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 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 ***:
<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.
nnc router1> trace frames xml --file router1.trace --quietFraming
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:
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 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 labThe 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:
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-replysend @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 lab> disconnect
nnc> connect lab --raw
nnc lab [raw]> received
nnc lab [raw]> disconnect
nnc> connect labsend 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:
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 streamnnc can't tell what you'll send in a framed or raw session, so a read-only target refuses both.
Next
- Output: how results are shown, and saved
- The session: errors, timeouts and closing