APT_PREFERENCES(5)APT_PREFERENCES(5)NAMEapt_preferences - Preference control file for APT
DESCRIPTION
The APT preferences file controls various aspects of the APT system.
It is meant to be user editable and manipulatable from software. The
file consists of a number of records formed like the dpkg status file,
space seperated sections of text with at the start of each line tags
seperated by a colon. It is stored in /sw/etc/apt/preferences.
VERSIONING
One purpose of the preferences file is to let the user select which
version of a package will be installed. This selection can be made in a
number of ways that fall into three categories, version, release and
origin.
Selection by version can be done by exact match or prefix match. The
format is 2.1.2 or 2.2* for a prefix match. Matching by prefix can be
used to ignore the r in the Debian release versioning, like 2.1r* or to
ignore Debian specific revisions, 1.1-*. When matching versions with a
prefix the highest matching version will always be picked.
Selection by release is more complicated and has three forms. The pri‐
mary purpose of release selections is to identify a set of packages
that match a specific vendor, or release (ie Debian 2.1). The first two
forms are shortcuts intended for quick command line use. If the first
character of the specification is a digit then it is considered to be a
release version match, otherwise a release label match. Specifications
which contain equals are full release data matches and are a comma
seperated list of one letter keys followed by an equals then by the
string. Examples:
v=2.1*,o=Debian,c=main
l=Debian
a=stable
The data for these matches are taken from the Release files that APT
downloads during an update. The available keys are:
a= Archive
This is the common name we give our archives, such as stable or
unstable. The special name now is used to designate the set of
packages that are currently installed.
c= Component
Referes to the sub-component of the archive, main, contrib etc.
Component may be omitted if there are no components for this ar‐
chive.
v= Version
This is a version string with the same properties as in the
Packages file. It represents the release level of the archive.
Typical Debian release numbers look like 2.1r2 with the r desig‐
nating the release of 2.1. New releases are limited to security
updates and other important changes.
o= Origin
This specifies who is providing this archive. In the case of
Debian the string will read Debian. Other providers may use
their own string.
l= Label
This carries the encompassing name of the distribution. For
Debian proper this field reads Debian. For derived distributions
it should contain their proper name.
The final selection method is by origin. This is simply the site name
of the originating package files. The empty string is used for file
URIs.
Version selection, particularly the latter two methods, are used in
many different parts of APT, not just the preferences file.
CANDIDATE VERSION POLICY
Internally APT maintains a list of all available versions for all pack‐
ages. If you place multiple releases or vendors in your
sources.list(5) file then these features are available. By default APT
selects the highest version from all automatic sources. Some sources,
such as project/experimental are marked Not Automatic - these fall to
the bottom of the selection pile.
When deciding what version to use APT assigns a priority to each avail‐
able version of the package. It then does two things, first it selects
the highest priorty version that is newer than the installed version of
the package, then it selects the highest priority version that is older
than the installed version. Next, if the older versions have a priority
greater than 1000 they are compared with the priority of the upgrade
set, the larger becomes the selected result. Otherwise the downgrade
versions are ignored and the highest priority of the ugprade set is
selected.
It is possible to think of the priorities in strata:
1000 and up
Downgradable priorities
1000 The downgrade prevention barrier
100 to 1000
Standard priorities. 990 is the priority set by the --target-
release apt-get(8) option. 989 is the start for auto priorities
and 500 are all the default package files.
100 The currently installed version
0 to 100
Non automatic priorities. These are only used if the package is
not installed and there is no other version available.
less than 0
The version is never selected.
Giving a pin a priority greater than 1000 will allow APT to downgrade
in order to get to that version.
Each package may be pinned to a specific version and each Packages file
has a priority for every package inside. The highest priority assigned
to a package is the one that is used.
A package pin looks like this:
Package: apt
Pin: version 0.4.0
Pin-Priority: 1001
The first line specifies the package, the second gives the Pin specifi‐
cation and the last gives the priority of this pin. The first word of
the pin specification may be version, release or origin, the remainder
of the field is described in the Versioning section above.
A default pin is how the priorities of package files are set. Any num‐
ber of default pins may be specified, the first matching default will
select the priority of the package file. Only release or origin may be
used in the Pin specification since they match Packages files.
Package: *
Pin: release v=2.1*
Pin-Priority: 998
If the Pin-Priority field is omitted then the priority defaults to 989
for both cases.
INTERESTING EFFECTS
Due to the downgrade prevention barrier at priority 1000 it is possible
that a lower priority version will be selected if the higher priority
would cause a downgrade. For instance, if package foo has versions 1.2,
1.1 and 1.0 installed, with 1.1 being the currently installed version
and the priorities of each version being 900, 100 and 950 repectively
the winning version will be 1.2.
In practice this is often desired. A user may use a default pin to make
the stable distribution the default and then use the --target-dist
option with apt-get(8) to select newer versions from unstable. The
packages that have been upgraded to unstable will continue to follow
the versions that are available in unstable since the stable versions
now fall below the downgrade prevention barrier.
If this is not desired then a default pin should be used to make unsta‐
ble have a priority less than 100.
Users of 3rd party add ons such as Helix GNOME can use this mechanism
to force the usage of Helix packages, or force the usage of Debian
packages by setting the priority of that source sufficiently high. It
is even possible to mass downgrade from one set of packages to another
by using a priority larger than 1000.
SEE ALSOapt-cache(8)apt.conf(5)BUGS
See the APT bug page <URL:http://bugs.debian.org/apt>. If you wish to
report a bug in APT, please see /usr/share/doc/debian/bug-reporting.txt
or the bug(1) command.
AUTHOR
APT was written by the APT team <apt@packages.debian.org>.
12 March 2001 APT_PREFERENCES(5)
