DEBOPS.APT_PREFERENCES(5)

NAME
debops.apt_preferences - Manage APT preferences using Ansible

SYNOPSIS

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

debops --tags role::apt_preferences [playbook] ... [--limit group,host,...] [--diff] [--check] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

debops --skip-tags skip::apt_preferences [playbook] ... [--limit group,host,...] [--diff] [--check] [--tags-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

APT preferences <https://wiki.debian.org/AptPreferences> can be used to influence package selection performed by APT during installation or upgrades. You can for example tell APT that you prefer packages from certain repositories or want to hold a package on a particular version no matter what (among other things).

By default, if you don't specify a version or provide a custom pin configuration, debops.apt_preferences role will configure the specified packages to be installed from the backports repository of the current OS release.

GETTING STARTED

  APT preferences configuration

You can use this role to select a different version of APT packages available without specifying the version directly in the playbooks or roles. This helps to ensure that the APT dependency tree is stable and there are no conflicts between different versions.

  Example inventory

The debops.apt_preferences role is included in the common.yml playbook, you can add your own entries to Ansible’s inventory and they should be picked up automatically on the next playbook run.

  Example playbook

Here's an example playbook that can be used to manage APT preferences:

---
- name: Manage APT preferences
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_apt_preferences' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]

DEFAULT VARIABLE DETAILS

Some of debops.apt_preferences default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  apt_preferences__list

List of apt_preferences(5) <https://manpages.debian.org/apt_preferences(5)> "pins", each pin is defined by a YAML dictionary. Supported parameters:

package or packages
    Required. String or YAML list of package names affected by this pin, each package separated by space. You can use a package-* wildcard to specify multiple packages. First package name will be included in the automatically generated filename of the pin preferences file.

backports
    List of OS releases which should be considered when the debops.apt_preferences role configures a pin for a backported package. If the current OS release is not on this list, the pin won't be created and a existing pin will be removed. This should allow for easy transition to the next OS release.

version
    Specify a particular package version you want to pin, for example 5.10. It will be configured with a * at the end to allow for upgrades.

    By default versioned pins are set with priority 1001, which should ensure that the selected package version is never upgraded, or it will be downgraded if required.

priority
    Specify a custom priority for a pin. By default pins are created with priority 500 to allow for easy installation of packages from backports, versioned pins are created with priority 1001.

reason
    A short description explaining the reason for a pin. Might be used to point the admin to useful documentation explaining why a particular pin is defined. Multi-line strings are handled properly by prepending each line by Explanation:.

filename
    Name of the generated file with pin preferences, saved in /etc/apt/preferences.d/. If undefined, the debops.apt_preferences role will automatically generate a filename.

suffix
    Additional string added at the end of the autogenerated filename, can be used to prevent filename collisions.

by_role
    Name of a Ansible role in the format ROLE_OWNER.ROLE_NAME which is responsible for the pin. The sanitized name will be included in the autogenerated filename.

role
    Deprecated. Use by_role instead.

pin Custom pin definition. If this variable is undefined, the debops.apt_preferences role will automatically configure selected packages with preference for a backported version.

raw Instead of generating a pin automatically, use contents of this YAML text block for pin configuration. Might be used to create several pins in one file.

state
    Optional. If not defined or present, an APT pin will be created. If absent, pin will be deleted.

when
    Deprecated. If this parameter is defined and True or False, enable or disable a particular pin conditionally.

delete
    Deprecated. If this parameter is defined and True, the preferences file for this pin will be deleted and a new one will not be created.

  Examples

Ensure that Perl 5.10 is installed on the system:

apt_preferences__list:
  - package: 'perl'
    reason: |-
      Ensure that Perl 5.10 is installed on the system.
      Any other Perl version breaks our legacy code!!! ;-)
      (Just an example for a multiline explanation).
    version: '5.10'

Prefer packages from a specific site:

apt_preferences__list:
  - package: '*'
    pin: 'origin "ftp.de.debian.org"'
    priority: '999'

Install the nginx packages from backports on Debian Wheezy and Debian Jessie:

apt_preferences__list:
  - packages: [ 'nginx', 'nginx-*' ]
    backports: [ 'wheezy', 'jessie' ]

AUTHOR
Maciej Delmanowski, Robin Schneider

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