sshd
Enables secure remote access to the machine over SSH
Clan service: sshd
What it does
- Generates and persists SSH host keys via vars
.
- Optionally issues CA‑signed host certificates for servers.
- Installs the server
CA public key into clients
known_hosts
for TOFU‑less verification.
When to use it
- Zero‑TOFU SSH for dynamic fleets: admins/CI can connect to frequently rebuilt hosts (e.g., server-1.example.com) without prompts or per‑host known_hosts
churn.
Roles
- Server: runs sshd, presents a CA‑signed host certificate for <machine>.<domain>
.
- Client: trusts the CA for the given domains to verify servers’ certificates.
Tip: assign both roles to a machine if it should both present a cert and verify others.
Quick start (with host certificates) Useful if you never want to get a prompt about trusting the ssh fingerprint.
{
inventory.instances = {
sshd-with-certs = {
module = { name = "sshd"; input = "clan-core"; };
# Servers present certificates for <machine>.example.com
roles.server.tags.all = { };
roles.server.settings = {
certificate.searchDomains = [ "example.com" ];
# Optional: also add RSA host keys
# hostKeys.rsa.enable = true;
};
# Clients trust the CA for *.example.com
roles.client.tags.all = { };
roles.client.settings = {
certificate.searchDomains = [ "example.com" ];
};
};
};
}
Basic: only add persistent host keys (ed25519), no certificates Useful if you want to get an ssh "trust this server" prompt once and then never again.
{
inventory.instances = {
sshd-basic = {
module = {
name = "sshd";
input = "clan-core";
};
roles.server.tags.all = { };
};
};
}
Example: selective trust per environment Admins should trust only production; CI should trust prod and staging. Servers are reachable under both domains.
{
inventory.instances = {
sshd-env-scoped = {
module = { name = "sshd"; input = "clan-core"; };
# Servers present certs for both prod and staging FQDNs
roles.server.tags.all = { };
roles.server.settings = {
certificate.searchDomains = [ "prod.example.com" "staging.example.com" ];
};
# Admin laptop: trust prod only
roles.client.machines."admin-laptop".settings = {
certificate.searchDomains = [ "prod.example.com" ];
};
# CI runner: trust prod and staging
roles.client.machines."ci-runner-1".settings = {
certificate.searchDomains = [ "prod.example.com" "staging.example.com" ];
};
};
};
}
Notes
- Connect using a name that matches a cert principal (e.g., server1.example.com
); wildcards are not allowed inside the certificate.
- CA private key stays in vars
(not deployed); only the CA public key is distributed.
- Logins still require your user SSH keys on the server (passwords are disabled).
Roles
The sshd module has the following roles:
- client
- server
Options for the client
role
certificate.searchDomains
List of domains to include in the certificate. This option will prepend the machine name in front of each domain before adding it to the certificate.
Type: list of string
Default:
Declared in: clanServices/sshd/default.nix
Options for the server
role
certificate.searchDomains
List of domains to include in the certificate. This option will prepend the machine name in front of each domain before adding it to the certificate.
Type: list of string
Default:
Declared in: clanServices/sshd/default.nix
hostKeys.rsa.enable
Whether to enable generating a RSA host key.
Type: boolean
Default:
Declared in: clanServices/sshd/default.nix