authorized_keys
authorized_keys manages a user's ~/.ssh/authorized_keys on the node: the
file <home>/.ssh/authorized_keys of the account named by
for_user_account, with the home from the account database. Every task
says what happens to keys it does not list, with the required
keys_not_listed. keep adds the listed keys and keeps other lines.
remove makes the file contain exactly the listed keys, so removing
someone from the list removes their access.
The node HTTPS API process reads the same file for every new connection.
A key added this way gains MMX access; a removed key's next connection is
refused, as
Administrator SSH keys authorize HTTPS
describes. To give an account on a node its own key pair, use
ssh_key_pair. If the node's AuthorizedKeysFile
points elsewhere, use MMX's file module to manage the configured path.
Inputs
for_user_account(string; required): the account and its home must exist; with state: absent, or with keys_not_listed: remove and no keys, a missing account is unchangedkeys(list of strings; optional): OpenSSH key lines: [options] type base64-key [comment]; a key's identity is its type and base64 key; no key twice; at least one of keys, key_files_on_controller_machine, or key_directories_on_controller_machinekey_files_on_controller_machine(list of strings; optional): files on the controller machine, relative to the project root, or to the role's directory inside a role like file.source, each with one or more key lines; blank lines and lines starting with # are skipped; read when the run starts, so mmx resume uses the same keyskey_directories_on_controller_machine(list of strings; optional): directories on the controller machine; every file directly inside whose name ends in .pub, in name order, read like key_files_on_controller_machine; a directory without a .pub file fails, since an empty list could lock everyone out (write keys: [] to remove every key); like file.source, key_files_on_controller_machine and key_directories_on_controller_machine may read the node's name, vars, role inputs, and loop itemsreplace_options_of_listed_keys(boolean; defaultfalse): with keys_not_listed: keep or remove, true replaces existing listed lines with the task's lines, including removing restrictions absent from them; without it, plain keys preserve existing lines and different explicit options fail before changes; omit with state: absentkeys_not_listed(removeorkeep; required): keep adds missing keys and keeps unlisted lines; remove keeps only listed keys, and keys: [] empties the file; both preserve existing lines for plain keys and refuse different explicit options unless replace_options_of_listed_keys: true; omit with absentstate(presentorabsent; defaultpresent): absent removes the listed keys whatever their options; accepts only for_user_account, keys, key_files_on_controller_machine, and key_directories_on_controller_machine
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.
statuschangevalue.addedvalue.updatedvalue.removed
What a dryrun reports
Supported; lists keys to add, update, or remove by type, fingerprint, and comment.
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
Keys written in the task
- authorized_keys:
for_user_account: deploy
keys:
- ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIORZZg3NlYdxJ28janK/DsJ1O0O2YgF7KN2aiEPskegs alice@laptop
- ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAII3tDLF30LgdbEPBetQzx/5yTYIIskR2lUV8GRnqXzer bob@laptop
- 'from="10.0.0.0/8",no-agent-forwarding ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPpV63vQaaUhs7d11ravJpkOpRWhCElUYrbh42Kg0rrS ci'
keys_not_listed: remove
The account deploy accepts exactly these three keys: Alice's, Bob's, and
the key of the CI machine, which works only from 10.0.0.0/8 and without
agent forwarding. Options come before the key type. An entry may also be a
reference to a public-key variable you define, such as
"{{ .vars.alice_key }}". With keys_not_listed: keep, the task would add
the three keys and keep every other line.
Keys from files in the project
With one file for each person, the files decide who can log in:
- authorized_keys:
for_user_account: deploy
key_directories_on_controller_machine: [files/public_keys/production_deploy]
key_files_on_controller_machine: [files/ci.pub]
keys_not_listed: remove
key_files_on_controller_machine names files on your controller machine, and key_directories_on_controller_machine
names directories whose files ending in .pub MMX reads, in name order.
Deleting barbara.pub from the directory removes Barbara's key on the next
run.
One directory of keys for each environment
Like file.source, a path may contain references to what the controller
machine knows before it connects: the node's name, vars, role inputs, and
loop items. With an environment value in each inventory's vars, every
environment gets its own directory of keys:
- authorized_keys:
for_user_account: deploy
key_directories_on_controller_machine: ["files/public_keys/{{ .vars.environment }}"]
keys_not_listed: remove
Remove a person's key
state: absent removes every line containing a listed key from the
selected account's <home>/.ssh/authorized_keys, regardless of the line's
options:
- authorized_keys:
for_user_account: deploy
key_files_on_controller_machine: [files/public_keys/former/barbara.pub]
state: absent
For an account that no longer exists, the state: absent task succeeds
without changes, so offboarding does not fail after the account is gone.
How it works
Where the keys come from
The keys come from three fields, which add up to one list; at least one of them is required:
keys: key lines written in the task. An entry may be a reference, such as"{{ .vars.alice_key }}".key_files_on_controller_machine: files on the controller machine. Each holds one or more key lines; blank lines and lines starting with#are skipped.key_directories_on_controller_machine: directories on the controller machine. MMX reads every file directly inside whose name ends in.pub, in name order.
Both kinds of paths are relative to the project root, or to the role's
directory inside a role, as file.source is. A path with references is
resolved for every node of the inventory before the run starts.
Each key line is one OpenSSH key line: optional options, key type, base64
key, and optional comment, parsed as MMX's HTTPS authorization parses it. A
key's identity is its type and base64 body. MMX reads the key files when
the run starts and saves the keys with the run, so mmx resume installs
the same keys even after the files changed.
Keys that are not listed
keepadds missing listed keys after existing lines and keeps unlisted lines.removekeeps only listed keys, in the task's order;keys: []empties the file.
Both choices use the same options rule. Without
replace_options_of_listed_keys: true, a plain public-key line keeps every
existing line for that key, including its options and comment. A task line
with options must match the existing options; different options fail the task
before any change, in dryrun too. The error names the key, the file, the
node's options, the task's options, and the line to add.
With replace_options_of_listed_keys: true, the task's line replaces existing
listed lines and drops repeats, under both keep and remove. This can
remove restrictions such as from= when the task's line has none. A key
missing from the node is always added exactly as the task gives it.
state: absent accepts for_user_account and the three key fields and
removes those keys wherever they appear, whatever their options; a missing
file or key is unchanged.
Accounts that do not exist
A task that only takes keys away, state: absent or
keys_not_listed: remove with no keys, changes nothing for an account that
no longer exists, so offboarding does not fail after the account is gone.
Except for the removal-only cases above, tasks require the account and the
account's home directory. Dryrun reports tasks requiring an account and home
directory as not checked when the account or home directory is missing.
During a run, a missing account or home directory fails tasks requiring the
account and home directory.
The file and its directory
MMX creates .ssh with mode 0700 and authorized_keys with mode 0600
when missing, and sets both to the user and the user's primary group with
those modes. It writes through the atomic installer without following
links; a symlink at .ssh or at the file fails the task, because the
account controls that directory. An unchanged rerun finds the keys and
metadata already in place. The file is not an input of a node task block's
service.
Dryrun and results identify keys by type, SHA-256 fingerprint, and comment,
in .this_node_task.value.added, .updated, and .removed, instead of a
text difference. A run that fails before the file is written shows no value, so
a node task in on_failure can read what happened.
Errors and what they mean
| What fails | What the failure means, and what to do |
|---|---|
| Validation fails and names the file and line | A key line is malformed. |
| Validation fails and names both places | A key appears twice. Keep one. |
| Validation fails and names the file | A key file holds no key. |
| Validation fails and names the directory, and for a path with references the node | A key directory holds no file ending in .pub. MMX does not read alice_ed25519 or alice.key. To remove every key on purpose, write keys: []. |
| The run fails before it starts, naming the node and the path | A path with references resolves to a missing file or directory for that node. |
| Validation fails for a path that reads a fact or a node task's result | A fact is a value MMX gathers about a node, such as .node.arch. Facts and node task results are known only during the run. Use the node's name, vars, role inputs, or loop items. |
| The task reports different node and task options | Add replace_options_of_listed_keys: true to replace the existing line with the task's line, or make the task's options match. No file or metadata changes first. Dryrun also refuses differing node and task options. |
| The task fails for a symlink | <home>/.ssh or <home>/.ssh/authorized_keys is a symlink. MMX refuses the authorized_keys task. |
| A dryrun reports the task not checked | The account or its home does not exist yet; an earlier node task may create it. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45.
The base suite covers this module (access.py, account_units.py) and runs on every tested distribution.
Three suites cover the module on Debian 12 and 13 and Ubuntu 24.04 and 26.04:
tests/integration/access.py:keys_not_listed: keepwith HTTPS access,removerefusing HTTPS and SSH, andstate: absentrefusing HTTPS;tests/integration/account_units.py: key files and directories, resume with saved keys, and removal for a removed account;tests/integration/ssh_key_pairs.py: a key made byssh_key_pairon one node and accepted on another through a fleet stage output.
The validation record gives the latest results.
Why it works this way
-
File input names say controller machine. The controller process reads the files named by
key_files_on_controller_machineandkey_directories_on_controller_machinebefore connecting to nodes. The input names distinguish controller machine paths from node paths. -
keys_not_listedis required. A task that owns a list says what happens to the rest, as the rule for every module says. Withremove, deleting a person's file removes that person's access. -
A key directory without a
.pubfile fails. An empty list would makekeys_not_listed: removeemptyauthorized_keysand lock out every administrator, the key MMX connects with included. A task that means "no keys" sayskeys: []. -
Plain public keys keep existing restrictions under
keepandremove. Reading a.pubfile must not remove an administrator's access restrictions. Different explicit options fail because ignoring a restriction the task writes would give a wrong result without telling anyone. Replacing options needsreplace_options_of_listed_keys: true, following the protective-choice rule. -
Keys are saved with the run.
mmx resumeinstalls the saved keys even after the controller machine's source key files changed. -
A task that only removes keys is unchanged for a missing account. Offboarding then does not fail after the account is gone.
-
A symlink at
<home>/.sshor<home>/.ssh/authorized_keysfails. The account controls<home>/.ssh.
This page is docs/reference/modules/authorized_keys.md in the MMX repository.