Preview and run changes
Who acts: you, or your coding agent, in your MMX project on your
controller machine: the computer where you run mmx.
When to use this page: you have a playbook, such as the one from Write a playbook, and you want to see what it would change on your servers, and then change them.
What this page does: you check the project files, preview the changes
with mmx dryrun, run the playbook on one server first, then on all of
them, and read what each result and exit code means.
Terms: a node is a server that MMX manages. A playbook lists
fleet stages; each picks nodes, and each node runs the fleet stage's
node tasks, in order. The examples use the playbook
set_up_web_servers and the server web01.
Steps
-
Check the project files.
mmx validate set_up_web_serversIt reads your files on your computer and contacts no server.
Check: it prints
Valid:and the project's name, with exit code 0. Otherwise it names the file, line, and field to fix, with exit code 1. -
See which servers the playbook selects.
mmx nodes set_up_web_serversCheck: the
Fleet stagespart lists the servers you expect after each fleet stage, such asset_up_nginx web_servers → web01, web02.mmx explain set_up_web_serversshows, in addition, every value each server's node tasks will get and where it came from. -
Preview the changes.
mmx dryrun set_up_web_servers --diff echo "exit code $?"mmx dryrunconnects to each selected server and reports what a run would change, without changing it.--diffadds each file's difference:set_up_nginx / web01 / write_home_page: succeeded, would_change set_up_nginx / web01 / write_home_page: would create "/srv/shop/public/index.html" absent -> 14 bytes, permissions_mode 0644, uid 0, gid 0 --- before +++ after @@ -0,0 +1,1 @@ +<h1>Shop</h1>A first dryrun on a server also sets up MMX there, so on that server even a dryrun installs MMX's node program and starts it.
Check: read each node task's result as What the results mean says, and the exit code as Exit codes says. Exit code 0 means nothing would change; 2 means something would change; 3 means some work could not be checked, so the line of that node task says why.
-
Run the playbook on one server first.
mmx run set_up_web_servers --limit web01--limitkeeps only the named nodes and groups, separated by commas, such as--limit web01,web02. It never adds a node that the playbook doesn't select.Check: the header line shows
Limit: web01 Selected: 1 node, each node task sayssucceededwithchangedorunchanged, and the run ends withRun ...: succeededand exit code 0. Look at the server, such as the page it now serves, before you go on. -
Run the playbook on every server it selects.
mmx run set_up_web_serversCheck:
Run ...: succeededand exit code 0.web01now saysunchangedfor every node task. -
If the run failed, choose how to go on. A failed run ends with the commands to use next:
Run 6bd33f06: failed 1 failed Saved: /home/you/shop/.mmx/runs/20261115T035339.314724231-6bd33f06bbfa8a71 Inspect: mmx results 6bd33f06 Resume unfinished work: mmx resume 6bd33f06 Start a new run: mmx run set_up_web_servers- You fixed a file of the project: run
mmx run set_up_web_servers. A new run reads your current files. - Nothing in the project was wrong, such as a server that was
briefly unreachable: run
mmx resume. What a resume repeats says what a resume does again.
mmx results 6bd33f06shows the saved results of that run again, without contacting a server.Check: the new run or the resume ends with
Run ...: succeeded. - You fixed a file of the project: run
What the results mean
Each node task gets a status and a change, such as succeeded, would_change.
| Status | Meaning |
|---|---|
succeeded |
The node task did its work, or in a dryrun, checked what it would do. |
failed |
The node task failed. Its line says why. That server then runs none of its later node tasks or fleet stages, except a failed node task block's own on_failure and cleanup node tasks. |
not_checked |
A dryrun could not check the node task, often because an earlier node task would install or create what it needs first. The line names the earlier node task. A run then checks it for real. Don't add node tasks only to make this go away. |
skipped |
The node task didn't run, such as a condition that was false, or in a dryrun, an activate node task that waits for the changes before it. |
| Change | Meaning |
|---|---|
would_change |
In a dryrun: a run would change the server. |
changed |
The run changed the server. |
unchanged |
The server already matched; nothing was changed. |
unknown |
MMX can't tell yet, such as a node task that a dryrun could not check. |
In a dryrun, the work that depends on an earlier node task can't be
checked until that node task has run. For example, nginx's package creates
/etc/nginx/conf.d. On a server without nginx, a dryrun reports the site
file in that directory as not_checked, and names install_nginx:
set_up_nginx / web01 / shop_site/changes/write_site_file: not_checked, unknown — the parent directory /etc/nginx/conf.d does not exist; create it with an earlier directory node task. The earlier node task install_nginx would change this node first and may provide what is missing; if the run then succeeds, change nothing.
If the run then succeeds, the playbook is right as it is.
The same holds in three more cases, each after an earlier node task on the same server would change it, in the same fleet stage or an earlier one:
- A check that fails, because it checked the server as it is now: a
verifyorvalidatenode task,check_new_file,wait_for,httpwithGETorHEAD, orshellwithchanged_when: false. The result keeps the check's output. Without an earlier change, the failure stands. - A condition or a value that reads an earlier node task's
changeor an output that only the run knows, such aswhen: {equals: ["{{ .node_tasks.app_config.change }}", changed]}. The same holds for the results of a node task that isnot_checked, and for a variable that aset_varsnode task sets from such a value. - A
shellorwait_fornode task whoserun_from_directorydoesn't exist yet. Without an earlier change, the dryrun fails it, as the run would.
Exit codes
For a dryrun, 0 means nothing would change, 2 means something would
change, and 3 means some work could not be checked. A run exits with 0
when it succeeded and 1 when it did not. A first dryrun on a new server
often exits with 2 or 3, because work that an earlier node task would make
possible shows as not_checked. The
commands reference has every code,
and mmx dryrun shows how to read
them in a script.
Output for many servers, and for a coding agent
--output=nodesshows each server.--output=summarygroups servers with the same results, such asset_up_nginx / 2 nodes [web01, web02]: succeeded. Without the flag, MMX shows each server for up to ten servers, and groups them for more.--jsonprints the whole run as one JSON object instead: itsid, itsstatus, whether it was adryrun, and inentriesone entry for each server and fleet stage, with the node tasks' results inresponse.results: each node task'sstatus,change,exit_code,stdout, andstderrwhere they apply.schema_versionis 1. The JSON of a run lists every field.--non-interactivenever asks a question, such as for a vault passphrase or a sudo password: a missing one is an error.--jsondoes the same.- MMX saves every run so
mmx resultscan show it again later: Where runs are kept, and for how long.
If something is different
| What you see | What it means and what to do |
|---|---|
A dryrun's exit code is 3 and the line says not_checked |
See What the results mean. Run, and change the playbook only if the run fails. |
mmx: --limit: no node or inventory group named "web99", exit code 4 |
A name in --limit is in no inventory file. mmx nodes lists the names. |
MMX could not connect to https://203.0.113.11:7443 (connection timed out). |
Port 7443 is closed between your computer and the server. MMX used SSH for that server and went on. |
| The run fails on one server and succeeds on the others | The others are finished. Fix the cause, then run mmx resume or mmx run: Resume a run says which to choose. |
| A node task's line ends with a long reason | The reason is the node task's own words: what was missing and what to do. mmx describe-module NAME explains the module's errors. |
This page is docs/how-to/preview-and-run-changes.md in the MMX repository.