pacman_package
pacman_package manages packages on an Arch Linux node through pacman,
Arch Linux's package manager; a node is a Linux server that MMX manages. A
task keeps packages installed or removed, or upgrades the whole system.
- pacman_package:
packages: [nginx, certbot]
pacman has one rule that shapes the module: Arch Linux supports no
partial upgrade. The package databases, pacman's lists of what the
package servers offer, and the installed packages must come from the same
moment. A package installed from newer databases than the rest of the
system can need a library version that the system does not have yet.
pacman's own answer is the full system upgrade, pacman -Syu, so:
- Every installation is a full system upgrade. A task that installs a
missing package refreshes the package databases and upgrades every
package in the same transaction, as
pacman -Syu nginxdoes. A task whose packages are all installed changes nothing and contacts no package server. - A package has no version setting. Arch Linux's repositories offer one
version of each package, the newest. A package cannot be kept at an older
version or brought to the newest version by itself.
upgrade_all_packages: truebrings every package to the newest version.
pacman_package follows the
rules that every package module follows,
except where pacman's own rules
differ.
pacman_package is an official extra module: a script in Starlark, a
small language with Python-like syntax, that the MMX project writes, tests,
and ships beside mmx.
Set up
The module installs nothing. pacman is part of every Arch Linux system.
A project with nodes of several distributions gives each package task a
condition on the node fact package_manager, which is pacman on Arch
Linux. Each node task below, one entry of a playbook's node_tasks,
installs nginx on the nodes of one package manager:
- when:
equals: ["{{ .node.package_manager }}", pacman]
pacman_package:
packages: [nginx]
- when:
equals: ["{{ .node.package_manager }}", apt]
apt_package:
packages:
- {name: nginx, version: newest_when_first_installed}
Inputs
| Input | Meaning | When omitted |
|---|---|---|
packages |
The names of the packages, as pacman -Q shows them, such as nginx: letters, digits, and @ . _ + -. Name each package itself: a group, such as gnome, or a name that another package provides, such as sh, fails the task, also with state: absent. |
Required, unless upgrade_all_packages is true. |
state |
present installs each package that is missing, with a full system upgrade. absent removes each package that is installed. |
present. |
also_remove_packages_that_depend_on_these |
With state: absent, true also removes the installed packages that depend on the named ones. |
A removal that would take other packages with it fails before anything changes. |
upgrade_all_packages |
true refreshes the package databases and upgrades every package that has a newer version, as pacman -Syu does. Takes no other input. |
No whole-system upgrade. |
Outputs
| Output | Holds |
|---|---|
changed_packages |
Every package that the task changed, sorted by name: name, from (the version before), and to (the version after). A package that the task installed has no from; a package that it removed has no to. The list includes the dependencies and the upgrades that pacman's transaction brought, not only the named packages. An unchanged task gives an empty list. |
The task's reason says the same in words, such as installed mailcap 2.1.54-3, nginx 1.30.6-3; upgraded glibc from 2.44-1 to 2.44-2. The
reason lists at most ten packages of each kind and counts the rest;
changed_packages lists every one.
What a dryrun reports
A dryrun reads the installed packages with pacman -Q and asks pacman
what a transaction would do with --print, which changes nothing, takes no
lock, and refreshes no package database.
- An installation:
would_change, with the packages that pacman would install or upgrade, judged against the package databases that the node has now. A run refreshes the databases first, so it can upgrade more packages than the dryrun listed.--printchecks no conflict between packages: a package that conflicts with an installed one shows as an installation, and the run fails with the conflict. - A removal:
would_change, with the packages that pacman would remove. A removal that would take packages outsidepackagesfails, as in a run, unlessalso_remove_packages_that_depend_on_theseistrue. - A whole-system upgrade: the packages that are newer in the databases
the node has now;
unchangedwhen the databases have nothing newer. not_checkedfor a package that the node's databases do not have: a run refreshes the databases first, and an earlier node task may add the repository that has the package.not_checkedalso on a node without pacman.- A failure, as in a run, for a group's name or a name that another package provides, to install or to remove, and for the inputs that break a rule.
- What the dryrun leaves on the node: nothing.
Examples
Install nginx and certbot, then start nginx with its configuration:
- task_block:
id: nginx
changes:
- pacman_package:
packages: [nginx, certbot]
- file:
path: /etc/nginx/nginx.conf
source: files/nginx.conf
permissions_mode: "0644"
activate:
- systemd_service:
name: nginx
state: running
start_at_boot: true
On the node, the pacman_package task installs the two packages and
upgrades the system with them, in one transaction; Arch Linux's packages
start no service. The file task writes the configuration, and the
systemd_service task starts nginx. At a later run, the
pacman_package task is unchanged. When a whole-system upgrade, in this
playbook or another, has brought a new nginx version since, the
systemd_service task restarts nginx once, because the node task block
tracks the installed versions of the packages that its tasks name.
Remove Apache and the modules that depend on it:
- pacman_package:
packages: [apache]
state: absent
also_remove_packages_that_depend_on_these: true
Upgrade the whole system:
- pacman_package:
upgrade_all_packages: true
How it works
Installing. The module reads the installed packages with pacman -Q.
When every package is installed, the task is unchanged. Otherwise the
module asks pacman for the whole transaction with pacman -Sup --needed <missing packages> --print, against the databases the node has, and
checks that each missing name is a package of its own. Then it waits for
pacman's lock, refreshes the package databases (pacman -Sy), asks again,
and installs with pacman -Su --needed --noconfirm <missing packages>. The
refresh and the upgrade together are pacman -Syu, in two steps so that a
wrong name fails before anything changes. A name that only the refreshed
databases know is checked after the refresh. At the end the module reads
pacman -Q again and reports every version that differs.
--print resolves names and dependencies and checks nothing else. pacman
finds a conflict between packages only when the transaction runs, and
fails before it changes a package. A name in IgnorePkg is installed,
because --noconfirm answers pacman's "install anyway?" with yes. A
package that replaces an installed one, by its Replaces field, may be
missing from a dryrun's list; the run's changed_packages shows it.
Removing. A name that is not installed under its own name, but is a
group with installed members (pacman -Qg) or a name that an installed
package provides (pacman -T), fails the task: pacman would remove other
packages under other names. The module asks pacman with pacman -Rcp which packages a
removal would take, including those that depend on the named ones. Without
also_remove_packages_that_depend_on_these, a removal that would take more
than the named packages fails here. Otherwise the module removes with
pacman -R, and with -c when other packages go too. pacman removes a
package's files; a configuration file that was changed on the node stays
as a .pacsave file beside the old name. The module does not remove the
dependencies that nothing needs any more; pacman -Qdt lists them.
Upgrading the whole system. The module waits for pacman's lock,
refreshes the package databases, and asks pacman with pacman -Sup what
is newer. With nothing newer, the task is unchanged. Otherwise the module
upgrades with pacman -Su --noconfirm. pacman skips each package that
IgnorePkg or IgnoreGroup in /etc/pacman.conf names, and says so in a
warning.
pacman's lock. pacman holds the file /var/lib/pacman/db.lck while it
changes packages or refreshes its databases, and refuses to start while
the file exists. Before each such command, the module waits up to 60
seconds for the file to go, such as while a person or a timer runs pacman.
Reading and --print take no lock.
Nothing prompts. pacman runs with --noconfirm, which takes the
default answer of each question. A configuration file that was changed on
the node stays, and pacman writes the package's new version beside it as a
.pacnew file. A file node task owns a configuration file's contents.
A service restarts when its package changes. Inside a
node task block,
the version of each package that the task names, or absent, is a
tracked input: MMX remembers it with the service's record, and a
systemd_service task in the block's activate section restarts the
service when the version differs from the one that the service last
loaded. A dryrun predicts the restart from the versions that pacman would
install.
Errors and what they mean
Every reason starts with pacman_package.
| The reason holds | What it means, and what to do |
|---|---|
the program pacman is not installed; pacman_package works only on a node whose package manager is pacman ... |
The node is not an Arch Linux node. A run fails without another try. Give the node task a condition on the node fact package_manager, as Set up shows. |
pacman_package.packages: pacman's package databases have no package NAME ... |
Also after a refresh, no repository of the node has the package. A run fails without another try and changes no package. Correct the name; pacman -Ss searches the databases. A package from a repository of your own needs the repository in /etc/pacman.conf, from an earlier node task. |
pacman_package.packages: NAME is a group or a name that another package provides, not a package of its own; ... |
pacman would install other packages under other names, or none because a package that provides the name is installed, and the task would try again on every run. Name the packages themselves; the reason lists those that pacman would install. |
removing NAME would also remove ..., which depend on them; ... |
Other installed packages need the named ones. Nothing changed. Add those packages to packages, or add also_remove_packages_that_depend_on_these: true. |
another pacman has held its lock /var/lib/pacman/db.lck for 60 seconds; ... |
Another pacman runs, or a pacman that was stopped left its lock file. MMX tries the task again. When pgrep -x pacman finds no pacman on the node, remove the file. |
refreshing the package databases: ... |
pacman -Sy failed, such as when no package server answers. The text behind the colon is pacman's message. MMX tries the task again. |
installing NAME: A and B are in conflict; unresolvable package conflicts detected; ... |
The package to install and an installed package cannot be installed together, such as nginx-mainline and nginx. No package changed. Remove the installed package first, with a pacman_package task with state: absent before this task. A dryrun does not see the conflict. |
installing NAME: ..., removing NAME: ..., upgrading all packages: ... |
pacman's transaction failed; the text behind the colon is pacman's message. MMX tries the task again. A HoldPkg was found in target list message means that HoldPkg in /etc/pacman.conf protects a package that the removal would take, such as glibc. invalid or corrupted package (PGP signature) on a node that was not upgraded for months means that the keys of the Arch Linux packagers are older than the packages; see the next row. |
invalid or corrupted package (PGP signature) |
The node's copy of the Arch Linux packagers' keys is older than the packages. Run the two node tasks below once, as a playbook of their own. |
... ended, and then reading the installed packages failed: ... |
pacman's command worked, and the read after it failed. MMX does not try the task again, because a new try would find the packages installed and report an unchanged task. Run the playbook again. |
After a failed transaction, and after a name that only a refresh showed to
be unknown, the node's package databases are newer than its installed
packages: the state that Arch Linux calls a partial upgrade, without
having installed anything. The next pacman_package installation or
whole-system upgrade brings both together. Until then, install nothing
with pacman -S by hand; use pacman -Syu.
Update the packagers' keys first
On a node that was not upgraded for months, run these node tasks once, in
a playbook of their own. The shell task updates only the package of the
packagers' keys, archlinux-keyring, which is the one package that Arch
Linux updates alone; the pacman_package task then upgrades the rest.
- shell:
script: pacman -Sy --needed --noconfirm archlinux-keyring
- pacman_package:
upgrade_all_packages: true
Tested on
Distributions: Arch Linux.
The integration suite tests/integration/pacman_packages.py runs the
module on an Arch Linux test node of the current rolling release, with
pacman 7.1.
Limits on each distribution says what is limited for this module on Arch Linux, and why.
Why it works this way
- Every installation is a full system upgrade. Arch Linux supports no
partial upgrade: a package from newer databases than the rest of the
system can need newer libraries than the system has.
pacman -Syu <package>is Arch Linux's own way to install. - No version setting. Arch Linux's repositories offer only the newest
version of each package, and pacman has no rule that keeps a package
inside a version pattern. pacman's
IgnorePkgkeeps a package back during an upgrade, which is a partial upgrade; an administrator who chooses it writes it into/etc/pacman.conf, such as with alinetask, and the module's upgrades keep to it. packagesis a list of names, not of entries with a version. With no version setting, an entry would hold only a name.- The module checks the names before it refreshes, and the transaction
again after. A group's name or a provided name fails before the
databases change; a name that no repository has fails before any package
changes.
--printchecks no conflict, so a conflict shows only in the run. A refresh changes no package, so a whole-system upgrade with nothing newer is unchanged. - A removal that takes other packages states so. pacman refuses to
remove a package that others need, unless it removes them too (
-c); the task says which, as every package module does. - A group's name, or a name that another package provides, fails the task. pacman installs and removes such a name under other names, so an installation would find the name missing and install again on every run, and a removal would remove nothing and report the task unchanged.
- The module waits for pacman's lock and then fails. A pacman that runs ends; a lock file that stays after 60 seconds is most often left by a pacman that was stopped, and only a person can tell that no pacman runs.
- No input for the dependencies that nothing needs any more. A removal
leaves them, as
apt_packagewithoutalso_remove_packages_no_longer_neededdoes;pacman -Qdtlists them, and apacman_packagetask withstate: absentremoves the ones you name.
This page is official_extra_modules/pacman_package/README.md in the MMX repository.