Skip to content

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
nnc> connect lab
nnc lab> status

The 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:

Output
nnc lab> connect lab
already connected to lab (client session); disconnect first

The 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:

json
{
  "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:

Output
nnc> connect router1-env
the password for netconf@192.0.2.10 comes from $ROUTER1_PW, which is not set

A prompt doesn't echo, and a wrong password is reported as such, once, with no second prompt (exit code 3 in a script):

Output
nnc> connect router1-ask
Password for netconf@192.0.2.10:
authentication failed for user netconf at 192.0.2.10:830

Passwords 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:

json
{
  "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:

Output
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:

Output
nnc> connect router1-agent
netconf@192.0.2.10 uses the SSH agent, but SSH_AUTH_SOCK is not set

With 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:

Output
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_hosts

A key that has changed is refused with the line that removes the old one:

Output
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_hosts

Pinning 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.

json
{
  "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:

Output
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.json

Not 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:

Output
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:

json
{
  "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:

Output
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:

Output
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:

Output
nnc> connect 192.0.2.30 --tls --cert me.pem --key me.key --ca ca.pem

A 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:

Output
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-sas

A 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
nnc lab> disconnect
nnc> connect lab --read-only
nnc lab [ro]> get-config running
nnc lab [ro]> disconnect
nnc> connect lab

While it's read-only, a change is refused locally, and nothing is sent:

Output
nnc lab [ro]> set /ietf-system:system/location rack-7
set: refused: lab is read-only and set changes device state; nothing was sent

Read-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:

Failurennc says
No route, refused, timed outcannot reach <host>:<port>: …
Wrong credentialsauthentication failed for user <user> at <host>:<port>
Host key unknown, changed, or not the pinnot connected: host key for …, with the fix
A jump hostfailed at jump host <hop>: …
No hello from the serverhello 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.

Released under the MIT Licence.