Skip to content

Call home ​

Devices behind NAT or a firewall can open the connection to you instead (RFC 8071). Only the TCP connection is reversed: you are still the SSH or TLS client, and still the NETCONF client.

listenCallHome() listens on port 4334 (SSH) and 4335 (TLS), and gives you an ordinary client for each device that calls:

Node.js
import { listenCallHome } from '@node-net/netconf';

const devices = new Map([
  ['SHA256:Ab12…', {
    name: 'router1',
    username: 'admin',
    password: () => vault.get('router1'),
  }],
]);

await using listener = await listenCallHome({
  // port 4334
  ssh: {},
  // port 4335; one client certificate for every call
  tls: { cert, key, ca },
  // undefined refuses the caller
  identify: (caller) => devices.get(caller.fingerprint),
});

listener.on('rejected', (e) => {
  console.warn('refused call home', e.remote, e.reason);
});
listener.on('failed', (e) => {
  console.warn('call home failed', e.remote, e.error.message);
});

for await (const { client, device } of listener) manage(device.name, client);

Identifying devices ​

A device is identified by its SSH host key or TLS certificate (caller.fingerprint, SHA256:…), never by its address.

Over SSH, identify runs only after the handshake has proved that the device holds its host key. The credentials it returns are the only ones sent, so an unknown caller gets nothing. The device entry can also give its own connect options, such as a profile or extensions.

Limits ​

These limits protect the open port:

Option
maxPendingcalls being set up at once
handshakeTimeouthow long a call may take to become a session
maxQueuedclients waiting for you to take them from the iterator

Watching a call ​

wrapConnection(connection, caller) receives each identified call's connection before the NETCONF hello and returns the one the client should use, so a tool can record or trace what passes over it. If it throws, the call fails (a failed event).

The CLI's listen command uses this listener: it waits for one target to call, checking the caller with the same host-key and certificate rules as connect.

Released under the MIT Licence.