DEBOPS.APT(5)

NAME
debops.apt - Manage APT repositories and keys using Ansible

SYNOPSIS

debops run service/apt [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

debops.apt configures and manages APT, the Advanced Package Tool in Debian and other derivative distributions.

GETTING STARTED

  Default configuration

The non-free and non-free-firmware sections of the Debian Archive will be enabled automatically on hardware-based hosts in case any non-free firmware is required. Otherwise, only the main and universe (on Ubuntu) repositories are enabled. Users can control this using the apt__nonfree and apt__nonfree_firmware boolean variables.

  Example inventory

The debops.apt role is included by default in the layer/common.yml DebOps playbook; you don't need to do anything to have it executed.

If you don’t want to let debops.apt manage APT, you can do this with the following setting in your inventory:

apt__enabled: False

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.apt role:

---
- name: Manage Advanced Package Manager
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_apt' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: apt
      tags: [ 'role::apt', 'skip::apt' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::apt
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

role::apt:keys
    Deploy only keys defined in inventory. Useful, if some keys are expired and the apt role refuses to work. Or start using debops on existing hosts with expired keys.

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 the filename 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) <https://manpages.debian.org/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. If absent, specified configuration file will be removed from the host. If divert, specified configuration file will be diverted away to not be included in the configuration (this is useful for files included in .deb packages). If ignore, 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) <https://manpages.debian.org/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), or absent for the key to be removed. The absent 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 <https://pve.proxmox.com/wiki/Package_Repositories> 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 <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/apt_repository_module.html> and deb822_repository <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/deb822_repository_module.html> 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. If ignore, a given configuration entry will not be processed during role execution.

    If divert, an existing configuration file with the specified filename will be diverted to disable it without removing it (this is useful for APT sources included in packages). This only works if the repo and uris 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 the repo and uris 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) <https://manpages.debian.org/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) or i386.

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 the filename parameter.

types
    Optional. Which types of packages to look for from a given source; either binary deb (default) or source code deb-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) <https://manpages.debian.org/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 same name 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. If absent, a given configuration file will be removed from the host. If ignore, 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) <https://manpages.debian.org/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) <https://manpages.debian.org/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 or uris
    Optional. The URI or other method known by APT (see sources.list(5) <https://manpages.debian.org/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 same name parameter are combined together.

type or types
    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 the apt__source_types value. The types lists from multiple entries with the same name parameter are combined together.

suite or suites
    Optional. Name of the "suite" to use for this source. The suite is usually a release name like jessie, xenal, or a "release class" like stable, 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. The suites lists from multiple entries with the same name parameter are combined together.

component or components
    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. The components lists from multiple entries with the same name 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 same name 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) <https://manpages.debian.org/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. If absent, a given APT source will not be included in the generated file. If comment, the APT source will be included, but it will be commented out. If ignore, 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; if False, no separation will be added.

SEE ALSO

apt(8) <https://manpages.debian.org/apt(8)>
    Advanced Package Tool command line interface

sources.list(5) <https://manpages.debian.org/sources.list(5)>
    /etc/apt/sources.list and /etc/apt/sources.list.d/*.list,sources documentation

apt.conf(5) <https://manpages.debian.org/apt.conf(5)>
    /etc/apt/apt.conf.d/*.conf documentation

apt_auth.conf(5) <https://manpages.debian.org/apt_auth.conf(5)>
    /etc/apt/auth.conf.d/*.conf documentation

AUTHOR
Maciej Delmanowski, Robin Schneider

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others