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 <[EMAIL PROTECTED]>. 08 December 2002 APT_PREFERENCES(5)