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 existprivate_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_accountkey_type(ed25519orrsa; required): an existing private key of another type fails the taskkey_comment_when_created(string; default<for_user_account>@<nodename>): 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.
statuschangepublic_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 baretypefor 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.