vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs(gateway): describe what is, not what changed

Browse source 
Per review: docs represent current state. Every "used to" / "no longer"
clause this branch introduced is gone — including the History section in
network.md, which was a whole subsection about a sync mechanism that
doesn't exist.

Where the removed clause was carrying a real constraint, the constraint
stays and is stated in the present tense instead of as a delta: nothing
narrows what the gateway's nginx can reach except the directory
permissions in front of a socket, and nothing bounds `ReloadGatewayNginx`
except the hard-coded unit name. Those read as rules now rather than as
the story of how they came to be rules.
This commit is contained in:
atlas 2026-08-11 18:09:51 +02:00
commit 98d895cf9e
15 changed files with 77 additions and 146 deletions
Download patch file Download diff file Expand all files Collapse all files

29
docs/boundary.md
View file

@ -121,25 +121,18 @@ The mode is load-bearing, not cosmetic. Write permission on a
them, and the sticky bit is the only thing that would restrain that (it
is not set here). A world-writable socket dir therefore lets anything
able to reach the path delete an agent's socket and bind its own — and
nginx reaches all of `/run/hive-agent` (as a plain host path since the
gateway moved out of its container; it used to be bind-mounted in, which
was the same reach through a longer route). Dropping `o=w` removes that
permission rather than qualifying it.
nginx reaches all of `/run/hive-agent` as a plain host path. Dropping
`o=w` removes that permission rather than qualifying it.
⚠️ **The gateway leaving its container is a deliberate trade, recorded
here so it is not mistaken for an oversight.** nginx and dnsmasq run on
the host next to `hive-c0re` (see `docs/gateway.md`). What was given up
is a *mount/pid* namespace — **not** a network one: that container ran
with `privateNetwork = false` and shared the host's netns, so nginx was
already binding host ports and already reaching `localhost` upstreams.
The boundary bought no network isolation while costing a resolv.conf
sync, a reload that had to cross the machine bus, and three bind mounts.
🔑 It did cost one real thing, and the replacement is explicit: the
privileged reload verb used to be scoped by `--machine=hive-gateway`,
which could only ever reach into that one container. With no namespace
to bound it, the unit name is hard-coded in `hive-priv` instead — see
`PrivRequest::ReloadGatewayNginx`. **A caller cannot name the unit, so
the verb cannot be steered at another service.**
⚠️ **The gateway's nginx and dnsmasq are host services, next to
`hive-c0re`** (see `docs/gateway.md`) — there is no namespace between
them and the rest of the host. That costs no network isolation: nginx
binds the host's `:80`/`:443` and reaches `localhost` upstreams, which a
netns would have to be opened up for anyway.
🔑 It does mean nothing *implicitly* scopes the privileged reload verb,
so the scope is explicit: the unit name is hard-coded in `hive-priv` —
see `PrivRequest::ReloadGatewayNginx`. **A caller cannot name the unit,
so the verb cannot be steered at another service.**
⚠️ Contrast `/shared`, which *is* sticky world-writable (`1777`): it has
many legitimate writers, so sticky is the best available answer there.