Playbook file reference
This page lists every field of a playbook file, for looking up. A
playbook is a file playbooks/<name>.yml in your MMX project. It lists
fleet stages, which run in order. Each fleet stage selects nodes,
the servers that MMX manages, from the inventory, the file
inventories/<name>.yml that lists them. Each selected node runs the
fleet stage's node tasks in order. Most node tasks call one module,
the code that does the work, such as file or apt_package.
A node task block (task_block) groups a change with the node tasks
that put the change into use and check it. The page also lists the
references and template functions that a value can use, and the facts that
MMX measures on each node. To write a playbook step by step, see
Write a playbook.
Each module's own inputs are on the module's page in
reference/modules/, or in mmx describe-module NAME.
The playbook file
# playbooks/set_up_web_servers.yml
command_line_vars: # values given with --var on the command line
release:
type: string
default: "1.4.3"
fleet_stages:
- id: set_up_nginx # a fleet stage
nodes: web_servers # the nodes it selects
max_nodes_at_once: 1 # one node at a time
node_tasks: # what each selected node does, in order
- id: install_nginx # a node task that calls the module apt_package
apt_package:
packages:
- {name: nginx, version: newest_when_first_installed}
- show: "Release {{ .vars.release }} on {{ .node.name }}"
| Field | Value | What it does |
|---|---|---|
fleet_stages |
A list of fleet stages; required, not empty | The work, in order. See Fleet stage fields. |
command_line_vars |
A mapping; optional | Variables that --var NAME=VALUE sets. See command_line_vars. |
- The name. The file's name without
.ymlis the playbook's name, which each command takes:mmx run set_up_web_servers. A command takes the name, never a path:mmx run playbooks/set_up_web_servers.ymlfails withplaybook must be a name, not a path. A playbook name starts with a letter or an underscore. A name that starts with a date is a one-time playbook inone_time_playbooks/. - YAML that MMX refuses. The file is one YAML document. MMX refuses
anchors and aliases (
&name,*name), merge keys (<<), explicit tags (!!str), and duplicate keys. A boolean istrueorfalse:Truefails withspell booleans true or false, andyeswithexpected bool, got !!str. A misspelled field fails with its line and column:line 4 column 5 (fleet_stages[0].unknown_thing): unknown field. - Check a playbook with
mmx validate set_up_web_servers. It needs no server and printsValid:and the project's name.
command_line_vars
command_line_vars declares the variables that a command sets with
--var NAME=VALUE. Node tasks read them as .vars.NAME, with the same
value on every node.
command_line_vars:
release: # a name you choose
type: string # no default: each run must give --var release=...
run_migrations:
type: boolean
default: true
mmx run deploy --var release=1.4.3 --var run_migrations=false
| Field | Value | Default |
|---|---|---|
type |
string, integer, or boolean; required |
None. |
default |
A value of the type, written out, not a reference | None: mmx explain, mmx dryrun, and mmx run then need --var for the variable. |
- A name starts with a letter or an underscore and holds letters, digits, underscores, and hyphens.
- The name must not also be in any
vars: of the project, the inventory, a group, or a node. The error iscommand-line variable release must not also be set in vars. - A reference as
defaultfails withcommand-line variable release default must be a literal string. - Command-line variables
lists how
--varreads each type, which commands take--var, and why MMX refuses an empty value for a variable without a default.
Fleet stage fields
A fleet stage is one entry in fleet_stages. The controller machine, the
computer where you run mmx, selects the fleet stage's nodes and starts
each node's work. A fleet stage needs id; nodes or a loop; and
node_tasks, outputs, or both. The other fields are optional.
| Field | Value | Default | What it does |
|---|---|---|---|
id |
A name; required | None | Names the fleet stage in output, results, --only-fleet-stages, requires, and .outputs.<id>. Starts with a letter or an underscore; letters, digits, underscores, and hyphens. Unique in the playbook. |
nodes |
A node or group name, a list of names, all, or a reference |
None | The nodes the fleet stage selects. |
except_nodes |
Like nodes |
None | Nodes left out of the selection. |
skip_when_no_nodes_are_selected |
true or false |
false |
Leaves out a fleet stage that selects no node, instead of refusing the playbook. |
when |
A condition | None: every selected node runs | Checked for each node, just before the node starts. |
node_tasks |
A list of node tasks | None | The work on each node. A fleet stage needs node_tasks, outputs, or both. |
outputs |
A mapping of names to values | None | Values that later fleet stages read. |
save_on_controller_machine |
A list of files | None | Writes outputs to files on the controller machine. |
max_nodes_at_once |
A count, such as 5, or a percentage, such as "50%" |
The project's max_nodes_at_once, or 100 |
How many nodes work at once. |
wait_for_all_in_batch |
true or false |
false |
Finishes each group of nodes before the next group starts. |
on_node_failure |
continue, stop_fleet_stage, or stop_run |
continue |
What a failed node stops. |
failed_nodes_allowed |
A count or a percentage | 0 |
Failures allowed before on_node_failure stops work. |
requires |
same_node and all_nodes lists of fleet stage IDs |
None | Earlier fleet stages that must have succeeded. |
loop, as, key, fleet_stages |
See the entry | None | Repeats a list of fleet stages for each item. |
for_each_node, as, fleet_stages |
See the entry | None | Repeats a list of fleet stages for each node. |
nodes and except_nodes
nodes selects the nodes that run the fleet stage. except_nodes removes
nodes from that selection.
fleet_stages:
- id: turn_on_security_updates
nodes: all # every node in the inventory
except_nodes: load_balancers # but not these
node_tasks:
- role: security_updates
- A value is one name or a list of names. A name is a node, a group, or
all, which selects every node of the inventory that the command uses. A list selects each node that any of its names selects. - A name that is not in the inventory fails with
no node or inventory group named "metrics". - An empty selection fails with
node selection is empty, and anexcept_nodesthat removes every node fails withexcept_nodes leaves no node of nodes. The reason: a group that someone emptied by mistake does not make its work disappear without a word. Set skip_when_no_nodes_are_selected for a group that may be empty on purpose. An empty group inexcept_nodesremoves nothing and is no error. - A value can be a reference, such as
nodes: "{{ .server }}"inside a for_each_node loop, or a reference to an earlier fleet stage's output. A selection that reads an output is known only during the run. mmx nodes set_up_web_serverslists each fleet stage's selection before any connection.--limitnarrows the selection further: Choose which servers a run touches.
skip_when_no_nodes_are_selected
skip_when_no_nodes_are_selected: true leaves a fleet stage out of the run
when its selection is empty, instead of refusing the whole playbook.
- id: configure_staging_server
nodes: staging # a group that may have no node
skip_when_no_nodes_are_selected: true
node_tasks:
- role: shop_website
inputs:
heading: Staging
- MMX looks at
nodesminusexcept_nodes, before--limit. A fleet stage that selects nodes ignores the setting. A name that is not in the inventory is still an error. mmx nodesand the run then say→ none; selection contains no nodes (skip_when_no_nodes_are_selected).- A left-out fleet stage's
.outputs.<id>is an empty mapping, andrequires: {all_nodes: [<id>]}on it is met. - A
for_each_nodeloop takes the setting. Aloopover items that are not nodes does not: put the setting on the fleet stages inside the loop. - Keep a fleet stage for a group that may be empty
shows a run, the secrets that such a run does not need, and the JSON
field
left_out_because_it_selects_no_nodes.
when on a fleet stage
A when on a fleet stage is checked by mmx on the controller machine for
each selected node, just before that node would start the fleet stage. A
node whose condition is false is recorded skipped.
- id: install_sensors
nodes: all
when:
equals: ["{{ .node.virtualization.type }}", none] # physical servers only
node_tasks:
- apt_package:
packages:
- {name: lm-sensors, version: newest_when_first_installed}
- What the condition reads: the node's own
.vars,.inventory, the node's name as.node.name, a loop'sasvariable, and the outputs and outcomes of earlier fleet stages, such asnot: "{{ .outputs.find_leader[.node.name].is_leader }}". On afor_each_nodeloop,.nodeis the loop's node. The condition cannot read node task results (.node_tasks), because no node task has run. - A condition that reads a fact, any
.nodefield except.node.name, makesmmxask that node for its facts just before it decides, over the usual connection. A node that cannot be reached, or does not answer, fails as its work would have, and the fleet stage'son_node_failureapplies. A condition that reads no fact contacts no node. - A skipped node starts no work, takes no place in
max_nodes_at_once, and is not a failure. Its result keeps the condition as the reason, and the facts that the decision used. It counts as succeeded for the record of the last success, and it is left out of the fleet stage's whole output collection.requires: {all_nodes: [...]}on the fleet stage is not met by a skipped node, because a requirement says that the work happened. mmx nodesmarks the selection asnarrowed during the run by `when`.mmx resumedoes not check awhenagain for a node that the run already let start. A newmmx runchecks everywhenagain.- On a
loopover fleet stages,whenis checked for each iteration. A skipped iteration is left out of the loop's output collection. - The forms of a condition, such as
equals,all, andnot, are listed in Conditions. - Decide for each server during the run shows a run with skipped nodes.
outputs
outputs names values that a fleet stage publishes for each of its nodes.
A later fleet stage reads them as .outputs.<fleet stage>.<node>.<name>.
- id: prepare_database
nodes: db01
node_tasks:
- id: read_database_name
read_file:
path: /etc/shop/database_name
content_is_secret: false
outputs:
database_name: "{{ .node_tasks.read_database_name.content }}"
address: "{{ .node.network.default_ipv4_address }}"
- An output name starts with a letter or an underscore. A value is any
value, with references; a value that is one condition, such as
equals: [...], becomestrueorfalse. - MMX computes a node's outputs after the fleet stage's node tasks
succeeded on that node. A fleet stage with
outputsand nonode_taskspublishes values only. - A loop's
outputsare published for each iteration, under the iteration'skey. - How a later fleet stage reads an output lists the references and what a failed, skipped, or left-out producer does to a reader.
save_on_controller_machine
save_on_controller_machine writes the fleet stage's outputs to files on
the controller machine, after the fleet stage's nodes finish.
save_on_controller_machine:
- output: address # one file for each node
path: "server_details/{{ .node.name }}.txt"
permissions_mode: "0644"
| Field | Value |
|---|---|
output |
An output name of the fleet stage: one file for each node. |
template |
A template file, rendered once from the whole output collection: one file. |
path |
The file to write. A relative path starts at the project directory and must stay inside it. An absolute path may name any place on the controller machine. |
permissions_mode |
The file's mode, such as "0644"; required. |
secret_readable_by_group, dangerously_let_every_account_read_secret |
For an output that holds a secret: see Secrets in files, output, and history. |
- Set exactly one of
outputandtemplate. - A
loopover fleet stages takes nosave_on_controller_machine; put it on a fleet stage inside the loop. - Save outputs to files on your controller machine shows both kinds and the files they write.
Rollout fields
These fields decide how many nodes work at once and what a failed node stops. Roll out a change gradually shows each one in a run.
- id: set_up_nginx
nodes: web_servers
max_nodes_at_once: "50%" # half of the selected nodes at a time
wait_for_all_in_batch: true # finish each half before the next starts
on_node_failure: stop_run # a failed node stops the run
failed_nodes_allowed: 1 # after a second failed node
node_tasks:
- role: shop_website
inputs:
heading: Shop
| Field | Value | What it does |
|---|---|---|
max_nodes_at_once |
A positive count, such as 5, or a whole-number percentage from 1% to 100%, such as "50%" |
How many of the fleet stage's nodes work at once. A percentage counts the nodes selected after --limit, rounds down, and is never less than one node. Without it, the project's max_nodes_at_once in mmx_project_settings.yml applies, or 100 nodes when that is unset. The project setting takes a count only. |
wait_for_all_in_batch |
true or false; default false |
false starts a node as soon as another finishes. true finishes each group of max_nodes_at_once nodes before any node of the next group starts. |
on_node_failure |
continue (the default), stop_fleet_stage, or stop_run |
continue: the other nodes go on. stop_fleet_stage: no further node starts this fleet stage. stop_run: no further node starts this fleet stage, and no later fleet stage starts. |
failed_nodes_allowed |
A count, such as 1, or a whole-number percentage up to 100%, such as "25%" |
The failures that the fleet stage tolerates before on_node_failure stops work. A percentage counts the nodes selected after --limit and rounds down. Needs on_node_failure: stop_fleet_stage or stop_run. |
- Under every policy, a failed node runs none of its later fleet stages, and nodes that already work finish.
- With
on_node_failure: continue,failed_nodes_allowedfails withfailed_nodes_allowed requires on_node_failure: stop_fleet_stage or on_node_failure: stop_run; on_node_failure: continue does not stop after node failures. - Inside a for_each_node loop, write
on_node_failureandfailed_nodes_allowedon the loop, which counts failures by the loop's nodes. On a fleet stage inside the loop they fail withfleet stage inner is inside for_each_node loop outer, which counts failures by the loop's nodes; write on_node_failure on the loop. - Choose what a failed server stops says how MMX counts failures.
requires
requires names earlier fleet stages that must have succeeded before a
node starts this fleet stage.
- id: write_price_list
nodes: web_servers
requires:
same_node: [back_up_price_list] # succeeded on the node about to start
all_nodes: [prepare_database] # succeeded on every node it selected
node_tasks:
- file:
path: /srv/shop/public/prices.html
permissions_mode: "0644"
content: "<h1>Prices</h1>\n"
same_node: each listed fleet stage succeeded on the node that is about to start.all_nodes: each listed fleet stage succeeded on every node that it selected.- Each ID must name an earlier fleet stage:
requirement X must name an earlier fleet stage. - When both fleet stages select from the inventory, a
same_nodefleet stage must select every node of the fleet stage that requires it. - A node that a requirement blocks does not start, and is not counted
against
failed_nodes_allowed. - A fleet stage that reads another fleet stage's outputs needs no
requiresfor it: reading an output already waits for that node's success. - Run a fleet stage only where an earlier one succeeded shows a run.
loop over fleet stages
A fleet stage with loop repeats its own fleet_stages for each item of a
list or a mapping, one item after the other. Use it for a list of things
that are not nodes.
- id: add_shops
loop: [north, south]
as: shop # each item, read as .shop
key: "{{ .shop }}" # names each iteration in output and results
fleet_stages:
- id: create_shop_directory
nodes: web_servers
node_tasks:
- directory:
path: "/srv/shops/{{ .shop }}"
| Field | Value |
|---|---|
loop |
A list, a mapping, or one whole reference to a list or a mapping; required. A list runs in written order; a mapping in the sorted order of its keys, with .<as>.key and .<as>.value. |
as |
The variable that holds each item; required. Not one of vars, inputs, node, inventory, this_node_task, node_tasks, outputs, fleet_stages, new_file, or secrets, and not a name that an enclosing loop uses. |
key |
A stable text for each iteration; required. Results show it as add_shops[north]/create_shop_directory. |
fleet_stages |
The fleet stages that each iteration runs; required. |
when, outputs |
As on any fleet stage, for each iteration. |
A loop selects no nodes itself: nodes, except_nodes,
skip_when_no_nodes_are_selected, node_tasks, requires,
save_on_controller_machine, and the rollout fields
belong on the fleet stages inside the loop.
for_each_node
A fleet stage with for_each_node repeats its fleet_stages for each
selected node, one node's whole sequence at a time. Use it when a node's
share of the work happens partly on another node, such as taking each app
server out of the load balancer while it changes.
- id: update_each_web_server
for_each_node: web_servers # selects nodes like nodes
as: server # the current node's name, read as .server
on_node_failure: stop_run
fleet_stages:
- id: take_out_of_balancer
nodes: lb01 # a helper node, working for .server
node_tasks:
- shell:
script: /usr/local/bin/balancer-drain "$SERVER"
env: {SERVER: "{{ .server }}"}
- id: update
nodes: "{{ .server }}"
node_tasks:
- role: shop_website
inputs:
heading: Shop
| Field | Value |
|---|---|
for_each_node |
Like nodes: the nodes to repeat for; required. Each node is one iteration, named by the node. |
as |
The variable that holds the current node's name; required. Same name rules as a loop's as. |
fleet_stages |
The fleet stages each iteration runs; required. They select their nodes, often nodes: "{{ .server }}". |
except_nodes, skip_when_no_nodes_are_selected, when, outputs |
As on a fleet stage. when is checked for each loop node, with .node as that node. |
max_nodes_at_once, wait_for_all_in_batch, on_node_failure, failed_nodes_allowed |
As on a fleet stage, counted by the loop's nodes: max_nodes_at_once: 2 runs two iterations at once. |
for_each_nodetakes noloop,key,nodes,node_tasks, orrequires, and it refusessave_on_controller_machine: put that on a fleet stage inside the loop.- A node that an iteration uses for another node, such as
lb01above, is a helper node. A--limitstill reaches the helper node. rebootis the last node task of a fleet stage. For a reboot in the middle of an iteration, use two fleet stages inside the loop.- Take each server out of the load balancer while it changes shows a whole run, and Do one server's work on another server shows a loop that hands a value from one node to another.
Node task fields
A node task is one entry in node_tasks. It does exactly one of five
things, and may add the settings in the second table.
| What the node task does | Field | Example |
|---|---|---|
| Calls a module | The module's name, with the module's inputs below it | file: {path: /etc/motd, content: "Hello\n", permissions_mode: "0644"} |
| Calls a role | role, with inputs |
role: shop_website (see Role calls) |
| Groups a change with what follows it | task_block |
See task_block fields |
| Shows a message or a value | show |
show: "{{ .node.name }}" (see show) |
| Sets variables for later node tasks | set_vars |
set_vars: {large_server: true} (see set_vars) |
A node task with two of these fails with a node task must specify exactly one action: a module call, role, task_block, show, or set_vars.
| Setting | Value | Default | What it does |
|---|---|---|---|
id |
A name | None | Names the node task and its result. |
when |
A condition | None: the node task runs | Skips the node task when false. |
loop |
A list, a mapping, or one whole reference | None | Runs the node task once for each item. |
as |
A name | None; required with loop |
The variable that holds each item. |
key |
Text, usually a reference to the item | The item's index or mapping key | Names each iteration. Required for some loops. |
retry |
true, false, or a mapping |
Depends on the module | Tries the node task again after a failure. |
time_limit |
A duration or null |
node_task_defaults.time_limit, else none |
Time for the whole node task, with every try. |
time_limit_per_try |
A duration or null |
node_task_defaults.time_limit_per_try, else none |
Time for one try. |
mmx describe-module task prints the settings table, and
mmx describe-module task_block, role, show, and set_vars print the
other forms.
id and the result of a node task
id names a node task. Output and saved results use the name, and later
node tasks of the same fleet stage on the same node read the node task's
result as .node_tasks.<id>. MMX has no separate field for saving a
result.
- id: installed_release
shell:
script: printf %s "$(/usr/local/bin/shop version)"
changed_when: false
- when:
not:
equals: ["{{ .node_tasks.installed_release.stdout }}", "{{ .vars.release }}"]
show: "Upgrade needed on {{ .node.name }}"
- An ID starts with a letter or an underscore and holds letters, digits,
underscores, and hyphens. It is unique in its fleet stage, together with
the node tasks in its node task blocks; a role file has its own IDs.
The error is
invalid or duplicate node task id "install_nginx". - A node task without
idis named in output by its block'sid, its role's name, or elsetask_and its position, such astask_3. Its result has no reference. - A reference reaches earlier node tasks only, in the same fleet stage or in the same role call. A later fleet stage reads values through outputs, and a role's caller through the role's declared outputs.
A result has these fields, where they apply. A module adds its own, which
its module page lists under "Outputs", such as content of read_file:
| Field | What it holds |
|---|---|
status |
succeeded, failed, skipped, not_checked (dryrun only), blocked, or stopped. What the results mean explains each. |
change |
changed, unchanged, would_change (dryrun only), or unknown. |
reason |
Why the node task failed or was skipped. |
exit_code, stdout, stdout_json, stderr |
A command's result, such as of shell. stdout_json is stdout read as JSON, field by field. |
http_status_code, response_body, response_body_json |
An HTTP response, of http or wait_for. |
value |
A module's value, such as show's value. |
outputs |
A role call's declared outputs. |
items |
A looped node task's results, one for each iteration in order, each with its iteration_key. |
What a failed node task keeps. A failed shell, http, or wait_for
node task, and a failed module that is not core, keep what they captured:
exit_code, stdout, stdout_json, stderr, http_status_code,
response_body, and response_body_json, so an on_failure node task can
read them. On every other node task that did not succeed, such as a
skipped one, reading these fields, or value, outputs, items,
content, or public_key, fails and names the node task's status; its
status, change, and reason stay readable. A looped node task that
failed keeps no captured output. A node task that did
not run has no result, and a reference to it fails.
when on a node task
when skips the node task when the condition is false. The result then
says skipped, unchanged — when is false.
- when:
equals: ["{{ .node.package_manager }}", apt]
apt_package:
packages:
- {name: nginx, version: newest_when_first_installed}
- A condition is a boolean, one whole reference to a boolean, such as
"{{ .vars.large_server }}", or a condition form:equals,contains,matches,number_equals,number_less_than,number_at_most,number_greater_than,number_at_least,version_equals,version_less_than,version_at_most,version_greater_than,version_at_least,path_exists,all,any, andnot. Conditions says what each form compares. path_existsworks only in thewhenof a node task or a node task block, because it looks at the node.- A false
whenskips the node task without working out its inputs, so an input may read a value that exists only when the condition is true. - On a looped node task,
whenis checked for each item and can read the item. - On a node task block or a role call,
whenskips the whole block or role call. - The
whenon a fleet stage is checked on the controller machine instead: see when on a fleet stage.
loop, as, and key
loop runs a node task, a role call, or a node task block once for each
item, in order, on the same node.
- id: create_shop_accounts
loop: [alice, bob]
as: person # each item, read as .person
user:
name: "{{ .person }}"
create_home_directory: true
looptakes a list, a mapping, or one whole reference to a list or a mapping, such as"{{ .vars.accounts }}". A list runs in written order. A mapping runs in the sorted order of its keys, and.<as>.keyand.<as>.valueread each entry.asis required, with the same name rules as on a loop over fleet stages.keynames each iteration in output and results, such ascreate_shop_accounts[alice]. Withoutkey, the name is the item's index as text (0,1, ...) for a list, or the mapping's key.keyis required on a looped node task block, and on a loop whose iterations run ashellnode task withonly_when_tracked_inputs_changed: true, because the node keeps a record under each iteration's key. Duplicate keys are an error. A looped node task block withoutkeyfails withfleet stage loops and node task block loops require key to identify each iteration; a loopedshellnode task withoutkeyfails witha loop whose iterations run a shell command with only_when_tracked_inputs_changed requires key: the node keeps each iteration's command record under the iteration's key, ....- With an
id,.node_tasks.<id>.itemsholds the iterations' results. - A looped
filenode task inside a node task block'schangesgives one activation after all the files. - Loop over the results shows a loop over another fleet stage's outputs.
show
show prints a message or a value in the run's output, at its place in the
node task list.
- show: "Release {{ .vars.release }} on {{ .node.name }}"
- show:
release: "{{ .vars.release }}"
home_page: "{{ .node_tasks.write_home_page }}"
showchanges nothing and runs in a dryrun too. A value that a dryrun cannot know yet is marked as not known, not shown as empty or false.- MMX hides secrets in the value, also inside text and inside a list or a mapping.
- The result's
valueholds the value with its structure, inmmx results --jsontoo.
set_vars
set_vars gives variables a value at a point in the node task list. Later
node tasks of the same fleet stage, loop iteration, or role call read them
as .vars.NAME.
- set_vars:
large_server:
number_at_least: ["{{ .node.memory.total_mib }}", 4096]
- when: "{{ .vars.large_server }}"
show: "{{ .node.name }} has at least 4096 MiB of memory"
- A value that is one condition, such as
number_at_least, becomestrueorfalse. set_varsworks out every value from the state before it, then sets them together. If one value fails, it sets none.set_varsmay replace a variable fromvars. Facts, role inputs, and results stay as they are.- A duration setting cannot read a variable that a
set_varsof the same fleet stage sets: see A duration from a var. - Values computed during the run shows a run.
Node task retries and time limits
A retry repeats one node task on its node, after a failed try. It differs
from mmx resume, which repeats a saved run's unfinished work. A time limit
ends a node task that takes too long.
- id: wait_for_job
shell:
script: /usr/local/bin/job-status
changed_when: false
time_limit: 2m # the whole node task, every try included
time_limit_per_try: 5s # one try
retry:
max_tries: 30
pause_between_tries: 2s
until: # a successful try must also show this
contains: ["{{ .this_node_task.stdout }}", "job_status=complete"]
retry_when: # try again only after these exit codes
any:
- equals: ["{{ .this_node_task.exit_code }}", 0]
- equals: ["{{ .this_node_task.exit_code }}", 75]
Here exit code 0 with job_status=complete in the output succeeds. Exit
code 0 without it, or exit code 75, tries again after two seconds. Any other
exit code fails at once, as do 30 tries or two minutes without success.
The project's defaults are in mmx_project_settings.yml, under
node_task_defaults:
# mmx_project_settings.yml
project_name: mmx_example
default_inventory: example
node_task_defaults:
time_limit: 5m
time_limit_per_try: 1m
retry:
max_tries: 3
pause_between_tries: 2s
A setting on a node task replaces the default for that node task.
mmx explain shows each node task's settings and where each came from,
such as retry.max_tries = 3 from MMX default.
retry
retry sets whether a node task that fails tries again, how often, and
how long it waits between tries.
retry:
max_tries: 5
pause_between_tries: 10s
| Value | What it does |
|---|---|
retry: true |
Retries with the defaults: node_task_defaults.retry, or else 3 tries in all with a 2-second pause. |
retry: false |
Tries once. |
retry: {...} |
Retries with the fields below; a field left out takes its default. |
| Field | Value | Default |
|---|---|---|
max_tries |
A positive whole number, counting the first try, or unlimited. unlimited needs a time_limit, on the node task or in node_task_defaults. null is refused. |
3 |
pause_between_tries |
A duration of 0 or more, such as 2s |
2s |
until |
A condition on .this_node_task that a successful try must also meet. |
Always met |
retry_when |
A condition on .this_node_task: another try is allowed only when true. |
Always true |
- Which node tasks retry without
retry. Most core modules, such asapt_packageandfile, and every module that is not core retry by default.shell,http,read_file,systemd_service,certbot_certificate,show, andset_varstry once unless the node task setsretry. Each module page says which under "Retries and time limits". - A failure that another try cannot fix is not repeated: invalid
configuration, a rejected validation, and a missing prerequisite, such as
a package, program, account, file, or parent directory that an earlier
node task or a person must provide. The result's
failure_kindthen saysconfig,validation, ormissing_prerequisite, and the reason names what is missing, such asthe parent directory /var/backups does not exist; create it with an earlier directory node task. The missing parent directory of a path thatfile,download,directory,symlink,unpack_archive, orgitwrites counts as a missing prerequisite, unless adirectorynode task setscreate_missing_parent_directories: true. So does arun_from_directorythat does not exist, forshelland for the script ofwait_for: no command can start there (run_from_directory /opt/openwisp2 does not exist; create it with an earlier directory node task). The reason is in MMX's own words, so a node task that reads a secret shows it too. untilcannot turn a failed try into success, andretry_whenonly allows another try. A condition that cannot be worked out fails the node task at once.- A role call or a node task block takes no
retry:retry must be set on an individual node task inside the role or node task block. - The saved results keep the first and the latest nine tries, and count the rest.
time_limit and time_limit_per_try
time_limit ends a node task that runs too long in all its tries
together; time_limit_per_try ends one try that runs too long. Both are
written on the node task, beside its module:
- id: install_nginx
apt_package:
packages:
- {name: nginx, version: newest_when_first_installed}
time_limit: 10m # the whole node task, every try included
time_limit_per_try: 2m # one try
| Field | Value | Default |
|---|---|---|
time_limit |
A positive duration, such as 30s, 5m, or 1h30m, or null |
node_task_defaults.time_limit, else no limit |
time_limit_per_try |
A positive duration, or null |
node_task_defaults.time_limit_per_try, else no limit |
time_limitcounts from the node task's start, with every try and pause.time_limit_per_trybounds each try.nullon a node task removes the project's default for that node task.- When
time_limitends, the node task fails with a reason that starts withtime_limit exceeded:, followed by the module's own reason, such as what it waited for, or elsecontext deadline exceeded. When the limit ends during a pause between tries, the reason istime_limit exceeded during retry.pause_between_tries. - A duration is a number with a unit, such as
500ms,90s,15m, or1h30m.
Modules that take no retry or time limit
These modules wait with an input of their own, and refuse retry,
time_limit, and time_limit_per_try. They also ignore
node_task_defaults.
| Module | Its own limit |
|---|---|
wait_for, reboot |
wait_at_most |
netplan_file, systemd_networkd_file, ifupdown_interfaces_file, networkmanager_connection_file, wireguard_interface, firewalld_zone_membership |
restore_unless_controller_confirms_within: how long the node waits for the controller machine to reach it again after the change, before the node puts the old configuration back |
The error names the input, such as wireguard_interface does not accept retry, time_limit, or time_limit_per_try; restore_unless_controller_confirms_within bounds the change.
Change SSH or network settings safely
explains the network modules' restore.
assert checks once and refuses retry, with assert evaluates once and rejects retry; retry the task that observes the value. Its time limits
apply as for any node task.
A duration from a var
A duration setting can read a variable, so that a team sets the duration in one place and different nodes can wait different times. Write the duration as one whole reference to the variable.
# mmx_project_settings.yml
project_name: mmx_example
default_inventory: example
vars:
reboot_wait_at_most: 2m
# inventories/example.yml, part of it
nodes:
db01:
address: 203.0.113.21
vars:
reboot_wait_at_most: 15m # a dedicated server that checks its hardware first
# playbooks/restart.yml
fleet_stages:
- id: restart
nodes: all
node_tasks:
- reboot:
wait_at_most: "{{ .vars.reboot_wait_at_most }}"
These settings take such a reference:
time_limit,time_limit_per_try, andretry.pause_between_tries;wait_at_mostofrebootandwait_for;random_delayandstop_a_run_afterofsystemd_scheduled_job;restore_unless_controller_confirms_withinofnetplan_file,systemd_networkd_file,ifupdown_interfaces_file,networkmanager_connection_file, andwireguard_interface.
Rules:
- MMX takes each node's value before the run, and checks it as that
setting's duration.
mmx validate,mmx explain, and the start of a run report a bad value with the node, the setting, and where the variable is set, here for a project value thatweb01uses:fleet stage restart, node web01: ... reboot.wait_at_most must be a positive duration; value supplied at mmx_project_settings.yml:4:24 (vars.reboot_wait_at_most).db01has its own value, so a bad project value is never reported fordb01. - The variable must be one that MMX knows before the run: from the vars of
the project, the inventory, a group, or a node, or from
--var. MMX refuses a reference to an output, a fact, or a secret, and text around the reference, such as"{{ .vars.minutes }}m":time_limit must be a duration, such as 15m, or one whole reference to a var, such as "{{ .vars.reboot_wait_at_most }}"; MMX takes the duration before the run, when outputs, facts, and secrets are not known yet. - MMX refuses a variable that a
set_varsnode task of the same fleet stage sets, and a reference inside a role, whose variables are only those its ownset_varssets during the run. In a role, pass the duration through an input. - Inside a
for_each_nodeloop whose nodes are known before the run, a fleet stage that selects the loop's node, such asnodes: "{{ .server }}", is checked for each of the loop's nodes. - A duration input that a module reads while its node task runs, such as
older_thanofdelete_old_files, takes any reference, as every other input does.
Module pages that rely on this section: systemd_service, shell, http, docker_compose_project, mysql_database.
task_block fields
A task_block groups a change with the node tasks that put it into use and
check it, in phases that run in a fixed order on the node.
- task_block:
id: shop_site
changes: # first, make the change
- id: write_site_file
file:
path: /etc/nginx/conf.d/shop.conf
permissions_mode: "0644"
content: |
server {
listen 8080;
root /srv/shop/public;
}
validate: # check the result before it is used
- id: check_nginx_configuration
shell:
script: nginx -t
activate: # put the change into use
- id: reload_nginx
systemd_service:
name: nginx
state: running
refresh: reload # reload only when a file in changes changed
verify: # check that it works
- id: check_home_page
wait_for:
url_responds: http://127.0.0.1:8080/
| Field | Value | What it holds and when it runs |
|---|---|---|
id |
A name; required | Names the block in output, such as shop_site/changes/write_site_file, and in the node's records. |
checks_before_restart_or_reload |
A list of node tasks | Checks that change nothing: assert, http with GET or HEAD, wait_for, show, and shell with changed_when: false. Runs before the block's first write when MMX can foresee the restart or reload, or else just before the restart, reload, or command; and only when the block would restart or reload a running service, or run a shell node task with only_when_tracked_inputs_changed: true. |
changes |
A list of node tasks; required, not empty | The change: files, packages, Git checkouts, and other node tasks. These are the block's tracked inputs. |
validate |
A list of shell or http node tasks |
Checks the result of changes before activate, such as nginx -t. |
activate |
A list of node tasks | Puts the change into use. |
verify |
A list of node tasks | Checks that the result works. |
on_failure |
A list of node tasks | Runs only when an earlier phase of the block failed. |
cleanup |
A list of node tasks | Runs last, whether the block succeeded or failed. |
- The phases run in the order of the table. A failed node task stops the
block's remaining normal phases;
on_failureand thencleanuprun. when,loop,as,key, and an outeridgo besidetask_block, not inside it. An outeridnames the block's result as.node_tasks.<id>, and replaces the block'sidin the result path. The block's ownidgives no.node_tasksreference.- A block takes no
retry. Its node tasks may each set one. - MMX has no notify field. A
systemd_servicenode task withstate: runninginactivaterestarts the service when a tracked input changed since the service last started or reloaded, or reloads it withrefresh: reload; a changed package or unit file always restarts it. This also happens when an earlier run wrote the file and stopped before the reload. Ashellnode task inactivatewithonly_when_tracked_inputs_changed: trueruns only then; it needs anid, and works only inactivate. Any othershellnode task inactivateruns on every run. checks_before_restart_or_reloadneeds asystemd_servicenode task or ashellnode task withonly_when_tracked_inputs_changedinactivate. Otherwise it fails withchecks_before_restart_or_reload would never run.- A dryrun runs
checks_before_restart_or_reloadwhen a restart or reload would be needed, never runson_failure, and previews the other phases by each node task's own rule. - Change a configuration and reload its service
walks through a block, and its section
The phases in order
says what a dryrun does in each phase.
Reload or restart
explains
refresh.
Put things back when a node task block fails
on_failure holds the node tasks that put things back when the block
failed. It runs only after an earlier phase of the block failed.
on_failure:
- systemd_service:
name: shop.service
state: running # start the old release again
- The block still fails.
on_failuredoes not turn the failure into success, unlike Ansible'srescue. The block fails with its first error, and the node does no more work in this fleet stage or in later fleet stages. When a node task ofon_failurealso fails, the result names both errors. - What
on_failurereads:.vars,.inputsin a role, and the results of earlier node tasks as.node_tasks.<id>, the failed node task's included. A failed node task keeps itsstatusandreason, and a failedshell,http, orwait_fornode task, or a failed module that is not core, keeps its captured output: see What a failed node task keeps. A node task that did not run has no result. cleanupruns afteron_failure, and after a block that succeeded.cleanupbelongs to the current run: after a run that stopped halfway, the next run does not repeat the old run'scleanup.- A failed check in
checks_before_restart_or_reloadstops the block before the restart or reload;on_failureandcleanuprun as for any failed block. When the check ran before the first write, nothing in the block was written. - A node task block does not undo
changesby itself.on_failuredoes what you write in it. - Back up, upgrade, and restore on failure
shows a whole upgrade with
on_failure.
Module pages that rely on this section: assert, http, shell, systemd_service.
Role calls
A role call runs a role: a reusable list of node tasks with declared inputs,
in its own file roles/<name>/main.yml.
- id: shop_website # names the role call's result
role: shop_website # runs roles/shop_website/main.yml
inputs:
heading: Shop
port: "{{ .vars.http_port }}"
- show: "{{ .node_tasks.shop_website.outputs.home_page_url }}"
| Field of a role call | Value |
|---|---|
role |
The role's directory name under roles/; required. |
inputs |
A mapping of the role's input names to values; values may be references. A node task that calls a module takes no inputs: inputs belongs to a role call; a module's inputs are written below the module's name. |
id, when, loop, as, key |
As on any node task. A role call takes no retry. |
The role file has three fields:
| Field of the role file | Value |
|---|---|
node_tasks |
The role's node tasks; required, not empty. |
inputs |
Each input's type (string, integer, boolean, list, or mapping), and required: true, a default written out, or secret: true. |
outputs |
Values the caller reads as .node_tasks.<role call id>.outputs.<name>. |
- A role reads its inputs, its node's facts, and its own node tasks'
results. Variables of the project, the inventory, and the command line
reach a role only through
inputs. - A role call inside a role needs
allow_role_calls_within_roles: trueinmmx_project_settings.yml. A role that calls itself, directly or through another role, fails withrecursive role call: shop_website. - Reuse work with roles explains inputs, files inside a role, and outputs, with their errors.
One-time playbooks
A one-time playbook holds work that must happen once on every node it selects, such as removing a program that the team no longer uses. It runs only when a command names it. Its fields are the fields of any playbook, with these differences:
# one_time_playbooks/2026-11-15_remove_old_ruby_manager.yml
fleet_stages:
- id: remove_old_ruby_manager
nodes: all
node_tasks:
- directory:
path: /opt/rvm
state: absent
- The file is
one_time_playbooks/YYYY-MM-DD_what_it_does.yml. The name without.ymlis the playbook's name:mmx run 2026-11-15_remove_old_ruby_manager. - Each entry in
command_line_varsneeds adefault. - A completed one-time playbook is in
one_time_playbooks/completed/. A command that names a completed playbook fails, and says to move the file back to make it runnable. one_time_playbooks/holds only one-time playbooks,completed/, and files whose names start with a dot.- Rules for one-time playbooks owns the rules for the name, the directory, and the defaults, and Make a one-time change shows how to write, check, run, and complete one.
Record of each playbook's last success on a node
Each node keeps one file for each playbook that has succeeded on it:
/var/lib/mmx/last_successful_run/<project_name>/<playbook>
The file holds one JSON line about the run that wrote it:
{"run_id":"20261115T053005.182485400-b28f493831cb8c18","inventory":"example","limit":"","only_fleet_stages":"","finished_at":"2026-11-15T05:30:49Z"}
| Field | What it holds |
|---|---|
run_id |
The run's full ID, which mmx results takes. |
inventory |
The inventory name that the run used. |
limit |
The run's --limit value, such as canary,db01; empty without one. |
only_fleet_stages |
The run's --only-fleet-stages value; empty without one. |
finished_at |
When the run, or the resume that completed it, finished, in UTC. |
When a node writes the file:
- After
mmx runormmx resumeof the playbook, on each node where every fleet stage that selected the node succeeded, whether something changed or not. A fleet stage that a falsewhenskipped on the node counts as succeeded. - A run with
--limitor--only-fleet-stageswrites the file too, also on a node that the run used only as a helper node. To count only whole runs, check thatlimitandonly_fleet_stagesare both empty.
When the node keeps its earlier file:
- A fleet stage's work on the node failed or stopped, or
/etc/mmx/do_not_managerefused the work. - The run stopped before MMX knew a later fleet stage's nodes. The later
fleet stage might have selected any node, so no node writes the file.
For example,
on_node_failure: stop_runcan end afor_each_nodeloop before some iterations start. Themmx resumethat finishes the run writes the file. - MMX could not reach the node to write the file after the run's work. The run's results show a note on that node, and the run's outcome does not change.
mmx dryrunandmmx run-commandnever write the file.
The file belongs to root and has mode 0600, so a check that reads it runs
as root. MMX replaces the file in one step: a reader sees the earlier line
or the new one, never part of either. Writing the file is not a change, and
never shows as changed.
When a playbook last succeeded on each server
reads the file on every server with one command.
Nesting limits
Some entries may hold others, and some may not. The table lists what may
go where. For example, a role call goes in a fleet stage's node_tasks,
never inside a node task block's phase:
node_tasks:
- role: shop_website # allowed here
- task_block:
id: shop_site
changes:
- file: {...} # a role call here is refused
| Where | What may go inside | Error otherwise |
|---|---|---|
| A node task block's phases | Individual node tasks, which may loop. No role call and no other node task block. | node task block phases accept individual node tasks; put role calls and nested node task blocks in the fleet stage's or role's node_tasks list |
A fleet stage's or a role's node_tasks |
Node tasks, role calls, and node task blocks | |
A role's node_tasks |
A role call only with allow_role_calls_within_roles: true; never a call back to the same role |
role calls within roles require allow_role_calls_within_roles: true; recursive role call: NAME |
A loop or for_each_node fleet stage's fleet_stages |
Fleet stages, other loops, and for_each_node loops |
|
A fleet stage inside a for_each_node loop |
No on_node_failure or failed_nodes_allowed: write them on the loop |
fleet stage X is inside for_each_node loop Y, which counts failures by the loop's nodes |
reboot |
Only as the last node task of a fleet stage's own node_tasks, outside roles, node task blocks, and loops |
reboot must be the last node task in a fleet stage's node_tasks list, outside roles, node task blocks, and loops |
The limits on saved output sizes are settings of the project: Saved output sizes.
References and templates
A reference reads a value that MMX knows, such as {{ .vars.http_port }}
in a node task's input. A template is a file in the project, such as
files/nginx.conf.tmpl, that MMX fills in for each node with Go's
text/template syntax.
Use variables and templates
shows both in a run.
Where a reference reads from
A reference starts with a dot and a name that says where MMX reads the
value, such as {{ .vars.http_port }} for the variable http_port. The
names are:
| Reference | The value |
|---|---|
.vars.NAME |
A variable from vars of the project, the inventory, the node's groups, or the node; a command-line variable; or a set_vars value. vars in the inventory file gives the order in which a later place replaces an earlier value. |
.node.NAME |
A fact that MMX measures on the node: see Node facts. |
.inventory.nodes.NAME |
A node's name, address, and vars (its groups' and its own). |
.inventory.groups.NAME |
A group's sorted list of node names. |
.inputs.NAME |
A role's input, inside the role. |
.secrets.KEY |
A secret: see Secrets reference. |
.node_tasks.ID |
An earlier node task's result: see id and the result of a node task. |
.this_node_task |
The current node task's own result, in retry.until, retry.retry_when, and a shell node task's changed_when and failed_when. |
.outputs.STAGE.NODE.NAME |
An earlier fleet stage's output on one node. |
.fleet_stages.STAGE.NODE.status |
How an earlier fleet stage ended on one node, also after a failure. |
.new_file.path |
The new file that check_new_file checks, in a file, download, line, or edit_file node task. |
.<as> |
The current item of a loop. |
- A missing value is an error, never empty text. The error names the file, the line, and the field.
- Names are case-sensitive.
- A reference inside other text, such as
listen {{ .vars.http_port }};, makes text. MMX fills in a value once: a variable whose value is"{{ .vars.site_name }}"gives that text, not the site name. - A value in the playbook's YAML takes references only, not function
calls:
"{{ add .vars.http_port 1 }}"fails withreference must start with a dot. Functions work in template files.
A number, a boolean, a list, or a mapping from a reference
A module input that takes a number, a boolean, a list, or a mapping also takes text that is exactly one reference. The value keeps its type.
- id: create_shop_account
user:
name: shop
uid: "{{ .vars.shop_user_id }}" # 1500, a number, from vars
create_home_directory: false
- The value must have the input's type and pass the module's own rules,
such as
account ID must be an integer from 0 through 4294967294; value supplied at mmx_project_settings.yml:5:17 (vars.shop_user_id). - A reference inside other text is text:
uid: "{{ .vars.shop_user_id }}0"fails withuser.uid must be an integer or one whole reference. - A value that holds a secret is refused in such an input.
- An input that names files on the controller machine, such as
authorized_keys.key_files_on_controller_machine, takes no whole-value reference. Write the list, with a reference for each item. - A number, a boolean, a list, or a mapping from a reference says when MMX checks each kind of value.
Double braces in scripts and in other text
MMX treats {{ in two ways, depending on the field:
| Where | What {{ means |
|---|---|
Most text values in a node task, such as content, path, and env values, and template files |
A reference or a template action, which MMX fills in. |
A script that runs as written: script and dryrun of shell, the scripts of run_only_if_this_command_succeeds and skip_if_this_command_succeeds, command of cron_job, script of systemd_scheduled_job, command_succeeds of wait_for, and the shell scripts of check_new_file and content_filter |
Text that the node gets as written. MMX fills in nothing. |
A file that a node task copies with source |
Text, copied as written. |
A value that MMX knows, in a script that runs as written, is refused,
because the shell would get the braces themselves. Pass the value through
env instead:
- shell:
script: echo "Release $RELEASE"
env:
RELEASE: "{{ .vars.release }}"
Writing script: echo "Release {{ .vars.release }}" fails with
shell.script runs as written, so the shell would receive the literal text {{ .vars.release }}; MMX does not replace references in shell.script; pass the value through env and read the environment variable in the script, such as env: {RELEASE: "{{ .vars.release }}"} and $RELEASE.
A module without env, such as reboot, gets the advice to use the node
task's when instead. MMX looks for the names it knows: vars, inputs,
secrets, node, outputs, node_tasks, new_file, fleet_stages,
inventory, this_node_task, and a loop's as name.
Another tool's template in a script, such as Docker's
docker ps --format '{{ .Names }}', names no value that MMX knows, so it
stays as written and needs nothing.
A literal {{ in a value that MMX fills in, such as a file's
content, goes in back quotes inside braces:
- file:
path: /usr/local/bin/show-containers
permissions_mode: "0755"
content: |
#!/bin/sh
docker ps --format '{{`{{.Names}}`}}: {{`{{.Status}}`}}'
The file on the node then says docker ps --format '{{.Names}}: {{.Status}}'. A }} on its own needs nothing. A template file uses the
same back-quote form.
Template functions
A template file can call the functions of Sprig, the function library that Helm templates use, with Sprig's names and argument order, and two functions of MMX's own:
| Function | What it returns |
|---|---|
percent NUMBER PERCENTAGE |
The percentage of a number that is 0 or more, rounded down to a whole number. The percentage is a whole number from 0 to 100: {{ percent .node.memory.total_mib 25 }} is 512 for 2048 MiB. |
toYaml VALUE |
The value as YAML with sorted keys and two-space indents, without a line end at the end, as in Helm. |
workers = {{ .node.cpu.count }}
cache_mib = {{ percent .node.memory.total_mib .vars.cache_percent }}
Ciphers {{ join "," .vars.ssh_ciphers }}
scrape_configs:
{{ .vars.scrape_configs | toYaml | indent 2 }}
The Sprig functions that MMX leaves out depend on more than their
arguments: the clock, the time zone, random values, the environment, or
the network. A template that called one could render different bytes on a
later run and not report unchanged. A template that calls one fails before MMX contacts a server, with
template function now is not available: the function reads the clock, random values, the environment, or the network:
- The clock and the time zone:
now,ago,date,date_in_zone,dateInZone,date_modify,dateModify,must_date_modify,mustDateModify,htmlDate,htmlDateInZone,toDate,mustToDate,unixEpoch, anddurationRound. - Random values:
randAlphaNum,randAlpha,randAscii,randNumeric,randBytes,randInt,shuffle,uuidv4,bcrypt,htpasswd,encryptAES,genPrivateKey,buildCustomCert,genCA,genCAWithKey,genSelfSignedCert,genSelfSignedCertWithKey,genSignedCert, andgenSignedCertWithKey. - The controller machine's environment and the network:
env,expandenv, andgetHostByName. hello.
For a random password, make the password once and keep it as a secret: Keep secrets.
Node facts
MMX measures each node's facts when the node starts a fleet stage, before
any node task, in a dryrun too. A resume and a new run measure them again.
Facts stay fixed within the node's work on one fleet stage. A node task
reads them as .node.NAME.
| Fact | Value |
|---|---|
.node.name |
The node's name in the inventory, such as web01. |
.node.hostname |
The server's host name. |
.node.fully_qualified_name |
The server's full host name with its domain, such as web01.example.net, or the host name when the node's resolver gives no domain. |
.node.os |
The fields of /etc/os-release (or /usr/lib/os-release) as a mapping, with lowercase keys and text values. |
.node.distribution.id |
ID from /etc/os-release, such as debian, ubuntu, rocky, almalinux, arch, or opensuse-leap. |
.node.distribution.version |
VERSION_ID as text, such as 13 or 24.04. Missing on a rolling release, such as Arch Linux. |
.node.distribution.major_version |
The digits before the first dot, as a number, such as 13 or 24. Missing on a rolling release. |
.node.distribution.codename |
VERSION_CODENAME, such as trixie or noble. Missing where the distribution sets none. |
.node.distribution.family |
debian (Debian, Ubuntu), redhat (RHEL, CentOS, Fedora, Rocky Linux, AlmaLinux, Amazon Linux, Oracle Linux), arch, or suse (openSUSE, SLES). For another ID, the first word of ID_LIKE that names one of these. Missing for a distribution outside the four families. |
.node.package_manager |
apt, dnf, pacman, or zypper, from the family. Missing outside the four families. |
.node.selinux.mode |
enforcing, permissive, or disabled. disabled also when selinuxfs is mounted but no policy is loaded. |
.node.virtualization.type |
What systemd-detect-virt reports: none on physical hardware, or the kind of virtual machine or container, such as kvm, vmware, lxc, or docker. |
.node.arch |
amd64 or arm64. |
.node.kernel.release |
The kernel release, from /proc/sys/kernel/osrelease. |
.node.boot_id |
The current boot's ID, which changes at each boot. |
.node.cpu.count |
The CPUs that are online; on a virtual machine, its virtual CPUs. |
.node.memory.total_bytes |
The memory that the kernel can use, from MemTotal in /proc/meminfo. Swap does not count, and the value is not the free memory. |
.node.memory.total_mib |
The same in MiB, rounded down: a server with 4 GiB of memory gives about 4096, and 2 GiB gives about 2048. |
.node.memory.swap_total_bytes |
The swap space. |
.node.network.interfaces |
A mapping by interface name, loopback included: index, mtu, mac, and addresses, each with family, address, and prefix_length, in the order that ip address shows. |
.node.network.default_routes |
The default routes: family, interface, metric, and where known gateway and source_address. |
.node.network.default_ipv4_address |
The address that the IPv4 default route with the lowest metric sends from: the route's source_address, or else the first IPv4 address of the route's interface. A keepalived virtual address that joins the interface later is not chosen. Missing without an IPv4 default route. |
.node.network.default_ipv6_address |
The same for IPv6, never a link-local address. Missing without an IPv6 default route. |
.node.storage.mounts |
The mounted filesystems: id, path, source, filesystem, and read_only; for a filesystem on a local disk also total_bytes and available_bytes. |
.node.storage.block_devices |
The node's disks, partitions, and other block devices: see Block-device fields. |
- A missing fact is not empty or zero. A node task that reads it fails with the reason, and the node then runs none of its later node tasks. Node tasks that do not read it are not affected.
- Collections are sorted, such as mounts, routes, and block devices, so the same server gives the same values on each run. An interface's addresses keep the kernel's order.
- Size settings from total capacity, such as
.node.memory.total_mib, not from free memory, which changes with load. - To see a node's facts, show them in a node task, or read
facts.valuesinmmx results --json. - Saved facts. Each saved response of a node job holds
facts.values,facts.collected_at, and the reason for each fact that was unavailable (facts.unavailable). A resume measures fresh facts and keeps the earlier attempts. The results list the facts that changed between two readings of one node within a run (facts_changed; human output saysfacts changed since the previous reading in the run). Such a change is not a resource change. A new run starts a new baseline. - A value known before the run. A field that MMX works out on the
controller machine before it connects, such as the
templatepath of afilenode task, may read.node.namebut no other fact. - Node facts shows the facts of a real server.
Block-device fields
.node.storage.block_devices lists each block device of the node whose
size is not zero, sorted by kernel name. Every entry has name, path,
kind, size_bytes, and read_only; the other fields are there when they
apply and are known.
| Field | What it holds |
|---|---|
name |
The kernel's name, such as sdb1 or dm-0. |
path |
/dev/<name>. A kernel path can name another disk after a reboot. |
kind |
disk, partition, lvm_logical_volume, device_mapper_device, loop_device, or raid_array. |
size_bytes |
The size in bytes. |
read_only |
true or false. |
part_of_disk |
For a partition, its disk's kernel name. |
built_on_devices |
For a device mapper device or a RAID array, the kernel names of the devices below it. |
device_mapper_name |
The name in /dev/mapper/, also for an LVM logical volume. |
stable_paths_by_id |
Every link in /dev/disk/by-id/ to the device, as full paths. Find a disk by one of these. |
mount_points |
Where the device is mounted. |
serial, model |
The serial number and model that udev reports. |
partition_table_type |
gpt or dos, for a device that holds a partition table. |
content_type, content_uuid, content_label |
What udev found on the device when udev last looked, such as ext4, xfs, swap, LVM2_member, or crypto_LUKS, with its UUID and label. |
MMX reads files and links to gather the list, and runs no program and
probes no device. The content_* fields say what udev found at its last
probe, not a fresh look at the device; storage modules probe the device
before they change it. Without the udev database, entries omit the fields
that udev supplies.
In a container, the list shows the block devices of the server that runs the container. Find a storage device shows how to pick a disk.
This page is docs/reference/playbook-file.md in the MMX repository.