Skip to content

sshd

Enables secure remote access to the machine over SSH with automatic host key management and optional CA-signed host certificates.

System
Network

What it does

  • Generates and persists SSH host keys via vars.
  • 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 = {
        # Optional: add additional search domains besides `meta.domain` from `clan.nix`
        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 = {
        # Optional: add additional search domains besides `meta.domain` from `clan.nix`
        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" ];
      };
    };
  };
}

Explanation

  • Admin -> server1.prod.example.com: zero-TOFU (verified via cert).
  • Admin -> server1.staging.example.com: falls back to TOFU (or is blocked by policy).
  • CI -> either prod or staging: zero-TOFU for both. Note: server and client searchDomains don't have to be identical; they only need to overlap for the hostnames you actually use.

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 service has the following roles:

  • client
  • server

Options for the client role

certificate.searchDomains

List of extra domains to include in the certificate in addition to the clan's internal domain configured via meta.domain in clan.nix. This option will prepend the machine name in front of each domain before adding it to the certificate.

Type: list of string

Default:

[ ]
Example 
[
  "mydomain.com"
]

Declared in: clanServices/sshd/default.nix

Options for the server role

authorizedKeys

SSH public keys authorized for root access. WARNING: Removing these keys will lock you out of SSH access to this machine.

Type: attribute set of string

Default:

{ }
Example 
{
  admin-key = "ssh-ed25519 AAAA...";
}

Declared in: clanServices/sshd/default.nix

certificate.searchDomains

List of extra domains to include in the certificate in addition to the clan's internal domain configured via meta.domain in clan.nix. This option will prepend the machine name in front of each domain before adding it to the certificate.

Type: list of string

Default:

[ ]
Example 
[
  "mydomain.com"
]

Declared in: clanServices/sshd/default.nix

generateRootKey

Whether to enable Generates an SSH key pair for ssh root access..

Type: boolean

Default:

false
Example 
true

Declared in: clanServices/sshd/default.nix

hostKeys.rsa.enable

Whether to enable generating a RSA host key.

Type: boolean

Default:

false
Example 
true

Declared in: clanServices/sshd/default.nix