Skip to content
ranet3

This page may contain unreviewed machine generated text. Use with care.

Pages

Getting started

Building the binary, the binary cache, and running a node by hand.

Building

cd pkgs/ranet3 && go build -o ranet3 ./cmd/ranet3

Requires Go 1.26.3 or later.

On Linux the daemon needs CAP_NET_ADMIN to create the tun and to write routes. A link.port below 1024 also needs CAP_NET_BIND_SERVICE. Root has both. On macOS, creating a utun and writing routes need root.

A binary run with these capabilities instead of root also needs a state directory it can write. The daemon refuses to start when it cannot create or read that directory. It is /var/lib/ranet3 on Linux and /var/db/ranet3 on macOS, unless --state-dir names another. Without write access to /var/run/ranet3, the daemon runs with no control socket. A --control path the daemon cannot create stops the start instead.

Binary cache

Running

With nix, from the flake:

sudo nix run github:ranet3/ranet3 -- daemon --config /etc/ranet3/config.toml

Or with the binary built above:

sudo ./ranet3 daemon --config /etc/ranet3/config.toml

--config defaults to /etc/ranet3/config.toml. The config file names the node, its key and trust document, its port and endpoints, and the peers it dials. examples/config.toml is an annotated example, with the same schema in YAML and JSON. The configuration reference lists every key, and command line lists the daemon's flags.

On startup the daemon logs the tun's name. The device is ranet3 on Linux unless link.tun names another (see Configuration). On macOS it is the utun unit the daemon got, such as utun6.

Without a cap.table block, the line ends in configure its addresses and kernel routes externally. Traffic won't flow until you configure them, for example on Linux:

ip addr add 203.0.113.10/32 dev ranet3
ip route add 203.0.113.0/24 dev ranet3

With cap.table, the node installs its routes itself. It assigns the addresses cap.table.addresses lists, and with cap.table.assign_announced the prefixes it announces, but for one written with its family's unspecified address, such as a default. On Linux the routes go into table cap.table.id, 200 unless set. The node writes the policy rules the host reads that table through itself. cap.border.overlay, Linux only, names the prefixes the mesh numbers its nodes from, and a lookup bound to no device for one of their addresses then ends as rows L1 to L5 of where a lookup ends give:

[cap.table]
addresses = ["203.0.113.10/32"]

[cap.border]
overlay = ["203.0.113.0/24"]

The line then names where the node reconciles, such as table 200 protocol 155 on Linux or interface utun6 on macOS.

daemon is the node. Most other subcommands speak to a running daemon over its control socket, and they ship in the same binary. Most of them ask a question, while disable, enable, redial, rekey, reload, down and up act on one. version without --daemon, licenses, completion, debug buildinfo and help run without a daemon. See Control socket and command line.

ranet3 completion bash, ranet3 completion zsh or ranet3 completion fish writes that shell's completion script, as command line describes. The Nix package does not install one.

Updated