zypper_repository
zypper_repository adds or removes one software repository on an openSUSE
node: the repository's file in /etc/zypp/repos.d and its signing key,
which the task gives explicitly. A node is a Linux server that MMX manages.
Put the task before the zypper_package task
that installs the vendor's packages.
- zypper_repository:
name: vendor
url: https://download.example.org/leap/16.1/
repository_metadata_is_signed: true
signing_key_url: https://download.example.org/key.asc
signing_key_sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
- zypper_package:
packages:
- {name: vendor-tool, version: newest_when_first_installed}
zypper_repository 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. It follows the same rules as
apt_repository where the concept is
the same: the signing key is part of the task, and the module never trusts a
key that the task did not name. The rules that differ are in
zypper's own rules.
Set up
The module installs nothing. zypper, rpm, and gpg2 (which zypper needs) are
part of every openSUSE system. A project with nodes of several distributions
gives the task a condition on the node fact package_manager, which is
zypper on openSUSE:
- when:
equals: ["{{ .node.package_manager }}", zypper]
zypper_repository:
name: vendor
url: https://download.example.org/leap/16.1/
repository_metadata_is_signed: true
signing_key_text: "{{ .vars.vendor_signing_key }}"
Inputs
| Input | Meaning | When omitted |
|---|---|---|
name |
A name you choose: letters, digits, and _ - .. It is the repository's alias for zypper and the base name of /etc/zypp/repos.d/NAME.repo and /etc/zypp/mmx_repository_keys/NAME.asc. |
Required. |
state |
present writes the key, imports it into rpm, and writes the repository file. absent removes the repository with its cache, the key from rpm, and the key file, and accepts only name and state. Packages that came from the repository stay installed. |
present. |
url |
The address of the repository, which holds the directory repodata. Starts with https:// or http://; with repository_metadata_is_signed: false, only https://, because nothing else then stops someone on the network from serving an old list of packages that keeps back security updates. |
Required with state: present. |
repository_metadata_is_signed |
true when the repository signs its metadata (repodata/repomd.xml.asc exists beside repomd.xml): zypper then checks the signature. false for a repository that does not sign its metadata, which zypper then cannot check. Packages are always checked. |
Required with state: present: only the repository's vendor knows. |
signing_key_text |
The public signing key as ASCII-armored text, usually a reference to a variable. | Exactly one of signing_key_text or signing_key_url is required with state: present. |
signing_key_url |
An https:// address of the ASCII-armored key. The node fetches it, and checks its SHA-256 first. |
See above. |
signing_key_sha256 |
The key's SHA-256 as 64 hexadecimal characters. | With signing_key_url, exactly one of signing_key_sha256 or dangerously_skip_checksum. |
dangerously_skip_checksum |
true in place of signing_key_sha256: the key is trusted as it arrives from the web address. |
false. |
A key from a file on the controller machine goes in as text: put the
file's content in a variable, or write the file to the node with a file
task first and give the task signing_key_url. MMX's Starlark modules
cannot read a controller machine's file by themselves.
Outputs
| Output | Holds |
|---|---|
created |
true when this task created the repository file, and in a dryrun when a run would. |
What a dryrun reports
A dryrun fetches the key from signing_key_url and checks its SHA-256, reads
the repository file and the keys in rpm, and reports what a run would write:
- A new repository:
would_change:would import the signing key ...; would add the repository NAME at URL. - A repository that differs, such as another address or another value of
repository_metadata_is_signed:would_change,would change the repository NAME, with the file's difference in--diff. - A repository that is as the task wants it:
unchanged. - A removal: the repository, key, and key file that are there.
- A failure, as in a run, for the inputs that break a rule, a checksum that does not match, and a key that is no OpenPGP key.
- What the dryrun leaves on the node: nothing, except gpg's own files in
/etc/zypp/mmx_repository_keys/gnupg_home, where gpg reads the key's identity once that directory exists. On a first dryrun that directory is not there, and the dryrun sayswould import the signing key for the repository NAMEwithout the key's identity.
Examples
Add a vendor's repository with a key from a web address, then install from it:
- zypper_repository:
name: vendor
url: https://download.example.org/leap/16.1/
repository_metadata_is_signed: true
signing_key_url: https://download.example.org/key.asc
# Replace with the SHA-256 of the key you have verified.
signing_key_sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
- zypper_package:
packages:
- {name: vendor-tool, version: newest_when_first_installed}
On the node, the zypper_repository task fetches the key and checks its
SHA-256, writes it to /etc/zypp/mmx_repository_keys/vendor.asc, imports it
into rpm's keyring, and writes /etc/zypp/repos.d/vendor.repo. The
zypper_package task then refreshes the repositories, because it has work,
and installs vendor-tool.
Remove a repository:
- zypper_repository:
name: vendor
state: absent
How it works
Adding. The module makes /etc/zypp/mmx_repository_keys, writes the
key, reads its identity with gpg --show-keys, and, when rpm's keyring does
not hold the key, imports it with rpm --import. Then it writes the
repository file with every setting spelled out:
/etc/zypp/repos.d/vendor.repo:
[vendor]
name=vendor
enabled=1
autorefresh=1
baseurl=https://download.example.org/leap/16.1/
type=rpm-md
gpgcheck=1
repo_gpgcheck=1
pkg_gpgcheck=1
gpgkey=file:///etc/zypp/mmx_repository_keys/vendor.asc
The key goes into rpm's keyring before the repository file, so zypper
never asks whether to trust a new key. A non-interactive zypper answers that
question no, and zypper refresh then ends with exit code 4 and the text
New repository or package signing key received. rpm's keyring is shared by
every repository and every package of the node, so a key that rpm holds can
sign any repository.
Removing. The module removes the repository with zypper removerepo,
which also removes the repository's cache; removes the keys that it imported
for the repository from rpm (rpm -e gpg-pubkey-ID); and removes the key
file and the record of the imported keys. The module records the ids of the
keys that it actually imported in /etc/zypp/mmx_repository_keys/NAME.imported_key_ids.
It removes only those, and only when no other repository's key file in
/etc/zypp/mmx_repository_keys holds them. So a key that rpm held before the
task, such as one of openSUSE's own that the task gave again, never leaves
rpm, and a key that two repositories share leaves rpm with the last of them.
When a task gives another key for an existing repository, the module imports
the new key and then removes the old one under the same rule. The module does
not remove packages.
The repository is refreshed by the next package task. The module does
not refresh. A zypper_package task that has work refreshes the
repositories first, in a run, and so finds the new repository's packages.
Errors and what they mean
Every reason starts with zypper_repository.
| The reason holds | What it means, and what to do |
|---|---|
the program zypper is not installed; zypper_repository works only on a node whose package manager is zypper ... |
The node is not an openSUSE node. A run fails without another try. Give the node task a condition on the node fact package_manager. |
the program gpg is not installed; install the package gpg2 in an earlier node task |
gpg2 is missing, which is rare on openSUSE. Install it with a zypper_package task. |
signing_key_sha256: is not the SHA-256 of the key at signing_key_url, which is ... |
The key at the address differs from the one you verified. A run fails without another try. Check the key, and then change the checksum in the task. |
signing_key_text: is not an ASCII-armored OpenPGP public key ..., signing_key_text: is not usable: ... |
The text is not an armored public key. Use the file that ends in .asc; a binary .gpg file is not accepted. |
fetching the signing key: ... |
The web address did not answer, or answered with another HTTP status than 200. MMX tries the task again. |
importing the signing key into rpm: ... |
rpm --import failed; the text behind the colon is rpm's message. MMX tries the task again. |
reading the keys of the other repositories: ... |
find or gpg could not read a key file in /etc/zypp/mmx_repository_keys. MMX tries the task again. |
removing the repository NAME: ... |
zypper removerepo failed, such as when another zypper holds its lock. MMX tries the task again. |
Tested on
Distributions: openSUSE Leap 16.1.
The integration suite tests/integration/zypper_packages.py runs the module
on an openSUSE Leap 16.1 test node with zypper 1.14, with a signed test
repository that the suite serves on the node and a key that the suite
fetches from openSUSE's build service over HTTPS.
Why it works this way
- The key is part of the task. A repository whose key zypper would trust
on first use gives an attacker who controls the repository's address the
key to everything it serves. As in
apt_repository, the task names the key, and a key from a web address needs its checksum. repository_metadata_is_signedis required. Vendors differ: many sign their packages and not the metadata. zypper cannot guess which, and a guess oftruefails the refresh while a guess offalseskips a check silently. Package signatures are always checked; the module offers no input that turns them off.- The key goes into rpm, not only into the repository file. zypper
asks to trust a key named in
gpgkey=, and a non-interactive zypper answers no. Importing it is the explicit trust that this task gives. - gpg reads the key's identity in a directory of its own. rpm names its
keys by the key's identity, and the module needs the name to tell whether
rpm holds the key and to remove it later. gpg would otherwise create
/root/.gnupgon the first call. - Every setting is written out.
enabled,autorefresh, and the checks are in the file, so zypper's defaults decide nothing.
This page is official_extra_modules/zypper_repository/README.md in the MMX repository.