kolo docsbeta

kolo-node

A bootstrap server for the kolo-dht network, the address new Kolo peers join through.

On this page

kolo-node is a command, not a Go package. It runs a kolo-dht server on one UDP port: it answers DHT queries, stores signed topic announcements and relays connect requests so peers can punch through their NATs. It carries no application data. kolo-node relay runs a kolo-relay server instead, for peers that cannot connect directly; it copies their encrypted traffic, which it cannot read. It keeps its kolo-id key in a file, shuts down cleanly on SIGINT and SIGTERM, and logs a few structured events with slog. Run a few of them on different hosts and give their addresses to peers.

Install

go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@latest

Builds without cgo; CGO_ENABLED=0 gives a static binary.

Quick start

Start a new network on loopback: its first node, with -first (no entry nodes yet) and its key in a new temporary directory:

Terminal
dir=$(mktemp -d)
kolo-node run -listen 127.0.0.1:7447 -identity "$dir/state/node.key" -first

Check it from a second terminal. It prints ok 127.0.0.1:7447:

Terminal
kolo-node check 127.0.0.1:7447

A peer bootstraps from the node by passing its address to (*kolodht.Node).Bootstrap. This program takes the addresses as arguments, for example go run . 127.0.0.1:7447:

main.go
package main

import (
	"context"
	"fmt"
	"log"
	"net/netip"
	"os"
	"time"

	kolodht "github.com/ciranda-dev/kolo-dht"
	koloid "github.com/ciranda-dev/kolo-id"
)

