Re: apt_preferences man page
Because this matter was mentioned in the 26 November Debian
Weekly News, it seems appropriate to post an update.
Susan Kleinmann took the bull by the horns and rewrote
the page from scratch. I have proposed some revisions
and hopefully we'll have a finished product soon. I
append the latest version I have, in the hopes that
people will point out any remaining errors.
--
Thomas Hood
APT_PREFERENCES(5) APT_PREFERENCES(5)
NAME
apt_preferences - Preference control file for APT
DESCRIPTION
The APT preferences file /etc/apt/preferences can be used
to control which version of a package will be selected for
installation.
Several versions of a package may be available for instal
lation when the sources.list(5) file contains references
to more than one release (for example, stable and test
ing), and several instances of the same version of a pack
age may be available when the file contains references to
more than one download site for a particular release. APT
assigns a "priority" to each instance that is available.
(In what follows, an "instance" will be an instance of a
package that is available according to sources.list(5).)
Subject to dependency constraints, apt-get installs the
instance with the highest priority.
The APT preferences file overrides the priorities that APT
assigns to package instances by default, thus giving the
user control over which one is selected.
APT'S DEFAULT PRIORITY ASSIGNMENTS
If there is no preferences file, or if there is no entry
in the file that applies to a particular instance, then
the priority assigned to an instance is the priority
assigned to the release to which that instance belongs.
It is possible to single out a release, called the "target
release", which receives a higher priority than other
releases. The target release can be set on the apt-get
command line or in the APT configuration file
/etc/apt/apt.conf. For example,
# Command to install the version of some-pkg from the testing
release
apt-get install -t testing some-pkg
# Configuration setting to make stable the target release
APT::Default-Release "stable";
If a target release has been specified, then APT uses the
following algorithm to set the priorities of the instances
of a package. Assign:
priority 100
to the instance of a package that is already
installed (if any).
priority 500
to the instances of a package that are not
installed and do not belong to the target release.
priority 990
to the instances of a package that are not
installed and belong to the target release.
If no target release has been specified, then APT simply
assigns priority 100 to all installed package instances
and priority 500 to all uninstalled package instances.
APT then applies the following rules to determine which
instance of a package to install:
· Never downgrade an installed package unless the priority
of an available instance of the package exceeds 1000.
(Note that none of APT's default priorities exceeds this
threshold; such high priorities can only be set in the
preferences file.)
· Always install or upgrade to the highest priority
instance of a package.
· If two or more instances of a package have the same pri
ority, install or upgrade to the most recent one.
In a typical situation, the installed instance of a pack
age (priority 100) is not as recent as one of the
instances available from the sites and releases listed in
the sources.list(5) file (priority 500 or 990). Then the
package will be upgraded with the command: apt-get install
or apt-get dist-upgrade.
Rarely, the installed instance of a package is more recent
than any of the other available instances. This package
will not be downgraded.
Sometimes the installed instance of a package is more
recent than the version belonging to the target release,
but not as recent as a version belonging to some other
release. Such a package will indeed be upgraded, because
at least one of the available instances has a higher pri
ority than the installed instance.
THE EFFECT OF APT PREFERENCES
The APT preferences file allows the system administrator
to customize priorities. The preferences file consists of
one or more multi-line records separated by blank lines.
Records can have one of two forms:
· The first form pins a priority (a "Pin-Priority") to a
named package version. For example, the following
record pins a high priority to all versions of the perl
package whose version name begins with "5.8":
Package: perl
Pin: version 5.8*
Pin-Priority: 1001
· The second form pins a priority to all of the package
versions in a given release (that is, to all the ver
sions of packages that are listed in a Release file), or
to all of the package instances coming from a particular
Internet site.
A note of caution: the keyword used in the APT prefer
ences file to select the source site is "origin". This
may lead one to confuse the source site with the "Ori
gin:" of a release as specified in a Release file.
Recall that what follows the "Origin:" tag in a Release
file generally is not an Internet site address but an
author or vendor name, such as "Debian" or "Ximian".
This second-form entry in the APT preferences file
applies only to groups of packages. For example, the
following record causes APT to assign a high priority to
all package instances available from the local site:
Package: *
Pin: origin ""
Pin-Priority: 999
The following record causes APT to assign a low priority
to all package versions belonging to any release whose
"Archive" (a) name is "unstable":
Package: *
Pin: release a=unstable
Pin-Priority: 50
The following record causes APT to assign a high prior
ity to all package versions belonging to any release
whose "Archive" (a) name is "stable" and whose release
"Version" (v) name is "3.0":
Package: *
Pin: release a=unstable, v=3.0
Pin-Priority: 50
HOW APT INTERPRETS PRIORITIES
Priorities (P) assigned in the APT preferences file must
be positive or negative integers. They are interpreted as
follows (roughly speaking):
P > 1000
causes an instance to be installed even if this
constitutes a downgrade of the installed package
990 < P <=1000
causes an instance to be installed even if it does
not come from the target release, unless the
installed instance is more recent
500 < P <=990
causes an instance to be installed unless there is
an instance available belonging to the target
release or the installed version is more recent
100 < P <=500
causes an instance to be installed unless there is
an instance available belonging to some other
release or the installed version is more recent
0 <= P <=100
causes an instance to be installed only if there is
no installed instance of the package
P < 0 prevents the instance from being installed
If one of the records of the first form described above
matches an available package instance, then that record
determines the priority of the instance. If two records
of the first form match an available instance, then the
first record encountered determines the priority. If two
records of the second form match an available instance,
then the first record encountered determines the priority.
For example, suppose the APT preferences file contains the
three records presented earlier:
Package: perl
Pin: version 5.8*
Pin-Priority: 1001
Package: *
Pin: origin ""
Pin-Priority: 999
Package: *
Pin: release unstable
Pin-Priority: 50
Then:
· The most recent available version of the perl package
will be installed, so long as that version's version
name begins with "5.8". If any 5.8* version of perl is
available and the installed version is 5.9*, then perl
will be downgraded.
· A version of any package other than perl that is avail
able from the local system and belongs to an unstable
release has priority over the version from the target
release.
· An instance of a package whose source is not the local
system but some other site listed in sources.list(5),
and which belongs to an unstable release, is only
installed if it is selected for installation and no
instance of the package is already installed.
DETERMINATION OF PACKAGE VERSION AND RELEASE PROPERTIES
The sites listed in a system's sources.list(5) file should
provide Packages and Release files to describe the package
instances available in each directory at that site.
The Packages file is normally found in the directory
for example,.../dists/stable/main/binary-i386/Packages. It
consists of a series of multi-line records, one for each
package available in that directory. Only two lines in
each record are relevant for setting APT priorities:
the Package: line
gives the package name
the Version: line
gives the version name for the named package
The Release file is normally found in the directory
for example, .../dists/stable/Release, or
.../dists/woody/Release. It consists of a single multi-
line record which applies to all of the package instances
in the directory tree below its parent. Unlike the Pack
ages file, nearly all of the lines in a Release file are
relevant for setting APT priorities:
the Archive: line
names the archive to which all the package
instances in the directory tree belong. For exam
ple, the line Archive: stable specifies that all of
the packages in the directory tree below the parent
of the Release file are in the stable archive.
Specifying this value in the APT preferences file
would require the line:
Pin: release a=stable
the Version: line
names the release version. For example, the pack
age instances in the tree might belong to Debian
GNU/Linux version 3.0. There is normally no
version name for releases of the "testing" or
"unstable" archive. Specifying this in the APT
preferences file would require one of the following
lines:
Pin: release v=3.0
Pin: release a=stable v=3.0
Pin: release 3.0
the Component: line
names the licensing component associated with the
package instances in the directory tree of the
Release file. For example, the line Component:
main specifies that all the instances in the direc
tory tree are from the main component, meaning that
they are licensed under terms listed in the Debian
Free Software Guidelines. Specifying this compo
nent in the APT preferences file would require the
line:
Pin: release c=main
the Origin: line
names the producer of the package instances in the
directory tree of the Release file. Most commonly,
this is Debian. Specifying this origin in the APT
preferences file would require the line:
Pin: release o=Debian
the Label: line
seems redundant. Most commonly, this is Debian.
Specifying this label in the APT preferences file
would require the line:
Pin: release l=Debian
All of the Packages and Release files retrieved from sites
listed in the sources.list(5) file are kept in the direc
tory /var/lib/apt/lists, or in the file named by the vari
able Dir::State::Lists in the apt.conf file. For example,
the file debian.lcs.mit.edu_debian_dists_unstable_con
trib_binary-i386_Release contains the Release file
retrieved from the site debian.lcs.mit.edu for binary-i386
architecture files from the contrib component of the
unstable release.
OPTIONAL LINES IN AN APT PREFERENCES RECORD
Each record in the APT preferences file can optionally
begin with a line beginning with the word Explanation:.
This provides an opportunity to comment on the record.
The Pin-Priority: line in each APT preferences record is
optional. If omitted, APT assigs a priority of 1 less
than the last value specified on a line beginning with
Pin-Priority: release ...
EXAMPLES
TRACKING STABLE
The following APT preferences file will cause APT to
assign a priority higher than the default (500) to all
package versions belonging to a stable release and a pro
hibitively low priority to package versions belonging to
other Debian releases.
Package: *
Pin: release a=stable
Pin-Priority: 900
Explanation: Do not install any Debian-originated package
instances
Explanation: other than those listed above
Package: *
Pin: release o=Debian
Pin-Priority: -10
With a typical sources.list(5) file and the above prefer
ences file, any of the following commands will cause APT
to upgrade to the latest stable version(s).
apt-get install package-name
apt-get upgrade
apt-get dist-upgrade
The following command will cause APT to upgrade the speci
fied package to the latest version from the testing
release; further upgrades will not occur automatically,
however:
apt-get install package/testing
TRACKING TESTING
The following APT preferences file will cause APT to
assign a high priority to package versions from the test
ing release, a lesser priority to package versions from
the unstable release, and a prohibitively low priority to
package versions from other Debian releases.
Package: *
Pin: release a=testing
Pin-Priority: 900
Package: *
Pin: release a=unstable
Pin-Priority: 800
Package: *
Pin: release o=Debian
Pin-Priority: -10
With the above preferences file, any of the following com
mands will cause APT to upgrade to the latest testing ver
sion(s).
apt-get install package-name
apt-get upgrade
apt-get dist-upgrade
The following command will cause APT to upgrade the speci
fied package to the latest version from the unstable
release. Thereafter, apt-get dist-upgrade and the others
will cause upgrade of the package to the latest unstable
version.
apt-get install package/unstable
SEE ALSO
apt-get(8) apt-cache(8) apt.conf(5) sources.list(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>.
08 December 2002 APT_PREFERENCES(5)
Reply to: