doc/apt_preferences.5.sgml

   1 <!-- -*- mode: sgml; mode: fold -*- -->
   2 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
   3
   4 <!ENTITY % aptent SYSTEM "apt.ent">
   5 %aptent;
   6
   7 ]>
   8
   9 <refentry>
  10  &apt-docinfo;
  11
  12  <refmeta>
  13    <refentrytitle>apt_preferences</>
  14    <manvolnum>5</>
  15  </refmeta>
  16
  17  <!-- Man page title -->
  18  <refnamediv>
  19     <refname>apt_preferences</>
  20     <refpurpose>Preference control file for APT</>
  21  </refnamediv>
  22
  23  <RefSect1><Title>Description</>
  24    <para>
  25    The APT preferences file controls various aspects of the APT system.
  26    It is meant to be user editable and manipulatable from software. The file
  27    consists of a number of records formed like the dpkg status file, space
  28    seperated sections of text with at the start of each line tags seperated
  29    by a colon. It is stored in <filename>/etc/apt/preferences</>.
  30  </RefSect1>
  31
  32  <RefSect1><Title>Versioning</>
  33    <para>
  34    One purpose of the preferences file is to let the user select which version
  35    of a package will be installed. This selection can be made in a number of
  36    ways that fall into three categories, version, release and origin.
  37    <para>
  38    Selection by version can be done by exact match or prefix match. The format
  39    is <literal/2.1.2/ or <literal/2.2*/ for a prefix match. Matching by prefix
  40    can be used to ignore the <literal/r/ in the Debian release versioning, like
  41    <literal/2.1r*/ or to ignore Debian specific revisions, <literal/1.1-*/.
  42    When matching versions with a prefix the highest matching version will
  43    always be picked.
  44    <para>
  45    Selection by release is more complicated and has three forms. The primary
  46    purpose of release selections is to identify a set of packages that match
  47    a specific vendor, or release (ie Debian 2.1). The first two forms are
  48    shortcuts intended for quick command line use. If the first character of the
  49    specification is a digit then it is considered to be a release version match,
  50    otherwise a release label match. Specifications which contain equals are
  51    full release data matches and are a comma seperated list of one letter keys
  52    followed by an equals then by the string. Examples:
  53 <informalexample><programlisting>
  54 v=2.1*,o=Debian,c=main
  55 l=Debian
  56 a=stable
  57 </programlisting></informalexample>
  58    <para>
  59    The data for these matches are taken from the <filename/Release/ files
  60    that APT downloads during an <literal/update/. The available keys are:
  61    <VariableList>
  62      <VarListEntry><term>a= Archive</term>
  63      <ListItem><Para>
  64      This is the common name we give our archives, such as <literal/stable/ or
  65      <literal/unstable/. The special name <literal/now/ is used to designate
  66      the set of packages that are currently installed.
  67      </VarListEntry>
  68
  69      <VarListEntry><term>c= Component</term>
  70      <ListItem><Para>
  71      Referes to the sub-component of the archive, <literal/main/,
  72      <literal/contrib/ etc. Component may be omitted if there are no
  73      components for this archive.
  74      </VarListEntry>
  75
  76      <VarListEntry><term>v= Version</term>
  77      <ListItem><Para>
  78      This is a version string with the same properties as in the Packages file.
  79      It represents the release level of the archive. Typical Debian release
  80      numbers look like <literal/2.1r2/ with the r designating the release of
  81      2.1. New releases are limited to security updates and other important
  82      changes.
  83      </VarListEntry>
  84
  85      <VarListEntry><term>o= Origin</term>
  86      <ListItem><Para>
  87      This specifies who is providing this archive. In the case of Debian the
  88      string will read <literal/Debian/. Other providers may use their own
  89      string.
  90      </VarListEntry>
  91
  92      <VarListEntry><term><term>l= Label</term>
  93      <ListItem><Para>
  94      This carries the encompassing name of the distribution. For Debian proper
  95      this field reads <literal/Debian/. For derived distributions it should
  96      contain their proper name.
  97      </VarListEntry>
  98    </VariableList>
  99    <para>
 100    The final selection method is by origin. This is simply the site name
 101    of the originating package files. The empty string is used for file URIs.
 102    <para>
 103    Version selection, particularly the latter two methods, are used in many
 104    different parts of APT, not just the preferences file.
 105  </RefSect1>
 106
 107  <RefSect1><Title>Candidate Version Policy</>
 108    <para>
 109    Internally APT maintains a list of all available versions for all packages.
 110    If you place multiple releases or vendors in your &sources-list; file then
 111    these features are available. By default APT selects the highest version
 112    from all automatic sources. Some sources, such as
 113    <filename>project/experimental</> are marked Not Automatic - these fall
 114    to the bottom of the selection pile.
 115    <para>
 116    When deciding what version to use APT assigns a priority to each available
 117    version of the package. It then does two things, first it selects
 118    the highest priorty version that is newer than the installed version of the
 119    package, then it selects the highest priority version that is older than
 120    the installed version. Next, if the older versions have a priority greater
 121    than 1000 they are compared with the priority of the upgrade set, the larger
 122    becomes the selected result. Otherwise the downgrade versions are ignored
 123    and the highest priority of the ugprade set is selected.
 124    <para>
 125    It is possible to think of the priorities in strata:
 126    <VariableList>
 127      <VarListEntry><term>1000 and up</term>
 128      <ListItem><Para>
 129      Downgradable priorities
 130      </VarListEntry>
 131
 132      <VarListEntry><term>1000</term>
 133      <ListItem><Para>
 134      The downgrade prevention barrier
 135      </VarListEntry>
 136
 137      <VarListEntry><term>100 to 1000</term>
 138      <ListItem><Para>
 139      Standard priorities. 990 is the priority set by the
 140      <option/--target-release / &apt-get; option. 989 is the start for auto
 141      priorities and 500 are all the default package files.
 142      </VarListEntry>
 143
 144      <VarListEntry><term>100</term>
 145      <ListItem><Para>
 146      The currently installed version
 147      </VarListEntry>
 148
 149      <VarListEntry><term>0 to 100</term>
 150      <ListItem><Para>
 151      Non automatic priorities. These are only used if the package
 152      is not installed and there is no other version available.
 153      </VarListEntry>
 154
 155      <VarListEntry><term>less than 0</term>
 156      <ListItem><Para>
 157      The version is never selected.
 158      </VarListEntry>
 159    </VariableList>
 160    <para>
 161    Giving a pin a priority greater than 1000 will allow APT to downgrade
 162    in order to get to that version.
 163    <para>
 164    Each package may be pinned to a specific version and each Packages file
 165    has a priority for every package inside. The highest priority assigned
 166    to a package is the one that is used.
 167    <para>
 168    A package pin looks like this:
 169 <informalexample><programlisting>
 170 Package: apt
 171 Pin: version 0.4.0
 172 Pin-Priority: 1001
 173 </programlisting></informalexample>
 174    The first line specifies the package, the second gives the Pin specification
 175    and the last gives the priority of this pin. The first word of the pin
 176    specification may be version, release or origin, the remainder of the field
 177    is described in the Versioning section above.
 178    <para>
 179    A default pin is how the priorities of package files are set. Any number
 180    of default pins may be specified, the first matching default will select
 181    the priority of the package file. Only release or origin may be used in
 182    the Pin specification since they match Packages files.
 183 <informalexample><programlisting>
 184 Package: *
 185 Pin: release v=2.1*
 186 Pin-Priority: 998
 187 </programlisting></informalexample>
 188    <para>
 189    If the Pin-Priority field is omitted then the priority defaults to 989 for
 190    both cases.
 191
 192    <RefSect2><title>Interesting Effects</>
 193    <para>
 194    Due to the downgrade prevention barrier at priority 1000 it is possible
 195    that a lower priority version  will be selected if the higher priority
 196    would cause a downgrade. For instance, if package foo has versions
 197    <literal/1.2/, <literal/1.1/ and <literal/1.0/ installed, with
 198    <literal/1.1/ being the currently installed version and the priorities of
 199    each version being 900, 100 and 950 repectively the winning version will be
 200    <literal/1.2/.
 201    <para>
 202    In practice this is often desired. A user may use a default pin to
 203    make the stable distribution the default and then use the
 204    <option/--target-dist/ option with &apt-get; to select newer versions
 205    from unstable. The packages that have been upgraded to unstable will
 206    continue to follow the versions that are available in unstable since
 207    the stable versions now fall below the downgrade prevention barrier.
 208    <para>
 209    If this is not desired then a default pin should be used to make unstable
 210    have a priority less than 100.
 211    <para>
 212    Users of 3rd party add ons such as Helix GNOME can use this mechanism to
 213    force the usage of Helix packages, or force the usage of Debian packages
 214    by setting the priority of that source sufficiently high. It is even
 215    possible to mass downgrade from one set of packages to another by
 216    using a priority larger than 1000.
 217    </RefSect2>
 218  </RefSect1>
 219
 220  <RefSect1><Title>See Also</>
 221    <para>
 222    &apt-cache; &apt-conf;
 223  </RefSect1>
 224
 225  &manbugs;
 226  &manauthor;
 227
 228 </refentry>