Module pages

Each page describes one module of MMX: what it manages, its inputs and outputs, examples, how it works, its errors, where it is tested, and why it works this way. mmx describe-module NAME prints the same page in a terminal.

Module What it does Tested on
file one regular file from content, template, source, or files already on the node; metadata of an existing file; or removal Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
line one line of an existing file, selected by a regular expression or its exact text; prefer a drop-in or whole file where the program has one Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
edit_file the text of an existing file, changed by a filter command the author writes; for edits line cannot make; prefer a drop-in, a whole file, or line Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
symlink one symbolic link and its target text Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
read_file reads one file on the node, so a later node task or, through a fleet stage output, another node can use its content Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45

Directories, downloads, and release directories

Module What it does Tested on
directory one directory and its metadata, optionally the metadata of everything inside it or a copied source tree; or its deletion, or the deletion of what it does not list Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
delete_old_files deletes the regular files in one directory whose names match a pattern and that were last modified longer ago than a duration, such as rotated logs; follows no symlink and stays on the directory's filesystem; value has deleted_files, deleted_bytes, and deleted_file_examples Debian 12 and 13, Ubuntu 24.04 and 26.04
download a pinned HTTPS file, fetched and verified on the controller, installed as a file Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
unpack_archive a release directory extracted from a tar, plain or compressed with gzip, xz, bzip2, or zstd, or a zip file Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
git a directory checked out from a Git repository at a tag, branch, or commit Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45

Packages and package sources

Module What it does Tested on
apt_package apt packages on Debian and Ubuntu: present, absent, kept inside a version pattern, brought to the newest version, or installed from a .deb file; or a whole-node upgrade Debian 12 and 13, Ubuntu 24.04 and 26.04
dnf_package dnf packages on the Red Hat family: present, absent, kept inside a version, brought to the newest version, or installed from an .rpm file; or a whole-node upgrade Rocky Linux 9, AlmaLinux 10, Fedora 45
apt_repository one apt source file and its signing key Debian 12 and 13, Ubuntu 24.04 and 26.04
apt_downloaded_package_files deletes the package files that apt downloaded into its archives directory, /var/cache/apt/archives/, with apt-get clean; value has deleted_package_files and deleted_bytes Debian 12 and 13, Ubuntu 24.04 and 26.04
dnf_repository one dnf repository file and its signing key, imported into rpm; or whether a repository already on the node is switched on Rocky Linux 9, AlmaLinux 10, Fedora 45

Accounts and service units

Module What it does Tested on
user a local user account: groups, home, shell, full name, password hash, password lock, explicit ID, or removal Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
group a local group, with an explicit ID, its supplementary members, or removal Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
systemd_unit a systemd unit file (.service, .timer, .path, .socket, .mount, .target, .swap, .slice, or .automount) or one drop-in, verified before installation Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
systemd_service running, enabled, and masked state of a systemd unit of any kind systemd_unit installs, and refresh after tracked changes Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
systemd_journal_vacuum deletes archived files of systemd's journal with journalctl --vacuum-size and --vacuum-time, the oldest first; never the journal's active files; value has freed_bytes and deleted_archived_journal_files Debian 12 and 13, Ubuntu 24.04 and 26.04

Commands, checks, and reboot

Module What it does Tested on
shell a Bash script run as root or an application user, with optional guards, dryrun command, and result rules Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
http one HTTP or HTTPS request from the node that checks the response status: a read, or a write to an application's API Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
wait_for waits for a TCP port, a path, an HTTP response, a command, or the health of a Docker container, a Docker Compose project, or a Podman container to report ready, from the node Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
assert a condition that must hold; otherwise the task fails with a message Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
reboot reboots the node as the last task of a fleet stage, not in a role, task block, or loop; the controller waits for the node to return on a new boot. MMX never reboots the machine that runs the controller process: a fleet stage that ends with reboot fails on that node before its first node task, in a dryrun and in a run Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45

Scheduled jobs

