120 lines
5.5 KiB
Markdown
120 lines
5.5 KiB
Markdown
# SSH access to a machine
|
|
|
|
Let an agent SSH into a machine you name, such as a test VM, without copying a
|
|
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.
|
|
2. **The machine trusts the CA** and lists the agent.
|
|
|
|
Every agent already has an SSH client, a key it makes in memory, and a
|
|
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. 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
|
|
certificate and nothing else.
|
|
|
|
**Host keys use trust on first use.** The agent accepts the key a machine
|
|
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
|
|
[the network page](../../4-implementation/networking/network.md).
|
|
|
|
## 2. Make a machine trust the CA
|
|
|
|
Open **on the target** in the same row. It shows the swarm's CA public key, a
|
|
public value, and the agent's name, in three forms. Replace `<user>` with the
|
|
account the agent logs in as. The target never contacts the swarm.
|
|
|
|
- **NixOS:** the CA key in `services.openssh.settings.TrustedUserCAKeys` and
|
|
`users.users.<user>.openssh.authorizedPrincipals = [ "<agent>" ];`. The same
|
|
as one module: import `hyperhive.nixosModules.agent-ssh-target` and set
|
|
`services.hyperhive.agentSshTarget` (`enable`, `caPublicKey`,
|
|
`principals.<user>`).
|
|
- **home-manager:** `home.file.".ssh/authorized_keys".text` holding one
|
|
`cert-authority` line.
|
|
- **plain ssh:** one line in the account's `~/.ssh/authorized_keys`:
|
|
|
|
```
|
|
cert-authority,principals="<agent>" ssh-ed25519 AAAA…
|
|
```
|
|
|
|
This works on any machine without a change to its sshd config.
|
|
|
|
To read the CA key outside the UI, run this on the swarm's store host:
|
|
|
|
```bash
|
|
bao read -field=public_key ssh-agents/config/ca
|
|
```
|
|
|
|
## What an agent can and can't do
|
|
|
|
- It can only get a certificate for **its own name**. The store signs for the
|
|
name its identity carries, so atlas can't obtain one that says maia.
|
|
- The certificate lasts an hour, and the agent signs a new one every 20
|
|
minutes. The key lives in the agent's `/run` (memory) and never reaches disk.
|
|
A new container start makes a new key.
|
|
- It signs ed25519 user keys only, and the certificate allows a terminal
|
|
(`permit-pty`) and nothing else.
|
|
|
|
## Revoking access
|
|
|
|
- **One agent from one machine:** remove its principal (the `authorizedPrincipals`
|
|
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 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.
|
|
- **The CA itself:** if the CA key changes, every machine needs the new public
|
|
key. Nothing replaces the CA by itself.
|
|
|
|
For the bao paths, field names and units, see
|
|
[the SSH CA implementation page](../../4-implementation/swarm/ssh-ca.md).
|