From 24f6490f4ba3572069619d88e053db5cb07e846c Mon Sep 17 00:00:00 2001 From: Arch Librarian Date: Mon, 20 Sep 2004 17:05:19 +0000 Subject: * Replace SGML manpages with XML man pages from richard... Author: mdz Date: 2004-02-07 21:48:14 GMT * Replace SGML manpages with XML man pages from richard.bos@xs4all.nl (Closes: #230687) --- doc/apt_preferences.5.xml | 528 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 528 insertions(+) create mode 100644 doc/apt_preferences.5.xml (limited to 'doc/apt_preferences.5.xml') diff --git a/doc/apt_preferences.5.xml b/doc/apt_preferences.5.xml new file mode 100644 index 000000000..db32b800e --- /dev/null +++ b/doc/apt_preferences.5.xml @@ -0,0 +1,528 @@ + + +%aptent; + +]> + + + + + apt_preferences + 5 + + + + + apt_preferences + Preference control file for APT + + + +Description +The APT preferences file /etc/apt/preferences +can be used to control which versions of packages will be selected +for installation. + +Several versions of a package may be available for installation when +the &sources-list; file contains references to more than one distribution +(for example, stable and testing). +APT assigns a priority to each version that is available. +Subject to dependency constraints, apt-get selects the +version with the highest priority for installation. +The APT preferences file overrides the priorities that APT assigns to +package versions by default, thus giving the user control over which +one is selected for installation. + +Several instances of the same version of a package may be available when +the &sources-list; file contains references to more than one source. +In this case apt-get downloads the instance listed +earliest in the &sources-list; file. +The APT preferences file does not affect the choice of instance, only +the choice of version. + +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 version then the priority assigned to that +version is the priority of the distribution to which that version +belongs. It is possible to single out a distribution, "the target release", +which receives a higher priority than other distributions do by default. +The target release can be set on the apt-get command +line or in the APT configuration file /etc/apt/apt.conf. +For example, + + +apt-get install -t testing some-package + + +APT::Default-Release "stable"; + + + +If the target release has been specified then APT uses the following +algorithm to set the priorities of the versions of a package. Assign: + + + +priority 100 +to the version that is already installed (if any). + + + +priority 500 +to the versions that are not installed and do not belong to the target release. + + + +priority 990 +to the versions that are not installed and belong to the target release. + + + + +If the target release has not been specified then APT simply assigns +priority 100 to all installed package versions and priority 500 to all +uninstalled package versions. + +APT then applies the following rules, listed in order of precedence, +to determine which version of a package to install. + +Never downgrade unless the priority of an available +version 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 priorities exceeds 1000; such high priorities can only be set in +the preferences file. Note also that downgrading a package +can be risky.) +Install the highest priority version. +If two or more versions have the same priority, +install the most recent one (that is, the one with the higher version +number). +If two or more versions have the same priority and +version number but either the packages differ in some of their metadata or the +--reinstall option is given, install the uninstalled one. + + + +In a typical situation, the installed version of a package (priority 100) +is not as recent as one of the versions available from the sources listed in +the &sources-list; file (priority 500 or 990). Then the package will be upgraded +when apt-get install some-package +or apt-get upgrade is executed. + + +More rarely, the installed version of a package is more recent +than any of the other available versions. The package will not be downgraded +when apt-get install some-package +or apt-get upgrade is executed. + +Sometimes the installed version 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 +when apt-get install some-package +or apt-get upgrade is executed, +because at least one of the available versions has a higher +priority than the installed version. + + +The Effect of APT Preferences + +The APT preferences file allows the system administrator to control the +assignment of 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 assigns a priority (a "Pin-Priority") to a +specified package and specified version or version range. For example, +the following record assigns 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 assigns 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 +versions coming from a particular Internet site, as identified by the +site's fully qualified domain name. + +This general-form entry in the APT preferences file applies only +to groups of packages. For example, the following record assigns a high +priority to all package versions 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 not an Internet address +but an author or vendor name, such as "Debian" or "Ximian". + +The following record assigns a low priority to all package versions +belonging to any distribution whose Archive name is "unstable". + + +Package: * +Pin: release a=unstable +Pin-Priority: 50 + + +The following record assigns a high priority to all package versions +belonging to any release whose Archive name is "stable" +and whose release Version 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 interpreted as follows (roughly speaking): + + + +P > 1000 +causes a version to be installed even if this +constitutes a downgrade of the package + + +990 < P <=1000 +causes a version to be installed +even if it does not come from the target release, +unless the installed version is more recent + + +500 < P <=990 +causes a version to be installed +unless there is a version available belonging to the target release +or the installed version is more recent + + +100 < P <=500 +causes a version to be installed +unless there is a version available belonging to some other +distribution or the installed version is more recent + + +0 < P <=100 +causes a version to be installed +only if there is no installed version of the package + + +P < 0 +prevents the version from being installed + + + + +If any specific-form records match an available package version then the +first such record determines the priority of the package version. +Failing that, +if any general-form records match an available package version then the +first such record determines the priority of the package version. + +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. +A version of any package other than perl +that is available from the local system has priority over other versions, +even versions belonging to the target release. + +A version of a package whose origin is not the local +system but some other site listed in &sources-list; and which belongs to +an unstable distribution is only installed if it is selected +for installation and no version of the package is already installed. + + + + + + +Determination of Package Version and Distribution Properties + +The locations listed in the &sources-list; file should provide +Packages and Release files +to describe the packages available at that location. + +The Packages file is normally found in the directory +.../dists/dist-name/component/arch: +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 number for the named package + + + + +The Release file is normally found in the directory +.../dists/dist-name: +for example, .../dists/stable/Release, +or .../dists/woody/Release. +It consists of a single multi-line record which applies to all of +the packages 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 packages +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 a +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 +packages in the tree might belong to Debian GNU/Linux release +version 3.0. Note that there is normally no version number for the +testing and unstable distributions because they +have not been released yet. 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 +packages in the directory tree of the Release file. +For example, the line "Component: main" specifies that +all the packages in the directory tree are from the main +component, which entails 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 originator of the packages 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 +names the label of the packages in the directory tree +of the Release file. 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 &sources-list; file are stored +in the directory /var/lib/apt/lists, or in the file named +by the variable Dir::State::Lists in the apt.conf file. +For example, the file +debian.lcs.mit.edu_debian_dists_unstable_contrib_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 +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 a place for comments. + +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. + + +Explanation: Uninstall or do not install any Debian-originated +Explanation: package versions other than those in the stable distro +Package: * +Pin: release a=stable +Pin-Priority: 900 + +Package: * +Pin: release o=Debian +Pin-Priority: -10 + + + +With a suitable &sources-list; 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 testing distribution; +the package will not be upgraded again unless this command is given +again. + + +apt-get install package/testing + + + + + + Tracking Testing or Unstable + +The following APT preferences file will cause APT to assign +a high priority to package versions from the testing +distribution, a lower priority to package versions from the +unstable distribution, and a prohibitively 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 a suitable &sources-list; file and the above preferences file, +any of the following 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 unstable distribution. +Thereafter, apt-get upgrade will upgrade +the package to the most recent testing version if that is +more recent than the installed version, otherwise, to the most recent +unstable version if that is more recent than the installed +version. + + +apt-get install package/unstable + + + + + + + +See Also + +&apt-get; &apt-cache; &apt-conf; &sources-list; + + + + &manbugs; + &manauthor; + + + -- cgit v1.2.3