#115517: Latest draft of apt_preferences(5) man page
Here's my latest draft of the apt_preferences(5) man page.
Please read it over and report any errors! // Thomas
<!-- -*- mode: sgml; mode: fold -*- -->
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY % aptent SYSTEM "apt.ent">
%aptent;
]>
<refentry>
&apt-docinfo;
<refmeta>
<refentrytitle>apt_preferences</>
<manvolnum>5</>
</refmeta>
<!-- Man page title -->
<refnamediv>
<refname>apt_preferences</>
<refpurpose>Preference control file for APT</>
</refnamediv>
<RefSect1><Title>Description</>
<para>
The APT preferences file <filename>/etc/apt/preferences</> controls
various aspects of the APT system. It is meant to be manipulable
either by user or by software. The file consists of a number of
records formed like those in dpkg status file: blocks of text
(paragraphs) separated by blank lines, each line of text consisting
of a tag followed by a colon, space and a string.
<para>
A main purpose of the preferences file is to let the user control
which version of a package will be selected for installation.
</RefSect1>
<RefSect1><Title>Version Selection Policy</>
<para>
When multiple sources are named in <filename>/etc/apt/sources.list</>,
APT maintains an internal list of all available versions of each
package, along with the release(s) to which each belongs and its
source.
<para>
In order to decide which version of a package to select, APT assigns a
priority to each available version and selects the version with the
highest priority. If two versions have the same priority then the
later one is selected. There are two exceptions to this, however.
First, a version of a package that is earlier than the version that
is installed is never selected if its priority is 1000 or less.
Second, a version of a package is never selected if its priority is
less than 0.
<para>
It is possible to think of the priorities in strata:
<VariableList>
<VarListEntry><term>above 1000</term>
<ListItem><Para>
Priorities that are high enough to cause a downgrade
</VarListEntry>
<VarListEntry><term>1000</term>
<ListItem><Para>
The downgrade prevention barrier
</VarListEntry>
<VarListEntry><term>101 to 1000</term>
<ListItem><Para>
Priorities that are high enough to cause an upgrade or sidegrade,
but not high enough to cause a downgrade.
990 is the priority assigned to all versions belonging to the
target release. (The target release can be specified on the
&apt-get; command line using the <option/--target-release/ option.)
Versions of packages belonging to other releases are assigned
priority 500, unless those releases are pinned as described below.
</VarListEntry>
<VarListEntry><term>100</term>
<ListItem><Para>
Priority of the currently installed version
</VarListEntry>
<VarListEntry><term>0 to 99</term>
<ListItem><Para>
Priorities not high enough to cause up-, side- or downgrade.
A version of sub-100 priority is only selected if it is the only
version available (because it necessarily has lower priority
than the currently installed version).
Versions from the <literal/experimental/ archive are assigned
priority 1.
</VarListEntry>
<VarListEntry><term>less than 0</term>
<ListItem><Para>
Priorities low enough to force removal.
</VarListEntry>
</VariableList>
<para>
Priorities may be manually assigned to one particular version of each
package, called the "pin". Assigning a priority greater than 1000 to
a pin will allow APT to downgrade in order to get to that version.
Assigning a priority less than 100 to a pin will prevent APT from
installing that version unless it is the only version available.
<para>
Thus, e.g., a method for using &apt-get; to track the <literal/stable/
archive even though one includes sources for the <literal/testing/
archive in <filename>/etc/apt/sources.list</> is to assign a priority
to <literal/stable/ versions that is higher than that assigned to
<literal/testing/ versions, but is beneath the downgrade prevention
barrier, so that <literal/testing/ versions installed using the
<option/--target-release/ option are not downgraded.
<para>
Pinning a package at a particular version with a particular priority
is done like this:
<informalexample><programlisting>
Package: apt
Pin: version 0.4.0
Pin-Priority: 1001
</programlisting></informalexample>
The first line specifies the package; the second specifies the pin version;
the last specifies the priority of this pin. The first word of the pin
specification may be <literal/version/, <literal/release/ or <literal/origin/
(i.e., source). The remainder of the field is as described in the
Version Selection Semantics section below.
<para>
Pinning a release, i.e., pinning all the packages listed in a
particular <filename/Packages/ file at the versions listed in that file,
with a particular priority is done like this:
<informalexample><programlisting>
Package: *
Pin: release v=2.1*
Pin-Priority: 998
</programlisting></informalexample>
The first word of the pin specification may be <literal/release/
or <literal/origin/ (i.e., source). The remainder of the field is
as described in the Version Selection Semantics section below.
<para>
If there is more than one entry that pins a particular release,
only the first one is used.
<para>
This kind of entry can be overridden by an entry that pins a
particular version of a package.
<para>
If there is no such entry for a particular release then APT behaves
as if there were such an entry, with a pin priority of 500.
<para>
If the Pin-Priority: field is omitted then the pin priority
defaults to one less than the last value specified on a
release Pin-Priority: line.
<para>
Some archives such as the <literal/experimental/ archive are marked
<literal/Not Automatic/ and are given a priority of 1, thus sending
them to the bottom of the selection pile.
<RefSect2><title>Interesting Effects</>
<para>
A downgrade is not preformed unless the version to install has
priority greater than 1000. Note that it is therefore possible
that a later, lower priority version will be selected in preference
to an earlier, higher (but not higher than 1000) priority version.
For instance, if package versions <literal/1.0/, <literal/1.1/ and
<literal/1.2/ of package foo are available with <literal/1.1/
currently installed, and the priorities of the versions are 950,
100 and 800 repectively, then the winning version will be
<literal/1.2/.
<para>
Users of third-party packages such as the GNOME packages from
Ximian can use the pinning mechanism to force the selection of these
packages by setting the priority of the preferred origin or source
sufficiently high.
<para>
It is also possible to mass downgrade from one set of packages to
another by assigning a priority greater than 1000 to the desired
release.
</RefSect2>
</RefSect1>
<RefSect1><Title>Version Specification Semantics</>
<para>
The specification of package versions can be done in three ways:
by version, by release or by source (corresponding to the
three keywords <literal/version/, <literal/release/ and
<literal/origin/, respectively).
<para>
Specification by version involves matching the package version identifier.
This can be done either exactly (e.g., <literal/2.1.3/) or by prefix
pattern (e.g., <literal/2.1*/). Such a pattern can be used, e.g., to
ignore the Debian version (i.e., the latter part of the version
identifier, beginning with the hyphen). When several version
identifiers match the prefix pattern then the rule is that the
latest version is specified.
<para>
Version specification is used in many different parts of APT, not just in
the preferences file.
<para>
Specification by release involves matching the properties of a release as
described by the <filename/Release/ files that APT downloads during an
update. A release specification is a comma-separated list of specifiers,
each of which consists of a one-letter key, the equals sign, and a string.
Some examples:
<informalexample><programlisting>
v=2.1*,o=Debian,c=main
l=Debian
a=stable
</programlisting></informalexample>
<para>
The available keys are:
<VariableList>
<VarListEntry><term>a=Archive</term>
<ListItem><Para>
This specifies the archive, e.g., <literal/stable/ or <literal/unstable/.
The pseudo-archive <literal/now/ consists of all the packages that are
currently installed.
</VarListEntry>
<VarListEntry><term>c=Component</term>
<ListItem><Para>
This specifies the component of the archive, e.g., <literal/main/ or
<literal/contrib/. This specifier is ignored if the archive has no
components.
</VarListEntry>
<VarListEntry><term>v=Version</term>
<ListItem><Para>
This specifies the release level of the archive, i.e., the Debian
release version, e.g., <literal/3.0/ or <literal/2.1r2/.
</VarListEntry>
<VarListEntry><term>o=Origin</term>
<ListItem><Para>
This specifies the origin of the archive. In the case of Debian the
origin is <literal/Debian/.
</VarListEntry>
<VarListEntry><term><term>l=Label</term>
<ListItem><Para>
This specifies the label of the distribution. In the case
of Debian the label is <literal/Debian/.
</VarListEntry>
</VariableList>
<para>
If the release specification contains no equals sign then it is
interpreted as a shorthand specification. If the first character of the
shorthand specification is a digit then it is considered to be a release
version specifier; otherwise it is considered to be an archive specifier.
A shorthand specification is easily given as the argument to the
&apt-get; <option/--target-release/ option.
<para>
The final specification method is by source. This is simply the name
of the site where the package files were obtained. The null string is
used for file URIs.
</RefSect1>
<RefSect1><Title>Examples</>
<para>
The following preferences file will make APT track <literal/stable/;
i.e., apt-get will always to upgrade to the latest version in the
<literal/stable/ archive when its <option/install/ or <option/upgrade/
or <option/dist-upgrade command is used.
Packages may be upgraded individually to their testing versions,
by doing
<informalexample><programlisting>
apt-get install package/testing
</programlisting></informalexample>
but APT will not track these.
The last paragraph prevents APT from installing any other versions
than those listed.
Remember to list both <literal/stable/ and <literal/testing/
archive sources in your &sources.list; file.
<informalexample><programlisting>
Package: *
Pin: release a=stable
Pin-Priority: 900
<para>
Package: *
Pin: release o=Debian
Pin-Priority: -10
</programlisting></informalexample>
<para>
The following preferences file will make APT track <literal/testing/.
Packages may be upgraded individually to their <literal/unstable/
versions, and apt will then track the <literal/unstable/ version.
<informalexample><programlisting>
Package: *
Pin: release a=testing
Pin-Priority: 900
<para>
Package: *
Pin: release a=unstable
Pin-Priority: 800
<para>
Package: *
Pin: release o=Debian
Pin-Priority: -10
</programlisting></informalexample>
<RefSect1><Title>See Also</>
<para>
&apt-get; &apt-cache; &apt-conf; &sources.list;
</RefSect1>
&manbugs;
&manauthor;
</refentry>
Reply to: