apt_preferences(5) revision -- comments, please
Trying to figure out the apt priority system I read the
apt_preferences(5) man page. I thought it could use some
clarification, so I took a stab at editing it. However,
I am not sure I have interpreted it all correctly, so I would
like to ask readers of this list who understand apt intimately
to go through this draft carefully. (It's in sgml, but it
is easy to read between the tags.) I have included some
questions in BLOCK LETTERS to which I would appreciate answers.
Thanks
// Thomas Hood
<!-- -*- 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
(stanzas) separated by blank lines; each line of text consisting
of a tag followed by a colon and a string.
</RefSect1>
<RefSect1><Title>Versioning</>
<para>
One purpose of the preferences file is to let the user control which
version of a package will be selected for installation. The selection
can be made in a number of ways: by version, by release or by source.
<para>
Selection 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, the latest version will always be selected.
<para>
Version selection is used in many different parts of APT, not just in the
preferences file.
<para>
Selection 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 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 may be omitted 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 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.
Shorthand specifications are especially useful on the command line.
<para>
The final selection 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>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 version 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 not installed if its priority is
less than 0. [IS THIS CORRECT?]
<para>
It is possible to think of the priorities in strata:
<VariableList>
<VarListEntry><term>above 1000</term>
<ListItem><Para>
Priorities high enough to induce a downgrade
</VarListEntry>
<VarListEntry><term>1000</term>
<ListItem><Para>
The downgrade prevention barrier
</VarListEntry>
<VarListEntry><term>101 to 999</term>
<ListItem><Para>
Ordinary priorities.
990 is the priority set by the <option/--target-release/ &apt-get; option.
989 is the maximum value for automatically assigned priorities. [CORRECT?]
500 is the priority of all the default package files. [WHAT DOES THIS MEAN?!?]
</VarListEntry>
<VarListEntry><term>100</term>
<ListItem><Para>
Priority of the currently installed version
</VarListEntry>
<VarListEntry><term>0 to 99</term>
<ListItem><Para>
Non-automatic priorities. 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.
</VarListEntry>
<VarListEntry><term>less than 0</term>
<ListItem><Para>
Priority of a version never to be selected under any circumstances.
</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 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
Versioning section above.
<para>
Pinning all the packages listed in a particular <filename/Packages/ file
at the versions 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 default pin specification may be <literal/release/
or <literal/origin/ (i.e., source). If more than one entry of this kind
appears in the preferences file, only the first one that applies will be
used. This kind of entry can be overridden by an entry that pins a
particular package. [IS THIS TRUE? CLARIFICATION NEEDED HERE.]
<para>
If the Pin-Priority field is omitted then the value defaults to 989.
<para>
Some archives such as the <literal/experimental/ archive are marked
<literal/Not Automatic/ and fall to the bottom of the selection pile.
[DOES THIS MEAN THAT THEY EFFECTIVELY HAVE PRIORITIES OF LESS THAN
100, OR EFFECTIVE PRIORITIES OF LESS THAN 0?]
<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 Helix GNOME can use the pinning
mechanism to force the usage of these packages by setting the priority
of the preferred origin 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>Examples</>
<para>
The following preferences file will make APT track stable;
i.e., it will cause apt-get always to upgrade to the latest
stable version 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.
Remember to list both stable and testing 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 testing.
Packages may be upgraded individually to their unstable versions,
and apt will then track the unstable version.
Remember to list both testing and unstable in your sources.list file.
<informalexample><programlisting>
Package: *
Pin: release a=testing
Pin-Priority: 900
<para>
Package: *
Pin: release a=unstable
Pin-Priority: 200
<para>
Package: *
Pin: release o=Debian
Pin-Priority: -10
</programlisting></informalexample>
<RefSect1><Title>See Also</>
<para>
&apt-cache; &apt-conf;
</RefSect1>
&manbugs;
&manauthor;
</refentry>
Reply to: