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@latestBuilds 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:
dir=$(mktemp -d)
kolo-node run -listen 127.0.0.1:7447 -identity "$dir/state/node.key" -firstCheck it from a second terminal. It prints ok 127.0.0.1:7447:
kolo-node check 127.0.0.1:7447A 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:
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:
kolo-node run -listen 127.0.0.1:7448 -identity "$dir/state2/node.key" -bootstrap 127.0.0.1:7447Stop 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.
Command kolo-node runs a kolo-dht bootstrap server or a kolo-relay; see the README for its commands, flags and config file.
Command
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
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
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 defaultkolo-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
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
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, onehost:portper 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-bootstrapentries first, then each file's in order, without duplicates, at most 16 in all.KOLO_BOOTSTRAP=host:port,...: read only when neither-bootstrapnor-bootstrap-fileis set (on the command line or in the config file, even to an empty list) and-firstis not set. A setKOLO_BOOTSTRAPthat is not read logs the warningKOLO_BOOTSTRAP ignored.-first: start a new network, with no entry nodes yet. It cannot be combined with-bootstrapor-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:
# entry nodes of our network
203.0.113.10:7447
node2.example.org:7447 # resolved to IPv4 at each attemptA 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:
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:7447What 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:
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 withStateDirectoryMode=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.jsonholds no secret (mode 0644). List the other entry nodes of your network inbootstrap, or in a file named bybootstrap-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": trueinstead ofbootstrap. - Raise
net.core.rmem_maxandnet.core.wmem_maxto 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=512MandGOMEMLIMIT=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_UNIXalso blocks DNS over IPv6, so on a host whose nameservers are all IPv6, use IP literals in-bootstrapor an IPv4 resolver.- Check the port from another machine with
kolo-node check 203.0.113.10:7447, where203.0.113.10stands for the public address.
Limits
- IPv4 only. An IPv6 address in
-listen,-bootstrap,-bootstrap-file,KOLO_BOOTSTRAP,-relay,-relay-file,KOLO_RELAYSorcheck, IPv4-mapped forms included, is a config error (exit 2), and names resolve to IPv4 addresses only. -listen::7447by 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-separatedhost:portentries (IPv4 addresses or DNS names), repeatable. With-bootstrap-fileandKOLO_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, andBootstrapthen gets 30s.-bootstrap-file: a text file of at most 64 KiB, onehost:portper 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-bootstrapor-bootstrap-file.KOLO_BOOTSTRAP: unset by default; as-bootstrap, read only when-bootstrap,-bootstrap-file(even set to an empty list) and-firstare all unset.-stats-interval: 5m, from 1s to 24h (288 lines a day at the default).-log-formatistextorjson;-log-levelisinfo,warnorerror.- 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-ipif 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,-timeout5s per address, from 1s to 1m. Each request waits at most half of-timeout.check -relay,-relay-fileandKOLO_RELAYS: at most 16 distinct relays in all; one key at two addresses or one address with two keys exits 2.relay -listenandrelay -identityare 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-sessionsif lower.-relay-reservation-lifetimeand-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-timeoutand-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-connsif 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-addrsis set. Nothing is logged per packet, so a flood cannot fill the disk. - A DNS name in
-bootstraponly 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.
relaylogs no peer address and no key of its clients. What a relay can still learn is on the kolo-relay page.runnever carries application traffic: relaying is the separaterelaycommand, 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
statsevent, and reachability is tested from outside withkolo-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
- RFC 1123, Requirements for Internet Hosts - Application and Support (Internet Standard, October 1989).
- Takes: the host name syntax check (section 2.1).