func main() {
	if len(os.Args) < 2 {
		log.Fatal("usage: join IP:PORT...")
	}
	var servers []netip.AddrPort
	for _, a := range os.Args[1:] {
		ap, err := netip.ParseAddrPort(a)
		if err != nil {
			log.Fatal(err)
		}
		servers = append(servers, ap)
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	id, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	n, err := kolodht.New(ctx, "127.0.0.1:0", id, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer n.Close()
	if err := n.Bootstrap(ctx, servers); err != nil {
		log.Fatal(err)
	}
	fmt.Println("joined:", n.Stats().Servers, "servers in the routing table")
}

It prints how many servers are in the client's routing table. Another kolo-node joins with -bootstrap, a list of host:port entries (IPv4 addresses or DNS names), with -bootstrap-file, a file of one entry per line, or with both:

Terminal
kolo-node run -listen 127.0.0.1:7448 -identity "$dir/state2/node.key" -bootstrap 127.0.0.1:7447

Stop a node with Ctrl-C: it logs stopping, a last stats line and stopped, and exits 0. Starting it again with the same -identity keeps the same key.

Without -bootstrap, -bootstrap-file, the KOLO_BOOTSTRAP environment variable or -first, run exits 2, so a list left empty by mistake never starts a lone node. kolo-node ships no list of public nodes; see Public and private networks.

API reference

The API reference is generated from the Go source and is in English.

Package main · github.com/ciranda-dev/kolo-node/cmd/kolo-node · v0.1.0

Command kolo-node runs a kolo-dht bootstrap server or a kolo-relay; see the README for its commands, flags and config file.

Command

kolo-node
usage:
  kolo-node run -identity FILE [flags]       run a kolo-dht bootstrap server
  kolo-node relay -identity FILE -listen ADDR [flags]
                                             run a kolo-relay server
  kolo-node check [-timeout 5s] [-relay HOST:PORT@KEY] [-relay-file FILE] [HOST:PORT...]
                                             check that kolo-dht servers and kolo-relays answer from here
  kolo-node version                          print the version

Run "kolo-node run -h" or "kolo-node relay -h" for their flags.

kolo-node run

kolo-node run
Usage of kolo-node run:
  -bootstrap host:port
    	comma-separated host:port list of entry nodes, repeatable
  -bootstrap-file file
    	file of entry nodes, one host:port per line, repeatable
  -config file
    	JSON config file; flags set on the command line override it
  -dht-max-inflight int
    	kolodht.Config.MaxInflight; 0 means the kolo-dht default
  -dht-max-records int
    	kolodht.Config.MaxRecords; 0 means the kolo-dht default
  -dht-max-records-per-ip int
    	kolodht.Config.MaxRecordsPerIP; 0 means the kolo-dht default
  -dht-max-records-per-topic int
    	kolodht.Config.MaxRecordsPerTopic; 0 means the kolo-dht default
  -dht-max-relays int
    	kolodht.Config.MaxRelays; 0 means the kolo-dht default
  -dht-max-requests int
    	kolodht.Config.MaxRequests; 0 means the kolo-dht default
  -dht-max-requests-per-ip int
    	kolodht.Config.MaxRequestsPerIP; 0 means the kolo-dht default
  -dht-max-requests-per-prefix int
    	kolodht.Config.MaxRequestsPerPrefix; 0 means the kolo-dht default
  -dht-punch-timeout duration
    	kolodht.Config.PunchTimeout; 0 means the kolo-dht default
  -dht-request-timeout duration
    	kolodht.Config.RequestTimeout; 0 means the kolo-dht default
  -first
    	start a new network: no entry nodes yet
  -identity file
    	key file, created on the first run (required)
  -listen address
    	IPv4 UDP address to listen on (default ":7447")
  -log-addrs
    	log full peer addresses instead of their /24
  -log-format format
    	log format: text or json (default "text")
  -log-level level
    	log level: info, warn or error (default "info")
  -stats-interval duration
    	interval between stats events, 1s to 24h (default 5m0s)

kolo-node relay

kolo-node relay
Usage of kolo-node relay:
  -allow-file file
    	file of the hex keys that may reserve, one per line; without it any key may
  -config file
    	JSON config file; flags set on the command line override it
  -identity file
    	key file of the relay, created on the first run (required)
  -listen address
    	IPv4 UDP address to listen on (required)
  -log-format format
    	log format: text or json (default "text")
  -log-level level
    	log level: info, warn or error (default "info")
  -relay-connect-timeout duration
    	kolorelay.ServerConfig.ConnectTimeout; 0 means the kolo-relay default
  -relay-control-timeout duration
    	kolorelay.ServerConfig.ControlTimeout; 0 means the kolo-relay default
  -relay-flush-interval duration
    	kolorelay.ServerConfig.FlushInterval; 0 means the kolo-relay default
  -relay-max-conns int
    	the listener's kolo-transport MaxConns; 0 means 128, kolo-relay's listener default
  -relay-max-conns-per-ip int
    	the listener's kolo-transport MaxConnsPerIP; 0 means 4, kolo-relay's listener default
  -relay-max-reservations int
    	kolorelay.ServerConfig.MaxReservations; 0 means the kolo-relay default
  -relay-max-session-bytes int
    	kolorelay.ServerConfig.MaxSessionBytes; 0 means the kolo-relay default
  -relay-max-session-duration duration
    	kolorelay.ServerConfig.MaxSessionDuration; 0 means the kolo-relay default
  -relay-max-sessions int
    	kolorelay.ServerConfig.MaxSessions; 0 means the kolo-relay default
  -relay-max-sessions-per-peer int
    	kolorelay.ServerConfig.MaxSessionsPerPeer; 0 means the kolo-relay default
  -relay-max-sessions-per-target int
    	kolorelay.ServerConfig.MaxSessionsPerTarget; 0 means the kolo-relay default
  -relay-rate-burst int
    	kolorelay.ServerConfig.RateBurst; 0 means the kolo-relay default
  -relay-rate-bytes int
    	kolorelay.ServerConfig.RateBytes, per second; 0 means the kolo-relay default
  -relay-reservation-lifetime duration
    	kolorelay.ServerConfig.ReservationLifetime; 0 means the kolo-relay default
  -relay-session-idle-timeout duration
    	kolorelay.ServerConfig.SessionIdleTimeout; 0 means the kolo-relay default

kolo-node a

kolo-node a
kolonode: unknown command "a"
usage:
  kolo-node run -identity FILE [flags]       run a kolo-dht bootstrap server
  kolo-node relay -identity FILE -listen ADDR [flags]
                                             run a kolo-relay server
  kolo-node check [-timeout 5s] [-relay HOST:PORT@KEY] [-relay-file FILE] [HOST:PORT...]
                                             check that kolo-dht servers and kolo-relays answer from here
  kolo-node version                          print the version

Run "kolo-node run -h" or "kolo-node relay -h" for their flags.

kolo-node check

kolo-node check
usage: kolo-node check [-timeout 5s] [-relay HOST:PORT@KEY] [-relay-file FILE] [HOST:PORT...]
  -relay host:port@key
    	comma-separated host:port@key list of kolo-relays, repeatable
  -relay-file file
    	file of kolo-relays, one host:port@key per line, repeatable
  -timeout duration
    	time allowed per address, 1s to 60s (default 5s)

kolo-node that

kolo-node that
kolonode: unknown command "that"
usage:
  kolo-node run -identity FILE [flags]       run a kolo-dht bootstrap server
  kolo-node relay -identity FILE -listen ADDR [flags]
                                             run a kolo-relay server
  kolo-node check [-timeout 5s] [-relay HOST:PORT@KEY] [-relay-file FILE] [HOST:PORT...]
                                             check that kolo-dht servers and kolo-relays answer from here
  kolo-node version                          print the version

Run "kolo-node run -h" or "kolo-node relay -h" for their flags.

Good to know

Public and private networks

A network is the set of kolo-dht servers that know each other, and a node is in the network of the entry nodes it bootstraps from. kolo-node ships no list of entry nodes, and run needs one of these:

  • -bootstrap host:port,...: entry nodes, comma separated; the flag can be repeated.
  • -bootstrap-file path: a text file of entry nodes, one host:port per line. # starts a comment, to the end of the line; blank lines are ignored; a UTF-8 BOM and CRLF line ends are accepted. Only a regular file of at most 64 KiB is read: a directory, device or FIFO is refused before it is opened. The flag can be repeated, and it adds up with -bootstrap: the -bootstrap entries first, then each file's in order, without duplicates, at most 16 in all.
  • KOLO_BOOTSTRAP=host:port,...: read only when neither -bootstrap nor -bootstrap-file is set (on the command line or in the config file, even to an empty list) and -first is not set. A set KOLO_BOOTSTRAP that is not read logs the warning KOLO_BOOTSTRAP ignored.
  • -first: start a new network, with no entry nodes yet. It cannot be combined with -bootstrap or -bootstrap-file.

With none of them, or with only empty lists, run exits 2: a list left empty by mistake never starts a lone node, and a flag or key set to an empty list never falls back to KOLO_BOOTSTRAP. A relative -bootstrap-file path, in the config file too, is relative to the working directory of kolo-node, not to the config file; systemd units should use absolute paths. Each config array element is one entry: an element with a comma is refused. The network log event gives the mode (first or join), the entries listed and, with join, where they from came (-bootstrap, -bootstrap-file or KOLO_BOOTSTRAP).

An entry is an IPv4 address or a DNS name, with a port from 1 to 65535. IPv6 in any form, IPv4-mapped included, is refused. A bootstrap file:

Text
# entry nodes of our network
203.0.113.10:7447
node2.example.org:7447   # resolved to IPv4 at each attempt

A public network is one whose operators publish their entry nodes; members list them. A private network runs its own: start its first node with -first, the others with -bootstrap (or a file) pointing at it, and give members only these addresses. Run at least two entry nodes on hosts that stay up, with their UDP port open. Two nodes of a private network on loopback:

Terminal
dir=$(mktemp -d)
kolo-node run -listen 127.0.0.1:7447 -identity "$dir/a/node.key" -first
kolo-node run -listen 127.0.0.1:7448 -identity "$dir/b/node.key" -bootstrap 127.0.0.1:7447

What it is: separation by topology. A kolo-dht server learns other servers only from the servers it asks and from servers that send it requests, so two networks with different entry nodes never see each other's servers, records or peers.

What it is not: access control. The list is not a secret. Anyone who learns one entry address can bootstrap from it, look up topics and announce on them, and a node that lists entry nodes of two networks joins them. Decide who may connect with kolo-secure keys and kolo-swarm's Allow, admit members with kolo-invite, and trust only signed records.

run without entry nodes and without -first exits 2, so a list left empty by mistake never starts a lone node; so does -bootstrap, -bootstrap-file or their config key set to an empty list. Give the first node -first, or "first": true in the config file, and every other node -bootstrap, -bootstrap-file or KOLO_BOOTSTRAP.

Running a relay

kolo-node relay runs a kolo-relay: peers that cannot connect directly, such as two computers behind firewalls that let only outgoing traffic through, reserve on it and meet through it. Each side runs its own kolo-secure connection through the relay, so it copies bytes it cannot read. kolo-swarm uses it when its Config.Relays lists it. A relay has its own key file and its own UDP port; one process is one relay. On loopback, with its key in a new temporary directory:

Terminal
dir=$(mktemp -d)
kolo-node relay -listen 127.0.0.1:7448 -identity "$dir/relay/relay.key"

It logs identity with its key and started with its addr. Peers list it as host:port@key, for example 203.0.113.20:7448@<key> with the logged key. Check it from a second terminal with kolo-node check -relay 127.0.0.1:7448@<key>, which prints ok relay 127.0.0.1:7448@<key>: check asks the relay for a random key with a new identity, which proves its address, its key and the protocol without reserving anything.

Without -allow-file the relay is open: any key may reserve and be reached, at the operator's cost, and 16 addresses can fill its 64 default reservations at 4 connections per address; it logs the warning open relay. With -allow-file path, only the keys in the file may reserve: one key per line as 64 hex characters, # comments, blank lines ignored, a regular file of at most 64 KiB, read at start. A file with no key is refused. check takes relays from -relay (comma separated, repeatable), -relay-file (one per line) or KOLO_RELAYS, at most 16 in all. For the commands of a whole network, see Run your own infrastructure.

Running on a VPS

To run it on a Linux VPS with systemd (the README has every step):

  • Install the unit deploy/kolo-node.service. It runs as a static system user with StateDirectoryMode=0700, which is required: kolo-id refuses a key directory that others can read or that is a symlink.
  • The config file /etc/kolo-node/config.json holds no secret (mode 0644). List the other entry nodes of your network in bootstrap, or in a file named by bootstrap-file. The same list on every node is fine: a node ignores its own address. The first node of a new network has no list yet: give it "first": true instead of bootstrap.
  • Raise net.core.rmem_max and net.core.wmem_max to 7500000 so the UDP socket gets the buffers it asks for.
  • Open UDP port 7447 in the host firewall and in the provider's firewall. Drop new IPv6 input, and connect to the host over IPv4.
  • The unit sets MemoryMax=512M and GOMEMLIMIT=480MiB. The worst-case live heap is about 416 MiB (a full record store plus the refused listener's 16 connections). Raise both together with the record limits.
  • Exit 2 is not restarted (RestartPreventExitStatus=2); other failures restart after 5s.
  • RestrictAddressFamilies=AF_INET AF_UNIX also blocks DNS over IPv6, so on a host whose nameservers are all IPv6, use IP literals in -bootstrap or an IPv4 resolver.
  • Check the port from another machine with kolo-node check 203.0.113.10:7447, where 203.0.113.10 stands for the public address.

Limits

  • IPv4 only. An IPv6 address in -listen, -bootstrap, -bootstrap-file, KOLO_BOOTSTRAP, -relay, -relay-file, KOLO_RELAYS or check, IPv4-mapped forms included, is a config error (exit 2), and names resolve to IPv4 addresses only.
  • -listen: :7447 by default.
  • -config: one JSON object of at most 64 KiB. Keys match exactly and once; an unknown, repeated or differently cased key, null, a number that is not an integer, or anything after the object is an error. Durations are strings such as "30s".
  • -bootstrap: comma-separated host:port entries (IPv4 addresses or DNS names), repeatable. With -bootstrap-file and KOLO_BOOTSTRAP, at most 16 distinct entries in all. A name gives at most 8 addresses, and there are at most 64 bootstrap addresses in all. Each name is resolved within 5s, in parallel, and Bootstrap then gets 30s.
  • -bootstrap-file: a text file of at most 64 KiB, one host:port per line, repeatable (in the config file, an array of paths). 16 entries of the longest form (a 253-byte name, a colon and a 5-digit port) take about 4 KiB, the rest leaves room for comments.
  • -first: false by default; true means no entry nodes, and it is refused with -bootstrap or -bootstrap-file.
  • KOLO_BOOTSTRAP: unset by default; as -bootstrap, read only when -bootstrap, -bootstrap-file (even set to an empty list) and -first are all unset.
  • -stats-interval: 5m, from 1s to 24h (288 lines a day at the default).
  • -log-format is text or json; -log-level is info, warn or error.
  • The -dht- flags set kolo-dht limits. Left at 0, each takes kolo-dht's default, and kolo-dht checks the range:
    • -dht-max-records: 65536, from 16 to 1,000,000. A full store takes about 710 bytes of heap per record, 44 MiB at the default.
    • -dht-max-records-per-topic: 512, from 1 to 65536.
    • -dht-max-records-per-ip: 256, from 1 to 65536.
    • -dht-max-inflight: 160, from 8 to 4096, and at least 75 with -bootstrap.
    • -dht-max-relays: 64, from 1 to 4096.
    • -dht-max-requests-per-ip: 50 per second, from 1 to 10,000.
    • -dht-max-requests-per-prefix: 200 per second, or -dht-max-requests-per-ip if higher, up to 100,000.
    • -dht-max-requests: 10,000 per second, or the per-prefix limit if higher, up to 1,000,000.
    • -dht-request-timeout: 1s, from 100ms to 10s.
    • -dht-punch-timeout: 45s, from 1s to 2m.
  • Until it has joined, the node tries again after 1 minute, doubling the wait after each failure up to 5 minutes. Once joined, it resolves and bootstraps again every 5 minutes while its table holds fewer than 20 servers.
  • Shutdown gets 10s, then the process exits 1. A second signal during the shutdown ends the process at once.
  • Inbound kolo-secure connections are all refused. The refused listener is capped at 16 connections, 16 pending, 1 dialed, 1 incoming stream and 64 KiB receive windows per stream and per connection.
  • check: 1 to 16 addresses, -timeout 5s per address, from 1s to 1m. Each request waits at most half of -timeout. check -relay, -relay-file and KOLO_RELAYS: at most 16 distinct relays in all; one key at two addresses or one address with two keys exits 2.
  • relay -listen and relay -identity are required; no port is assigned to kolo-relay, so pick one. relay -allow-file: none by default (an open relay), a text file of at most 64 KiB with at least one key.
  • The -relay- flags set kolo-relay limits. Left at 0, each takes kolo-relay's default, and kolo-relay checks the range:
    • -relay-max-reservations: 64, from 1 to 100000.
    • -relay-max-sessions: 16, from 1 to 10000. -relay-max-sessions-per-peer: 4 and -relay-max-sessions-per-target: 8, or -relay-max-sessions if lower.
    • -relay-reservation-lifetime and -relay-max-session-duration: 1h, from 1s to 24h.
    • -relay-max-session-bytes: 1 GiB in each direction, from 64 KiB to 1 TiB.
    • -relay-session-idle-timeout: 60s, from 1s to 10m. -relay-connect-timeout and -relay-control-timeout: 15s, from 1s to 60s.
    • -relay-rate-bytes: 1 MiB per second per client connection, from 16 KiB to 1 GiB. -relay-rate-burst: 256 KiB, from 16 KiB to 64 MiB. -relay-flush-interval: 1ms, from 100µs to 100ms.
    • -relay-max-conns: 128, from 1 to 10000, and -relay-max-conns-per-ip: 4, or -relay-max-conns if lower: the listener's limits. The listener's memory bound is raised to (-relay-max-conns + 1) × 256 KiB of receive window when that is above 1 GiB, about 2.4 GiB at 10000.

Security

  • Logs never contain the seed, packet contents, topics, record keys, or a peer address beyond its /24 unless -log-addrs is set. Nothing is logged per packet, so a flood cannot fill the disk.
  • A DNS name in -bootstrap only leads to public addresses, or to ones in the scope of the listen address, so whoever controls the name cannot point the node into a private network. Literal addresses are used as configured.
  • The config file path must name a regular file before it is opened, so a device is never opened.
  • The key file is created only after the socket is open, so a config or listen error leaves nothing on disk.
  • relay logs no peer address and no key of its clients. What a relay can still learn is on the kolo-relay page.
  • run never carries application traffic: relaying is the separate relay command, with its own key and port.

Known limits

  • kolo-dht v0.1.x derives a server's DHT ID from its IP and a random choice made at each start, and its PINGs are not authenticated, so the stable key identifies the operator's node but no peer checks it.
  • There is no HTTP endpoint. Health is the stats event, and reachability is tested from outside with kolo-node check, which uses the real UDP path.
  • kolo-node is experimental. The command line and config file may change before v1.0.0.

Errors

This package has no exported error variables.

kolo-node reports errors as log events and exit codes: 0 after SIGINT or SIGTERM once everything is closed; 1 if the identity or the socket cannot be set up, or the shutdown fails or takes over 10s; 2 for an invalid command, flag, config file or kolo-dht limit, for no entry nodes and no -first, and for a key file or key directory that kolo-id refuses. check prints ok ADDRESS or failed ADDRESS: reason for each address, then ok relay ADDRESS@KEY or failed relay ADDRESS@KEY: reason for each relay, and exits 0 only if every server and relay answered.

References