Aleksandr BogomiakovandClaude
c184ef0914
The README is now a landing page: the idea (a mesh VPN with no server, joined with a network name and a secret), install and platform tables, exit nodes, and a short build section. Implementation detail stays in docs/. The flake builds tsng and the tray from source and ships a NixOS module (services.tsunagi). Dist install notes now show the real `join -n -s` syntax, and two links that pointed into the old README are redirected. Co-Authored-By: Claude <noreply@anthropic.com>
2.6 KiB
Running tsunagi on Linux
This archive holds a static tsunagi binary (musl), so it runs on any
distribution — Arch, Alpine, NixOS, old glibc systems — with no shared-library
dependencies. Alongside it are a systemd unit, a polkit rule, and an installer.
Creating the TUN interface needs CAP_NET_ADMIN, and configuring
systemd-resolved is decided by polkit. There are three ways to run it; pick one.
On Debian/Ubuntu and Arch, prefer the native package (
.deb/.pkg.tar.zst) from the release — it does all of the below for you.
Quick install — systemd service as a dedicated user
sudo ./install.sh
sudo systemctl enable --now tsunagi
The service runs as an unprivileged tsunagi user with just CAP_NET_ADMIN
and CAP_NET_BIND_SERVICE (granted by systemd), not root. systemd creates its
state (/var/lib/tsunagi), cache (/var/cache/tsunagi) and runtime
(/run/tsunagi) directories, and the polkit rule lets it configure the
resolver. Control it with sudo — the CLI finds the running service's socket at
/run/tsunagi/agent.sock with no flags. The socket is open to the tsunagi
group, so after sudo usermod -aG tsunagi "$USER" (and logging in again) no
sudo is needed:
sudo tsng status
sudo tsng join -n <network-name> -s <tsn1…secret>
As your own user — one capability, no service
sudo install -m 0755 tsunagi /usr/local/bin/tsng
sudo setcap cap_net_admin,cap_net_bind_service+p /usr/local/bin/tsng
sudo usermod -aG tsunagi "$USER" # so the resolver works; log in again after
tsng up
Nothing runs as root. The capability is lost on every rebuild or copy of the
binary, so re-run setcap after replacing it. The agent uses your per-user
state directory and socket, so plain tsng status (no sudo) reaches it.
Without touching the OS
tsng up --no-tun
Tunnels form and handshake between agents, but no interface, address or route is created, so traffic never reaches the operating system. Needs no privileges.
What the agent installs
Everything is tagged to its own interface, computed from local state, and reversible — removed when a network leaves, broadcast is turned off, or the agent stops:
- a TUN interface configured over netlink (addresses, MTU, up);
- while broadcast is on, a
255.255.255.255route through the interface and an inbound-UDP firewall allowance from the overlay range (iptables, tagged); - the systemd-resolved setting that sends the overlay zones' questions to the local resolver.
Nothing taken from a remote peer ever becomes a path, a command argument or an OS setting.