Skip to main content

Hubs

A hub lets nodes find and reach each other. Every node on a hub appears in the Nodes section of every other node's dashboard, and you can manage all of them, their pipelines and their networks, from any one of them.

There are two kinds of hub:

  • The cloud hub, hosted by NanoPing. Every organization has one, and nodes join it by themselves.
  • Your own hub, run by one of your nodes. Use it when nodes cannot reach the internet, or when you want the control plane on your own infrastructure.

A node is on one hub at a time.

The cloud hub​

When a node is activated, it joins your organization's cloud hub with the license it holds. There is nothing to approve and nothing to type. If the cloud hub cannot be reached, the node keeps working and joins when it can.

A node stays off the cloud hub when:

To put a node that is on no hub back on the cloud hub, open its Settings from the Nodes section, pick Hub Connection from the menu and click Join Cloud Hub. Clicking Connect to hub in the status bar gets you there too. The node needs a device license for it. From the command line:

sudo np cloud join

It waits up to 30 seconds for the node to connect, which --timeout changes. A node that has not connected by then keeps trying in the background.

To see whether a node is on the cloud hub, and why not when it is not:

sudo np cloud status

Hosting your own hub​

Any node can run a hub server. Add a hubServer section to its config file. A node that is on a hub, such as the cloud hub it joined when it was activated, has to leave it first: NanoPing does not start a node that is on a hub and runs a hub server, and stops with Hub can only be started as server or client, not both.

config.yaml
node:
  name: server

http:
  address: 0.0.0.0:8769

hubServer:
  authenticationByRequest:
    timeout: 5m

Other nodes join by sending a request, which you accept on the hub server. timeout is how long a request waits to be accepted. See Hub server for the other settings, and Mutual TLS to only accept nodes with a client certificate.

Versions

Upgrade your nodes together with the hub server. A hub server turns away nodes on a version of NanoPing too old for it, and its Nodes page shows them as Needs update. Not every release raises that bar, so a node one release behind its hub server often still joins.

Connecting a node​

  1. On the node that should join, open Nodes, click Settings on its row and pick Hub Connection from the menu. Clicking Connect to hub in the status bar gets you there too.
  2. Under Your own hub, enter the address of the hub server as the Hostname, for example 192.168.1.10:8769, keep http:// in front of it (or pick https://), and click Request to join. The button shows Awaiting approval... until the hub server answers.
  3. On the hub server's dashboard, open Nodes. The request shows at the top. Click Accept.

The node joins right away and shows up in the node list.

The same from the command line. On the node that should join:

sudo np authenticate-by-request http://192.168.1.10:8769

And on the hub server, to list the requests and accept one with Enter:

sudo np -c /path/to/config.yaml authentication-requests

Leaving a hub​

Open the node's Settings, pick Hub Connection from the menu, click Leave hub and confirm with Leave Hub. From the command line:

sudo np disconnect-from-hub

On the cloud hub, sudo np cloud leave does the same. It also stops a node that has not joined the cloud hub yet from joining it.

The node is removed from the hub's node list, and stays off every hub, including the cloud hub, until you join one again from Settings or with np cloud join.

When the hub cannot be reached​

If the hub does not answer, the dashboard asks whether to leave anyway. Leave Anyway disconnects the node. What happens to its entry on the hub depends on why the removal failed:

  • The hub could not be reached, for example because it is offline. The node retries the removal in the background for up to 7 days, across restarts. If the hub comes back in that time, the node disappears from its list by itself.
  • The hub refused, for example because it requires a client certificate the node does not have. Retrying will not help, so remove the node on the hub.

np disconnect-from-hub has nobody to ask, so it always leaves, and prints why the node could not be removed.

Removing a node​

On your own hub server, open Nodes, open the ⋯ menu on the node's row, choose Remove and confirm. This works whether or not the node is online. The node is disconnected at once and does not reconnect.

The hub server also removes nodes that have been offline for 30 days, such as wiped or decommissioned machines. See Pruning offline nodes to change the period.