82 lines
3.0 KiB
Markdown
82 lines
3.0 KiB
Markdown
 
|
# Running tsunagi on macOS
|
||
|
|
|
||
|
|
The agent needs **root** on macOS: creating a `utun` interface and writing
|
||
|
|
`/etc/resolver` are both root-only, and macOS has no per-capability grant like
|
||
|
|
Linux. There are two ways to run it.
|
||
|
|
|
||
|
|
## Quick start — `sudo`
|
||
|
|
|
||
|
|
```sh
|
||
|
|
sudo tsunagi up
|
||
|
|
```
|
||
|
|
|
||
|
|
In another terminal, the control commands talk to it over the system control
|
||
|
|
socket and do **not** need `sudo`:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
tsunagi status
|
||
|
|
tsunagi join <network-name> <tsn1…secret>
|
||
|
|
```
|
||
|
|
|
||
|
|
The agent uses fixed system paths, so the commands find it regardless of whose
|
||
|
|
shell started `sudo`:
|
||
|
|
|
||
|
|
| what | path |
|
||
|
|
|---|---|
|
||
|
|
| mandatory state | `/var/db/tsunagi` |
|
||
|
|
| disposable cache | `/var/db/tsunagi/cache` |
|
||
|
|
| control socket | `/var/run/tsunagi/agent.sock` |
|
||
|
|
|
||
|
|
## Native deployment — root LaunchDaemon
|
||
|
|
|
||
|
|
For an always-on agent that starts at boot, install the bundled
|
||
|
|
[`cy.hexor.tsunagi.plist`](cy.hexor.tsunagi.plist).
|
||
|
|
|
||
|
|
```sh
|
||
|
|
# Put the binary where the plist expects it (edit the plist for another path).
|
||
|
|
sudo install -m 0755 target/release/tsunagi /usr/local/bin/tsunagi
|
||
|
|
|
||
|
|
# Install the daemon. launchd refuses a daemon plist that is not owned by
|
||
|
|
# root:wheel or that is group/world-writable.
|
||
|
|
sudo install -m 0644 -o root -g wheel \
|
||
|
|
dist/macos/cy.hexor.tsunagi.plist \
|
||
|
|
/Library/LaunchDaemons/cy.hexor.tsunagi.plist
|
||
|
|
|
||
|
|
# Load and start it.
|
||
|
|
sudo launchctl bootstrap system /Library/LaunchDaemons/cy.hexor.tsunagi.plist
|
||
|
|
sudo launchctl enable system/cy.hexor.tsunagi
|
||
|
|
```
|
||
|
|
|
||
|
|
Manage it afterwards with:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
sudo launchctl kickstart -k system/cy.hexor.tsunagi # restart
|
||
|
|
sudo launchctl bootout system/cy.hexor.tsunagi # stop and unload
|
||
|
|
tail -f /var/log/tsunagi.log # logs
|
||
|
|
```
|
||
|
|
|
||
|
|
The control commands (`status`, `join`, `network`, `dns`) work the same against
|
||
|
|
the daemon as against a `sudo tsunagi up`, over the same socket.
|
||
|
|
|
||
|
|
## What the agent does to the system
|
||
|
|
|
||
|
|
Everything it installs is tagged to its own interface, computed from local
|
||
|
|
state, and reversible — it is removed when a network leaves, broadcast is turned
|
||
|
|
off, or the agent stops:
|
||
|
|
|
||
|
|
- a **`utun` interface**, configured with `ifconfig` (addresses, MTU, up) and a
|
||
|
|
subnet `route` for the overlay range. The kernel assigns the `utunN` name; the
|
||
|
|
agent adopts whatever it is given. A `utun` is torn down with the process, so
|
||
|
|
a crash never leaves one behind.
|
||
|
|
- `/etc/resolver/<network>` files pointing the system resolver at the overlay
|
||
|
|
DNS server for each network's zone, with a `port` so the server stays off 53.
|
||
|
|
Each file carries a marker line; the agent only ever replaces or removes files
|
||
|
|
it wrote, never one you created by hand.
|
||
|
|
- while broadcast is on, a `255.255.255.255` **route** through the overlay
|
||
|
|
interface. The matching inbound-UDP firewall allowance is **not** implemented
|
||
|
|
yet (it needs a `pf` anchor); `tsunagi status` reports that half as incomplete
|
||
|
|
and names what to allow by hand if your host firewall drops discovery replies.
|
||
|
|
|
||
|
|
Nothing taken from a remote peer ever becomes a path, a command argument or an
|
||
|
|
OS setting: the interface name comes from the kernel, addresses and ranges from
|
||
|
|
signed state the agent already verified.
|