Skip to main content

Config file

The config file makes it possible to customize the NanoPing application to fit your needs. It's also possible to start services such as the hub server, that let's NanoPing nodes connect with each other. The configuration file is written in YAML format.

Basic Usage​

Use the provided example configuration (config.example.yaml) or copy the following as your starting point:

config.yaml
node:
  name: server # Can be left out, will be hostname if not set

errorReporting:
  allow: true

http:
  address: 127.0.0.1:8769

  # To enable basic HTTP authentication, uncomment the following lines and set the username and password
  #basicAuth:
  #  username: admin
  #  password: admin

  # Uncomment the line to enable tls.
  #tls: true

  # Add custom certificates. The certificates must be in pem format.
  # You must provide the path to the certificate and private key.
  #certificate:
  #  certificate: "/path/to/certificate.pem"
  #  privateKey: "/path/to/private-key.pem"

hubServer:
  authenticationByRequest:
    timeout: 5m

# To enable the gRPC bridge, uncomment the following lines
#grpcBridge:
#  address: 127.0.0.1:10564

# If you run the executable from a working directory containing a `config.yaml` file
sudo np [cmd]

# If you run the executable from a different working directory, specify the config file.
# Importantly that every command needs the -c flag to specify the config file, therefore
# it easier to create a `config.yaml` file in the working directory.
sudo np -c /path/to/config.yaml [cmd]

Start the gRPC API Server​

To serve the gRPC API on a specific port (e.g., 10432), add the following to the configuration file:

... my other config

grpcBridge:
  address: 127.0.0.1:10564

Enable HTTP Basic Authentication​

To enable HTTP Basic Auth, add the following section to the http configuration:

http:
  address: 127.0.0.1:8769

  # Enable HTTP Basic Auth
  basicAuth:
    username: "admin"
    password: "admin"

Enable TLS​

To enable HTTPS, you have to add the following inside the http configuration:

http:
  address: 127.0.0.1:8769

  tls: true

This will start NanoPing with tls enable and the application will self sign a certificate. If you want an authorized connection where you will not get a browser warning, then you have to provide your own certificate.

Providing custom certificates​

In addition to the previous snippet you will have to specify a path to the certificate and the private key.

http:
  address: 127.0.0.1:8769

  tls: true
  certificate:
    certificate: "/path/to/your/certificate.pem"
    privateKey: "/path/to/your/privatekey.pem"

An easy method to get started with custom certificates is to use the mkcert tool. If you want to utilize your own certificates, do note that they must be in pem format.

The tool can be found in arch distributions and brew. If using another OS, check the mkcert installation guide on the mkcert git repository.

# Arch
pacman -S mkcert

# Brew (MacOS and Linux)
brew install mkcert

Creating and installing the certificates is as easy as running the following commands

mkdir certificates      # A directory to hold the certificates, you should know the path.
cd certificates

mkcert -install -ecdsa localhost 127.0.0.1 ::1

This will produce two files, the key file and the certificate file.

The -install option installs the certificates locally on your machine, and browsers.

You can specify more ip addresses or hostnames if necessary.

Now add the certificates to the HTTP configuration.

http:
  address: 127.0.0.1:8769

  tls: true
  certificate:
    certificate: ".../certificates/{certificate_name}.pem"
    privateKey: ".../certificates/{certificate_name}-key.pem"

Start NanoPing with the configuration and you will see that TLS is enabled with a trusted connection.

Pruning offline nodes​

A node that leaves a hub removes itself from the hub server's node list. A node that is wiped, decommissioned or otherwise never comes back cannot, and would stay in the list forever. The hub server therefore removes nodes that have been offline for longer than hubServer.pruneOfflineNodesAfter:

config.yaml
hubServer:
  # Defaults to 720h (30 days) when omitted.
  pruneOfflineNodesAfter: 720h

The value is a duration: a number followed by s, m or h. For example 720h (30 days), 168h (7 days), 24h, or 90m. Set it to 0 to never prune:

config.yaml
hubServer:
  pruneOfflineNodesAfter: "0"

Mutual TLS (mTLS)​

With mutual TLS, a hub server can require connecting nodes to present a client certificate and reject any node whose certificate is not signed by a trusted certificate authority (CA). This lets the hub server decide which nodes are allowed to connect, on top of the access-token check.

mTLS builds on top of regular TLS: the hub server must already be serving HTTPS (http.tls: true with a certificate).

On the hub server​

Add a clientAuth section under http pointing at the CA that signed your client certificates, and set requireClientCertificate on the hubServer:

http:
  address: 127.0.0.1:8769

  tls: true
  certificate:
    certificate: "/path/to/server-certificate.pem"
    privateKey: "/path/to/server-private-key.pem"

  # Verify client certificates against this CA.
  clientAuth:
    clientCa: "/path/to/client-ca.pem"

hubServer:
  authenticationByRequest:
    timeout: 5m

  # Reject nodes that do not present a verified client certificate.
  requireClientCertificate: true

By default (clientAuth set without required: true) the server only verifies a client certificate when one is presented, so the browser portal keeps working without a client certificate. The hubServer.requireClientCertificate flag then enforces that a verified certificate is present specifically for nodes connecting to the hub (the /hub and authenticate-by-request endpoints).

If you want the whole HTTP server — including the browser portal — to refuse any connection without a valid client certificate, set required: true:

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

requireClientCertificate needs http.clientAuth.clientCa to be configured — otherwise there is no CA to verify certificates against, and the hub server logs a warning at startup.

On the node​

Give the node the client certificate it should present when connecting out to a hub server. This is a top-level hubClientCertificate section (it is your own static configuration and is not modified by the authenticate-by-request sign-in flow):

node:
  name: my-node

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

The node then presents this certificate for every HTTPS call to the hub, including authenticate-by-request and the persistent hub connection. A node without a certificate — or with one not signed by the configured CA — is rejected.

Generating the certificates​

All certificates (server and client) must be signed by the same CA that you point clientAuth.clientCa at. Using mkcert, the local CA lives at $(mkcert -CAROOT)/rootCA.pem:

# Server certificate (for http.certificate)
mkcert -ecdsa localhost 127.0.0.1 ::1

# Client certificate (for hubClientCertificate)
mkcert -ecdsa -client my-node

# The CA to verify client certificates against (for http.clientAuth.clientCa)
echo "$(mkcert -CAROOT)/rootCA.pem"

Custom Networks​

As we are completing our new Network feature, there is a temporary preview that let you create Custom Networks. The custom network are custom configurations of pipelines and which node they should be run on. In the final version of the Network feature, you will instead provide a template for a pipeline, and all the variables will be replaced with the corresponding values. As of for now, you'll have to create the whole pipeline and copy its json to a file and specify which node it should be run on by the node ID. The following is an example of how to create a custom network. Again, we will like to preface this is a temporary feature and it will be removed as soon as the final version is ready.

... my other config

# Configuration of networks
networks:
  custom_networks:
    - id: my_custom_network # requires some unique random ID
      name: My Custom Network # Human-readable name
      node_pipelines:
        - node_id: 2abc8870-3ad2-4dfd-8bf4-4ab1c3f7e113 # Node ID of some node
          pipeline_json_configs:
            - /home/user/configs/custom-network-pipeline-sender.json # Path to the pipeline JSON file that will be run on the node
        - node_id: 04488ddf-a305-4a1b-8e97-b036a3f6bca9 # Node ID of some other node
          pipeline_json_configs:
            - /home/user/configs/custom-network-pipeline-receiver.json
            - /home/user/configs/custom-network-pipeline-other-pipeline.json # You can specify multiple pipelines for the same node