shell
shell runs a command on the node: its script runs with bash -c, as
root unless the task names another account with run_as_user_account. Use
it for custom commands and existing tools that no module covers.
A bare shell task runs in written order on every requested attempt,
including in a node task block's activate phase, so it must be safe to
repeat. It is not triggered by another node task reporting a change. Use
explicit conditions, guards, or a script that inspects the current state
when work should be conditional. A command that must run because a file,
package, or checkout changed says so with
only_when_tracked_inputs_changed. It
reports changed when it runs, and exit code zero means success. MMX does not
infer anything from the script's contents or output beyond the declared
rules below.
Where a systemd unit applies a file, a
systemd_service task on that unit is the first
choice: systemd-sysctl.service applies /etc/sysctl.d/, and
nftables.service applies a firewall file that is the node's whole
firewall. A firewall file that keeps the rules of other tools, such as
Docker, ufw, or firewalld, holds a table of its own and is loaded with
nft --file as a command that follows a change; see
One nftables file instead. Work that needs structured
results beyond stdout_json belongs in a
module of the project's own.
The ad hoc command mmx run-command runs a command the same way; see
ad hoc commands.
Inputs
script(string; required): run with bash -c; no profile filesdryrun(string; optional): read-only command run instead during dryrunrun_script_in_dryrun(boolean; defaultfalse): true runs script as written during a dryrun, with the same guards, run_as_user_account, run_from_directory, env, and result rules; for a script that changes nothing, because a dryrun must not change a node: MMX does not check that the script only reads; cannot be used with dryrun, run_only_once_marker_file, or only_when_tracked_inputs_changedenv(mapping; optional): environment variables; pass values here, not in scriptrun_from_directory(string; default/): the directory the script, guards, and dryrun command run from; a directory that does not exist is a missing prerequisite: a run fails without another try, and a dryrun reports the node task not checked when an earlier node task would change the noderun_as_user_account(string; defaultroot): local account for the script, guards, and dryrun command: its UID, primary GID, and groups, with HOME, USER, and LOGNAME from it; no sudo or login shellskip_if_this_path_exists(string; optional): skip when this path exists; relative to run_from_directoryrun_only_if_this_path_exists(string; optional): run only when this path exists; relative to run_from_directoryrun_only_if_this_command_succeeds(command or mapping; optional): run only when the check exits 0; 1 skips; {script, true_exit_codes, false_exit_codes}skip_if_this_command_succeeds(command or mapping; optional): run only when the check exits 1; 0 skipsrun_only_once_marker_file(string; optional): absolute path of a file MMX creates after the script succeeded; while the file exists the script is skipped; delete the file to run the script again; keep such files in /var/lib/mmx/commands_run_once/only_when_tracked_inputs_changed(boolean; defaultfalse): only in a task_block's activate phase, on a task with an id: the command runs when the block's tracked inputs (the files, units, packages, and Git checkouts in its changes) differ from what it last ran with, also when an earlier run stopped before the commandsuccess_exit_codes(list of integers; default[0])changed_when(boolean or predicate; defaulttrue): reads .this_node_task.exit_code, .this_node_task.stdout, .this_node_task.stderrfailed_when(boolean or predicate; defaultfalse): an additional failure conditionoutput_holds_no_secret(boolean; defaultfalse): true promises that the program prints no secret: a run and a dryrun show stdout, stderr, and the failure reason although the task read a secret, with every secret value of the node job replaced by [redacted] first; diffs and outputs stay hidden; cannot be true with output_is_secretoutput_is_secret(boolean; defaultfalse): true marks stdout and stderr secret: never printed, never saved; an output made from them is secret too; on mmx resume, work that reads such an output is blocked until a new mmx run produces it again
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.
statuschangeexit_codestdoutstdout_jsonstderr
What a dryrun reports
Runs only the dryrun command, or script as written with run_script_in_dryrun: true; without either, guards may skip it, otherwise it is skipped with change unknown, or unchanged in a task_block's validate while no earlier node task of the dryrun would change the node; a check (in validate, or with changed_when: false) that fails after an earlier node task of the dryrun would change the node is not_checked, with its output kept; with run_only_once_marker_file or only_when_tracked_inputs_changed it reports whether the command would run.
Retries and time limits
Runs once unless the task sets retry.
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
Run a command after a change
Many programs do not read their configuration themselves: something has to be
rebuilt after a file changes. postmap rebuilds a Postfix lookup table,
update-ca-certificates rebuilds the certificate store, and touching
tmp/restart.txt restarts an application under Passenger. Put the command in
the activate phase of the node task block that writes the file, give the
task an id, and add only_when_tracked_inputs_changed: true:
# roles/postfix_virtual_map/main.yml
node_tasks:
- task_block:
id: postfix_virtual_map
changes:
- file:
permissions_mode: "0644"
path: /etc/postfix/virtual
source: files/virtual
activate:
- id: rebuild_virtual_map
shell:
script: postmap /etc/postfix/virtual
only_when_tracked_inputs_changed: true
postmap now runs on the node when /etc/postfix/virtual changed and is
skipped on an unchanged run. It also runs on the next run when a run wrote
the file and stopped before the command, for example because the connection
dropped.
Run a command when new application code arrives
only_when_tracked_inputs_changed also makes new application code trigger
a command. After git checks out a new commit, MMX runs touch on
Passenger's restart file:
# roles/shop_code/main.yml
inputs:
release:
type: string
required: true
node_tasks:
- task_block:
id: shop_code
changes:
- git:
repo: https://github.com/example/shop.git
check_out_tag: "{{ .inputs.release }}"
path: /srv/shop
run_as_user_account: deploy
activate:
- id: tell_passenger_to_restart
shell:
script: touch /srv/shop/tmp/restart.txt
run_as_user_account: deploy
only_when_tracked_inputs_changed: true
Run a command only once
Some commands must run one time on each node but provide no check for
whether the work already succeeded: a vendor's setup script, a first import.
run_only_once_marker_file names a file that MMX creates after the command
succeeded. While the file exists, MMX skips the command:
- shell:
script: percona-release setup ps80
run_only_once_marker_file: /var/lib/mmx/commands_run_once/percona_release_setup
To run the command again on purpose, delete the file on the node. Keep these
files in /var/lib/mmx/commands_run_once/; MMX creates the directory.
Run as an application account
- shell:
run_as_user_account: app
run_from_directory: /srv/app/current
script: bin/migrate
env:
DATABASE_URL: "{{ .secrets.database_url }}" # a secret name you choose
The script, guards, and dryrun command all run as the account app on the
node. MMX looks up the account when the node task runs, so an earlier node
task can create it. The account must be able to enter run_from_directory.
Report a change by the exit code
For a script that exits 0 when already correct and 2 after updating:
- shell:
script: /usr/local/bin/update-config
success_exit_codes: [0, 2]
changed_when:
equals: ["{{ .this_node_task.exit_code }}", 2]
Use changed_when: false for read-only commands.
Ask a program whether to run
- shell:
script: /usr/local/bin/update-app
run_only_if_this_command_succeeds:
script: /usr/local/bin/app-needs-update
true_exit_codes: [0]
false_exit_codes: [3]
The check runs first on the node. Exit code 0 runs update-app, and exit
code 3 skips update-app. The mapping form is for a check with conventions
different from the default exit codes.
A command with its own dryrun
- shell:
script: /usr/local/bin/configure-app
dryrun: /usr/local/bin/configure-app --dry-run
During a dryrun, MMX runs only the dryrun command.
A script that only reads
- id: hostname_checksum
shell:
script: sha256sum /etc/hostname
run_script_in_dryrun: true
changed_when: false
With run_script_in_dryrun: true, a dryrun runs script as written, where it
would run the dryrun command. Use it for a script that changes nothing, so
you do not keep a second copy of the script in dryrun that can drift from
the first. A dryrun must not change a node, and MMX does not check that the
script only reads. The guards, run_as_user_account, run_from_directory,
env, and the result rules apply as in a run. MMX refuses the setting together
with dryrun (two answers to the same question), run_only_once_marker_file,
and only_when_tracked_inputs_changed (a dryrun already reports whether the
command would run, and running the script there would run work that is meant to
run once or only after a change).
A command that prints a secret
Some commands print a secret, such as one that creates an access token. Mark
such a command with output_is_secret: true:
- id: new_token
shell:
script: /usr/local/bin/myapp create-token
changed_when: false
output_is_secret: true
Its stdout and stderr are then secret: MMX never prints them and never
saves them, on the controller machine or on the node. An output made from them
is secret too, so a later fleet stage can pass the token to other nodes; see
secrets that start on a node.
The exit code and status stay visible.
How it works
The environment of a command
shell does not load a login shell, profile files, or BASH_ENV. Its
environment is the
fixed base that every command gets
plus env, and the command runs from /
unless run_from_directory names another directory. Pass values through
env rather than substituting them into the script. A script that needs
initialization, such as a language version manager, sources it explicitly.
script, dryrun, and the scripts of the two guards run as written: MMX
fills in no reference there. Validation therefore refuses a reference to a
value MMX knows in them, such as echo {{ .vars.swap_mib }}, which the
shell would get with its braces. Pass the value through env and read the
variable:
- shell:
script: echo "$SWAP_MIB"
env:
SWAP_MIB: "{{ .vars.swap_mib }}"
A template for another tool, such as docker inspect -f '{{.State.Status}}',
names no value MMX knows and runs as written.
An env value that is a list or a mapping, such as one whole reference to a
list in vars, reaches the script as JSON text on one line. With
listen_ports: [80, 443] in vars, this script prints [80,443]:
- shell:
script: echo "$LISTEN_PORTS"
env:
LISTEN_PORTS: "{{ .vars.listen_ports }}"
The script reads the text with a JSON tool, such as jq. A reference within
other text, such as "ports {{ .vars.listen_ports }}", cannot hold a list or
a mapping, and validation refuses it.
Every command MMX runs on a node, a shell script, a git checkout, or an
installer, starts with umask 022, as systemd starts its services: a file it
creates is readable by other accounts unless the command sets another mode.
env values, including secrets, reach the process only through its
environment, never its command line or the script text. That environment is
readable by the account's other processes, as any process environment is.
Time limits follow the node task timing design.
A program that the script starts in the background with its output
redirected, such as nohup worker >/var/log/worker.log 2>&1 &, keeps
running after the script ends. A program that still holds the script's
output open 0.2 seconds after the script ends fails the node task: MMX keeps
what was written until then and ends the programs left in the script's
process group. A program that must keep running is a service; manage it
with systemd_service.
Running as another account
run_as_user_account names a local account. The node runner executable,
mmx-runner, is the MMX program installed on each node and already runs as
root. For the shell task, mmx-runner starts the script, dryrun command,
and command guards directly as the named account. The command guards are
run_only_if_this_command_succeeds and skip_if_this_command_succeeds.
MMX reads the account's user ID (UID) and primary group ID (GID) from
/etc/passwd on the node. MMX also reads supplementary group memberships
from /etc/group. The account lookup is also used to resolve file owners.
No password, sudo, su, or login shell is involved, so a nologin service
account works. MMX opens no PAM session: the command gets no login-session
setup from Linux's Pluggable Authentication Modules. There is no
become setting
(privilege design).
The node runner executable checks skip_if_this_path_exists and
run_only_if_this_path_exists paths itself. Relative guard paths start at
run_from_directory, which defaults to /, just as the script does.
A symlinked working directory follows the link before .. selects its parent.
The guard and script use the same path.
The environment is the same fixed base with HOME, USER, and LOGNAME
taken from the account, then env on top. Profile files still do not load.
The command still runs from / unless run_from_directory is set. Output
suppression works as for root tasks.
Result rules
A task fails if its exit code is not in success_exit_codes or
failed_when matches. changed_when does not affect success, and a failed
command still reports changed by default. changed_when and failed_when
take a boolean or a condition that reads .this_node_task.exit_code,
.this_node_task.stdout, .this_node_task.stderr, and
.this_node_task.stdout_json (standard output parsed as JSON, when valid),
with the ordinary conditions.
A shell change result only drives reporting: it does not queue a service
reload or make a command safe for dryrun. File validators and
validate-phase commands accept only exit 0 and report unchanged. The
configuration design
explains how to assign a result name with id and read the named result.
Guards
| Guard | Run only when |
|---|---|
skip_if_this_path_exists: /path |
The path does not exist. |
run_only_if_this_path_exists: /path |
The path exists. |
run_only_if_this_command_succeeds: <check> |
The check command succeeds. |
skip_if_this_command_succeeds: <check> |
The check command does not succeed. |
run_only_once_marker_file: /path |
The marker file does not exist. |
Guards are optional; when several are present, all must allow the command. Guards run before the command, also during dryrun, so check commands must be read-only. A skip reports its reason. An error reading a guard path fails the task rather than counting as absent.
Command checks distinguish true, false, and a failed inspection:
| Check result | Meaning | run_only_if_this_command_succeeds |
skip_if_this_command_succeeds |
|---|---|---|---|
Exit 0 |
True | Run | Skip |
Exit 1 |
False | Skip | Run |
| Any other exit, timeout, or launch failure | Inspection failed | Fail task | Fail task |
In the mapping form, an explicit list of true_exit_codes or
false_exit_codes replaces its default; overlapping lists are a validation
error. skip_if_this_command_succeeds reverses only the true or false
answer, never a failed inspection. Guard codes apply only to the check, not
to the guarded command. For decisions based on output or earlier results,
use .node_tasks and when.
skip_if_this_path_exists looks similar to run_only_once_marker_file but is different: it
skips the command when a path that the command itself makes exists. The
marker file is for commands that leave no such path.
Commands that follow tracked inputs
- What the command follows. The command follows tracked inputs declared
in the
changessection of the node task block containing the command. Tracked inputs include files, links, systemd unit files, packages, Git checkouts, installations by a language or tool installer, Docker images, and state managed by modules that are not core. Asystemd_servicetask in the command's node task block would follow the listed resources too. The execution design lists the tracked inputs. The command does not see a file that another block, another role, or another program wrote. There is no separate list of paths to keep in step. - How MMX remembers. For each such command MMX keeps a command record on
the node in
/var/lib/mmx/command_records/: the hash of each tracked input as it was when the command last succeeded. The command runs when an input differs from the record. Comparing tracked input hashes with saved hashes is also how MMX decides whether to restart a service (execution design), so a command and a service follow a change by the same rule. - After a failed run. Before the command starts, MMX saves the record as
"not finished"; it saves it as finished only after the command succeeded.
A run that stopped anywhere in between leaves a record that does not
match, and the next run runs the command, although the
filetask then reports unchanged. - The first run. With no record yet, MMX takes the inputs as they are on the node before the block's first write. The command runs if the block then changes one of them, and does not run if everything was already as declared. A change made before MMX's first run counts as already applied. A module that is not core counts by the fingerprint that its node task reports: the command runs if that task changes something, and does not run if it changes nothing.
- What names the record. The project's
project_nameand the task's result path, the namemmx resultsshows: theidof each role call around it, the node task block'sid, and the task'sid. That is why the task and its node task block need anid. Renaming one of them starts a new record, which takes the current inputs and does not run the command, so finish a successful run before renaming one. Two different commands anywhere in the project, in any playbook, need different result paths;mmx validateand every run refuse two with the same result path. In a loop, each item has its own record under its loop key; such a loop requires akey, because without one an item is named by its position in the list. Inside a fleet stage loop or afor_each_nodeloop, each iteration also has its own record, so iterations that reach one node, such as a load balancer drained for each application node, do not share a record (the key). - A
shelltask inactivatewithout the field runs on every run. - Dryrun reads the record and writes nothing. It reports
would_changewith the reason, for example "would run: tracked input /etc/postfix/virtual would change". - A command that must run once ever, such as creating an application's first
administrator, does not follow a change. Use
run_only_once_marker_file. - The page Checks before a restart or reload also run before such a command.
Marker files
- MMX writes the file only after the command succeeded. A command that failed, or a run that stopped in the middle of it, runs again next time.
- The skipped node task reports "the shell command has already run; delete the marker file /var/lib/mmx/... to run the shell command again". The message shows the marker file's full path and explains how to repeat the guarded command.
- Dryrun reads the file: the node task reports
would_changewhen the file is missing and is skipped when it exists.
The dryrun command
During a dryrun, MMX runs only the declared dryrun command, with the same
run_as_user_account, run_from_directory, and env, and applies the result
rules to it; a reported change becomes would_change. Without one, guards can
still establish a skip; otherwise the task is skipped with its change
unknown. The author is responsible for the dryrun command being read-only. With
run_script_in_dryrun: true, a dryrun runs script instead, under the same
responsibility.
Secret output
A node task that reads a secret through env already has its output
suppressed; it needs no output_is_secret. With output_is_secret: true,
the command's changed_when and failed_when still read its output on the
node. The secret rules own
what happens to such a value in outputs and after mmx resume.
A command that promises never to print a secret can set
output_holds_no_secret: true. This makes configuration check errors useful
without requiring you to read hidden details on the node. In a run and a
dryrun, MMX shows that command's standard output, standard error, and failure
reason even when the node task read a secret. Before showing those texts,
MMX replaces every secret value the node job holds or the node task read
with [redacted]. It also replaces each value without surrounding whitespace,
each nonempty line without surrounding whitespace, the keys of a secret
mapping, and the JSON text MMX gives a secret list or mapping through env.
It uses the same replacement rules as a
login handed only to a tool.
MMX cannot know other forms, such as part of a line or its Base64 text; the
program's promise must cover those too.
The node task stays secret. Its differences, module outputs, and any output
made from its standard output remain hidden. The field defaults to false;
setting both output_holds_no_secret and output_is_secret to true is
refused when MMX loads the project. The same promise is available on the
shell inside a file check.
A token that later fleet stages need after an interruption belongs in a file
on the node, read with read_file: mmx resume can read a
file again, but it never runs a completed command again to get its output.
Errors and what they mean
- A missing account in
run_as_user_account. The node task fails. A dryrun reports it as not checked, because an earlier node task may create the account. - A check command that exits with another code than 0 or 1, times out, or does not start. The inspection failed, and the task fails. It never counts as "no". Give the mapping form the exit codes the check uses.
- An error reading a guard path. The task fails rather than counting the path as absent.
- "details suppressed for a task using secrets". A failed command with secret output reports "details suppressed for a task using secrets" in place of the failure reason. The failure reason could quote secret output. The displayed suppression message also names a file on the node where root can read the actual failure reason and the command's output (which node tasks have a hidden result).
- Validation errors for
only_when_tracked_inputs_changed. Validation rejects the field anywhere outside anactivatephase, and two different commands anywhere in the project with the same result path.
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 (vm.py test, fleet.py, deployment.py) and runs on every tested distribution.
The suite account_units.py covers run_only_once_marker_file, a command
with only_when_tracked_inputs_changed, and
checks_before_restart_or_reload. release_directories.py covers a Git
checkout as a tracked input of such a command. server_resources.py covers
application-user commands. The whole catalog runs these suites on Debian 12 and 13 and Ubuntu 24.04 and 26.04 (validation record).
Why it works this way
- No setting that selects an interpreter. Bash can run any interpreter, so there is one way to do it.
- No read-only shorthand of
shell. Thedryruncommand already shows what a run would do without changing the node. - One
shellfor custom commands, with nocommandandshellsplit. Pipes and redirects just work, and there is one execution mode to learn. - Shell is noninteractive Bash without profile or rc loading, also with
run_as_user_account. Shell behavior is consistent across nodes; initialization is explicit in the script. - A bare
shelltask tries once. Module tasks that reconcile managed resources, such as files and packages, are safe to repeat. Arbitrary scripts may not be. Automatic repeats require the node task to setretry; see node task retries. - A script's output never sets its own result.
stdout_jsononly lets conditions and later tasks read JSON output as data. Structured results use the module protocol; one JSON contract is enough. - Guards have names that say what happens, and a failed check is not "no". A broken check never counts as false.
- A command that follows a change uses the service record. There is no second mechanism with its own list of paths: one mechanism for one pattern, and it already recovers after an interrupted run.
- A command record is in
/var/lib/mmx/, a service record in/run/mmx/. A reboot clears/run/mmx/: after a reboot the service has started with the files on disk. A reboot does not runpostmap, so a command's record survives a reboot. - A marker file, not a hidden record. You can inspect, list, and delete
the
run_only_once_marker_filewith ordinary tools. Restoring a backup of the node restores the marker file together with the data the command created. - Prefer a guard that asks the program over a marker file. A migration
guarded by
skip_if_this_command_succeeds: bin/migrate --is-up-to-dateis still right after someone restored an old database; a marker file would wrongly say "already done". - Path guards name their condition.
skip_if_this_path_existsskips the command when the path exists.run_only_if_this_path_existsruns the command only when the path exists. A relative path uses the command’s directory, so the guard and the script check the same file.
This page is docs/reference/modules/shell.md in the MMX repository.