ssh_key_pair

ssh_key_pair gives an account on one node its own SSH key, for example so that a backup service on backup01 can log in to the database servers. MMX runs the node's own ssh-keygen as the account named by for_user_account. The key has no passphrase, because a service uses it without a person typing one. The pair is made only when the private key does not exist, and MMX never replaces it.

The task's result field public_key holds the public key's line. A fleet stage output can give the public key line to authorized_keys on other nodes.

Set up

ssh-keygen comes from the package openssh-client on Debian and Ubuntu and openssh on the Red Hat family. Without it the task fails with the package to install:

- when: {equals: ["{{ .node.package_manager }}", apt]}
  apt_package: {packages: [{name: openssh-client, version: newest_when_first_installed}]}
- when: {equals: ["{{ .node.package_manager }}", dnf]}
  dnf_package: {packages: [{name: openssh, version: newest_when_first_installed}]}

Inputs

  • for_user_account (string; required): the account that owns the key files and runs ssh-keygen; it must exist
  • private_key_path (string; required): absolute private key path, such as /home/backup/.ssh/id_ed25519; the public key path adds .pub. MMX creates a missing parent directory with permissions_mode 0700, owned by for_user_account
  • key_type (ed25519 or rsa; required): an existing private key of another type fails the task
  • key_comment_when_created (string; default <for_user_account>@<node name>): one line, written at the end of the public key

Outputs

The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.

  • status
  • change
  • public_key

What a dryrun reports

Supported; reads an existing key's public key, or reports that the pair would be created; public_key is then not known, and tasks that read it report not checked.

Retries and time limits

Bounded automatic retries by default; retry: false turns them off.

The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.

Examples

A backup service that logs in to the database servers

The first fleet stage makes the key on backup01; the second gives its public key to authorized_keys on the nodes of group database:

# playbooks/backup_access.yml
fleet_stages:
  - id: create_backup_key
    nodes: backup01
    node_tasks:
      - id: backup_key
        ssh_key_pair:
          for_user_account: backup
          private_key_path: /home/backup/.ssh/id_ed25519
          key_type: ed25519
    outputs:
      backup_public_key: "{{ .node_tasks.backup_key.public_key }}"

  - id: accept_backup_key
    nodes: database
    requires:
      all_nodes: [create_backup_key]
    node_tasks:
      - authorized_keys:
          for_user_account: postgres
          keys:
            - "{{ .outputs.create_backup_key[\"backup01\"].backup_public_key }}"
          keys_not_listed: keep

On backup01, MMX runs the node's own ssh-keygen as the account backup and makes the private key /home/backup/.ssh/id_ed25519 and the public key /home/backup/.ssh/id_ed25519.pub. The task's result field public_key holds the public key's line, and the fleet stage publishes it as its output backup_public_key. The second fleet stage runs on the nodes of group database; the reference reads that output of fleet stage create_backup_key for node backup01. On each database node, authorized_keys adds that line for the account postgres.

key_comment_when_created, the text at the end of the public key, defaults to <account>@<node name>, here backup@backup01.

Make a new key

The module never replaces a key. To make a new key pair, first use file tasks to remove /home/backup/.ssh/id_ed25519 and /home/backup/.ssh/id_ed25519.pub. The next ssh_key_pair task then makes a new pair:

- file:
    path: /home/backup/.ssh/id_ed25519
    state: absent
- file:
    path: /home/backup/.ssh/id_ed25519.pub
    state: absent
- ssh_key_pair:
    for_user_account: backup
    private_key_path: /home/backup/.ssh/id_ed25519
    key_type: ed25519

Every node that accepted the old public key needs the new one.

How it works

The pair is made only when the private key does not exist. Every later run changes nothing and returns the same public_key, read from the .pub file, so the database nodes keep the key they already accepted.

When the private key exists and its .pub file is missing, MMX writes the .pub file again from the private key. A private key of another type than key_type, or a .pub file that holds another key than the private key's, fails the task.

When the directory directly above the private key, usually .ssh, is missing, MMX creates it with mode 0700, owned by the account. The private key gets mode 0600 and the public key 0644, both owned by the account and its group.

MMX never reads the private key, and it never appears in a result, in the output, in the saved run history, or on a command line: ssh-keygen writes it, and ssh-keygen -y derives the public key from it. The private key never leaves the node.

A dryrun on a node without the key reports that the pair would be created. The public key is not known yet, so node tasks and outputs that read public_key report not checked. A dryrun on a node that has the key reads public_key from the existing key pair, as a run does.

Errors and what they mean

What fails What the failure means, and what to do
The task fails and names the package to install ssh-keygen is missing; see Set up.
The task fails for another key type The private key exists and has another type than key_type. Correct key_type, or make a new key as in Make a new key.
The task fails for a .pub file that holds another key The public key file does not belong to the private key. Remove the .pub file; the next run writes it again from the private key.

Tested on

Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.

The suite tests/integration/ssh_key_pairs.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, with two nodes: a key made on one node and accepted on the other through an output, resume after a failure on the other node, an unchanged rerun, a rewritten .pub, another key type, and the private key absent from output, saved runs, job records, and the journal. The validation record gives the latest results.

Why it works this way

  • MMX never replaces an existing key. A second run must return the same public key, and a key in use must not change under the service that uses it.
  • No passphrase. A service uses the key unattended.
  • The fields name the key in full: for_user_account, private_key_path, key_type, key_comment_when_created. The task has two files, and MMX uses a bare type for the type of a command-line variable.

The name key_comment_when_created follows the creation-name rule: changing the requested comment does not rewrite an existing key.

This page is docs/reference/modules/ssh_key_pair.md in the MMX repository.