Bug#115517:
On Fri, 2002-10-18 at 03:14, Bill Wohler wrote:
> I've attached a diff that fixes one spelling error and adjusts some
> awkward text. The editors I've worked with forbid the use of i.e. and
> e.g., so I've replaced those as well.
OK, I've eliminated them.
> Also, don't jump back and forth between the terms origin and source.
I use 'origin' to refer to that which is specified by the
"Origin:" line in a Release file. I use 'source' to refer
to the fqdn of the host where the package was obtained.
These are different. It is just unfortunate that the apt
preferences file uses the keyword 'origin' to designate source
source, when the word 'source' is already used for that
purpose, as in "/etc/apt/sources.list". I have filed a bug
report about this.
> It's very confusing. Since the parameter is "o", let's stick with
> origin and nuke references to source.
You are confusing origin and source (as I define those
terms above), which is why I tried to distinguish them by
using different terms.
> The major problem with this document is the organization. The details
> are discussed first with no context.
I attach my latest draft of the man page. I think you
looked at an earlier draft when you prepared your diff.
(I didn't want to post every revision that I have
circulated to people to the BTS, lest bug log #115517 grow
too large.) I have integrated some of your changes, and
I hope that the other changes in this version cure some of
the problems you mentioned with organization.
I'd be glad if you would read it over again and offer
a second round of criticisms.
--
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, for example, 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 name;
the second line specifies the pin version;
the last line specifies the priority of this pin.
The pin version specification is as described in the
Version Selection Semantics section below.
Keywords permitted are <literal/version/, <literal/release/ and <literal/origin/.
<para>
Pinning a release (that is, pinning all the packages listed in a
particular <filename/Packages/ file at the versions listed in that file)
with a particular priority is done by putting an asterisk as the package
name, like this:
<informalexample><programlisting>
Package: *
Pin: release v=2.1*
Pin-Priority: 998
</programlisting></informalexample>
The second line specifies the pin version;
the last line specifies the priority of this pin.
The pin version specification is as described in the
Version Selection Semantics section below.
Keywords permitted are <literal/release/ and <literal/origin/.
<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 performed 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 number, by release or by source (signified by the three keywords
<literal/version/, <literal/release/ and <literal/origin/, respectively).
<RefSect2><title>Specification by version number</>
<para>
A version number specification begins with the keyword <literal/version/.
<para>
Specification by version number involves matching the package version
identifier. This can be done either exactly (for example, <literal/2.1.3/) or
by prefix pattern (for example, <literal/2.1*/). A prefix pattern might be used,
for example, to ignore the Debian revision level (that is, the latter part of the
version identifier beginning with the hyphen). When several version
identifiers match the given prefix pattern then the rule is that the latest
version is specified.
<para>
Specification by version number is used in many different parts of APT,
not just in the preferences file.
</RefSect2>
<RefSect2><title>Specification by release</>
<para>
A release specification begins with the keyword <literal/release/.
<para>
Specification by release involves specifying 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 specifiers are:
<VariableList>
<VarListEntry><term>a=Archive</term>
<ListItem><Para>
This specifies the archive; for example, <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; for example, <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, that is, the Debian
release version; for example, <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 number 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.
</RefSect2>
<RefSect2><title>Specification by source</>
<para>
A source specification begins with the keyword <literal/origin/.
<para>
The source specification is simply the fully qualified domain name
of the host where the version was obtained; for example, ftp.debian.org.
The null string is used for local files.
</RefSect2>
</RefSect1>
<RefSect1><Title>Examples</>
<para>
The following preferences file will make APT track <literal/stable/:
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: