3.3 KiB
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.
Nothing changes until you do both of these:
- Switch SSH on for the agent and name the machines it may reach.
- Make each machine trust the CA and list the agents allowed in.
1. Switch it on for an agent
In the agent's config:
services.hyperhive.agent.ssh = {
enable = true;
hosts.testvm = {
hostName = "10.0.0.7";
user = "test";
port = 22; # the default
hostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
};
};
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.
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.
2. Make a machine trust the CA
On the swarm's store host, read the CA's public key:
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:
{
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 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 name from that user's
principalsand deploy the machine. The next login attempt fails. - One agent from every machine: delete its cert-auth role
hive-agent-<name>in the store. It can no longer log in to the store, so nothing signs for it, and its last certificate lapses within three hours. - 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.