Module What it does Tested on
systemd_scheduled_job a command that systemd runs on a schedule: a oneshot service <name>.service and a timer <name>.timer, checked with systemd-analyze, with the timer enabled and started; output goes to the journal (journalctl -u <name>), and a run never starts while the previous one is still going Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
cron_job one cron entry in its own file, /etc/cron.d/<name>, root-owned with mode 0644 and MMX's marker line; cron must be installed (package cron on Debian and Ubuntu, cronie on the Red Hat family); systemd_scheduled_job is the recommended alternative Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10

SSH keys and firewalls

Module What it does Tested on
authorized_keys one user's SSH authorized keys in <home>/.ssh/authorized_keys; they also authorize MMX's HTTPS access Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45
ssh_key_pair an SSH key pair for an account, without a passphrase, created once with the node's ssh-keygen (package openssh-client on Debian and Ubuntu, openssh on the Red Hat family) and never replaced Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
ufw the ufw firewall: incoming rules, routed rules, outgoing rules, default policies, its logging level, and whether it is enabled Debian 12 and 13, Ubuntu 24.04 and 26.04
firewalld the services, ports, and rich rules of one firewalld zone Rocky Linux 9, AlmaLinux 10, Fedora 45
firewalld_zone_membership Manage the interfaces and IP source networks of one firewalld zone, with automatic restoration when new connections cannot reach the node. Rocky Linux 9, AlmaLinux 10
firewalld_zone Create or remove a firewalld zone. When needed, the task reloads firewalld. A reload replaces every zone's running settings with its stored settings. Settings that exist only in the running firewall are dropped. Stored settings that are not running become active. Rocky Linux 9, AlmaLinux 10

Network configuration

Module What it does Tested on
ifupdown_interfaces_file Manages /etc/network/interfaces or one file in /etc/network/interfaces.d for ifupdown, the Debian package, and takes the changed interfaces down and up. The node restores an unconfirmed change by itself. Debian 12 and 13
netplan_file This module manages one Netplan YAML file with the systemd-networkd renderer. The node restores an unconfirmed change by itself. Ubuntu 24.04 and 26.04
networkmanager_connection_file Manages one NetworkManager keyfile and activates its profile. The node restores an unconfirmed change and the previously activated profiles by itself. Rocky Linux 9, AlmaLinux 10
systemd_networkd_file Manages one .network or .netdev file and reloads systemd-networkd. The node restores an unconfirmed change by itself. Debian 12 and 13
wireguard_interface Manages one WireGuard interface that wg-quick brings up: its file in /etc/wireguard, a private key that the node creates and keeps, and the service wg-quick@<name>.service. The node restores an unconfirmed configuration file change by itself. Debian 12 and 13, Ubuntu 24.04 and 26.04

SELinux, access control lists, and capabilities

Module What it does Tested on
selinux_boolean one SELinux boolean, now and in the stored policy; skipped where SELinux is not enabled Rocky Linux 9, AlmaLinux 10, Fedora 45
selinux_file_context the node's local SELinux label rule for a path, and the labels of the files there; skipped where SELinux is not enabled Rocky Linux 9, AlmaLinux 10, Fedora 45
selinux_port the SELinux type of a network port or range; skipped where SELinux is not enabled Rocky Linux 9, AlmaLinux 10, Fedora 45
selinux_mode whether SELinux enforces its policy or only reports, now and in /etc/selinux/config; skipped where SELinux is not installed Rocky Linux 9, AlmaLinux 10, Fedora 45
file_access_control_list the named account and group entries of a file's or directory's access control list, through getfacl and setfacl (package acl) Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
linux_capability_on_program_file the Linux capabilities of a program file, through getcap and setcap (package libcap2-bin on Debian and Ubuntu, libcap on the Red Hat family) Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10

Host name, time zone, locale, and alternatives

Module What it does Tested on
hostname the node's host name, stored and running, set through hostnamectl; /etc/hosts is not changed Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
time_zone the node's time zone, set through timedatectl; running services read it when they start Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
locale one locale the node offers, and whether it is the system default; write one task for each locale Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
update_alternatives which installed program a generic command, such as editor or java, runs, through the node's update-alternatives (the same program as alternatives on the Red Hat family) Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10

