Commit 6a7c7ed4 by PLN (Algolia)

README: document Linux, Arch and Ubuntu setup, the LAN face and the new commands

parent c57e079d
......@@ -23,13 +23,23 @@ setup — no `/etc/hosts`, no resolver config, no mDNS (`.local` collides with
Bonjour). Names are local-program-only **by construction**: the generated
Caddyfile aborts every connection whose source is not loopback, so nothing
leaks onto the LAN even though the proxy binds the wildcard (the only way an
unprivileged process can bind a low port on macOS).
unprivileged process can bind a low port on macOS; on Linux the
unprivileged-port sysctl opens low ports to every local process, so the guard
matters there too).
## Install
Requirements: macOS or Linux, [Caddy](https://caddyserver.com), Python 3.
For https: [mkcert](https://github.com/FiloSottile/mkcert) with a trusted root
(`mkcert -install`).
Requirements: macOS, Linux (Ubuntu, Debian, Arch, Fedora, others), or any Unix
that can run a foreground process; [Caddy](https://caddyserver.com); Python
3.9+ with the standard library only. For https:
[mkcert](https://github.com/FiloSottile/mkcert) with a trusted root
(`TRUST_STORES=system,nss mkcert -install`: skipping the Java store avoids an
exit 1 when no JDK keystore exists).
All OS specifics live in one platform layer. `devname doctor` names the
platform it detected and, for every failing check, prints the exact command
to fix it (brew, apt, pacman, dnf, sysctl, setcap, systemctl). It never runs
them.
```bash
git clone https://git.nech.pl/pln/devname.git && cd devname
......@@ -46,26 +56,45 @@ runs `devname serve`: Caddy as a supervised child plus the index server.
macOS lets an unprivileged process bind a low port only on the wildcard
address, which is exactly what devname does — no privileges needed.
### Linux — systemd (user unit)
### Linux: systemd (user unit)
`devname agent install` writes `~/.config/systemd/user/devname.service` and
starts it — no root for the daemon itself:
starts it. The daemon itself needs no root:
```bash
devname agent install --print # preview the unit; writes and starts nothing
devname agent install # unit + daemon-reload + enable --now
devname agent status # is-active
devname agent status # active / not active
devname agent restart # also: uninstall
loginctl enable-linger $USER # optional: run at boot without a login session
journalctl --user -u devname.service
```
The unit runs the system `python3` with `Restart=on-failure`, `RestartSec=5`
and a 5-starts-in-120-s limit, so a broken setup stops instead of looping
forever. Install refuses (unless `--force`) when the unit would crash-loop:
caddy missing, low ports closed, or a system caddy holding :80.
Binding `:80`/`:443` as an unprivileged user needs one of (pick one, once):
```bash
sudo sysctl net.ipv4.ip_unprivileged_port_start=80 # or 0
sudo setcap cap_net_bind_service=+ep "$(command -v caddy)"
# survives caddy upgrades; opens ports 80-1023 to every local user
echo 'net.ipv4.ip_unprivileged_port_start=80' | sudo tee /etc/sysctl.d/60-devname-low-ports.conf
sudo sysctl -p /etc/sysctl.d/60-devname-low-ports.conf
# or: only caddy, but a package upgrade of caddy drops it
sudo setcap cap_net_bind_service=+ep "$(readlink -f "$(command -v caddy)")"
```
`*.localhost` resolves to loopback through systemd-resolved (most distros);
without it, add the names to `/etc/hosts` yourself.
Debian and Ubuntu: `apt install caddy` (distro archive or the Caddy apt repo)
also enables and starts a **system** `caddy.service` on :80, which collides.
Turn it off: `sudo systemctl disable --now caddy`. For https add
`libnss3-tools` next to `mkcert` (Firefox/Chrome trust). Arch: `pacman -S caddy
mkcert nss`.
`*.localhost` must resolve to loopback for curl, Python and agents (browsers
hard-wire it and prove nothing). `doctor` checks it with `getaddrinfo`.
systemd-resolved answers it on most distros; otherwise add `myhostname` to the
`hosts:` line of `/etc/nsswitch.conf`, or list the names in `/etc/hosts`.
### Other inits
......@@ -76,19 +105,46 @@ Caddyfile, starts Caddy, serves the index page, and cleans up on SIGTERM.
## Commands
```
devname ensure [project] [--service S] [--branch B|auto] [--port N] [--keep-host] [--format url|port|json]
devname ensure [project] [--service S|'*'] [--branch B|auto] [--port N] [--alias] [--keep-host] [--format url|port|json]
devname ls [--json] devname rm <host> devname check <host>
devname gc [--idle-hours N] [--yes] (stale names; dry-run by default)
devname render devname serve devname doctor
devname agent install|status
devname agent install|uninstall|status|restart [--print] [--force]
```
- `<project>.localhost` — the project's main site
- `<service>.<project>.localhost` — a sub-service (`tests.leboard.localhost`)
- `<name>--<branch>[.<project>].localhost` — a branch variant; a worktree never
collides with the main checkout
- `*.<project>.localhost` (`--service '*' --port N`): one server routing any
single-label subdomain by Host; `--alias --port N` puts another name on an
already-registered port
The agent also serves the **index page** (`devname.localhost`): every
registered name with live up/down status, probed per request, plus `/json`.
registered name with live up/down status, plus `/json`. A poller probes every
name once a minute through the proxy and keeps 14 days of history, so the page
shows 24 h availability, 5xx count, p50/p95 latency and a 24 h / 14 d strip.
## LAN face (optional)
While an ssh handshake with a trusted host succeeds (`ssh <gate> true` with
BatchMode, so the gate's pinned host key is the proof), every name also
answers as `<name>.<lan host>.local` over https for phones on the home wifi,
with a private-range guard instead of the loopback one. If the gate fails or
there is no mDNS announcer, nothing is announced, Caddy gets no LAN blocks,
and loopback is untouched. `http://<lan host>.local/CA` serves the mkcert root
over plain http so a phone that trusts nothing yet can fetch it.
- Announcer: `dns-sd -P` on macOS, `avahi-publish -a -R` on Linux (needs
avahi-daemon and avahi-utils).
- `<lan host>`: `$DEVNAME_LAN_HOST`, else `lan_host` in
`$DEVNAME_HOME/config.json`, else `mac` on macOS and the short hostname
elsewhere (avahi already announces that one, so devname never re-announces
it).
- Gate host: `lan_gate_ssh` in the same file (default `domovoy-admin`).
- The LAN address is the kernel's route source toward the mDNS group, RFC 1918
only: a VPN address is never advertised.
- Firewalls: `doctor` prints the socketfilterfw, ufw or firewalld commands.
## For agents
......@@ -110,6 +166,10 @@ The registry is a flat `names.json` (`$DEVNAME_HOME`, default
python3 -m unittest discover tests
```
Every platform branch (launchd, systemd, other Unix, avahi, dns-sd, the
low-port and system-caddy checks) is covered with mocks, so the suite runs on
any OS without root, caddy or network.
## License
GPL-3.0-only — see [LICENSE](LICENSE).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment