X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/bbe8a3f57c602f27d7f41f927458ee72fc7145b0..b55bbd49219548feab8fee50d04048cfa6a7053b:/doc/apt_preferences.5.sgml diff --git a/doc/apt_preferences.5.sgml b/doc/apt_preferences.5.sgml index cb4d0c5a9..7fa2afdf2 100644 --- a/doc/apt_preferences.5.sgml +++ b/doc/apt_preferences.5.sgml @@ -8,221 +8,562 @@ &apt-docinfo; - + apt_preferences 5 - + apt_preferences Preference control file for APT - - Description</> - <para> - The APT preferences file controls various aspects of the APT system. - It is meant to be user editable and manipulatable from software. The file - consists of a number of records formed like the dpkg status file, space - seperated sections of text with at the start of each line tags seperated - by a colon. It is stored in <filename>/etc/apt/preferences</>. - </RefSect1> - - <RefSect1><Title>Versioning</> - <para> - One purpose of the preferences file is to let the user select which version - of a package will be installed. This selection can be made in a number of - ways that fall into three categories, version, release and origin. - <para> - Selection by version can be done by exact match or prefix match. The format - is <literal/2.1.2/ or <literal/2.2*/ for a prefix match. Matching by prefix - can be used to ignore the <literal/r/ in the Debian release versioning, like - <literal/2.1r*/ or to ignore Debian specific revisions, <literal/1.1-*/. - When matching versions with a prefix the highest matching version will - always be picked. - <para> - Selection by release is more complicated and has three forms. The primary - purpose of release selections is to identify a set of packages that match - a specific vendor, or release (ie Debian 2.1). The first two forms are - shortcuts intended for quick command line use. If the first character of the - specification is a digit then it is considered to be a release version match, - otherwise a release label match. Specifications which contain equals are - full release data matches and are a comma seperated list of one letter keys - followed by an equals then by the string. Examples: -<informalexample><programlisting> -v=2.1*,o=Debian,c=main -l=Debian -a=stable -</programlisting></informalexample> - <para> - The data for these matches are taken from the <filename/Release/ files - that APT downloads during an <literal/update/. The available keys are: - <VariableList> - <VarListEntry><term>a= Archive</term> - <ListItem><Para> - This is the common name we give our archives, such as <literal/stable/ or - <literal/unstable/. The special name <literal/now/ is used to designate - the set of packages that are currently installed. - </VarListEntry> - - <VarListEntry><term>c= Component</term> - <ListItem><Para> - Referes to the sub-component of the archive, <literal/main/, - <literal/contrib/ etc. Component may be omitted if there are no - components for this archive. - </VarListEntry> - - <VarListEntry><term>v= Version</term> - <ListItem><Para> - This is a version string with the same properties as in the Packages file. - It represents the release level of the archive. Typical Debian release - numbers look like <literal/2.1r2/ with the r designating the release of - 2.1. New releases are limited to security updates and other important - changes. - </VarListEntry> - - <VarListEntry><term>o= Origin</term> - <ListItem><Para> - This specifies who is providing this archive. In the case of Debian the - string will read <literal/Debian/. Other providers may use their own - string. - </VarListEntry> - - <VarListEntry><term><term>l= Label</term> - <ListItem><Para> - This carries the encompassing name of the distribution. For Debian proper - this field reads <literal/Debian/. For derived distributions it should - contain their proper name. - </VarListEntry> - </VariableList> - <para> - The final selection method is by origin. This is simply the site name - of the originating package files. The empty string is used for file URIs. - <para> - Version selection, particularly the latter two methods, are used in many - different parts of APT, not just the preferences file. - </RefSect1> - - <RefSect1><Title>Candidate Version Policy</> - <para> - Internally APT maintains a list of all available versions for all packages. - If you place multiple releases or vendors in your &sources-list; file then - these features are available. By default APT selects the highest version - from all automatic sources. Some sources, such as - <filename>project/experimental</> are marked Not Automatic - these fall - to the bottom of the selection pile. - <para> - When deciding what version to use APT assigns a priority to each available - version of the package. It then does two things, first it selects - the highest priorty version that is newer than the installed version of the - package, then it selects the highest priority version that is older than - the installed version. Next, if the older versions have a priority greater - than 1000 they are compared with the priority of the upgrade set, the larger - becomes the selected result. Otherwise the downgrade versions are ignored - and the highest priority of the ugprade set is selected. - <para> - It is possible to think of the priorities in strata: - <VariableList> - <VarListEntry><term>above 1000</term> - <ListItem><Para> - Downgradable priorities - </VarListEntry> - - <VarListEntry><term>1000</term> - <ListItem><Para> - The downgrade prevention barrier - </VarListEntry> - - <VarListEntry><term>101 to 999</term> - <ListItem><Para> - Standard priorities. 990 is the priority set by the - <option/--target-release / &apt-get; option. 989 is the start for auto - priorities and 500 are all the default package files. - </VarListEntry> - - <VarListEntry><term>100</term> - <ListItem><Para> - The currently installed version - </VarListEntry> - - <VarListEntry><term>0 to 99</term> - <ListItem><Para> - Non automatic priorities. These are only used if the package - is not installed and there is no other version available. - </VarListEntry> - - <VarListEntry><term>less than 0</term> - <ListItem><Para> - The version is never selected. - </VarListEntry> - </VariableList> - <para> - Giving a pin a priority greater than 1000 will allow APT to downgrade - in order to get to that version. - <para> - Each package may be pinned to a specific version and each Packages file - has a priority for every package inside. The highest priority assigned - to a package is the one that is used. - <para> - A package pin looks like this: -<informalexample><programlisting> -Package: apt -Pin: version 0.4.0 + +<RefSect1> +<Title>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. + + +APT's Default Priority Assignments</> + +<para> +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 <command>apt-get</command> command +line or in the APT configuration file <filename>/etc/apt/apt.conf</filename>. +For example, +<programlisting> +<command>apt-get install -t testing <replaceable>some-package</replaceable></command> +</programlisting> +<programlisting> +APT::Default-Release "stable"; +</programlisting> +</para> + +<para> +If the target release has been specified then APT uses the following +algorithm to set the priorities of the versions of a package. Assign: +<variablelist> +<varlistentry> +<term>priority 100</term> +<listitem><simpara>to the version that is already installed (if any).</simpara></listitem> +</varlistentry> +<varlistentry> +<term>priority 500</term> +<listitem><simpara>to the versions that are not installed and do not belong to the target release.</simpara></listitem> +</varlistentry> +<varlistentry> +<term>priority 990</term> +<listitem><simpara>to the versions that are not installed and belong to the target release.</simpara></listitem> +</varlistentry> +</variablelist> +</para> + +<para> +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. +</para> + +<para> +APT then applies the following rules, listed in order of precedence, +to determine which version of a package to install. +<itemizedlist> +<listitem><simpara>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.)</simpara></listitem> +<listitem><simpara>Install the highest priority version.</simpara></listitem> +<listitem><simpara>If two or more versions have the same priority, +install the most recent one (that is, the one with the higher version +number).</simpara></listitem> +<listitem><simpara>If two or more versions have the same priority and +version number but either the packages differ in some of their metadata or the +<literal/--reinstall/ option is given, install the uninstalled one.</simpara></listitem> +</itemizedlist> +</para> + +<para> +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 <command>apt-get install <replaceable>some-package</replaceable></command> +or <command>apt-get upgrade</command> is executed. +</para> + +<para> +More rarely, the installed version of a package is <emphasis/more/ recent +than any of the other available versions. The package will not be downgraded +when <command>apt-get install <replaceable>some-package</replaceable></command> +or <command>apt-get upgrade</command> is executed. +</para> + +<para> +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 <command>apt-get install <replaceable>some-package</replaceable></command> +or <command>apt-get upgrade</command> is executed, +because at least <emphasis/one/ of the available versions has a higher +priority than the installed version. +</para> + +</RefSect2> + +<RefSect2><Title>The Effect of APT Preferences</> + +<para> +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. +<itemizedlist> +<listitem> +<simpara> +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 <filename/perl/ package whose version number begins with "<literal/5.8/". +</simpara> + +<programlisting> +Package: perl +Pin: version 5.8* Pin-Priority: 1001 -</programlisting></informalexample> - The first line specifies the package, the second gives the Pin specification - and the last gives the priority of this pin. The first word of the pin - specification may be version, release or origin, the remainder of the field - is described in the Versioning section above. - <para> - A default pin is how the priorities of package files are set. Any number - of default pins may be specified, the first matching default will select - the priority of the package file. Only release or origin may be used in - the Pin specification since they match Packages files. -<informalexample><programlisting> +</programlisting> +</listitem> + +<listitem><simpara> +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 <filename/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. +</simpara> + +<simpara> +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. +</simpara> + +<programlisting> Package: * -Pin: release v=2.1* -Pin-Priority: 998 -</programlisting></informalexample> - <para> - If the Pin-Priority field is omitted then the priority defaults to 989 for - both cases. - - <RefSect2><title>Interesting Effects</> - <para> - Due to the downgrade prevention barrier at priority 1000 it is possible - that a lower priority version will be selected if the higher priority - would cause a downgrade. For instance, if package foo has versions - <literal/1.2/, <literal/1.1/ and <literal/1.0/ installed, with - <literal/1.1/ being the currently installed version and the priorities of - each version being 900, 100 and 950 repectively the winning version will be - <literal/1.2/. - <para> - In practice this is often desired. A user may use a default pin to - make the stable distribution the default and then use the - <option/--target-dist/ option with &apt-get; to select newer versions - from unstable. The packages that have been upgraded to unstable will - continue to follow the versions that are available in unstable since - the stable versions now fall below the downgrade prevention barrier. - <para> - If this is not desired then a default pin should be used to make unstable - have a priority less than 100. - <para> - Users of 3rd party add ons such as Helix GNOME can use this mechanism to - force the usage of Helix packages, or force the usage of Debian packages - by setting the priority of that source sufficiently high. It is even - possible to mass downgrade from one set of packages to another by - using a priority larger than 1000. - </RefSect2> - </RefSect1> - - <RefSect1><Title>See Also</> - <para> - &apt-cache; &apt-conf; - </RefSect1> +Pin: origin "" +Pin-Priority: 999 +</programlisting> + +<simpara> +A note of caution: the keyword used here is "<literal/origin/". +This should not be confused with the Origin of a distribution as +specified in a <filename/Release/ file. What follows the "Origin:" tag +in a <filename/Release/ file is not an Internet address +but an author or vendor name, such as "Debian" or "Ximian". +</simpara> + +<simpara> +The following record assigns a low priority to all package versions +belonging to any distribution whose Archive name is "<literal/unstable/". +</simpara> + +<programlisting> +Package: * +Pin: release a=unstable +Pin-Priority: 50 +</programlisting> + +<simpara> +The following record assigns a high priority to all package versions +belonging to any release whose Archive name is "<literal/stable/" +and whose release Version number is "<literal/3.0/". +</simpara> + +<programlisting> +Package: * +Pin: release a=unstable, v=3.0 +Pin-Priority: 50 +</programlisting> +</listitem> +</itemizedlist> +</para> + +</RefSect2> + +<RefSect2> +<Title>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 +A version of any package other than +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 + + + + + +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 +gives the package name + + +the +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 + +the +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 + +Pin: release a=stable + + + + + +the +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 + + + +Pin: release v=3.0 +Pin: release a=stable v=3.0 +Pin: release 3.0 + + + + + + +the +names the licensing component associated with the +packages in the directory tree of the + +Pin: release c=main + + + + + +the +names the originator of the packages in the +directory tree of the + +Pin: release o=Debian + + + + + +the +names the label of the packages in the directory tree +of the + +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 debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release +contains the Release file retrieved from the site + + + + + +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 + + +The + + + + +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 +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 +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 +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 +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 + +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 apt-get upgrade will upgrade +the package to the most recent +apt-get install package/unstable + + + + + + + +See Also + +&apt-get; &apt-cache; &apt-conf; &sources-list; + + &manbugs; &manauthor; - +