Watch
0
0
Fork
You've already forked hyperhive
0

egress: document the allowed ssh connections

This commit is contained in:
atlas 2026-11-20 03:25:50 +01:00
commit eab2dcb0a2
2 changed files with 73 additions and 19 deletions

View file

@ -737,11 +737,21 @@ also refuses the flow.
leaves alone too (see _Intercepted web traffic_). They leave no line, so a
`hive-egress-would-drop` line is exactly a flow that `reject` would refuse,
and a service container keeps every port and protocol under `reject`.
- **Named SSH connections.** Right after the `direct_mac` rule the chain
accepts TCP from an agent's MAC to an address and port in the `agent_allow`
set, in both modes, so such a flow leaves no count and no log line either.
The set holds, for each agent whose `ssh` switch is on, the addresses its
connections' hosts resolve to and their ports (see
[the SSH CA page](../swarm/ssh-ca.md#egress)). `hive-c0re` renders them into
`services.hyperhive.deploy.hive-controller.egress.connectionsFile`
(`/var/lib/hive-squid/ssh-connections`), and `hive-egress-pin` fills the set
from the file like `direct_mac`, when the file changes and on its timer. The
set is empty while the file is missing or empty.
- **What `reject` refuses.** Everything from the bridge to the uplink that the
chain didn't exempt, whether a flow is new or not: TCP on any port but the
80 and 443 that squid takes, UDP (DNS to an outside resolver, QUIC and NTP
included), ICMP and IPv6. A TCP flow gets a reset, so the connect fails at
once instead of stalling. Everything else gets ICMP administratively
chain didn't exempt or allow, whether a flow is new or not: TCP on any port
but the 80 and 443 that squid takes, UDP (DNS to an outside resolver, QUIC
and NTP included), ICMP and IPv6. A TCP flow gets a reset, so the connect
fails at once instead of stalling. Everything else gets ICMP administratively
prohibited. The log lines of this mode carry the prefix `hive-egress-reject `
(and `hive-egress-reject-unmetered `); the rate limit and the counter work as
in `log` mode. Still open to every agent are the host's own addresses: the
@ -761,6 +771,11 @@ also refuses the flow.
agent in the gap.
- An unreadable `unrestricted` file lists no agent, so `unrestricted` agents
lose every non-web flow.
- A new named connection, or a flipped `ssh` switch, reaches the set about a
minute after the write: the hive reads the swarm every 30 seconds and the
file's change runs a pass at once. A host that moves to an address the hive
hasn't looked up yet gets refusals for up to ten minutes. An agent whose
connection names a host that never resolved has no allowance for it.
- An agent in per-agent `log` mode keeps its web traffic, which squid only
observes, and loses every other port and protocol.
- **Which traffic.** IPv4 and IPv6 alike (the table is `inet`). The chain never

View file

@ -147,7 +147,8 @@ stores a connection and by the agent before it renders one:
its own proxy, so no direct connection there can exist.
The swarm doesn't check the hive's own bridge subnet, because each hive sets its
own and an agent can move between hives.
own and an agent can move between hives. Each hive drops an address of its own
subnet when it resolves a host (see [Egress](#egress)).
`hive-agent`'s `ssh_connections.rs` renders the list each time the harness reads
the record (every ten seconds) into `/run/hive-agent-ssh-connections/config`:
@ -159,11 +160,35 @@ agent user, because ssh refuses an included file that another user owns.
A controller older than the field drops the list when it next writes the
record through `PUT /permissions`.
## Not covered
## Egress
Egress. The default `egress.forward = "log"` lets a direct connection from an
agent to a machine's SSH port through, and `reject` blocks it; there is no
per-agent allowance for it yet.
The hive's forward chain accepts a named connection of an agent that has `ssh`
on, whatever `egress.forward` is (`log` or `reject`). Each hive does this for
the agents it has:
1. `hive-c0re`'s `workers::egress_connections` reads the permissions the hive
last read from the swarm and, for each agent with `ssh` on, resolves the
`host` of each connection with the host's resolver. An IPv4 literal passes
through. It asks the hosts of a pass together, each for at most five seconds,
so a hung resolver delays the file by that long and no more. It keeps an
answer for ten minutes and keeps the last answer when a lookup fails or
times out (one warning, until the name resolves again). It drops loopback,
link-local, multicast and IPv6 answers, and any address inside the hive's
bridge subnet (`HIVE_NETWORK_SUBNET`) with one warning per host, because a
flow to the bridge never reaches the forward chain. It writes
`<agent> <ipv4> <port>` lines to `egress.connectionsFile`, beside squid's
users file.
2. `hive-priv egress-pin` maps each agent to the MAC of its port and fills the
`agent_allow` set of the `inet hive_egress` table, in the same transaction
as `direct_mac`. `hive-egress-connections.path` runs a pass when the file
changes.
3. The forward chain accepts `ether saddr . ip daddr . tcp dport @agent_allow`
right after the `direct_mac` rule, so a matching flow is neither counted
nor logged.
The allowance is for TCP and IPv4 only: the agent bridge has no IPv6
addressing. An agent whose port has no binding yet has no allowance until it
gets one. See [the network page](../networking/network.md).
## Revocation