Watch
0
0
Fork
You've already forked hyperhive
0

sign ssh certificates on demand from ssh itself, warn before setup, say what to do when a host key changes

This commit is contained in:
atlas 2026-11-16 19:42:44 +01:00 • committed by mara
commit 3d7541c0af

View file

@ -5,6 +5,13 @@ key onto it. The agent holds no standing SSH key. While you allow it, the agent
gets a certificate from the swarm's SSH certificate authority (CA) that lasts
an hour. The machine trusts the CA, so it needs no list of keys.
> **Warning:** SSH access with no constraints on the machine makes the agent
> unconstrained there. Whatever the agent's own sandbox stops it doing, it can
> do on a machine it can log in to. Switch SSH on only for machines you would let
> the agent control completely. What the agent can do on the machine is up to
> the account you let it use: give it an account with only the rights you want
> it to have.
Two things have to be true before an agent gets in:
1. **You switch SSH on for that agent**, in the swarm UI.
@ -16,9 +23,14 @@ certificate unit. The switch alone decides whether the swarm signs.
## 1. Switch it on for an agent
Open the agent's card in the swarm UI and find the **ssh** row. Select it and
tick **allow the agent to get SSH certificates**. The default is off. The
agent has a certificate within about 25 minutes of the change. Untick the box
to stop new certificates. The row also shows the three forms of the target
tick **allow the agent to get SSH certificates**. The default is off. Untick the
box to stop new certificates.
The change takes seconds, not minutes. The swarm updates the agent's login
within a few seconds. The agent gets its certificate the first time it runs
`ssh` after that, so there is nothing to wait for on the agent. If it ran `ssh`
just before you ticked the box, the next run within ten seconds still finds the
refusal remembered; after that it signs. The row also shows the three forms of the target
setup below, already filled in with the swarm's CA key and the agent's name.
The agent then runs `ssh user@host`, with no other setup. It offers its
@ -29,6 +41,25 @@ shows on the first connection, keeps it in its state directory (so it survives
restarts), and refuses a changed key afterwards. A swapped machine on the first
contact would go unnoticed. The row's explainer says so.
### When a host's key changes
The agent refuses a machine whose key differs from the one it kept, and `ssh`
says the host identification changed. A rebuilt or replaced machine does this.
Verify the new key out of band first: read the machine's host key on the machine
itself (`ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`) and compare it with
the fingerprint the agent reports. If it matches, tell the agent to forget the
old one. On the hive host, as root:
```bash
ssh-keygen -R <host> -f /agents/<agent>/state/ssh_known_hosts
```
The next connection records the new key. You can also delete the line, or the
whole file, at that path. To work inside the agent's container instead, see
[`hivectl`](../hives/hivectl.md) for the shell it opens as the agent user. If the
key changed and you didn't change the machine, don't clear it: something else
answers at that address.
This doesn't open the network. If you set the hive's `egress.forward` to
`reject`, the hive refuses the agent's direct connection to the machine's port
until a separate allowance exists; the default `log` lets it through. See
@ -77,8 +108,8 @@ bao read -field=public_key ssh-agents/config/ca
entry, or the `cert-authority` line) and deploy the machine. The next login
attempt fails.
- **One agent from every machine:** untick the switch. The swarm stops signing
for it within five minutes; an agent already signed in can still sign
for up to an hour. Destroying the agent cuts its store identity off within
for it within seconds; a token the agent got while the switch was on can still
sign for up to an hour. Destroying the agent cuts its store identity off within
minutes. Either way a certificate already signed stays valid until it
expires, at most three hours, so removing the principal on a machine is what
cuts it off there at once.