Kernel settings and kernel modules

Module What it does Tested on
sysctl_setting one kernel setting under /proc/sys, set now and kept for the next boot in /etc/sysctl.d/90-mmx-<name>.conf Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
kernel_module one loadable kernel module, loaded now with modprobe and at every boot from /etc/modules-load.d/mmx-<name>.conf, with its options in /etc/modprobe.d/mmx-<name>.conf; or unloaded Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10

Swap, filesystems, and mounts

Module What it does Tested on
swap_file a swap file, active now and after a reboot, through mkswap, swapon, swapoff, and a line in /etc/fstab Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
create_filesystem_on_empty_device a filesystem on a block device that holds nothing yet, made with mkfs.<filesystem_type>; a device that holds anything else fails the task, and nothing ever forces it Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
fstab_mount one line of /etc/fstab, identified by its mount point, and the live mount in step with it, through mount, umount, and findmnt Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10

Language and tool installers

Module What it does Tested on
pip_package Python packages installed with pip into a virtual environment or the system's Python; value lists each package that changed as {name, from, to} Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
gem_package Ruby gems installed with gem; value lists each gem that changed as {name, from, to} Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
npm_global_package command-line tools installed for the whole node with npm install --global; value lists each package that changed as {name, from, to}; an application's own packages are npm_project_dependencies Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
snap_package snaps installed by the snap service (the package snapd), which then keeps them up to date inside their channel; value lists each snap that changed as {name, from, to}, each a channel and revision Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
npm_project_dependencies what an application's package-lock.json (or npm-shrinkwrap.json) lists, installed into its node_modules with npm ci, which never rewrites the lock file; a record .mmx-npm-project-dependencies in the directory makes a rerun unchanged Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
yarn_project_dependencies what an application's yarn.lock lists, installed with the Yarn install that refuses to change yarn.lock: yarn install --frozen-lockfile with Yarn 1, --immutable with Yarn 2 and newer; a record .mmx-yarn-project-dependencies in the directory makes a rerun unchanged Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
bundler_project_dependencies what an application's Gemfile.lock lists, installed with bundle install in Bundler's deployment mode, which fails when Gemfile.lock does not fit the Gemfile; a record .mmx-bundler-project-dependencies in the directory makes a rerun unchanged; value.bundler_settings lists the settings the application must run with Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
composer_project_dependencies what an application's composer.lock lists, installed into its vendor directory with composer install, without prompts; a record .mmx-composer-project-dependencies in the directory makes a rerun unchanged Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
uv_project_dependencies what a Python application's uv.lock lists, installed into its .venv with uv sync --locked, which never rewrites the lock file and never downloads a Python; a record .mmx-uv-project-dependencies in the directory makes a rerun unchanged Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10

Containers

Module What it does Tested on
docker_image one Docker image on the node, pulled from a registry; never removes an image Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
docker_compose_project the containers of one Docker Compose project: running, stopped, or removed; the Compose file is written by a file task and holds every container setting Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
docker_unused_images removes the Docker images that no container, running or stopped, uses, as docker image prune does: only those without a name, or every one; value has removed_images and freed_bytes Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
podman_image one Podman image on the node, pulled from a registry into the system's image store or an ordinary account's; value has image_id and previous_image_id Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
podman_quadlet one Quadlet file, which Podman turns into a systemd service at each systemd reload, checked with Podman's generator before installation; value.generated_service names the service; needs Podman 4.4 or newer Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
podman_unused_images removes the images of a Podman image store that no container, running or stopped, uses, with podman image prune: only those without a name, or every one; value has removed_images and freed_bytes Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10

Databases

Module What it does Tested on
postgresql_role one role (account) inside a PostgreSQL server that is installed and runs: its password, its attributes, and the roles it is a member of, or its removal; runs the node's psql program Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
postgresql_database one database inside a PostgreSQL server that is installed and runs: its owner and its extensions, or its removal with all its data; runs the node's psql program Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
mysql_user one account inside a MySQL or MariaDB server that is installed and running, with its password and its privileges; MMX runs the node's own client, mariadb or mysql Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
mysql_database one database inside a MySQL or MariaDB server that is installed and running; MMX runs the node's own client, mariadb or mysql Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10

