Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/2-handbook/external-accounts/ssh.md

89 lines
4 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.
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. 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
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.
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 five minutes; an agent already signed in 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).