Config file

Every node can be given a YAML config file. It sets the node's name and HTTP address, turns on services such as the hub server and the APIs, and configures TLS.

Pass the file with -c on every command:

sudo np -c /path/to/config.yaml up
sudo np -c /path/to/config.yaml down

If a config.yaml is in the working directory, np picks it up without -c.

Config file and dashboard

Settings in the file win. The node merges the file over its stored settings every time it reads them, so a setting that is in the file cannot be changed from the dashboard: saving it there is refused with a message naming the setting. Settings that are not in the file can be changed from the dashboard as usual.

Example

config.yaml
node:
  name: server # Defaults to the hostname

errorReporting:
  allow: true

http:
  address: 127.0.0.1:8769

hubServer:
  authenticationByRequest:
    timeout: 5m

restApi:
  address: 127.0.0.1:10565

Sections

Section	Purpose
`node`	The node's `name`, shown in the dashboard and to other nodes.
`http`	The dashboard address, or none, basic authentication, TLS and mutual TLS.
`errorReporting`	`allow: true` lets the node send error reports to the NanoPing team.
`hubServer`	Runs a hub server on this node.
`cloudHub`	Whether the node joins the NanoPing cloud hub.
`hubClientCertificate`	The client certificate the node presents to a hub server that requires one.
`verifyHubServerCertificate`	Whether the node verifies the certificate of a hub server of your own.
`grpcBridge`	Serves the gRPC API.
`restApi`	Serves the REST API.
`pipelines`	Pipeline runtime settings, see Pipelines.
`networks`	Keeps networks on this node.
`defaultNetworkCarriers`	The carriers this node gets when it joins a network.

HTTP

http.address is where the node serves its dashboard. The --http flag of np up sets it too.

http:
  address: 127.0.0.1:8769

To reach the dashboard from other machines, listen on an address they can reach, such as 0.0.0.0:8769, and turn on basic authentication and TLS.

Without an HTTP address

A node on a hub does not need an address of its own, as one node's dashboard controls every node on the hub. Set listen: false, or start the node with np up --no-http, and it opens no port for its dashboard:

http:
  listen: false

The node is then reached only through another node's dashboard, so put it on a hub. A hub server cannot run without its address, as joining nodes connect to it, and refuses to start. np up refuses --http together with --no-http, and --tls, --certificate and --private-key whenever the node has no address.

Headless builds, which come without a dashboard, never open the port unless they run a hub server.

Basic authentication

http:
  address: 127.0.0.1:8769
  basicAuth:
    username: admin
    password: change-me

The dashboard then asks for the username and password on a login page. A login lasts six hours, or until the credentials change or the node restarts. Setting, changing or removing the credentials takes a restart of the node, and removing the section turns authentication off.

The login protects the node's own address. Other nodes on the hub, reached through its dashboard, do not ask again.

TLS

http:
  address: 127.0.0.1:8769
  tls: true

With only tls: true the node signs its own certificate, and browsers show a warning. To avoid it, give the node a certificate your browser trusts. Both files must be in PEM format:

http:
  address: 127.0.0.1:8769
  tls: true
  certificate:
    certificate: /path/to/certificate.pem
    privateKey: /path/to/private-key.pem

mkcert is an easy way to make a locally trusted certificate:

# Arch: pacman -S mkcert    macOS and Linux: brew install mkcert
mkdir certificates && cd certificates
mkcert -install -ecdsa localhost 127.0.0.1 ::1

This writes a certificate and a key file, and -install adds mkcert's CA to your system and browsers. Add more hostnames or IP addresses to the command if you reach the node by other names.

Verifying a hub server's certificate

A node always verifies the cloud hub's certificate. A hub server of your own often signs its own certificate, so by default a node accepts any certificate it presents. Once yours has one the node's system trusts, such as one from a public CA or from mkcert with its CA installed on the node, make the node verify it:

verifyHubServerCertificate: true

A node that cannot verify the certificate does not sign in or connect. Signing in to a hub does not change this setting.

Mutual TLS (mTLS)

With mutual TLS, a hub server only accepts nodes that present a client certificate signed by a CA you choose. This comes on top of the normal access token check, and requires TLS with a certificate.

On the hub server, point http.clientAuth.clientCa at the CA and set hubServer.requireClientCertificate:

http:
  address: 127.0.0.1:8769
  tls: true
  certificate:
    certificate: /path/to/server-certificate.pem
    privateKey: /path/to/server-private-key.pem
  clientAuth:
    clientCa: /path/to/client-ca.pem

hubServer:
  authenticationByRequest:
    timeout: 5m
  requireClientCertificate: true

The dashboard keeps working without a client certificate: the server only checks a certificate when one is presented, and requireClientCertificate demands one only from nodes joining the hub. To make the whole HTTP server, dashboard included, refuse connections without a valid client certificate, add required: true:

http:
  clientAuth:
    clientCa: /path/to/client-ca.pem
    required: true

On each node, set the certificate it presents to the hub server:

hubClientCertificate:
  certificate: /path/to/client-certificate.pem
  privateKey: /path/to/client-private-key.pem

The node presents it on every call to the hub. A node without a certificate, or with one the CA did not sign, is rejected.

All certificates must be signed by the CA in clientCa. With mkcert:

mkcert -ecdsa localhost 127.0.0.1 ::1        # server certificate (http.certificate)
mkcert -ecdsa -client my-node                # client certificate (hubClientCertificate)
echo "$(mkcert -CAROOT)/rootCA.pem"          # the CA (http.clientAuth.clientCa)

note

requireClientCertificate needs http.clientAuth.clientCa. Without it there is nothing to check certificates against, and the hub server logs a warning at startup.

Hub server

The hubServer section runs a hub server on the node.

Setting	Description
`authenticationByRequest.timeout`	How long a node's request to join waits for approval, for example `5m`.
`requireClientCertificate`	Only accept nodes with a verified client certificate, see Mutual TLS.
`pruneOfflineNodesAfter`	How long a node may stay offline before the hub server removes it. Defaults to `720h` (30 days).

Pruning offline nodes

A node that leaves the hub removes itself from the node list. A node that is wiped or decommissioned never does, so the hub server removes nodes that have been offline for longer than pruneOfflineNodesAfter:

hubServer:
  pruneOfflineNodesAfter: 168h

The value is a number followed by s, m or h, for example 720h (30 days), 24h or 90m. Set it to "0" to never remove offline nodes. Nodes that have never connected are never removed.

Cloud hub

A licensed node joins the NanoPing cloud hub on its own, unless it is connected to another hub or runs a hub server. To keep it off the cloud hub:

cloudHub:
  enabled: false

APIs

The gRPC API and the REST API are off by default. Each gets its own address, and either can run without the other:

grpcBridge:
  address: 127.0.0.1:10564

restApi:
  address: 127.0.0.1:10565

The --grpc and --rest-api flags of np up set the same addresses. See API for how to use them.

Pipelines

Setting	Description
`pipelines.metricDecimalPlaces`	How many decimals the dashboard shows metric values with. Defaults to `2`.
`pipelines.telemetryPollIntervalMs`	How often, in milliseconds, the node collects metrics from running pipelines. Defaults to `1000`.

Example​

Sections​

HTTP​

Without an HTTP address​

Basic authentication​

TLS​

Verifying a hub server's certificate​

Mutual TLS (mTLS)​

Hub server​

Pruning offline nodes​

Cloud hub​

APIs​

Pipelines​