Connecting
connect opens one session to a target. A target is a device named in your targets file, or an ad hoc user@host[:port]. This page shows what nnc does at each step of connecting, and what it says when a step fails.
The terminal on this site has no network, so its only target is the simulated lab device. Connect to it, and see the session:
nnc> connect lab
nnc lab> statusThe examples below that reach real devices show what nnc prints. Device names and addresses in them are examples.
One session at a time
nnc holds one session. A second connect is refused until you disconnect:
nnc lab> connect lab
already connected to lab (client session); disconnect firstThe prompt names the target, and marks what's special about the session: [ro] for read-only, [insecure] for an unverified host key, [framed eom] or [raw] for the lower-level sessions.
SSH passwords
A target's password comes from a file, an environment variable or a prompt, never from the command line or the targets file itself:
{
"router1": {
"host": "192.0.2.10", "username": "netconf",
"password": { "file": "~/.config/net-netconf/router1.pass" }
},
"router1-env": {
"host": "192.0.2.10", "username": "netconf",
"password": { "env": "ROUTER1_PW" }
},
"router1-ask": {
"host": "192.0.2.10", "username": "netconf",
"password": { "prompt": true }
}
}A password from a file or a variable is read without a prompt. An unset variable is refused before anything is sent:
nnc> connect router1-env
the password for netconf@192.0.2.10 comes from $ROUTER1_PW, which is not setA prompt doesn't echo, and a wrong password is reported as such, once, with no second prompt (exit code 3 in a script):
nnc> connect router1-ask
Password for netconf@192.0.2.10:
authentication failed for user netconf at 192.0.2.10:830Passwords never appear in history or in a trace.
SSH keys and the agent
A target can name a private key, with its passphrase from a file, a variable or a prompt:
{
"router1-key": {
"host": "192.0.2.10", "username": "netconf",
"privateKey": "~/.ssh/netconf_ed25519",
"passphrase": { "prompt": true }
}
}The key is decrypted before connecting, so a wrong passphrase is reported without trying the device:
nnc> connect router1-key
Passphrase for key ~/.ssh/netconf_ed25519:
the private key ~/.ssh/netconf_ed25519 could not be decrypted (wrong passphrase?)If the device refuses the key, nnc falls back to a password prompt, as OpenSSH does.
The SSH agent ($SSH_AUTH_SOCK) is used by a target with no password and no key. A target with either uses it only with "agent": true, and never with "agent": false. Each key offered counts against the device's limit of failed logins, and routers lock accounts out, so nnc doesn't offer agent keys a target didn't ask for. A target that asks for the agent when there is none is refused before connecting:
nnc> connect router1-agent
netconf@192.0.2.10 uses the SSH agent, but SSH_AUTH_SOCK is not setWith no password, key or agent, nnc prompts for a password.
Host keys
nnc checks the device's host key before sending any credentials. By default the key must be in ~/.ssh/known_hosts; a target's knownHosts names another file. A host that isn't listed is refused, with the fingerprint received and the line that adds it:
nnc> connect router1
not connected: host key for 192.0.2.10:830 is not in /home/you/.ssh/known_hosts
received fingerprint SHA256:Qx3c…
check it with the device's administrator, then add it with: ssh-keyscan -p 830 192.0.2.10 >> /home/you/.ssh/known_hostsA key that has changed is refused with the line that removes the old one:
nnc> connect router1
not connected: host key for 192.0.2.10:830 does not match /home/you/.ssh/known_hosts
received fingerprint SHA256:Qx3c…
if the key changed legitimately, remove the old entry with: ssh-keygen -R '[192.0.2.10]:830' -f /home/you/.ssh/known_hostsPinning a key
A target's hostKey can pin the key instead: a SHA256: fingerprint, a public key line, or a list of them, any one of which is accepted. Only the pin is checked, so knownHosts can't be used with one.
{
"router1": {
"host": "192.0.2.10", "username": "netconf",
"password": { "prompt": true },
"hostKey": "SHA256:5jz6plf3ShmbYvtqc5V1AkhDFzVWxR8aNWO1b+iLZnc"
}
}status shows the key as (pinned). A malformed pin is an error when the targets file is read, and a key that doesn't match the pin is refused, naming the target to update:
nnc> connect router1
not connected: host key for 192.0.2.10:830 does not match the target's pinned hostKey
received fingerprint SHA256:Qx3c…
if the key changed legitimately, update hostKey for router1 in /home/you/.config/net-netconf/targets.jsonNot checking the key
"hostKey": "insecure-accept-any" accepts any key, for lab devices whose keys change with every rebuild. nnc warns with the fingerprint it received, and marks the session [insecure] until it ends:
nnc> connect lab1
warning: the host key of 192.0.2.20:830 was not verified (hostKey is insecure-accept-any); received fingerprint SHA256:D8c/…
connected to lab1 (192.0.2.20:830) · session-id 7 · base:1.1 · no profile matched · insecure
nnc lab1 [insecure]> status
...
host key SHA256:D8c/… (not verified: insecure-accept-any)Jump hosts
jumpHost reaches a device through one SSH host, or a list of them in order. Each hop has its own username, authentication and host-key check:
{
"router2": {
"host": "10.0.0.2", "username": "netconf",
"password": { "file": "~/.config/net-netconf/router2.pass" },
"jumpHost": { "host": "jump1", "username": "me", "agent": true },
"readOnly": true
}
}The connected line and status show the route:
nnc> connect router2
connected to router2 (10.0.0.2:830 via jump1:22) · session-id 57 · base:1.1 · profile nokia-7210-sas · read-only
nnc router2 [ro]> status
target router2
host 10.0.0.2:830 via jump host jump1:22
...A failure names the hop at fault, whether the jump host can't be reached or the jump host can't reach the device:
failed at jump host jump1:2222: connection refused
failed at jump host jump1:22: it could not reach 10.0.0.2:831 (connection refused)TLS
A target with "transport": "tls" connects with NETCONF over TLS (RFC 7589). The client certificate is the credential, so there is no username or password. The server is verified by a CA (ca), by its certificate's fingerprint (fingerprint), or not at all ("insecure": "insecure-accept-any"). serverName is the name its certificate must carry, if it isn't host. See TLS targets.
For a one-off session, give the files on the command line:
nnc> connect 192.0.2.30 --tls --cert me.pem --key me.key --ca ca.pemA server certificate that doesn't verify, and a client certificate the server refuses, are reported as such, with no password prompt.
Call home
Some devices connect to you instead (RFC 8071). listen <target> waits for the target's device to call, on port 4334 for SSH or 4335 for TLS, and the call becomes a client session exactly as connect would make it:
nnc> listen router1
listening for router1 on 0.0.0.0:4334 (ssh); Ctrl-C stops waiting
refused a call from 192.0.2.9:50122: unknown device (SHA256:Qx…); not the host key /home/you/.ssh/known_hosts lists for router1:830
router1 called home from 192.0.2.7:41234 · session-id 12 · base:1.1 · profile nokia-7210-sasA caller must prove it is the target, with the same host-key or certificate checks as connect. Its address is never trusted. See Call home for the options.
Read-only sessions
A target with "readOnly": true, or connect <target> --read-only, refuses anything that could change the device, before it's sent. Try it on the lab device:
nnc lab> disconnect
nnc> connect lab --read-only
nnc lab [ro]> get-config running
nnc lab [ro]> disconnect
nnc> connect labWhile it's read-only, a change is refused locally, and nothing is sent:
nnc lab [ro]> set /ietf-system:system/location rack-7
set: refused: lab is read-only and set changes device state; nothing was sentRead-only lists what is refused, including rpc and device profile operations.
When connecting fails
Each kind of failure has its own message and exit code 3, so a script can tell them apart from a device's rpc-error:
| Failure | nnc says |
|---|---|
| No route, refused, timed out | cannot reach <host>:<port>: … |
| Wrong credentials | authentication failed for user <user> at <host>:<port> |
| Host key unknown, changed, or not the pin | not connected: host key for …, with the fix |
| A jump host | failed at jump host <hop>: … |
| No hello from the server | hello exchange failed: no hello from <host>:<port> (hello timed out after 30000 ms) |
connect --timeout <ms> shortens the wait for a device that doesn't answer. A target's timeouts sets the waits for connect, hello, rpc and close separately.