Certificates

Module What it does Tested on
certbot_certificate one TLS certificate that certbot gets from an ACME certificate authority such as Let's Encrypt; certbot's own timer renews it, MMX never does; install certbot with a package task first; using this module accepts the terms of service of the certificate authority, as certbot's --agree-tos does Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9

Official extra modules

These modules are Starlark scripts that ship with MMX in official_extra_modules/ beside mmx. Each one's page is the README.md in its directory.

Module What it does Tested on
create_partitions_on_empty_disk Writes a GPT partition table with named partitions on a disk that holds nothing yet, with sfdisk; a disk that holds anything else fails the task, and nothing ever forces it. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
grow_filesystem_to_fill_device Grows a mounted ext4 or XFS filesystem to fill its block device, without shrinking, checking, repairing, or creating a filesystem. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
grow_partition_into_free_space_after_it Grows one existing partition into the free space after it through growpart, without changing its contents. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
incus_instance Manages one Incus container or virtual machine on the node: its profiles, its configuration, its devices, and whether it runs. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
incus_profile Manages one Incus profile on the node: its description, its configuration, and its devices. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
libvirt_domain Manages one libvirt domain, which is a virtual machine, through virsh. It defines the domain from an XML file on the node, starts it or shuts it off, and sets whether libvirt starts it when the node boots. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
lvm_logical_volume Manages one LVM logical volume, which a later run can grow together with its filesystem and never shrinks, with the programs of the package lvm2. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
lvm_volume_group Manages one LVM volume group and its physical volumes, with the programs of the package lvm2; it never wipes a device. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
mongodb_user Manages one user of a MongoDB server, with its password and its roles, through MongoDB's shell mongosh on the server's node. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
pacman_package Keeps packages installed or removed on an Arch Linux node through pacman, or upgrades the whole system. Arch Linux
pg_auto_failover_monitor Manages the pg_auto_failover monitor of a formation on the monitor's server, with its systemd unit, the password of its login autoctl_node, and which nodes belong to the formation. Debian 12 and 13, Ubuntu 24.04 and 26.04
pg_auto_failover_node Manages one PostgreSQL node of a pg_auto_failover formation on its database server, with its systemd unit, its failover settings, maintenance, and its PostgreSQL settings. Debian 12 and 13, Ubuntu 24.04 and 26.04
pg_auto_failover_primary Makes one node of a pg_auto_failover formation its primary with a planned switchover, on the monitor's server. Debian 12 and 13, Ubuntu 24.04 and 26.04
pgbackrest_restore Restores a PostgreSQL cluster with pgBackRest into an empty or missing data directory, to the end of the archive or to a chosen time, starts it, and waits until its recovery ends. Debian 12 and 13, Ubuntu 24.04 and 26.04
pgbackrest_stanza Manages one pgBackRest stanza in its repositories, which it creates when it is missing and upgrades after a major upgrade of PostgreSQL. Debian 12 and 13, Ubuntu 24.04 and 26.04
rabbitmq_plugin Enables or disables one plugin of RabbitMQ. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
rabbitmq_policy Manages one policy of a virtual host of a RabbitMQ server. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
rabbitmq_user Manages one user of a RabbitMQ server, with its password, its tags, and its permissions. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
rabbitmq_virtual_host Manages one virtual host of a RabbitMQ server. Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10
zfs_dataset Manages one ZFS filesystem dataset and its properties, with the zfs program; the pool must exist. Ubuntu 24.04 and 26.04, Debian 13, Rocky Linux 9, AlmaLinux 10
zypper_package Keeps packages installed at a version rule or removed on an openSUSE node through zypper, or updates the whole system. openSUSE Leap 16.1
zypper_repository Adds or removes one software repository, with its signing key, on an openSUSE node through zypper's repository files. openSUSE Leap 16.1

This page is docs/reference/modules/README.md in the MMX repository.