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.

.. contents::
   :local:
   :depth: 1

.. _apt_preferences__list:

apt_preferences__list
---------------------

List of :man:`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
  :file:`/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:

.. code-block:: yaml

   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:

.. code-block:: yaml

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

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

.. code-block:: yaml

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