Watch
0
0
Fork
You've already forked hyperhive
0

swarm ui ssh row with target snippets, docs for the per-agent switch

This commit is contained in:
atlas 2026-11-16 18:38:10 +01:00 • committed by mara
commit e621397252

View file

@ -1,44 +1,33 @@
# 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. It asks the swarm's secret
store for a certificate that lasts an hour, and the machine trusts the swarm's
SSH certificate authority (CA) instead of a list of keys.
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.
Agent-side, nothing changes until you do both of these:
Two things have to be true before an agent gets in:
1. Switch SSH on for the agent and name the machines it may reach.
2. Make each machine trust the CA and list the agents allowed in.
1. **You switch SSH on for that agent**, in the swarm UI.
2. **The machine trusts the CA** and lists the agent.
The permission to get a certificate is in the policy every agent shares, so
every agent with a store identity can already get a certificate for its own
name, whether or not you switch SSH on for it. That's harmless: no machine
trusts a name it doesn't list. Switching SSH on only sets up the key, the
renewal and the client config.
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
In the agent's config:
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.
```nix
services.hyperhive.agent.ssh = {
enable = true;
hosts.testvm = {
hostName = "10.0.0.7";
user = "test";
port = 22; # the default
hostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
};
};
```
The agent then runs `ssh user@host`, with no other setup. It offers its
certificate and nothing else.
`hostKey` is the machine's own host public key, the one line in
`/etc/ssh/ssh_host_ed25519_key.pub` on it. The agent pins it: it refuses a
machine that presents any other key, and never trusts a key on first sight.
The agent then runs `ssh testvm` with no other flag. The agent's SSH client
offers its certificate and nothing else. The option needs the agent to have a
store identity, the same as for its other store credentials.
**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
@ -47,33 +36,31 @@ until a separate allowance exists; the default `log` lets it through. See
## 2. Make a machine trust the CA
On the swarm's store host, read the CA's public key:
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
```
The store also serves the same key without a token at
`<store address>/v1/ssh-agents/public_key`. The key is public and you set it
once. Then import the module on the machine, which can be any NixOS machine,
and not only a hive host:
```nix
{
imports = [ hyperhive.nixosModules.agent-ssh-target ];
services.hyperhive.agentSshTarget = {
enable = true;
caPublicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
principals.test = [ "atlas" "maia" ];
};
}
```
`principals.<user>` lists the agents that may log in as that local account. The
account has to exist. An account with no entry accepts no certificate. The
module writes no `authorized_keys`.
## What an agent can and can't do
- It can only get a certificate for **its own name**. The store signs for the
@ -86,19 +73,17 @@ module writes no `authorized_keys`.
## Revoking access
- **One agent from one machine:** remove its name from that user's
`principals` and deploy the machine. The next login attempt fails.
- **One agent from every machine:** remove its name from every machine's
`principals`. That's the revocation. No swarm-wide switch
stops signing for an agent that a hive still declares: if you delete
its cert-auth role `hive-agent-<name>` in the store, `swarm-controller`
writes it back within five minutes. Signing stops only once no hive declares
the agent any more (you destroyed it); the controller then stops renewing
its store identity, and the identity lapses with its 7-day certificate.
- **A certificate already issued** stays valid until it expires, at most three
hours, whatever you remove. Removing a principal blocks new logins at once.
- **The CA itself:** if the CA key changes, every machine needs the
new public key. Nothing replaces the CA by itself.
- **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).