Re: Some myths regarding apt pinning
Bruno Diniz de Paula <diniz () cs ! rutgers ! edu> wrote:
> But before looking at the priority, it looks at the version
> of the packages.
No, it is the other way around, I believe. First priority,
then version.
I include an updated edition of the apt preferences(5)
manual page; it hasn't yet been uploaded. Some of the
formatting may be out of whack, but here goes.
// 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
installation when the file contains references to more
than one distribution (for example, stable and test
ing); furthermore, several instances of the same ver
sion of a package may be available when the file con
tains references to more than one download site for a
particular distribution. 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 .) Subject to dependency con
straints, apt-get installs the instance with the high
est priority. If two instances have the same priority
then it installs the more recent one, that is, the one
with the higher version number.
The APT preferences file overrides the priorities that
APT assigns to package instances by default, thus giv
ing the user control over which one is selected for
installation.
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 that instance
is the priority of the distribution to which that
instance belongs. It is possible to single out a dis
tribution, called the "target release", which receives
a higher priority than other distributions. 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 testing version of some-package
apt-get install -t testing some-package
# Config 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 that is already installed (if
any).
priority 500
to the instances that are not installed and do
not belong to the target release.
priority 990
to the instances 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, listed in order
of precedence, to determine which instance of a package
to install.
· Never downgrade unless the priority of an available
instance exceeds 1000. ("Downgrading" is installing
a less recent version of a package in place of a more
recent version. Note that none of APT's default pri
orities exceeds 1000; such high priorities can only
be set in the preferences file.)
· Install the highest priority instance.
· If two or more instances have the same priority,
install the most recent one.
· If two or more instances have the same version num
ber, install the one whose source is listed earliest
in . (The installed instance, if there is one, is
always preferred in such a comparison unless apt-get
--reinstall is used.)
In a typical situation, the installed instance of a
package (priority 100) is not as recent as one of the
instances available from the sources listed in the
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. The
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 distribution. Such a package will indeed be
upgraded, because at least one of the available
instances has a higher priority than the installed
instance.
THE EFFECT OF APT PREFERENCES
The APT preferences file allows the system administra
tor to customize priorities. The file consists of one
or more multi-line records separated by blank lines.
Records can have one of two forms, a specific form and
a general form.
· The "specific" form pins a priority (a "Pin-Prior
ity") to a specified package and specified version or
version range. For example, the following record
pins a high priority to all versions of the perl
package whose version number begins with "5.8".
Package: perl
Pin: version 5.8*
Pin-Priority: 1001
· The "general" form pins a priority to all of the
package versions in a given distribution (that is, to
all the versions of packages that are listed in a
certain Release file), or to all of the package
instances coming from a particular Internet site, as
identified by its fully qualified domain name.
This general-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
A note of caution: the keyword used here is "origin".
This should not be confused with the "Origin:" of a
distribution as specified in a Release file. What
follows the "Origin:" tag in a Release file is usu
ally not an Internet site address but an author or
vendor name, such as "Debian" or "Ximian".
The following record causes APT to assign a low pri
ority to all package versions belonging to any dis
tribution whose "Archive" (a) name is "unstable".
Package: *
Pin: release a=unstable
Pin-Priority: 50
The following record causes APT to assign a high pri
ority to all package versions belonging to any
release whose "Archive" (a) name is "stable" and
whose release "Version" (v) number 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 inter
preted as follows (roughly speaking):
P > 1000
causes an instance to be installed even if this
constitutes a downgrade of the 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
distribution 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 specific-form records described above
matches an available package instance, then that record
determines the priority of the instance. If two spe
cific-form records match an available instance, then
the first record encountered determines the priority.
If two general-form records 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
number 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.
· An instance of any package other than perl that is
available from the local system has priority over
other instances, even instances belonging to the tar
get release.
· An instance of a package whose origin is not the
local system but some other site listed in , and
which belongs to an "unstable" distribution, is only
installed if it is selected for installation and no
instance of the package is already installed.
DETERMINATION OF VERSION AND DISTRIBUTION PROPERTIES
The locations listed in a system's file should provide
Packages and Release files to describe the package
instances available at that location.
The Packages file is normally found in the directory
for example, .../dists/stable/main/binary-i386/Pack
ages. 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 number 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 Packages 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
example, 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 pref
erences file would require the line:
Pin: release a=stable
the Version: line
names the release version. For example, the
package instances in the tree might belong to
Debian GNU/Linux release version 3.0. There is
normally no version number for the "testing" and
"unstable" distributions because they have not
yet been released. Specifying this in the APT
preferences file would require one of the fol
lowing 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 Compo
nent: main specifies that all the instances in
the directory tree are from the main component,
meaning that they are licensed under terms
listed in the Debian Free Software Guidelines.
Specifying this component 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 ori
gin 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
locations listed in the file are kept in the directory
/var/lib/apt/lists, or in the file named by the vari
able Dir::State::Lists in the apt.conf file. For exam
ple, the file debian.lcs.mit.edu_debian_dists_unsta
ble_contrib_binary-i386_Release contains the Release
file retrieved from the site debian.lcs.mit.edu for
binary-i386 architecture files from the contrib compo
nent of the unstable distribution.
OPTIONAL LINES IN AN APT PREFERENCES RECORD
Each record in the APT preferences file can optionally
begin with one or more lines 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 distribution and
a prohibitively low priority to package versions
belonging to other Debian distributions.
Package: *
Pin: release a=stable
Pin-Priority: 900
Explanation: Uninstall or do not install any Debian-originated
Explanation: instances other than those in the stable distro
Package: *
Pin: release o=Debian
Pin-Priority: -10
With a suitable file and the above preferences 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
specified package to the latest version from the test
ing distribution; further upgrades will not occur auto
matically, 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
testing distribution, a lesser priority to package ver
sions from the unstable distribution, and a pro
hibitively low priority to package versions from other
Debian distributions.
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 APT preferences file, any of the follow
ing commands will cause APT to upgrade to the latest
testing version(s).
apt-get install package-name
apt-get upgrade
apt-get dist-upgrade
The following command will cause APT to upgrade the
specified package to the latest version from the unsta
ble distribution. 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
26 January 2003 APT_PREFERENCES(5)
--
Thomas Hood <jdthood@yahoo.co.uk>
Reply to: