Re: apt_preferences(5) revision -- comments, please
On Wed, 2002-10-09 at 07:54, Jason Gunthorpe wrote:
> All the priority mechanism does is select which version APT/Dselect see as
> being 'new'. It's possible to make the version (and potentially package)
> completely vanish with negative priorities.
Please read the paragraph as I have revised it (slightly).
FYI I swapped the order of the Version Selection Policy
and the Version Selection Semantics (formerly "Versioning")
sections.
> Is that all of them?
There remains a "WHAT DOES THIS MEAN?!?". :)
If this checks out, perhaps we can convert this to easily
readable text and post again on various lists for more
feedback. I am rather worried about having introduced
falsehoods. Thanks! // 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 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 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.
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 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/
(meaning "source"). The remainder of the field is as described in the
Version Selection Semantics section below.
<para>
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 default pin specification may be <literal/release/
or <literal/origin/ (meaning "source"). The remainder of the field is
as described in the Version Selection Semantics section below.
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 entries that pin particular
versions of packages.
<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 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 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 Selection Semantics</>
<para>
The selection of package versions can be done in three 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>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-get; &apt-cache; &apt-conf;
</RefSect1>
&manbugs;
&manauthor;
</refentry>
Reply to: