DEBOPS.APT(5)

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

SYNOPSIS

debops 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

Role tries to detect the original APT repositories configured on the system and use them in the generated /etc/apt/sources.list configuration file. They will be placed before the default repositories, with assumption that the original repositories pointed to the closest mirror. The original APT repositories can be completely disabled by setting apt__original_sources: [] in your inventory.

The non-free repositories 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; you can control this using the apt__nonfree variable.

  Example inventory

debops.apt is included by default in the 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

If you have a local APT mirror that you want a group of hosts to use exclusively, you could compose your inventory like this:

# Don't use the default mirrors
apt__default_sources_state: 'absent'
# Don't use the default security mirrors
apt__security_sources_state: 'absent'
# Replace the original APT mirror
apt__original_sources: []
# Define local APT mirror
apt__group_sources:
  - uri:          'http://mirrors.domain.fqdn/debian'
    comment:      '{{ "Local " + apt__distribution + " repositories" }}'
    distribution: 'Debian'
# Define local APT security mirrors
apt__group_security_sources:
  - uri:          'http://mirrors.domain.fqdn/debian-security'
    comment:      '{{ "Local " + apt__distribution + " Security repository" }}'
    suite:        '{{ apt__distribution_release + "-security" }}'
    distribution: 'Debian'

  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. Usefull, 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__conf

This list, along with apt__group_conf and apt__host_conf can be used to manage APT configuration files through Ansible inventory. Each entry is a YAML dictionary with keys and values the same as the ones used by the Ansible ansible.builtin.copy module <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/copy_module.html>. See its documentation for parameter advanced usage and syntax.

Here are some more important parameters:

item.dest or item.name or item.path
    Required. Filename on the remote host. The role will automatically prefix it with item.priority and put it in the right directory.

item.priority
    Optional. Priority that prefix the filename to order the instruction with the different configuration files. If not specified, priority 60 is used by default.

item.src
    Path to the source file on the Ansible Controller. Alternatively you can use item.content to provide the file contents directly in the inventory.

item.content
    String or YAML text block with the file contents to put in the destination file. Alternatively you can use item.src to provide the path to the source file on Ansible Controller.

item.state
    Optional. If not specified, or if specified and present, the file(s) will be created. If specified and absent, file will be removed.

  Examples

Copy file from the Ansible Controller to all remote hosts:

apt__conf:
  - name: personnal
    src: 'path/to/apt.conf.d/02personnal.conf'
    priority: '99'

Create a configuration file that calls script before/after DPKG in order to set/unset extras options on some mount points :

apt__host_conf:
  - name: filesystem
    priority: '02'
    content: |
      # This file is managed remotely, all changes will be lost
      {% if (ansible_virtualization_type != 'lxc') %}
      Dpkg
      {
        Pre-Invoke { "/usr/local/bin/remountrw" };
        Post-Invoke { "/usr/local/bin/remountdefault" };
      };

  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. 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.

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. See also architecture, distribution and distribution_release parameters.

url Optional. The URL of the GPG key to download and install on the host.

    If you don't specify the state parameter directly, you can use additional parameters that control how the specified key is managed:

architecture
    Optional. Name of the system architecture, for example amd64 or i386. If the current host has the specified architecture, the key will be installed. Only one architecture can be specified at a time, use the state parameter for more complex conditions.

distribution
    Optional. Name of the OS distribution. If the current host has the specified distribution, the key will be installed. Only one distribution can be specified at a time, use the state parameter for more complex conditions.

distribution_release
    Optional. Name of the OS release. If the current host has the specified distribution, the key will be installed. Only one release can be specified at a time, use the state parameter for more complex conditions.

    You need to specify either an URL, path to the file or key contents for the role to install a given GPG key.

  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'
    distribution: 'Debian'

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|d() and ansible_local.apt|d() and
                   ansible_local.apt.configured|bool and
                   ansible_distribution == "Ubuntu")
               else "absent" }}'

  apt__repositories

This list, along with apt__group_repositories and apt__host_repositories can be used to manage APT repositories through Ansible inventory. Each entry is a YAML dictionary with parameters that correspond to the apt_repository module parameters:

repo
    Required. The APT repository to configure, in the sources.list(5) <https://manpages.debian.org/sources.list(5)> format.

filename
    Optional. Name of the source file in /etc/apt/sources.list.d/ directory. Ansible automatically adds .list suffix, therefore it's not needed..

mode
    Optional. The file mode in octal. Needs to be quoted to be interpreted correctly by Ansible.

state
    Optional. Either present for the repository to be present (default), or absent for the repository to be removed. See also architecture, distribution and distribution_release parameters.

    If you don't specify the state parameter directly, you can use additional parameters that control how the specified repository is managed:

architecture
    Optional. Name of the system architecture, for example amd64 or i386. If the current host has the specified architecture, the repository will be configured. Only one architecture can be specified at a time, use the state parameter for more complex conditions.

distribution
    Optional. Name of the OS distribution. If the current host has the specified distribution, the repository will be configured. Only one distribution can be specified at a time, use the state parameter for more complex conditions.

distribution_release
    Optional. Name of the OS release. If the current host has the specified distribution, the repository will be configured. Only one release can be specified at a time, use the state parameter for more complex conditions.

  Examples

Add an APT repository on all hosts without any conditions:

apt__repositories:
  - repo: 'deb http://example.com/debian jessie main'

Add an APT repository only on hosts with Debian OS:

apt__repositories:
  - repo: 'deb http://example.com/debian jessie main'
    distribution: 'Debian'

Add an APT repository only on Ubuntu hosts that have been already configured once (delayed repository configuration):

apt__repositories:
  - repo: 'deb http://example.com/ubuntu xenial main'
    state: '{{ "present"
               if (ansible_local|d() and ansible_local.apt|d() and
                   ansible_local.apt.configured|bool and
                   ansible_distribution == "Ubuntu")
               else "absent" }}'

Configure an Ubuntu PPA on Ubuntu hosts:

apt__repositories:
  - repo: 'ppa:nginx/stable'
    distribution: 'Ubuntu'

  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

This list as well as other apt__*_sources lists are used to configure what APT package sources are configure in the /etc/apt/sources.list file. This file defines the primary OS package sources and indirectly defines the OS release that's present on the host. The configuration template will track what sources are present and will comment out the duplicates if they show up in more than one list.

Apart from the usual inventory lists for all hosts, group of hosts and specific hosts, there are additional lists that are included in the finished config file:

apt__original_sources
    This list defines the APT sources that are present in the original, diverted /etc/apt/sources.list file. The security sources are automatically filtered out based on the contents of the apt__security_sources list.

apt__default_sources
    The role provides a set of default package sources for each known OS distribution. These sources are usually URLs to mirror redirectors, which will try to point to the closest available mirror. They are provided as a backup in case the host does not have any recognized package sources available.

apt__security_sources
    This is a list of APT sources that provide security updates. This list has a more specific entries than the normal lists since security repositories tend to have different naming scheme than the regular mirrored repositories.

apt__combined_sources
    This list combines all of the above list and is used in the configuration template. It defines the order in which the APT sources are specified in the configuration file.

    Each list entry that defines an APT source can have different forms.

    The simplest entry is a string. It does not have any conditions and it will be added to the /etc/apt/sources.list file unless it is a duplicate. The string should only contain the URL of the APT mirror, the rest will be added automatically according to detected OS distribution and release. Example:

    apt__sources:
      - 'http://ftp.debian.org/debian'

    A more advanced alternative is a YAML dictionary, which uses OS distribution names as keys and mirror URLs as values. You can specify multiple distributions in one entry, they will be filtered according to the current OS. Example:

    apt__sources:
      - Debian: 'http://ftp.debian.org/debian'

    The third version of an APT sources entry is similar to the Ansible ansible.builtin.apt_repository module <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/apt_repository_module.html>, and should be defined as a YAML dictionary with repo as the key and complete APT source specification as the value. These entries are not filtered by the role, and they are not checked for duplicates. Example:

    apt__sources:
      - repo: 'deb http://ftp.debian.org/debian jessie main contrib non-free'

    The last version is a YAML dictionary with multiple keys as parameters. These parameters allow for fine control over when a particular APT source is present, what source types are used, which components are enabled, etc. Known parameters:

uri or uris
    Required. 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.

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.

option or options
    Optional. String or list of strings of APT options. Settings are expected in the form setting=value. See sources.list(5) <https://manpages.debian.org/sources.list(5)> for details.

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. If not specified, role will use the apt__distribution_suffixes value to generate a list of default suites for a given OS release.

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. If not specified, role will use the apt__distribution_components value.

comment or comments
    Optional. A string or a YAML text block with comments about the given APT source.

state
    Optional. Either present if a given APT source should be present in the generated config file, or absent if not.

architecture
    Optional. If state is not specified, you can specify a system architecture name on which a given APT source is active. Only one architecture can be specified, use the state parameter for more complex conditions.

distribution
    Optional. If state is not specified, you can specify an OS distribution name on which a given APT source is active. Only one distribution can be specified, use the state parameter for more complex conditions.

distribution_release
    Optional. If state is not specified, you can specify an OS release on which a given APT source is active. Only one release can be specified, use the state parameter for more complex conditions.

  Examples

Add an archive repository in /etc/apt/sources.list configuration file:

apt__sources:
  - uri: 'http://archive.debian.org/debian'
    suite: 'sarge'
    components: [ 'main', 'contrib' ]

Enable repository with source packages:

apt__sources:
  - uri: 'http://ftp.debian.org/debian'
    types: [ 'deb', 'deb-src' ]

Enable Canonical Partner repositories, only on Ubuntu hosts:

apt__sources:
  - uri: 'http://archive.canonical.com/ubuntu'
    component: 'partner'
    distribution: 'Ubuntu'

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 documentation

AUTHOR
Maciej Delmanowski, Robin Schneider

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