apt_package
apt_package manages packages on a Debian or Ubuntu node through apt and
dpkg. A task keeps packages present or absent, keeps packages at a
version or inside a version pattern, brings named packages to the newest
version, installs a package that comes as a .deb file, or upgrades the
whole node.
- apt_package:
packages:
- {name: nginx, version: newest_when_first_installed}
- {name: certbot, version: newest_when_first_installed}
A task gives a packages list. Each present entry requires name and
version; each absent entry gives only name. One entry may use a version
pattern while another uses a keyword or a package file. Every check runs
before any version rule is written. MMX writes all rules before installing
all entries with one package-manager command, so list order does not matter.
A node that uses dnf gets dnf_package tasks
instead; a role for several distributions has one task for each package
manager, as one module for each
tool shows.
The rules that the two package modules share, such as "the package index is the module's business", are in
what every package manager module
does.
A vendor's package source comes from an
apt_repository task before the package task.
Inputs
packages(list of mappings; required): one entry per package: required name and version (omit version with state: absent); version is an exact version or a*pattern, or one of the keywords below; a keyword deletes only MMX's rule and leaves administrator rules. Each entry may set allow_downgrade, package_file_source or package_file_url with package_file_sha256 or dangerously_skip_checksum. A file entry gives its exact version, checked against the file. Write entry mappings directly in the task so controller files can be prepared; use references in individual fields. Omit packages with upgrade_all_packages_within_their_version_rules. newest_when_first_installed: installs the newest version when the package is missing, then never upgrades it; newest_on_every_run: also upgrades it to the newest version on every runstate(presentorabsent; defaultpresent)upgrade_all_packages_within_their_version_rules(boolean; defaultfalse): upgrades the whole node; every package stays inside MMX's and administrator version rulesalso_remove_packages_no_longer_needed(boolean; defaultfalse): with state: absent: apt --autoremove removes automatically installed packages nothing needs; with a whole-node upgrade: apt autoremove afterwardsalso_remove_packages_that_depend_on_these(boolean; defaultfalse): with state: absent: permits the package manager's simulation to remove packages the task does not namealso_delete_its_config_files(boolean; defaultfalse): with state: absent: apt purgeallow_package_to_start_its_services(boolean; defaultfalse): lets package scripts start stopped services; otherwise they can only restart running services
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.
statuschangevalue
What a dryrun reports
Supported; inspects installed versions without refreshing indexes; installations, upgrades and removals simulate against the current indexes; reports not_checked when those indexes cannot find a requested package.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
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
Choose each package's version
The version field has no default. Choose an exact version, a *
pattern, or a keyword for each entry; Package versions lists what
each does. Both keywords remove only the version rule MMX wrote for the
package, and administrator rules stay. The
required-settings rule
explains why each entry must state its version policy.
Install or remove packages
- apt_package:
packages:
- {name: nginx, version: newest_when_first_installed}
- {name: certbot, version: newest_when_first_installed}
On the node, MMX asks dpkg which listed packages are installed and runs apt only when a package must change, in one command. A package that is installed stays at its version: a rerun never upgrades by surprise.
- apt_package:
packages:
- {name: apache2}
state: absent
state: absent keeps configuration files and does not refresh the index.
MMX asks apt to simulate removal first. If apt would also remove packages
that the task does not name, the task fails before changing anything.
Add also_remove_packages_that_depend_on_these: true to permit removal of
packages outside the task's packages list. To restrict removal to an
explicit list, put every package apt would remove in packages and leave
also_remove_packages_that_depend_on_these off. A package already absent is
unchanged, also when only its configuration files remain. The result lists
each removal as
{name, from}. A dryrun asks apt to simulate removal and fails if apt would
remove an unlisted package without
also_remove_packages_that_depend_on_these: true.
Keep a package at a version
- apt_package:
packages:
- {name: docker-ce, version: "5:27.3.*"}
Each present entry requires version. A version rule is the exact
version text that apt shows (5:27.3.1-1~debian.12~bookworm), or a pattern
in which * stands for any text (5:27.3.*). * is the only pattern
character.
On the node, MMX installs the newest version that matches and writes a rule
for apt, /etc/apt/preferences.d/mmx-docker-ce.pref, so apt itself keeps
the package inside the pattern at all times: during MMX runs, during
upgrade_all_packages_within_their_version_rules: true, during the distribution's automatic security updates, and
when an administrator runs apt by hand. Updates inside the pattern still
arrive: with 5:27.3.*, a security fix 5:27.3.2 is installed by the next
upgrade, and 5:27.4.0 never is. A version outside the pattern is refused
by apt, whoever asks.
The task does not move an installed package to a newer version inside the
pattern; upgrade_all_packages_within_their_version_rules: true and automatic updates do that.
Changing the entry to newest_when_first_installed or
newest_on_every_run deletes MMX's rule.
newest_when_first_installed keeps the installed version; later upgrades
are free to move the package to another version. An apt_package task with
newest_on_every_run can upgrade the package during the task's execution.
Deleting the task from the project leaves both the rule and the package.
The version rule file says what the rule holds and
what each situation on the node leads to.
Use version: newest_on_every_run to follow the newest available version.
Bring named packages to the newest version
- apt_package:
packages:
- {name: ca-certificates, version: newest_on_every_run}
- {name: openssl, version: newest_on_every_run}
- {name: tzdata, version: newest_on_every_run}
version: newest_on_every_run installs each named package that is missing and
upgrades each named package to the newest version apt selects from the
node's package sources under the administrator's rules. MMX refreshes the
package index once per node job first. A node job is one attempt to execute
one fleet stage on one node. The task is unchanged when apt has
nothing newer. The newest_on_every_run task's result's value lists every
package changed by the command, including dependencies outside packages, as
{name, from, to}; a package that was missing has no from. The task
deletes MMX's version rule for each name. A dryrun does not refresh the index
and lists name, from, and to for packages that would change.
Packages with different needs can share the same packages list. A version rule that MMX
or the administrator wrote for another package still applies.
Upgrade the whole node
- apt_package:
upgrade_all_packages_within_their_version_rules: true
also_remove_packages_no_longer_needed: true
upgrade_all_packages_within_their_version_rules: true takes no other field except
also_remove_packages_no_longer_needed.
Preview this node task with mmx dryrun. On the node, apt simulates its
full-upgrade against the package index the node has now, without refreshing
it. The result's value lists each package it would upgrade, install, or
remove, with the fields name, from, and to. On a node whose index is
older than its package sources (apt's daily timer normally keeps it within a
day), the run can find more upgrades than the preview listed.
With mmx run, MMX refreshes the node's package index once per node job,
then runs apt's full-upgrade without prompts, keeping configuration files
that were changed on the node. apt may install packages that the upgrade
needs (a new kernel, say) and remove packages it must remove to complete the
upgrade. Version rules are honoured: a package with a version task stays
inside its pattern, and so does a package that the administrator holds with
apt-mark hold or with a preferences file of their own.
With also_remove_packages_no_longer_needed: true, MMX then runs apt's
autoremove, which removes automatically installed packages that nothing
needs any more, such as old kernels. Without it, MMX removes none of them.
The task is unchanged when nothing is upgradable and nothing is to be
removed. Otherwise its result's value lists the packages that change as
{name, from, to}: an upgraded package has both versions, a newly installed
one has no from, and a removed one has no to.
A package's scripts may restart a running service during the upgrade, as
packages do not start their services
allows, so running services load the upgraded software. A node task block
that declares an upgraded package restarts its service once at its next
activation, because the installed version differs from the one its service
record holds. A patching playbook therefore upgrades, then applies the roles
whose services must load the upgraded software, then reboots where a new
kernel requires it. Roll it out with the fleet stage's concurrency and
failure settings (execution). The
reboot page has a
one-node-at-a-time patch-and-reboot example.
Apply only security updates on Debian and Ubuntu
apt has no option to select only security updates, so apt_package has no
only_security_updates input. The distribution's own tool
unattended-upgrade applies security updates on the node. The
security-updates-on-debian-and-ubuntu example
sets up the distribution's daily timers and applies updates on demand with
shell, including the tool's own dryrun. On a dnf node,
dnf_package has only_security_updates.
Install a package from a .deb file
Some vendors publish a .deb file and no package source:
- apt_package:
packages:
- {name: rclone, version: "1.68.2", package_file_url: https://downloads.rclone.org/v1.68.2/rclone-v1.68.2-linux-amd64.deb, package_file_sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}
Each file entry gives its name, the exact version inside the file, and
exactly one of:
package_file_urlwithpackage_file_sha256(ordangerously_skip_checksum: true, which installs the file as it arrives): the controller machine fetches the file once per run and verifies it, as files fetched from a web address describes.package_file_source: a.debin the project, found the wayfile.sourcefinds one.
On the node, MMX reads the package name and version from the file and fails
when the file holds another name or version than the entry states. The task is
unchanged when that version is installed. Otherwise apt installs the file
and takes the packages it depends on from the node's package sources. MMX
also writes the version rule for the file's
version, so a package source that offers another version of the same package
does not replace the one the project installs. To move to another version,
point the task at another file. An installed version newer than the file's
is an error unless the task says allow_downgrade: true.
A file for one processor architecture gets a condition:
- when:
equals: ["{{ .node.arch }}", amd64]
apt_package:
packages:
- {name: rclone, version: "1.68.2", package_file_url: https://downloads.rclone.org/v1.68.2/rclone-v1.68.2-linux-amd64.deb, package_file_sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}
- when:
equals: ["{{ .node.arch }}", arm64]
apt_package:
packages:
- {name: rclone, version: "1.68.2", package_file_url: https://downloads.rclone.org/v1.68.2/rclone-v1.68.2-linux-arm64.deb, package_file_sha256: "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"}
A dryrun compares the file's version with the installed one and installs nothing.
Remove a package completely
- apt_package:
packages:
- {name: newrelic-sysmond}
state: absent
also_delete_its_config_files: true
also_remove_packages_no_longer_needed: true
also_remove_packages_that_depend_on_these: true
also_delete_its_config_files and also_remove_packages_no_longer_needed
are off unless the task sets the fields to true. Purge requires
state: absent; autoremove also works after a whole-node upgrade.
also_delete_its_config_files: trueuses apt's purge. A package that was removed earlier and whose configuration files remain is then not yet absent: the task purges it.also_remove_packages_no_longer_needed: truepasses apt's own--autoremove. apt decides what goes: the automatically installed packages that nothing needs once the named packages are gone. Autoremove includes a package that was already unneeded before theapt_packagetask. MMX does not work out dependencies itself.
The result's value lists every removed package as {name, from}. A dryrun
lists what apt's simulation would remove.
Install a package, write its configuration, then start its service
On Debian and Ubuntu, a package's installation scripts normally start the
package's services at once, with the packaged configuration, before the role
has written its own. apt_package stops that, so a service starts only when
a systemd_service task says state: running. The
usual order in a node task block is therefore: install the package and write
its configuration in changes, and start the service in activate.
- task_block:
id: loki
changes:
- apt_package:
packages:
- {name: loki, version: newest_when_first_installed}
- file:
permissions_mode: "0644"
path: /etc/loki/config.yml
source: files/loki-config.yml
activate:
- systemd_service:
name: loki
state: running
start_at_boot: true
On the node, the apt_package task installs Loki without starting it, the
file task writes its configuration, and the systemd_service task in
activate starts the service with that configuration.
allow_package_to_start_its_services: true runs one task's apt command
without this rule, for a package whose installation fails or is incomplete
unless its service starts.
How it works
Installation and the package index
With packages[].name and state: present, MMX inspects each name with dpkg. Before a
required installation it refreshes the package index once per node job and
installs the missing names in one apt command. A changed file or link under
/etc/apt/ in the same node job, such as a new source from an
apt_repository task, makes the next installation
refresh again, so the new source is found. MMX also compares the contents of
the node's package sources, signing keys, and logins under /etc/apt/
(sources.list, sources.list.d/, trusted.gpg, trusted.gpg.d/,
keyrings/, and auth.conf.d/) with those at the last refresh, and
refreshes again when they differ. A source that a vendor's release package
or a shell node task adds is therefore found by the next installation.
A dryrun refreshes no index and writes no source file. When the current
indexes cannot find a requested package, the installation reports
not_checked, with apt's reason. This also applies when an earlier node
task would add the source: that source is only previewed during a dryrun.
A real run refreshes the indexes first and fails if the package is still
missing. Version rules and packages stay unchanged on that refusal.
apt waits up to 60 seconds for the dpkg lock, such as while the daily update
that a fresh server runs at first boot is still busy. MMX tries the index
refresh again for up to 60 seconds while another apt holds the lock on the
package lists. dpkg keeps a configuration file that was changed on the node
instead of prompting; a file node task owns that file's contents when MMX
should own them. A package that dpkg left unpacked but not configured, after
an interrupted installation, is configured.
The version rule file
MMX carries a version out with apt's own mechanism, a preferences file. It
writes one file for the package:
/etc/apt/preferences.d/mmx-docker-ce.pref:
Explanation: Written by MMX for an apt_package task with a version.
Package: docker-ce
Pin: version 5:27.3.*
Pin-Priority: 999
Explanation: Versions outside the pattern are never installed.
Package: docker-ce
Pin: version *
Pin-Priority: -1
The file's name is mmx-<package>.pref. apt reads a preferences file only
when its name has letters, digits, -, _, and ., so MMX writes each
other character of a package name as _ and its two-digit hexadecimal code:
mmx-g_2b_2b.pref for g++. Preferences files that MMX did not write are
left alone and still apply.
The task is unchanged when the file has the right contents and the installed
version matches the pattern. Matching the pattern is a text comparison.
Whether one version is newer than another is dpkg's answer
(dpkg --compare-versions).
MMX checks before it writes anything, so a refused task changes nothing:
| Situation on the node | What the task does |
|---|---|
| The package is not installed. | Refreshes the index, writes the file, and installs the newest version that matches. An interrupted run leaves the file; the next run installs. |
| The installed version matches. | Writes the file if it differs. The package is not touched. |
| The installed version does not match, and the newest matching version is newer. | Writes the file, then upgrades to the newest matching version. |
| The installed version does not match, and the newest matching version is older. | Fails and writes nothing, with the installed version and the newest matching version in the message. With allow_downgrade: true: writes the file, then installs the older version. |
| No version in the node's package sources matches. | Fails and writes nothing. The message lists the versions that are available. |
Changing what the project asks for:
| Change in the project | Effect on the node at the next run |
|---|---|
version is changed to a newer series. |
The file is rewritten and the package upgraded. |
version is changed to an older series. |
Needs allow_downgrade: true, as above. |
version is changed to newest_when_first_installed. |
MMX deletes its file. The installed version stays; later upgrades are free to move it. |
| The task is deleted from the project. | Nothing. The file and the package stay. |
The task says state: absent. |
The package is removed, then MMX deletes its file. |
A dryrun shows the preferences file as a file change and the version it would install or remove. It judges against the index the node has now; when that index holds no matching version, it reports the task as not checked, because a run refreshes the index first.
Package files
The bytes of a package file, from package_file_url or
package_file_source, are frozen with the run and travel to the node as a
streamed asset. MMX deletes its copy of the file on the node after apt has
installed it. apt does not check a signature on a package file that it
installs by path; the SHA-256 in the task is what establishes that the bytes
are the publisher's.
Packages do not start their services
The rule for every apt command that apt_package runs:
- A package's scripts may restart a service that is running. An upgrade therefore still puts upgraded software into the services that are up, as apt does by itself.
- A package's scripts may not start a service that is not running.
MMX uses Debian's own switch for this, the policy program
/usr/sbin/policy-rc.d, which the package scripts ask before each service
action. Before the apt command, MMX puts its policy program there; after the
command, MMX removes it. The program's second line, after #!/bin/sh,
marks it as written by MMX. A leftover from an interrupted run is removed by the next apt_package
task and at the start of every node job that may change the node. When the
node already has a policy-rc.d that MMX did not write, MMX leaves it in
place, that program decides, and the task's result says so.
A package may still enable its service for the next boot. A
systemd_service task with start_at_boot states what the project wants.
Errors and what they mean
- The node uses another package manager. The task fails with a reason
that says to give the node task a condition so that it runs only on nodes
that use apt, such as
apt_package installs with apt, but this node's package manager is dnf (the node fact package_manager); give the node task a condition so that it runs only on nodes that use apt. - The current indexes cannot find a requested package. A dryrun reports
not_checked, because an earlier task may only preview the package source. A run refreshes first and fails with apt's reason if the package is still missing. Other simulation failures, such as unsatisfied dependencies, still fail the dryrun. - No version in the node's package sources matches
version. A run fails, writes nothing, and lists the versions that are available. Correct the pattern, or add the package source that offers the version. - The installed version is newer than every version that matches. The
task fails, writes nothing, and names both versions. Add
allow_downgrade: truewhen the older version is wanted. - One node job names the same package with a version rule in one task and a version keyword in another. The two tasks would undo each other on every run. MMX rejects that at validation when it can see both names, and otherwise fails the second task before it changes anything. Keep one rule for each package in a fleet stage.
- A package file holds another package than the task names. The task
fails. Correct the entry's
name, or point the task at the right file. - The installed version is newer than the package file's. The task
fails unless it says
allow_downgrade: true. - A source that apt cannot use fails the index refresh, and apt's message names the source.
- The node stopped inside dpkg during an upgrade, such as when it lost
power. The next attempt fails with apt's instruction to run
dpkg --configure -a, and MMX does not retry it, because a retry cannot fix it. The reason starts "Run dpkg --configure -a on the node first". Run that command on the node, then run the playbook again ormmx resume.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04.
The suite server_resources.py covers pinned package versions, package
sources, and a whole-node upgrade, and runs on Debian 12 and 13 and Ubuntu 24.04 and 26.04 in
the whole catalog. apt_package runs on these, with the apt version that the
test harness records:
| Distribution | apt |
|---|---|
| Debian 12 | 2.6 |
| Debian 13 | 3.0 |
| Ubuntu 24.04 | 2.8 |
| Ubuntu 26.04 | 3.2 |
The security updates example
passed server_resources.py on Debian 13.
Why it works this way
-
The preview includes every entry and the proposed version rules. A package file can satisfy another entry's dependency. Checking the complete transaction before writing rules prevents partial changes on refusal.
-
also_remove_packages_no_longer_needednames apt's actual scope. apt's autoremove can delete packages that were already unneeded before theapt_packagetask. The name makes removal of already unneeded packages visible. -
One list, one transaction. Dependencies may require several packages at matching versions. Writing all rules first and installing together makes entry order irrelevant.
-
An unknown package in a dryrun is not checked. Earlier node tasks may only preview the source that supplies the unknown package. A real run refreshes the indexes before deciding that a package is missing. A dryrun keeps uncertainty about the package's availability visible without changing the node.
-
Every present entry states its version policy. Presence alone cannot say whether an installed package should upgrade. See the required-settings rule.
-
Removal checks the package manager's simulation first. An unnamed removal needs
also_remove_packages_that_depend_on_these: true, so the task states its wider effect. See protective choices. -
Package entry mappings are written in the task. Controller files must be prepared while the project loads. Whole-list and whole-entry references would leave those files unavailable on the node; references in individual fields remain supported.
-
The result includes dependency changes. A native transaction can change packages outside the task's list. Reporting those changes makes the full effect visible.
-
A file entry states its exact version. Checking the file's name and version before writing any rule catches a mismatched artifact before the transaction changes packages.
-
Version keywords remove only MMX's rules. An administrator's rule remains under the administrator's control. Candidate selection keeps administrator rules when MMX removes its own rule.
-
A
versionis kept by apt's own rule, a preferences file. A version that MMX alone enforced would be undone by every other upgrade on the node: an administrator's apt command,upgrade_all_packages_within_their_version_rules: true, and the distribution's automatic updates. -
A package's scripts may restart a running service and may not start a stopped one, unless the task says
allow_package_to_start_its_services: true. A service then starts only where the project says so, on every distribution, and an upgrade still reaches running services. A node then behaves the same on Debian and on the Red Hat family, whose packages do not start their services. -
MMX retries the index refresh while another apt holds the lock on the package lists.
apt-get updatedoes not wait for that lock itself, and apt's daily timer holds it just after a first boot. -
Two tasks for one package, one with a version rule and one with a keyword, are refused. Each would undo the other on every run.
-
A package file needs a SHA-256 in the task. apt checks no signature on a file it installs by path.
-
No
only_security_updates. apt has no option that selects only security updates; the distribution'sunattended-upgradedoes that. -
No field for answers to a package's installation questions. A
shelltask that runsdebconf-set-selectionsbefore the package task, withskip_if_this_command_succeeds: dpkg -s <package>, gives them.
This page is docs/reference/modules/apt_package.md in the MMX repository.