Default variable details
Some of debops.apt
default variables have more extensive configuration than
simple strings or lists, here you can find documentation and examples for them.
apt__configuration
The apt__*_configuration
lists defined as the default variables can be used
to manage APT configuration files located in the /etc/apt/apt.conf.d/
directory through Ansible inventory, using the Universal Configuration
system.
Examples
Create a configuration file that executes a script before/after the dpkg command in order to set/unset extras options on some mount points:
apt__configuration:
- name: 'filesystem'
filename: '02filesystem.conf'
comment: 'Remount filesystems for package changes'
raw: |
Dpkg
{
Pre-Invoke { "/usr/local/bin/remountrw" };
Post-Invoke { "/usr/local/bin/remountdefault" };
};
state: '{{ "present"
if (ansible_virtualization_type != "lxc")
else "absent" }}'
You can see other examples in the apt__default_configuration
default
variable.
Syntax
Each configuration entry is a YAML dictionary with specific parameters:
name
Required. Name of the configuration entry, used as a part of the configuration file name. The role will automatically append the
.conf
suffix if it's not specified (unless thefilename
parameter is used).Configuration entries with the same
name
parameter are merged in order of appearance and can affect each other.filename
Optional. Specify the full name of the configuration file which should be managed. This can be useful for diverting existing files which might have unusual names without the
.conf
suffix.raw
Optional. String or YAML text block with apt.conf(5) configuration options.
comment
Optional. String or YAML text block with additional comments included with the configuration file.
state
Optional. If not specified or
present
, the configuration file will be created in the/etc/apt/apt.conf.d/
directory. Ifabsent
, specified configuration file will be removed from the host. Ifdivert
, specified configuration file will be diverted away to not be included in the configuration (this is useful for files included in.deb
packages). Ifignore
, a given configuration entry will not be processed at runtime.
apt__keys
This list, along with apt__group_keys
and apt__host_keys
and can be used to manage APT repository keys through Ansible inventory, using
the apt-key(8) command.
Warning
Support for the apt-key command is deprecated in Debian and might be removed in future release. Consider using the apt__repositories configuration to set up APT keys with their respective repositories.
Examples
Add an APT GPG key on all hosts without any conditions:
apt__keys:
- url: 'http://example.com/apt-key.asc'
Add an APT GPG key only on hosts with Debian OS:
apt__keys:
- url: 'http://example.com/apt-key.asc'
state: '{{ "present"
if (ansible_distribution == "Debian")
else "absent" }}'
Add an APT GPG key only on Ubuntu hosts that have been already configured once (delayed key configuration):
apt__keys:
- url: 'http://example.com/apt-key.asc'
state: '{{ "present"
if ((ansible_local.apt.configured | d()) | bool and
ansible_distribution == "Ubuntu")
else "absent" }}'
Syntax
Each entry is a YAML dictionary with parameters that correspond to the
apt_key
module parameters:
data
Optional. GPG key contents provided directly.
file
Optional. Path to the GPG key file on the remote host.
id
Optional. GPG key identifier.
url
Optional. The URL of the GPG key to download and install on the host.
keyring
Optional. Path to the keyring file in
/etc/apt/trusted.gpg.d/
directory.keyserver
Optional. IP address or FQDN of the GPG keyserver to download the keys from.
state
Optional. Either
present
for the key to be present (default), orabsent
for the key to be removed. Theabsent
state might be ignored due to the issues with not enough information provided about the key to remove it.
You need to specify either an URL, path to the file or key contents for the role to install a given GPG key.
apt__repositories
The apt__*_repositories
variables can be used to manage APT sources in the
/etc/apt/sources.list.d/
directory. The role supports both one-line
*.list
configuration files, as well as Deb822-format *.sources
configuration files (with support for GPG key management), depending on the
used parameters. Configuration is defined using the
Universal Configuration principles.
Examples
Add an APT repository on all hosts without any conditions, using the one-line style syntax:
apt__repositories:
- name: 'example-repo'
filename: 'example-repo.list'
repo: 'deb http://example.com/debian jessie main'
Add an APT repository only on hosts with Debian OS, using the one-line syntax:
apt__repositories:
- name: 'example-repo'
filename: 'example-repo.list'
repo: 'deb http://example.com/debian jessie main'
state: '{{ "present"
if (ansible_distribution == "Debian")
else "ignore" }}'
Add an APT repository only on Ubuntu hosts that have been already configured once, using the one-line syntax (delayed repository configuration):
apt__repositories:
- name: 'example-repo'
filename: 'example-repo.list'
repo: 'deb http://example.com/ubuntu xenial main'
state: '{{ "present"
if ((ansible_local.apt.configured | d()) | bool and
ansible_distribution == "Ubuntu")
else "ignore" }}'
Configure an Ubuntu PPA on Ubuntu hosts:
apt__repositories:
- name: 'nginx-ppa'
filename: 'nginx-ppa.list'
repo: 'ppa:nginx/stable'
state: '{{ "present"
if (ansible_distribution == "Ubuntu")
else "ignore" }}'
Add an APT repository with several components on all hosts without any conditions, using Deb822 format:
apt__repositories:
- name: 'debian'
filename: 'debian.sources'
types: 'deb'
uris: 'http://deb.debian.org/debian'
suites: 'bookworm'
components:
- 'main'
- 'non-free-firmware'
- 'contrib'
- 'non-free'
Add third-party APT repository with GPG key URL, using Deb822 format:
apt__repositories:
- name: 'my-repo'
filename: 'my-repo.sources'
uris: 'http://example.com/debian'
signed_by: 'http://example.com/debian/example.com.asc'
Switch Proxmox VE APT repositories from the default ones which require subscription to community versions (this example is included in documentation as a separate file for convenience):
---
apt__repositories:
# Preserve the original configuration since it's packaged in the
# 'pve-manager' APT package
- name: 'proxmox-enterprise'
filename: 'pve-enterprise.list'
# repo: 'deb https://enterprise.proxmox.com/debian/pve {{ ansible_distribution_release }} pve-enterprise'
state: 'divert'
- name: 'proxmox-ceph-enterprise'
filename: 'ceph.list'
repo: 'deb https://enterprise.proxmox.com/debian/ceph-quincy {{ ansible_distribution_release }} enterprise'
state: 'absent'
- name: 'proxmox-no-subscription'
filename: 'proxmox-community.sources'
uris: 'http://download.proxmox.com/debian/pve'
suites: '{{ ansible_distribution_release }}'
signed_by: 'https://enterprise.proxmox.com/debian/proxmox-release-{{ ansible_distribution_release }}.gpg'
components: 'pve-no-subscription'
state: 'present'
- name: 'proxmox-ceph-no-subscription'
filename: 'proxmox-community-ceph.sources'
uris: 'http://download.proxmox.com/debian/ceph-quincy'
suites: '{{ ansible_distribution_release }}'
signed_by: 'https://enterprise.proxmox.com/debian/proxmox-release-{{ ansible_distribution_release }}.gpg'
components: 'no-subscription'
state: 'present'
Syntax
The configuration entries are defined as YAML dictionaries with specific parameters. You can check the documentation of the apt_repository and deb822_repository Ansible modules for available options.
The parameters below are used for both one-line and Deb822 formats:
name
Required. An identifier for a specific APT source configuration, not used otherwise. Entries with the same
name
parameter are merged together in order of appearance and can affect each other.filename
Required. Name of the configuration file stored in the
/etc/apt/sources.list.d/
directory. The.list
and.sources
suffixes are automatically stripped from the specified filename and added as necessary.When the Deb822 format is used, this parameter is used in the
X-Repolib-Name
field, as well as the name of the keyring with the signing GPG key.mode
Optional. The file mode in octal. Needs to be quoted to be interpreted correctly by Ansible.
state
Optional. If not specified or
present
, a given APT source will be configured on the host. Ifignore
, a given configuration entry will not be processed during role execution.If
divert
, an existing configuration file with the specifiedfilename
will be diverted to disable it without removing it (this is useful for APT sources included in packages). This only works if therepo
anduris
parameters are not specified to avoid conflicts with Ansible modules that manage the APT repositories.If
absent
, the specified APT source will be removed from the host. If therepo
anduris
are not specified, the role assumes that a diverted configuration is present and the diversion will be removed in this case.
The parameters below are used for one-line format APT sources (the
*.list
configuration files):
repo
Required. The APT repository to configure, in the one-line format described in the sources.list(5) manual page.
codename
Optional. Override the distribution codename to use for PPA repositories.
The parameters below are used for Deb822 format APT sources (the
*.sources
configuration files):
uris
Required. Must specify the base of the Debian distribution archive, from which APT finds the information it needs. Multiple URIs can be specified in a list.
architectures
Optional. Architectures to search within repository, for example
amd64
(default) ori386
.components
Optional. Specify different sections of one distribution version present in Suite, such as
main
(default),non-free-firmware
,contrib
,non-free
suites
Optional. Can take the form of a distribution release name (default).
signed_by
Optional. Either:
a URL to a GPG key
absolute path to a keyring file stored in the filesystem
one or more fingerprints of keys stored in the
/etc/apt/trusted.gpg
kerying or in one of the keyrings in the/etc/apt/trusted.gpg.d/
directory
Keys downloaded via the URL will be stored in
/etc/apt/keyrings/
directory (automatically created if absent), with filenames based on thefilename
parameter.types
Optional. Which types of packages to look for from a given source; either binary
deb
(default) or source codedeb-src
.
The role supports most of the deb822_repository
options, check its
documentation for in-depth explanation.
apt__auth_files
The apt__*_auth_files
lists can be used to create and manage
/etc/apt/auth.conf.d/
configuration files which caontain authentication
credentials required by specific APT repositories. The format and more details
about these files can be found in apt_auth.conf(5) manual page. The
debops.reprepro role can be used to create APT repositories that require
authentication.
Note
Private APT repositories accessible over HTTPS might result in issues during host bootstrapping due to lack of trusted Root CA certificates on the host. You can avoid that by applying the debops.pki role before the actual bootstrap playbook, for example:
$ debops run service/python_raw service/pki -l <host> -u root
This command will prepare the host for use via Ansible and set up PKI environment, including custom Root CA certificates.
This functionality is also available in the debops.keyring role for use by other Ansible roles via dependent role variables. See keyring__dependent_apt_auth_files for more details.
Examples
Provide credentials for a private APT repository, with password stored in the
secret/
directory managed by the debops.secret role. The APT
repository is managed by the debops.reprepro role which uses the
debops.nginx role to manage the authentication credentials.
apt__auth_files:
- name: 'private_repo'
machine: 'https://repo.example.org/debian'
login: 'username'
password: '{{ lookup("password", secret + "/credentials/repo"
+ "/nginx/htpasswd"
+ "/apt_access/username") }}'
Syntax
The variables are defined as a list of YAML dictionaries .Each configuration
entry defines a separate file in the /etc/apt/auth.conf.d/
directory.
The state and contents of the file are specified using specific parameters:
name
Required. Name of the configuration file with authentication credentials, can contain
.conf
suffix which will be stripped. Entries with the samename
parameter are merged together using Universal Configuration and can affect each other in order of appearance.machine
Required. The URL of the APT repository that requires the following credentials.
login
Required. The username expected by the APT repository during HTTP Basic Authentication.
password
Required. The password expected by the APT repository during HTTP Basic Authentication. It can be stored in the
secret/
directory and retrieved from there if needed.state
Optional. If not defined or
present
, a given configuration file will created on the host. Ifabsent
, a given configuration file will be removed from the host. Ifignore
, a given entry will not be evaluated during role execution.comment
Optional. String or YAML text block with additional comments included in the generated configuration file.
apt__sources
The apt__*_sources
lists define the contents of the
/etc/apt/sources.list
configuration file. The default configuration is
composed from multiple entries at runtime; each entry conditionally updates the
configuration based on the host facts. For convenience, role defaults are split
into multiple variables based on the OS
distribution.
Note
The /etc/apt/sources.list
should be focused only on the
official OS repositories. If you want to add third-party or external APT
repositories to your hosts, consider using the apt__repositories
variables to put them in the /etc/apt/sources.list.d/
directory.
Examples
Add an archive repository in /etc/apt/sources.list
configuration file:
apt__sources:
- name: 'debian-archive'
uri: 'http://archive.debian.org/debian'
suite: 'sarge'
components: [ 'main' ]
Add custom options to existing debian-release
APT source configuration (see
sources.list(5) manual page for details):
apt__sources:
- name: 'debian-release'
options:
- arch: [ 'amd64', 'i386' ]
- signed-by: '{{ "/usr/share/keyrings/debian-archive-"
+ ansible_distribution_release
+ "-stable.gpg" }}'
To see more examples, you can check the apt__debian_sources
,
apt__devuan_sources
and apt__ubuntu_sources
default
variables.
Syntax
Configuration is defined using Universal Configuration syntax. Each entry is a YAML dictionary with specific parameters (singular spelling is for strings, plural spelling is for YAML lists):
name
Required. Repository identifier, not used otherwise. Entries with the same
name
parameter are merged together in order of appearance and can affect each other. This is used extensively in the default configuration of the role.raw
Optional. String or YAML text block with sources.list(5) one-line repository format entries included in the configuration file as-is. If this parameter is specified, it takes precedence over other parameters.
uri
oruris
Optional. The URI or other method known by APT (see sources.list(5)) for a given APT source. It is possible to specify multiple entries as a list, they will be treated as one. The
uris
lists from multiple entries with the samename
parameter are combined together.type
ortypes
Optional. What type of the packages are used for this source. It can be either a string of 1 type, or a list of types. Known source types:
deb
,deb-src
. If not set, role will use theapt__source_types
value. Thetypes
lists from multiple entries with the samename
parameter are combined together.suite
orsuites
Optional. Name of the "suite" to use for this source. The suite is usually a release name like
jessie
,xenal
, or a "release class" likestable
,oldstable
,testing
, or a directory path in case of simple repositories (which needs to end with a slash). It can also be a list of releases. Thesuites
lists from multiple entries with the samename
parameter are combined together.component
orcomponents
Optional. Name of a repository component or section to enable, for example
main
,contrib
,non-free
,universe
,restricted
,multiverse
. It can also be a list of components. Thecomponents
lists from multiple entries with the samename
parameter are combined together.options
Optional. List of YAML dictionaries which describe options for a given APT repository. Each dictionary key is an option name, and dictionary value is an option value. Values can be strings or YAML lists. The
options
lists in configuration entries with the samename
parameter are combined together.Option names will be written in the configuration file as-is. You should use the short option names specified in brackets in the sources.list(5) manual page to conform to the one-line format.
state
Optional. If not specified or
present
, a given APT source will be included in the generated/etc/apt/sources.list
configuration file. Ifabsent
, a given APT source will not be included in the generated file. Ifcomment
, the APT source will be included, but it will be commented out. Ifignore
, a given entry will not be processed during role execution.comment
Optional. A string or a YAML text block with comments about the given APT source.
separate
Optional, boolean. If
True
(default), a given APT source will be visually separated from the next one in the generated configuration file; ifFalse
, no separation will be added.