Default variables: configuration
================================

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 :manpage:`apt_preferences(5)` "pins", each pin is defined by a YAML
dictionary. Supported parameters:

``package``
  Required. String 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.

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

``role`` or ``by_role``
  Name of a role which sets a particular pin. This name will be included in the
  autogenerated filename.

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

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

``delete``
  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'
        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:
      - package: 'nginx nginx-*'
        backports: [ 'wheezy', 'jessie' ]

