Aleksandr BogomiakovandClaude
c62d29fa14
The control socket is now opened to the tsunagi group (unit), the Arch package enables and starts the service on install, adds the installing user to the group, restarts a running agent on upgrade, and depends on the libraries the tray loads at run time. The tray looks for the agent's socket again on every poll instead of once at start, and a missing indicator library is reported instead of panicking. Repository URLs unified. Co-Authored-By: Claude <noreply@anthropic.com>
70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
sudo tsunagi status
|
|
sudo tsunagi join <network-name> <tsn1…secret>
|
|
```
|
|
|
|
## As your own user — one capability, no service
|
|
|
|
```sh
|
|
sudo install -m 0755 tsunagi /usr/local/bin/tsunagi
|
|
sudo setcap cap_net_admin,cap_net_bind_service+p /usr/local/bin/tsunagi
|
|
sudo usermod -aG tsunagi "$USER" # so the resolver works; log in again after
|
|
tsunagi 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 `tsunagi status` (no sudo) reaches it.
|
|
|
|
## Without touching the OS
|
|
|
|
```sh
|
|
tsunagi 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.255` route 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.
|