dnf_repository
dnf_repository adds a vendor's repository to a node that uses dnf: one
signing key, imported into rpm's key store, and one repository file with one
section. It can also switch on or off a repository that is already on the
node, such as CRB on Enterprise Linux 9. Put the task before the
dnf_package task that installs from the repository. On a
node that uses apt, apt_repository does the same.
- dnf_repository:
name: docker-ce-stable
description: Docker CE Stable
baseurl: ["https://download.docker.com/linux/rhel/$releasever/$basearch/stable"]
signing_key_source: files/docker-rpm-key.asc
- dnf_package:
packages:
- {name: docker-ce, version: newest_when_first_installed}
On the node, the task writes:
/etc/pki/rpm-gpg/RPM-GPG-KEY-docker-ce-stable
/etc/yum.repos.d/docker-ce-stable.repo:
[docker-ce-stable]
name=Docker CE Stable
baseurl=https://download.docker.com/linux/rhel/$releasever/$basearch/stable
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-docker-ce-stable
name is the repository id and the base name of the files: letters, digits,
_, -, and .. description is the line dnf shows for the repository
(dnf's own name). The inputs baseurl (a list), metalink, mirrorlist,
priority, includepkgs, and exclude are dnf's own. dnf's own variables
$releasever and $basearch pass through unchanged for dnf to fill in.
Inputs
name(string; required): the repository id; writes/etc/yum.repos.d/<name>.repoand/etc/pki/rpm-gpg/RPM-GPG-KEY-<name>; omit with existing_repositoryexisting_repository(string; optional): in place of name: a repository id the node already defines; the task then accepts only enabled, which dnf config-manager setsstate(presentorabsent; defaultpresent): absent removes the repository file, then the key file, and accepts only name and state; packages stay installeddescription(string; required): omit with absent or existing_repository; the line dnf shows for the repository (dnf's name)baseurl(list of strings; optional): exactly one of baseurl, metalink, or mirrorlist; dnf's $releasever and $basearch pass throughmetalink(string; optional)mirrorlist(string; optional)enabled(boolean; defaulttrue): false: only a dnf_package task that names the id in repositories_enabled_only_for_this_task uses the repositorypriority(integer; optional): 1 to 99; dnf's own fieldincludepkgs(list of strings; optional): dnf's own fieldexclude(list of strings; optional): dnf's own fieldsigning_key_source(string; optional): local signing key, relative to the project root, or to the role's directory inside a role; one of signing_key_source or signing_key_url; MMX imports it into rpm's key store, and the file always says gpgcheck=1signing_key_url(string; optional): HTTPS URL of the signing key, fetched and verified on the controller like downloadsigning_key_sha256(string; optional): the key's SHA-256 in hex; with signing_key_url, exactly one of signing_key_sha256 or dangerously_skip_checksumdangerously_skip_checksum(boolean; defaultfalse): true in place of signing_key_sha256: the key is trusted as it arrivesusername(string; optional): with password: the login for a private repository, written into the repository file, which is then root-only 0600password(string; optional): with username; must be a whole-value secret reference, or in a role one whole reference to an input declared secret: true
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.
statuschange
What a dryrun reports
Supported; previews the key and repository file, or reads whether the existing repository is switched on.
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
Add a vendor's repository
The first example above writes Docker's repository with a key from the
project. The signing key comes from exactly one of signing_key_source, or
signing_key_url with signing_key_sha256 (or
dangerously_skip_checksum: true), as on apt_repository:
- dnf_repository:
name: docker-ce-stable
description: Docker CE Stable
baseurl: ["https://download.docker.com/linux/rhel/$releasever/$basearch/stable"]
signing_key_url: https://download.docker.com/linux/rhel/gpg
signing_key_sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
The controller process fetches and verifies the key, as
files fetched from a web address
describes. On the node, MMX writes the key to
/etc/pki/rpm-gpg/RPM-GPG-KEY-docker-ce-stable, imports it into rpm's key
store, and writes /etc/yum.repos.d/docker-ce-stable.repo with one section
that always says gpgcheck=1.
A repository that only one task uses
- dnf_repository:
name: example-tools
description: Example tools
baseurl: ["https://repo.example.com/el/$releasever/$basearch/"]
signing_key_source: files/example-tools-rpm-key.asc
enabled: false
- dnf_package:
packages:
- {name: example-tool, version: newest_when_first_installed}
repositories_enabled_only_for_this_task: [example-tools]
enabled: false writes a repository that only a dnf_package task naming it
in repositories_enabled_only_for_this_task uses.
Switch a repository that is already on the node
Some repositories arrive switched off, as part of the distribution or of a package. CRB on Enterprise Linux 9, which EPEL needs, is the usual case:
- dnf_package:
packages:
- {name: epel-release, version: newest_when_first_installed}
- dnf_repository:
existing_repository: crb
enabled: true
existing_repository takes the place of name, and the task then accepts
only enabled, which is required. MMX reads the repository's state from dnf
and, when it differs, changes it through dnf's own config-manager command.
MMX never edits the file that defines the repository. With dnf 4,
config-manager is part of the package dnf-plugins-core; when it is
missing, the task says so.
A private repository
username and password give the login for a private repository, as on
apt_repository: they come
together, and password must be one whole reference to a secret, or, inside
a role, to a role input declared secret: true. The login is
written into the repository file, which is then root-owned 0600;
otherwise the file is 0644. A web address that contains a login is
rejected.
Remove a repository
- dnf_repository:
name: docker-ce-stable
state: absent
state: absent accepts only name and removes the repository file, then the
key file. Packages installed from the repository stay. A key that MMX
imported into rpm's key store is removed too, with rpm -e and the key's
gpg-pubkey name, because rpm's key store is trusted by every repository on
the node. MMX imports only keys that rpm did not hold already, and lists them
in /etc/pki/rpm-gpg/<name>.imported_key_ids. A key the node held before,
such as the distribution's own or EPEL's, stays when the repository goes.
A key that another file in /etc/pki/rpm-gpg also holds stays too, because
another repository still needs it; a repository whose key another repository imported lists it too, so the last repository to go removes it. When the signing key of a repository
changes, MMX imports the new key and then removes the keys it had imported
from the old file, under the same rules. Reading key ids needs gpg, from
the package gnupg2; a node without it fails the task before anything
changes. A run also imports a key file whose key rpm does not hold, for example
when rpm refused the key on an earlier try, so a retry does not leave the
repository without its key.
How it works
The files use the ordinary atomic file installer, key first. A change makes the next installation in the same node job refresh dnf's index.
A repository file with several sections, such as a vendor's file with debug
and source sections, is one task for each section, or the whole file as a
file task.
Errors and what they mean
- The node uses another package manager. The task fails and names the
module to use instead: on an apt node,
apt_repository. - An
existing_repositoryid that the node does not define. The task fails with the ids the node has. config-manageris missing. The task says that the packagednf-plugins-coreis needed (on dnf 5,dnf5-plugins). Install it in an earlierdnf_packagetask.- A web address that contains a login is rejected. Give the login in
usernameandpassword.
Tested on
Distributions: Rocky Linux 9, AlmaLinux 10, Fedora 45.
The suite server_resources.py covers package sources and runs on every
target distribution in the whole catalog: for dnf_repository, Rocky Linux
9 (dnf 4.14), AlmaLinux 10 (dnf 4.20), and Fedora 45 (dnf 5.4.7).
Why it works this way
- MMX imports the verified key into rpm's key store itself. Left alone,
dnf would download a repository's key and trust it without asking the
first time it installs from the repository; with MMX the key is the one
you committed or whose SHA-256 the task gives. The repository file always
says
gpgcheck=1. - MMX never edits the file that defines an existing repository. The package that owns the file rewrites it.
This page is docs/reference/modules/dnf_repository.md in the MMX repository.