Move from Ansible or Salt
Who acts: you, or your coding agent, on your controller machine: the
computer where you run mmx, usually your laptop. No command on this page
asks a question when MMX logs in as root with a key. With a sudo
password, a coding agent adds --non-interactive and gives the password as
Passwords for automation
shows.
When to use this page: you have an Ansible playbook or a Salt state, and you want the MMX way to do the same work.
What this page does: a table gives the MMX counterpart of each Ansible and Salt idea, with a link to the page that explains the MMX side. Then you convert a small Ansible playbook to MMX, step by step: nginx with a template, a handler, a group, and a variable for the group. Last, tables map Ansible's commands, task keywords, and modules to MMX.
Terms:
- A node is a Linux server that MMX manages. An inventory is a
file in
inventories/that lists the nodes, how to reach each node, and the groups of nodes. - A playbook is a file in
playbooks/that lists fleet stages, run in order. Each fleet stage picks nodes, and each of those nodes runs the fleet stage's node tasks, in order. - A node task names one module, the code that does the work, such as
apt_packageorfile, with the module's inputs below its name. - A node task block groups a change with what follows it on the same node: making the change, putting the change into use, and checking the change.
| What you need | Where |
|---|---|
| The MMX counterpart of an Ansible or Salt idea, such as handlers or pillar | Ansible and Salt ideas in MMX |
| A worked conversion of a playbook, run on real servers | Convert a playbook |
The MMX command for an ansible-playbook or salt command |
Commands |
The MMX form of a task keyword, such as register or become |
Task keywords |
| The MMX module for an Ansible module or a Salt state function | Modules |
Before you start
mmxis installed on your controller machine, as Get started step 1 shows.- Your controller machine trusts each server's SSH host key, as Get started
step 2 shows. MMX logs in as
root, or as an account that can run any command withsudo. - For the worked conversion: two servers that run Debian or Ubuntu,
because the playbook installs nginx with
apt_package. The examples useweb01at203.0.113.11andweb02at203.0.113.12, both Debian 13. - MMX manages only Linux servers that run systemd. For Windows servers, network devices, or Linux without systemd, keep Ansible or Salt for those machines.
Ansible and Salt ideas in MMX
Each row names the Ansible idea, the Salt idea, and what MMX uses instead. The link in each row goes to the page that explains the MMX side.
| Ansible / Salt | In MMX |
|---|---|
| Inventory (Ansible) / minion targeting, nodegroups (Salt) | An inventory file, inventories/<name>.yml, lists each node with its address and ssh_user, and the groups. A command chooses an inventory with --inventory <name>. A fleet stage selects nodes by inventory node and group names only, not by facts or name patterns: --limit web01,web02 replaces Salt's -L, there is no pattern algebra such as web:&prod or !web03, and environments are separate inventories. Describe your servers, Choose which servers a run touches |
group_vars, host_vars (Ansible) / pillar (Salt) |
vars in four places: the project settings file mmx_project_settings.yml, the top of the inventory, a group, and a node. A later place replaces an earlier one, in that order. When two groups of one node set the same variable, MMX refuses the inventory instead of choosing a group. For secret pillar values, see the vault row below. Describe your servers step 3, Where a value comes from |
| Playbook, play (Ansible) / top file, highstate (Salt) | A playbook, playbooks/<name>.yml, applied with mmx run <name>. MMX has no default playbook, so each command names one. An Ansible play becomes a fleet stage: nodes in place of hosts, and node_tasks in place of tasks. Write a playbook |
Task (Ansible) / state, state function such as pkg.installed (Salt) |
A node task: an id you choose and one module with its inputs. Each module is named for its tool, such as apt_package for apt and dnf_package for dnf. MMX has no module that picks the tool for you, such as Ansible's package. Find the module for a job, Modules below |
Handlers, notify (Ansible) / watch, onchanges (Salt) |
A node task block. The changes phase writes files, and the activate phase reloads or restarts the service when a file in changes differs from what the service last loaded. MMX keeps that record on the node, so the next run still reloads after a run that stopped between the write and the reload. Change a configuration and reload its service, A run that stopped before the reload |
block, rescue, always (Ansible) / onfail (Salt) |
A node task block's on_failure and cleanup phases. on_failure runs only when an earlier phase of the block failed, and cleanup runs last, after success or failure. Unlike a successful Ansible rescue, a successful on_failure does not clear the failure: the node task block still fails. The phases in order |
| Roles (Ansible) / formulas, SLS files (Salt) | A role: a file roles/<name>/main.yml with declared inputs and node tasks, called from a node task with role: and inputs:. Ansible's include_tasks and import_tasks also become roles. Reuse work with roles |
| Ansible Vault / secrets in pillar | The vault: one encrypted file of secrets in the project, edited with mmx secrets edit. A node task reads a secret as {{ .secrets.<key> }}, and MMX hides the value in output and saved runs. A node receives only the secrets that its own node tasks use. Keep secrets, Secrets reference |
Facts, gather_facts (Ansible) / grains (Salt) |
Facts under .node, such as .node.distribution.id and .node.memory.total_mib. MMX collects the facts each time a node starts a fleet stage, so a playbook has no setting for gathering. A fleet stage cannot select nodes by a fact, as Salt's grain targeting does: put the nodes in a group, or use a when condition on a fact. Node facts |
ansible_host, ansible_user, ansible_port, ansible_ssh_private_key_file, SSH and sudo passwords (Ansible) |
Node fields address, ssh_user, ssh_port, and ssh_identity_file. The fields ssh_known_hosts and ssh_config name SSH client files for the node. A password is a secret reference with no text around it: ssh_password: "{{ .secrets.ssh_password }}" and sudo_password: "{{ .secrets.sudo_password }}". MMX keeps a password only in the memory of the mmx process on the controller machine, and never writes it to the inventory, to the node, or to a result. connection: ssh_only skips HTTPS, and https_address sets the HTTPS address when it is not address with port 7443. Inventory file, Connect to your servers |
| Jinja2 templates and filters (Ansible) | Go text/template files, with the functions of the Sprig library and toYaml. MMX leaves out the Sprig functions that read the clock, random values, the environment, or the network, so that a run with nothing new reports unchanged. Functions in templates |
hostvars[other], groups['web'] (Ansible) / Salt mine |
.inventory.nodes.NAME and .inventory.groups.NAME for the inventory, and fleet stage outputs for values a fleet stage found out. Values about other servers |
A role or vars/{{ ansible_os_family }}.yml for every distribution (Ansible) |
MMX has no module that picks the tool for the distribution. A mixed fleet uses a when on .node.distribution.id or .node.distribution.family to choose between node tasks that name their tool, such as apt_package and dnf_package. One role for several distributions |
serial, forks (Ansible) / --batch-size (Salt) |
max_nodes_at_once on a fleet stage: a number or a percentage. wait_for_all_in_batch: true makes each batch finish before the next one starts. Roll out a change gradually |
delegate_to (Ansible) |
MMX has no counterpart keyword, because each fleet stage names the nodes that do the fleet stage's work. Write the other node's work as its own fleet stage on that node. For work on another node for each node in turn, such as taking each web server out of a load balancer, use a for_each_node loop. Do one server's work on another server, Take each server out of the load balancer while it changes |
run_once (Ansible) |
A fleet stage whose nodes names one node, such as nodes: db01, for work such as a database migration. A later fleet stage can wait for that work with requires. Run a fleet stage only where an earlier one succeeded |
Tags, --tags, --skip-tags, --start-at-task (Ansible) |
MMX has no tags and no option to start at a node task, because tags and a start task can skip work that a later step needs. Keep each part that you apply on its own in its own fleet stage, and choose fleet stages with --only-fleet-stages. MMX refuses to leave out a fleet stage that a kept one needs. Run only some fleet stages |
Check mode, --check --diff (Ansible) / test=True (Salt) |
mmx dryrun <playbook>, with --diff for the lines of each file that would change. The exit code says whether anything would change. Preview and run changes |
Ad hoc commands, ansible all -m shell -a '...' (Ansible) / salt '*' cmd.run '...' (Salt) |
mmx run-command --nodes all -- <command>. Run a command on servers now |
Ansible Galaxy, collections / Salt formulas from saltstack-formulas |
MMX has no counterpart: no shared collection of roles to download, and no search path for roles. MMX has no shared collection of roles: a project's roles are written for that project. To reuse a role, copy the role's directory into the other project's roles/. The shared parts are the core modules, which come with MMX, and the official extra modules, which come in the same release archive. What MMX does not have, Official extra modules |
Salt master and minions, salt-key -A |
MMX has no master and no key acceptance. mmx-runner, MMX's node program, resembles a minion: it runs as root on the node, runs jobs there, and keeps their results. The first mmx dryrun or mmx run on a server logs in over SSH and installs MMX's node program, mmx-runner. Your trusted SSH host keys and your SSH login decide which servers and people MMX trusts. What the first dryrun did on the server |
| Salt mine | A fleet stage output: a value that a fleet stage publishes from each of its nodes, which later fleet stages read. Use a result from one server on another |
Salt reactor, beacons, scheduler / ansible-pull, AWX schedules |
MMX works only when you or a program run an mmx command. To apply a playbook on a schedule, run mmx run from CI or from a systemd timer on a controller machine. For health checks and automatic restarts, use a monitoring tool. Run the project from CI |
Convert a playbook
The Ansible project below installs nginx on the group web_servers. A
template writes an nginx site whose port comes from a variable of the
group, and a handler reloads nginx when the site file changed:
# inventory.yml
web_servers:
hosts:
web01:
ansible_host: 203.0.113.11
ansible_user: root
web02:
ansible_host: 203.0.113.12
ansible_user: root
# group_vars/web_servers.yml
http_port: 8080
# templates/shop.conf.j2
server {
listen {{ http_port }};
default_type text/plain;
return 200 "Shop on {{ inventory_hostname }}\n";
}
# site.yml
- name: Set up nginx
hosts: web_servers
tasks:
- name: Install nginx
ansible.builtin.apt:
name: nginx
state: present
update_cache: true
- name: Write the shop site
ansible.builtin.template:
src: templates/shop.conf.j2
dest: /etc/nginx/conf.d/shop.conf
mode: "0644"
notify: Reload nginx
- name: Start nginx
ansible.builtin.service:
name: nginx
state: started
enabled: true
handlers:
- name: Reload nginx
ansible.builtin.service:
name: nginx
state: reloaded
The steps write the same work as an MMX project and run it on two fresh Debian 13 servers.
Steps
-
Create an MMX project. In a new, empty directory beside the Ansible project:
mkdir shop && cd shop mmx init rm playbooks/example.ymlmmx initwrites an example playbook,playbooks/example.yml, that this conversion does not need.Check:
mmx initprints:Created mmx_project_settings.yml, inventories/example.yml, and playbooks/example.yml. Set the SSH destination in inventories/example.yml, then run mmx dryrun example. -
Convert the inventory and
group_vars. Replace the contents ofinventories/example.yml. The group's variables go into the inventory file, under the group:# inventories/example.yml nodes: web01: address: 203.0.113.11 # ansible_host ssh_user: root # ansible_user web02: address: 203.0.113.12 ssh_user: root groups: web_servers: nodes: [web01, web02] vars: http_port: 8080 # group_vars/web_servers.ymlEvery key of a
group_varsfile moves into thevarsof that group, so a second key such assite_title: Shopbecomes a second line belowhttp_port. Variables fromgroup_vars/all.ymlgo intovarsat the top of the inventory file, and variables fromhost_vars/web01.ymlgo intovarsunder the nodeweb01.An INI inventory maps in the same way. Each
[web_servers]section becomes an entry undergroups:with anodes:list. Each host line becomes an entry undernodes:, withansible_hostasaddress,ansible_userasssh_user, andansible_portasssh_port. A variable written on a host line, such asweb01 http_port=8081, goes intovarsunder the nodeweb01. A[web_servers:vars]section goes intovarsunder the group.Check:
mmx nodeslists both servers in the group.mmx nodescontacts no server.Inventory: example (inventories/example.yml, 2 nodes) Nodes web01 203.0.113.11 root web_servers web02 203.0.113.12 root web_servers Groups web_servers web01, web02If
mmx nodesnames a field that is wrong, compare the field with The inventory file reference. -
Convert the template. Create
files/shop.conf.tmpl. MMX templates use Go'stext/templatesyntax instead of Jinja2, so each reference changes:server { listen {{ .vars.http_port }}; default_type text/plain; return 200 "Shop on {{ .node.name }}\n"; }Jinja2 in Ansible MMX template {{ http_port }}, a variable{{ .vars.http_port }}{{ inventory_hostname }}, the server's name in the inventory{{ .node.name }}{{ ansible_facts['distribution'] }}, a fact{{ .node.distribution.id }}A filter, such as {{ name | title }}A function, such as {{ .vars.name | title }}, from the list in Functions in templatesCheck: step 6 shows the template filled in for
web01. A reference to a variable that the node does not get is an error there, not empty text. -
Convert the play and the package task. Create
playbooks/set_up_web_servers.yml:# playbooks/set_up_web_servers.yml fleet_stages: - id: set_up_nginx # the play nodes: web_servers # hosts: web_servers node_tasks: - id: install_nginx # the task "Install nginx" apt_package: packages: - {name: nginx, version: newest_when_first_installed}Three settings of the Ansible task have no line in the MMX file:
state: presentbecomesversion: newest_when_first_installed. MMX installs the newest version when nginx is missing, and then leaves the installed version alone.update_cache: truehas no counterpart, becauseapt_packagerefreshes the package index itself before an installation.- Ansible's
become: trueruns a task as root through sudo. MMX runs each node task as root, so MMX has nobecome.
Check:
mmx validate set_up_web_serversprintsValid: mmx_example. -
Convert the template task, the service task, and the handler into a node task block. Add this below
install_nginx, at the same indent:- task_block: id: shop_site changes: # the task "Write the shop site" - id: write_site_file file: path: /etc/nginx/conf.d/shop.conf permissions_mode: "0644" template: files/shop.conf.tmpl activate: # the task "Start nginx" and the handler "Reload nginx" - id: reload_nginx systemd_service: name: nginx start_at_boot: true # enabled: true state: running # state: started refresh: reload # state: reloaded, when the site file changed verify: # new: check that the site answers - id: check_shop_site wait_for: url_responds: "http://127.0.0.1:{{ .vars.http_port }}/" response_body_contains: Shop onReason: Ansible's handler runs at the end of the play, and only when the template task reported a change in this run. In MMX, the
activatephase runs inside the node task block, after thechangesphase, on the same node.systemd_servicestarts nginx when nginx is stopped.systemd_servicereloads nginx when the site file differs from the file that nginx last loaded, also when an earlier run wrote the file and then stopped before the reload.verifyasks the server itself for the page and fails the node task block when the answer does not containShop on.Check:
mmx validate set_up_web_serversprintsValid: mmx_example. The whole file now reads:# playbooks/set_up_web_servers.yml fleet_stages: - id: set_up_nginx nodes: web_servers node_tasks: - id: install_nginx apt_package: packages: - {name: nginx, version: newest_when_first_installed} - task_block: id: shop_site changes: - id: write_site_file file: path: /etc/nginx/conf.d/shop.conf permissions_mode: "0644" template: files/shop.conf.tmpl activate: - id: reload_nginx systemd_service: name: nginx start_at_boot: true state: running refresh: reload verify: - id: check_shop_site wait_for: url_responds: "http://127.0.0.1:{{ .vars.http_port }}/" response_body_contains: Shop on -
See what one server will get.
mmx explain set_up_web_servers --limit web01mmx explaincontacts no server.mmx explainprints each node task's values and the line of your files that each value came from.Check: the site file appears filled in for
web01, and the URL of the check shows the inventory line ofhttp_port:web01 / set_up_nginx/shop_site/changes/write_site_file: file (ready) ... file.template, rendered for web01: server { listen 8080; default_type text/plain; return 200 "Shop on web01\n"; } ... web01 / set_up_nginx/shop_site/verify/check_shop_site: wait_for (ready) ... wait_for.url_responds = "http://127.0.0.1:8080/" from playbooks/set_up_web_servers.yml:29:31 (fleet_stages[0].node_tasks[1].task_block.verify[0].wait_for.url_responds) value from inventories/example.yml:14:18 (groups.web_servers.vars.http_port)If
mmx explainsays that a reference names a value that is not declared, check the spelling of the variable in the template and in the inventory. -
Preview the playbook.
mmx dryrun set_up_web_servers echo "exit code $?"The first dryrun on each server also sets up MMX there, over SSH. Part of the output:
203.0.113.12: setting up MMX through verified SSH 203.0.113.11: setting up MMX through verified SSH ... set_up_nginx / web01 / install_nginx: succeeded, would_change [{"name":"nginx-common","to":"1.26.3-3+deb13u10"},{"name":"nginx","to":"1.26.3-3+deb13u10"}] 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. set_up_nginx / web01 / shop_site/activate/reload_nginx: skipped, unknown — service state can be checked after the node task block's proposed changes are applied set_up_nginx / web01 / shop_site/verify/check_shop_site: not_checked, unchanged — Get "http://127.0.0.1:8080/": dial tcp 127.0.0.1:8080: connect: connection refused ... Run 76f63216: succeeded 2 finished Saved: /home/you/shop/.mmx/runs/20261115T073157.780081110-76f63216ed591b19 exit code 3Check:
install_nginxsayswould_change, the site file saysnot_checked, and the exit code is 3. Exit code 3 means that the dryrun worked but could not check some work. Thenot_checkedresult is expected on a fresh server: the nginx package creates/etc/nginx/conf.d, and a dryrun installs nothing. Preview and run changes explains each result. -
Run the playbook.
mmx run set_up_web_serversPart of the output, for
web01:set_up_nginx / web01 / install_nginx: succeeded, changed [{"name":"nginx-common","to":"1.26.3-3+deb13u10"},{"name":"nginx","to":"1.26.3-3+deb13u10"}] set_up_nginx / web01 / shop_site/changes/write_site_file: succeeded, changed set_up_nginx / web01 / shop_site/changes/write_site_file: created "/etc/nginx/conf.d/shop.conf" absent -> 85 bytes, permissions_mode 0644, uid 0, gid 0 set_up_nginx / web01 / shop_site/activate/reload_nginx: succeeded, changed — service is not running set_up_nginx / web01 / shop_site/verify/check_shop_site: succeeded, unchanged set_up_nginx / web01 / shop_site: succeeded, changed ... Run 5f3e7ce9: succeededCheck: the run ends with
Run ...: succeededand exit code 0, andcurl http://203.0.113.11:8080/printsShop on web01.reload_nginxsaysservice is not runningbecauseapt_packageinstalls a package without starting its services, soreload_nginxstarted nginx. On Debian and Ubuntu, a package's own scripts start a newly installed service unless apolicy-rc.dprogram forbids it. Ansible'saptmodule leaves that alone, so the Ansible task "Start nginx" found nginx already running. Packages do not start their services explains the rule. -
Run it again.
mmx run set_up_web_serversCheck: every node task says
succeeded, unchanged. If a node task sayschanged, a value differs between runs: read the node task's line, which says what changed. -
Change the variable, and preview on one server. Step 10 shows how MMX does the handler's work. In
inventories/example.yml, changehttp_port: 8080tohttp_port: 8081. Then:mmx dryrun set_up_web_servers --limit web01 --diff echo "exit code $?"set_up_nginx / web01 / shop_site/changes/write_site_file: would update "/etc/nginx/conf.d/shop.conf" 85 bytes, permissions_mode 0644, uid 0, gid 0 -> 85 bytes, permissions_mode 0644, uid 0, gid 0 --- before +++ after @@ -1,5 +1,5 @@ server { - listen 8080; + listen 8081; default_type text/plain; return 200 "Shop on web01\n"; } set_up_nginx / web01 / shop_site/activate/reload_nginx: succeeded, would_change — tracked input /etc/nginx/conf.d/shop.conf changed after the service last started or reloadedCheck: the diff shows the new port, and
reload_nginxsayswould_change. The checkcheck_shop_sitesaysnot_checked, and the exit code is 3, because nothing listens on port 8081 before the run. -
Run the change.
mmx run set_up_web_serversCheck: on each server,
write_site_filesaysupdatedandreload_nginxsayssucceeded, changed — tracked input /etc/nginx/conf.d/shop.conf changed after the service last started or reloaded. The run ends with exit code 0, andcurl http://203.0.113.12:8081/printsShop on web02.
The Ansible playbook above, run on a third fresh Debian 13 server, left
the same /etc/nginx/conf.d/shop.conf, byte for byte, as the MMX playbook.
nginx was enabled and running in both cases, and listened on the same
ports.
Commands
| Ansible or Salt | MMX |
|---|---|
ansible-playbook -i inventories/prod.yml site.yml |
mmx run site --inventory prod. Without --inventory, MMX uses default_inventory from mmx_project_settings.yml. Use one inventory for each environment |
ansible-playbook --check --diff / salt '*' state.apply test=True |
mmx dryrun site --diff. Preview and run changes |
ansible-playbook --syntax-check |
mmx validate site, and mmx explain site for every value and the line that each value came from. Write a playbook |
--limit web01 |
--limit web01. Run on some servers only |
--list-hosts, ansible-inventory --graph |
mmx nodes for the inventory's nodes and groups, and mmx nodes site for the nodes that each fleet stage selects. See the selection before you run |
-e release=1.2.3 |
--var release=1.2.3, for a variable that the playbook declares in command_line_vars. Command-line variables |
--limit @site.retry |
mmx resume, which finishes a saved run's failed and unfinished work and leaves finished nodes alone. Resume a run |
ansible all -m ping / salt '*' test.ping |
mmx run-command --nodes all -- true. Run a command on servers now |
ansible web_servers -b --become-user app -m shell -a '...' / salt '*' cmd.run '...' runas=app |
mmx run-command --nodes web_servers --run-as-node-user-account app -- .... Run a command on servers now |
ansible-doc apt |
mmx describe-module apt_package. Find the module for a job |
ansible-vault edit |
mmx secrets edit. mmx secrets list-keys, diff-keys, usage, add-random, and set work on the keys without showing a value. The mmx secrets commands |
salt-run jobs.lookup_jid, returners |
mmx results reads a run that MMX saved in the project's .mmx/ directory, and mmx status asks the nodes how a run's work stands. Read a saved run |
salt-ssh |
MMX itself: mmx connects over HTTPS on port 7443, and uses SSH when HTTPS is closed or when the node has connection: ssh_only. A server whose port 7443 is closed |
Task keywords
| Ansible or Salt | MMX |
|---|---|
become: true |
Nothing: MMX runs node tasks as root. |
become_user: app |
run_as_user_account: app on shell and on the modules that take the input, such as git. Running as another account |
register: result |
The node task's id. A later node task of the same fleet stage, on the same node, reads .node_tasks.<id>.<field>. A looped node task keeps its results in .node_tasks.<id>.items. A fleet stage output carries a value to another fleet stage or node. Use a result from one server on another |
set_fact |
set_vars. The value lasts until the end of the fleet stage, role call, or loop turn that set it. To carry a value across a fleet stage or role boundary, declare an output. Values computed during the run |
debug |
show. Values computed during the run |
when, loop, dict2items |
when and loop on a node task or a fleet stage. A loop over a mapping gives each turn .<as>.key and .<as>.value, in the sorted order of the keys, so dict2items is not needed. Decide for each server during the run, Loop over the results |
until, retries, delay |
A retry mapping with until, max_tries, and pause_between_tries. Node task retries and time limits |
handlers with register and when: result.changed |
A shell node task with only_when_tracked_inputs_changed: true in a node task block's activate phase runs the command only when a tracked input of the block changed, such as a file, a unit, or a package. Run a command after a change |
changed_when, failed_when |
changed_when and failed_when on shell, and success_exit_codes for the exit codes that count as success. Result rules |
ignore_errors |
MMX has no counterpart. A module checks the server first, so removing something that is already gone reports unchanged instead of failing. For a command whose failure is expected, list its exit codes in success_exit_codes. |
creates, removes / Salt creates, unless, onlyif |
skip_if_this_path_exists, run_only_if_this_path_exists, skip_if_this_command_succeeds, and run_only_if_this_command_succeeds on shell. Guards |
chdir, environment |
run_from_directory and env on shell. A shell script cannot contain a reference to an MMX value, such as {{ .vars.port }}, so pass values to the script through env. Where a value comes from |
no_log |
Values from the vault are hidden automatically. For a secret that a command prints, set output_is_secret: true on shell, and for a secret in a file that a node task reads, content_is_secret: true on read_file. A secret that a module uses only as a login to its tool is hidden without hiding the module's whole result. Secrets in files, output, and history |
max_fail_percentage, any_errors_fatal |
failed_nodes_allowed, a count or a percentage of the whole fleet stage and not of each batch, with on_node_failure: stop_fleet_stage or on_node_failure: stop_run. Choose what a failed server stops |
hosts: all:!db_servers |
except_nodes on the fleet stage. Leave some servers out of a fleet stage |
strategy: free |
The default: with max_nodes_at_once, a node starts as soon as another node finishes. wait_for_all_in_batch: true finishes each batch before the next one starts. |
connection: local, local_action, delegate_to: localhost |
A Linux controller machine can be a node in the inventory, reached over SSH. MMX has no local mode. A macOS controller machine cannot be a node, and MMX never reboots its controller machine. Manage the controller machine itself |
| A playbook that runs once, such as a migration | A one-time playbook in one_time_playbooks/. Make a one-time change |
Salt require |
Written order: node tasks run in the order of the file, and fleet stages run in the order of the playbook. requires on a fleet stage names earlier fleet stages that must have succeeded. |
| YAML anchors and aliases | MMX refuses them: mmx validate prints aliases, anchors, and explicit tags are not supported. Reuse values with vars, and node tasks with roles, which mmx explain can trace. |
Modules
Each MMX module has a page, and mmx describe-module <name> prints the
same page. The modules in the last rows are official extra modules, which
come with mmx in the same release archive.
| Ansible module | MMX module |
|---|---|
apt, dnf, yum, package |
apt_package or dnf_package, with a packages list. Each entry of an installed package gives name and version, such as version: newest_when_first_installed, and an entry of a package to remove gives only name. dnf_package drives dnf 4, the dnf of Enterprise Linux 9 and 10, and dnf 5, the dnf of Fedora 41 and newer. There is no update_cache: MMX refreshes the package index once for each node job before an install or upgrade, and again after a package source changes. |
apt with upgrade: dist |
apt_package with upgrade_all_packages_within_their_version_rules: true, which is apt's full-upgrade and leaves held packages back. version: newest_on_every_run on named package entries upgrades those packages on every run. Upgrade the whole node |
apt with name: nginx=1.26.*, dpkg_selections with hold |
A version pattern on the package entry; the package manager's own rule then keeps the package inside the pattern. Keep a package at a version |
apt with deb: |
package_file_source, or package_file_url with package_file_sha256, on the package entry. The exact version of the entry must match the file. Install a package from a .deb file |
dnf with security: true |
dnf_package with upgrade_all_packages_within_their_version_rules: true and only_security_updates: true; the node task fails, also in a dryrun, when the node's package sources list no advisories. apt_package has no security-only option. On Debian and Ubuntu, see Apply only security updates on Debian and Ubuntu. |
apt_repository, deb822_repository, apt_key, yum_repository |
apt_repository, dnf_repository |
pip, gem, npm, snap, bundler, composer |
pip_package, gem_package, npm_global_package, snap_package, and the ..._project_dependencies modules. Install languages and application dependencies |
copy, template |
file with content, source, or template |
copy with remote_src: true, assemble |
file with content_from_node_paths. Install a file from paths on the node |
copy or template with force: false |
file with if_file_exists: keep_existing_content. Write a file once, then leave its content alone |
backup: true |
file with backup_original_file_to, which keeps the one original file, not a copy for each change. Keep the original of a file MMX takes over |
file with state: directory or state: link |
directory, symlink. recurse: true is also_apply_to_everything_inside: true. |
file with state: absent on a directory |
directory with state: absent and also_delete_everything_inside: true. Delete a directory, or what it no longer lists |
find and a loop that deletes |
directory with delete_everything_inside_except, or delete_old_files for files older than a duration |
synchronize |
directory with source. delete: true is also_delete_entries_not_in_source: true. Copy a directory from the controller machine |
slurp, fetch |
read_file, for a regular file of at most 1 MiB. A fleet stage's save_on_controller_machine saves the content on the controller machine. |
lineinfile |
line. regexp is match, a Go regular expression, and the replacement text in line must match it too. insertafter and insertbefore are the insert_... inputs. When more than one line matches, the node task fails instead of editing the last one. |
blockinfile, replace, ini_file |
A whole file with file, or a drop-in file in the program's configuration directory. Otherwise edit_file. |
get_url |
download: MMX fetches an HTTPS file on the controller machine, checks its SHA-256, and sends it to the nodes. download accepts no credentials in the URL: for a source that needs credentials, use git or shell. |
unarchive |
unpack_archive, into a new directory for each release; it never extracts over an existing directory. unpack_without_wrapping_folder: true removes one enclosing folder and refuses entries outside it, and is not a general strip-components option. A symlink node task then switches current to the new release, and the service refresh that the node task block's refresh names, reload or restart, follows from the switch. Unpack a release and switch a symlink |
git |
git. version becomes one of follow_branch, check_out_tag, or check_out_commit, dest is path, become_user is run_as_user_account, and force: true is files_changed_in_checkout_on_node: discard_the_changes. MMX checks out a detached commit as run_as_user_account. For an SSH repository, ssh_private_key holds the content of the key, normally from a secret, with ssh_known_hosts_lines; it does not take a path on the node. The checkout is shallow unless full_history: true, and submodules and Git LFS content are not fetched. |
user, group |
user, group. append: false is supplementary_groups_not_listed: remove, and remove: true is also_delete_home_directory_and_mail: true. update_password: on_create is apply_password_hash: only_when_account_has_no_password, which also sets a password on an existing account that has none. user has no input for account expiry or password aging: run chage with shell for account expiry and password aging. |
authorized_key |
authorized_keys. user is for_user_account, and exclusive: true is keys_not_listed: remove. key_files_on_controller_machine and key_directories_on_controller_machine read keys from files. |
openssh_keypair, user with generate_ssh_key |
ssh_key_pair. path, type, comment, and owner become private_key_path, key_type, key_comment_when_created, and for_user_account. ssh_key_pair never replaces an existing key, so there is no force or regenerate. |
systemd, service |
systemd_service to start, stop, enable, or mask a unit. systemd_unit writes a unit file, and MMX runs systemctl daemon-reload after a changed unit. You write state: running, stopped, or do_not_start_or_stop, and start_at_boot for boot activation. scope: user is in_systemd_of_user_account, and masked: true masks a unit. |
cron |
systemd_scheduled_job (recommended) or cron_job |
mount, filesystem |
fstab_mount, create_filesystem_on_empty_device; a .mount unit also works. |
hostname, timezone, locale_gen |
hostname, time_zone, locale |
sysctl, modprobe, alternatives |
sysctl_setting, kernel_module, update_alternatives |
ufw, firewalld |
ufw with incoming_rules, routed_rules, and outgoing_rules; incoming_rules_not_listed: remove (and the same for routed and outgoing) makes the node task own that whole set. firewalld manages one zone's services, ports, and rich rules, and rules_not_listed: remove owns that set only. firewalld_zone creates or removes zones, and firewalld_zone_membership manages a zone's interfaces and source networks. An interface that NetworkManager controls belongs in networkmanager_connection_file. |
interfaces_file, nmcli, a template of a network file |
One whole network file for the node's network tool: ifupdown_interfaces_file, netplan_file, networkmanager_connection_file, or systemd_networkd_file. Where interfaces_file changes one option, MMX takes the whole file. When a change cuts the node off from the controller machine, the node restores the previous file. netplan_file supports only the systemd-networkd renderer; for NetworkManager, use networkmanager_connection_file. |
seboolean, sefcontext, seport, selinux |
selinux_boolean, selinux_file_context, selinux_port, selinux_mode. selinux_mode selects enforcing or permissive and has no disabled state. |
acl, capabilities |
file_access_control_list, linux_capability_on_program_file |
wait_for |
wait_for, for a port, a path, an HTTP response, or a command, often in a node task block's verify phase |
uri |
http, with method, json_body, and expected_http_status_codes (default [200]). The request is sent once unless the node task sets retry. Later node tasks read .node_tasks.<id>.response_body, .response_body_json, and .http_status_code. |
validate: on copy, template, or lineinfile |
check_new_file on file, download, line, or edit_file, such as visudo -cf for a sudo rule or logrotate --debug for a log rotation file. The check reads the new file at .new_file.path, and there are no sudoers or logrotate modules: write a file node task with check_new_file. Change a configuration and reload its service |
assert, fail with when |
assert, with the condition that must hold |
reboot |
reboot, as the last node task of a fleet stage. reboot_timeout is wait_at_most, and test_command becomes a readiness check in the next fleet stage. |
command, shell, script |
shell, which runs Bash on the node and interprets shell syntax, unlike command. For a script file, copy the script with file, then run it with shell. |
docker_compose_v2, docker_container, docker_image |
docker_compose_project and docker_image. For a single container, use a Compose file with one service, or a systemd unit: Run containers. |
podman_container, podman_image |
podman_quadlet, podman_image |
postgresql_user, postgresql_db, mysql_user, mysql_db |
postgresql_role, postgresql_database, mysql_user, mysql_database. Manage a database |
acme_certificate, a certbot command |
certbot_certificate |
parted, or a growpart command |
create_partitions_on_empty_disk writes a GPT partition table with named partitions on a disk that holds nothing, and never changes a disk that holds anything. grow_partition_into_free_space_after_it grows one existing partition into free space after it and leaves its contents alone. |
filesystem with resizefs: true |
grow_filesystem_to_fill_device, for an ext4 or XFS filesystem mounted for writing. It grows the filesystem and never shrinks it. |
lvg, lvol |
lvm_volume_group, lvm_logical_volume. pvs is physical_volumes, vg is volume_group, and resizefs is grow_filesystem_with_volume, which you set explicitly: true grows the filesystem with the volume, and false grows only the volume. There is no shrink or force. |
zfs |
zfs_dataset. extra_zfs_properties is properties, and state: absent is state: deleted_with_all_its_data. |
lxd_container, lxd_profile |
incus_instance, incus_profile, for Incus |
virt |
libvirt_domain. The XML comes from a file on the node that a file node task writes, and autostart is start_at_boot. |
rabbitmq_vhost, rabbitmq_user, rabbitmq_policy, rabbitmq_plugin |
rabbitmq_virtual_host, rabbitmq_user, rabbitmq_policy, rabbitmq_plugin. Each rabbitmq_user.permissions entry gives virtual_host, configure, write, and read instead of vhost, configure_priv, write_priv, and read_priv, and permissions_not_listed: remove or keep is required. |
mongodb_user |
mongodb_user. update_password has no counterpart: the module sets the password only when the user cannot log in with it. |
Salt's common state functions map to the same modules: pkg.installed
to apt_package or dnf_package, pkgrepo.managed to apt_repository
or dnf_repository, file.managed to file, service.running to
systemd_service, and cmd.run to shell. A salt:// path becomes a
path in your project, such as files/shop.conf.tmpl, or in a role's
directory inside a role.
When no module does the job, When no module fits lists the smallest tool for it.
Not built, and why
These operations have no MMX module or input. Each row gives the reason and the way to do the work.
| Ansible or Salt work | In MMX |
|---|---|
NAT masquerading and port forwarding in ufw or firewalld |
ufw has no NAT command, and Incus, libvirt, Docker, and Podman write their own NAT rules. Write the NAT rules as a validated file with an explicit activation node task; ufw shows a gateway with a nft rules file. |
Security-only upgrades with apt |
apt has no security-only selection. Debian and Ubuntu use unattended-upgrade; the security updates example configures it and applies updates on demand. |
| Snap refresh schedules and holds | Run the snap command in a guarded shell node task. snap_package installs snaps. |
| Account expiry and password aging | Run chage with shell. |
A condition that picks one entry of a list fact, such as one mount of .node.storage.mounts |
Conditions cannot pick one mount or block device. To check that /var has 10 GiB free, run df in a shell node task and test its output with a number_at_least condition. |
| Cloud inventory generators inside MMX | Each provider needs its own API integration, credentials, and tests against the real provider. Any program can write the inventory YAML that MMX reads: Inventory file. |
| A module for sudo rules, log rotation, time synchronization, or NFS exports | Combine a package node task, a file node task with check_new_file, and a service node task. A module is added only when it does more than wrap a configuration file. |
If something is different
| What you see | What it means and what to do |
|---|---|
mmx validate prints line 3: aliases, anchors, and explicit tags are not supported |
The file uses a YAML anchor or alias, such as &web and *web. Write the value out, or move it to vars. |
mmx explain says reference .vars.http_port is not declared for node web01 |
The node does not get the variable. Check that the variable is in the vars of the node's group, the node, the inventory, or the project. Use variables and templates lists the causes. |
| The node belongs to two groups that set the same variable | MMX refuses the inventory. Set the variable in one group only, in the inventory's vars, or in each node's vars. |
| A converted Jinja2 template fails with an unknown function | Go templates have other functions than Jinja2 filters. Functions in templates lists the functions. |
| The server runs Fedora, Rocky Linux, or AlmaLinux | Use dnf_package instead of apt_package in step 4, with the same inputs. |
You used Ansible's async with poll: 0 |
MMX has no counterpart. The node keeps working on a fleet stage if the controller machine disconnects, but node tasks still run in order. Run a long-lived program as a systemd service with systemd_unit and systemd_service. |
| A package installed on Debian or Ubuntu did not start its service | apt_package stops package scripts from starting services. Set allow_package_to_start_its_services: true on the node task when the installation needs the service. Package scripts may still restart a service that already runs. Packages do not start their services |
Ansible's append, exclusive, or purge had other defaults for each module |
A node task that owns a list has one required input, <things>_not_listed, with the value remove or keep, for example keys_not_listed or rules_not_listed. |
You used pause or vars_prompt |
MMX has no prompt in a playbook, because a coding agent or CI cannot answer a prompt. Run mmx dryrun before mmx run, and pass a value with --var. |
Where to go next
- Write a playbook: a playbook from the start, without Ansible.
- Change a configuration and reload its service: checking a new file before nginx loads it, and putting the old file back when a check fails.
- Use variables and templates: every place a value can come from, and the template functions.
- Reuse work with roles: turning an Ansible role into an MMX role.
- Roll out a change gradually:
serialandmax_fail_percentagein MMX. - Coming from Ansible: the Ansible habits that the subscription web service example replaced. The example comes from a real company's Ansible repository, with invented names and services and without product-specific parts.
This page is docs/how-to/move-from-ansible-or-salt.md in the MMX repository.