diff options
Diffstat (limited to 'doc/apt_preferences.5.sgml')
| -rw-r--r-- | doc/apt_preferences.5.sgml | 720 |
1 files changed, 520 insertions, 200 deletions
diff --git a/doc/apt_preferences.5.sgml b/doc/apt_preferences.5.sgml index cb4d0c5a9..2d9c9a052 100644 --- a/doc/apt_preferences.5.sgml +++ b/doc/apt_preferences.5.sgml @@ -8,221 +8,541 @@ <refentry> &apt-docinfo; - + <refmeta> <refentrytitle>apt_preferences</> <manvolnum>5</> </refmeta> - + <!-- Man page title --> <refnamediv> <refname>apt_preferences</> <refpurpose>Preference control file for APT</> </refnamediv> - - <RefSect1><Title>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</> +<para> +The APT preferences file <filename>/etc/apt/preferences</> +can be used to control which version of a package will be selected +for installation. +</para> + +<para>Several versions of a package may be available for installation when +the &sources-list; file contains references to more than one distribution +(for example, <literal>stable</literal> and <literal>testing</literal>); +furthermore, several instances of the same version of a package may be +available when the file contains 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 &sources-list;.) +Subject to dependency constraints, <command>apt-get</command> installs the +instance with the highest priority. If two instances have the same +priority then it installs the more recent one, that is, the one with the +higher version number. +</para> + +<para>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 for installation. +</para> + +<RefSect2><Title>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 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 distribution, called the +"target release", which receives a higher priority than other distributions. +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 to install the <literal/testing/ version of <replaceable>some-package</replaceable> +<command>apt-get install -t testing <replaceable>some-package</replaceable></command> +</programlisting> + +<programlisting> +# Configuration setting to make <literal/stable/ the target release +APT::Default-Release "stable"; +</programlisting> +</para> + +<para>If a target release has been specified then APT uses the following +algorithm to set the priorities of the instances of a package. Assign: + +<variablelist> +<varlistentry> +<term>priority 100</term> +<listitem><simpara>to the instance that is already installed (if any). +</simpara></listitem> +</varlistentry> +<varlistentry> +<term>priority 500</term> +<listitem><simpara>to the instances that are not installed +and do not belong to the target release. +</simpara></listitem> +</varlistentry> +<varlistentry> +<term>priority 990</term> +<listitem><simpara>to the instances that are not installed +and belong to the target release. +</simpara></listitem> +</varlistentry> +</variablelist> +</para> + +<para>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. +</para> + +<para>APT then applies the following rules, listed in order of precedence, +to determine which instance of a package to install. + +<itemizedlist> +<listitem><simpara>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 priorities +exceeds 1000; such high priorities can only be set in the preferences file.) +</simpara></listitem> +<listitem><simpara>Install the highest priority instance. +</simpara></listitem> +<listitem><simpara>If two or more instances have the same priority, +install the most recent one. +</simpara></listitem> +<listitem><simpara>If two or more instances have the same version number, +install the one whose source is listed earliest in &sources-list;. +(The installed instance, if there is one, is always preferred in such a +comparison unless <command>apt-get --reinstall</command> is used.) +</simpara></listitem> +</itemizedlist> +</para> + +<para>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 &sources-list; file (priority 500 or 990). Then the package will be +upgraded with the command: +<command>apt-get install</command> or <command>apt-get dist-upgrade</command>. +</para> + +<para>Rarely, the installed instance of a package is <emphasis/more/ recent +than any of the other available instances. The package will not be downgraded. +</para> + +<para>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 <emphasis/one/ of the available instances has a higher +priority than the installed instance. +</para> + +</RefSect2> + +<RefSect2><Title>The Effect of APT Preferences</> + +<para>The APT preferences file allows the system administrator 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. +<itemizedlist> +<listitem> +<simpara>The "specific" form pins a priority (a "Pin-Priority") to a +specified package and specified version or version range. For +example, the following record pins 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> +</listitem> + +<listitem><simpara> +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 <filename/Release/ file), or to all of the package +instances coming from a particular Internet site, as identified by its +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 causes APT to +assign a high priority to all package instances available from the local +site. +</simpara> + +<programlisting> +Package: * +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 usually not an Internet site address +but an author or vendor name, such as "Debian" or "Ximian". +</simpara> + +<simpara>The following record causes APT to assign a low priority to all +package versions belonging to any distribution whose "Archive" +(<literal/a/) name is "<literal/unstable/". +</simpara> + +<programlisting> +Package: * +Pin: release a=unstable +Pin-Priority: 50 +</programlisting> + +<simpara>The following record causes APT to assign a high priority to all +package versions belonging to any release whose "Archive" (<literal/a/) +name is "<literal/stable/" and whose release "Version" (<literal/v/) +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</Title> + +<para>Priorities (P) assigned in the APT preferences file must be positive +or negative integers. They are interpreted as follows (roughly speaking): + +<variablelist> +<varlistentry><term>P > 1000</term> +<listitem><simpara>causes an instance to be installed +even if this constitutes a downgrade of the package +</simpara></listitem> +</varlistentry> +<varlistentry><term>990 < P <=1000</term> +<listitem><simpara>causes an instance to be installed +even if it does not come from the target release, +unless the installed instance is more recent +</simpara></listitem> +</varlistentry> +<varlistentry><term>500 < P <=990</term> +<listitem><simpara>causes an instance to be installed +unless there is an instance available belonging to the target release +or the installed version is more recent +</simpara></listitem> +</varlistentry> +<varlistentry><term>100 < P <=500</term> +<listitem><simpara>causes an instance to be installed +unless there is an instance available belonging to some other +distribution or the installed version is more recent +</simpara></listitem> +<varlistentry><term>0 <= P <=100</term> +<listitem><simpara>causes an instance to be installed +only if there is no installed instance of the package +</simpara></listitem> +</varlistentry> +<varlistentry><term>P < 0</term> +<listitem><simpara>prevents the instance from being installed +</simpara></listitem> +</varlistentry> +</variablelist> +</para> + +<para>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 specific-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. +</para> + +<para>For example, suppose the APT preferences file contains the three +records presented earlier: + +<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> + 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> - +Pin: origin "" +Pin-Priority: 999 + +Package: * +Pin: release unstable +Pin-Priority: 50 +</programlisting> + +Then: + +<itemizedlist> +<listitem><simpara>The most recent available version of the <literal/perl/ +package will be installed, so long as that version's version number begins +with "<literal/5.8/". If <emphasis/any/ 5.8* version of <literal/perl/ is +available and the installed version is 5.9*, then <literal/perl/ will be +downgraded.</simpara></listitem> +<listitem><simpara>An instance of any package other than <literal/perl/ +that is available from the local system has priority over other instances, +even instances belonging to the target release. +</simpara></listitem> +<listitem><simpara>An instance of a package whose origin is not the local +system but some other site listed in &sources-list;, and which belongs to +an "<literal/unstable/" distribution, is only installed if it is selected +for installation and no instance of the package is already installed. +</simpara></listitem> +</itemizedlist> +</para> +</RefSect2> + +<RefSect2><Title>Determination of Package Version and Distribution Properties</Title> + +<para>The locations listed in a system's &sources-list; file should provide +<filename>Packages</filename> and <filename>Release</filename> files +to describe the package instances available at that location. +</para> + +<para>The <filename>Packages</filename> file is normally found in the directory +<filename>.../dists/<replaceable>dist-name</replaceable>/<replaceable>component</replaceable>/<replaceable>arch</replaceable></filename>: +for example, <filename>.../dists/stable/main/binary-i386/Packages</filename>. +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: +<variablelist> +<varlistentry> +<term>the <literal/Package:/ line</term> +<listitem><simpara>gives the package name</simpara></listitem> +</varlistentry> +<varlistentry> +<term>the <literal/Version:/ line</term> +<listitem><simpara>gives the version number for the named package</simpara></listitem> +</varlistentry> +</variablelist> +</para> + +<para>The <filename>Release</filename> file is normally found in the directory +<filename>.../dists/<replaceable>dist-name</replaceable></filename>: +for example, <filename>.../dists/stable/Release</filename>, +or <filename>.../dists/woody/Release</filename>. +It consists of a single multi-line record which applies to <emphasis/all/ of +the package instances in the directory tree below its parent. Unlike the +<filename/Packages/ file, nearly all of the lines in a <filename/Release/ +file are relevant for setting APT priorities: + +<variablelist> +<varlistentry> +<term>the <literal/Archive:/ line</term> +<listitem><simpara>names the archive to which all the package instances +in the directory tree belong. For example, the line +<literal/Archive: stable/ specifies that all of the packages in the directory +tree below the parent of the <filename/Release/ file are in the +<literal/stable/ archive. Specifying this value in the APT preferences file +would require the line: +</simpara> + +<programlisting> +Pin: release a=stable +</programlisting> +</listitem> +</varlistentry> + +<varlistentry> +<term>the <literal/Version:/ line</term> +<listitem><simpara>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 +following lines. +</simpara> + +<programlisting> +Pin: release v=3.0 +Pin: release a=stable v=3.0 +Pin: release 3.0 +</programlisting> + +</listitem> +</varlistentry> + +<varlistentry> +<term>the <literal/Component:/ line</term> +<listitem><simpara>names the licensing component associated with the +package instances in the directory tree of the <filename/Release/ +file. For example, the line <literal/Component: main/ specifies that +all the instances in the directory tree are from the <literal/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: +</simpara> + +<programlisting> +Pin: release c=main +</programlisting> +</listitem> +</varlistentry> + +<varlistentry> +<term>the <literal/Origin:/ line</term> +<listitem><simpara>names the producer of the package instances in the +directory tree of the <filename/Release/ file. Most commonly, this is +<literal/Debian/. Specifying this origin in the APT preferences file +would require the line: +</simpara> + +<programlisting> +Pin: release o=Debian +</programlisting> +</listitem> +</varlistentry> + +<varlistentry> +<term>the <literal/Label:/ line</term> +<listitem><simpara>seems redundant. Most commonly, this is +<literal/Debian/. Specifying this label in the APT preferences file +would require the line: +</simpara> + +<programlisting> +Pin: release l=Debian +</programlisting> +</listitem> +</varlistentry> +</variablelist> +</para> + +<para>All of the <filename>Packages</filename> and <filename>Release</filename> +files retrieved from locations listed in the &sources-list; file are kept +in the directory <filename>/var/lib/apt/lists</filename>, or in the file named +by the variable <literal/Dir::State::Lists/ in the <filename/apt.conf/ file. +For example, the file +<filename>debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release</filename> +contains the <filename>Release</filename> file retrieved from the site +<literal/debian.lcs.mit.edu/ for <literal/binary-i386/ architecture +files from the <literal/contrib/ component of the <literal/unstable/ +distribution. +</para> + +</RefSect2> + +<RefSect2><Title>Optional Lines in an APT Preferences Record</Title> + +<para>Each record in the APT preferences file can optionally begin with +one or more lines beginning with the word <literal/Explanation:/. +This provides an opportunity to comment on the record. +</para> + +<para>The <literal/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 <literal/Pin-Priority: release .../. +</para> +</RefSect2> +</RefSect1> + +<RefSect1><Title>Examples</> +<RefSect2><Title>Tracking Stable</Title> + +<para>The following APT preferences file will cause APT to assign a +priority higher than the default (500) to all package versions belonging +to a <literal/stable/ distribution and a prohibitively low priority to +package versions belonging to other <literal/Debian/ distributions. + +<programlisting> +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 +</programlisting> +</para> + +<para> +With a suitable &sources-list; file and the above preferences file, +any of the following commands will cause APT to upgrade to the +latest <literal/stable/ version(s). + +<programlisting> +apt-get install <replaceable>package-name</replaceable> +apt-get upgrade +apt-get dist-upgrade +</programlisting> +</para> + +<para>The following command will cause APT to upgrade the specified +package to the latest version from the <literal/testing/ distribution; +further upgrades will not occur automatically, however. + +<programlisting> +apt-get install <replaceable>package</replaceable>/testing +</programlisting> +</RefSect2> + + <RefSect2><Title>Tracking Testing</Title> + +<para>The following APT preferences file will cause APT to assign +a high priority to package versions from the <literal/testing/ +distribution, a lesser priority to package versions from the +<literal/unstable/ distribution, and a prohibitively low priority +to package versions from other <literal/Debian/ distributions. + +<programlisting> +Package: * +Pin: release a=testing +Pin-Priority: 900 + +Package: * +Pin: release a=unstable +Pin-Priority: 800 + +Package: * +Pin: release o=Debian +Pin-Priority: -10 +</programlisting> +</para> + +<para> +With the above APT preferences file, any of the +following commands will cause APT to upgrade to the latest +<literal/testing/ version(s). + +<programlisting> +apt-get install <replaceable>package-name</replaceable> +apt-get upgrade +apt-get dist-upgrade +</programlisting> +</para> + +<para>The following command will cause APT to upgrade the specified +package to the latest version from the <literal/unstable/ distribution. +Thereafter, <command>apt-get dist-upgrade</command> and the others +<emphasis/will/ cause upgrade of the package to the latest +<literal/unstable/ version. + +<programlisting> +apt-get install <replaceable>package</replaceable>/unstable +</programlisting> +</para> + +</RefSect2> +</RefSect1> + <RefSect1><Title>See Also</> - <para> - &apt-cache; &apt-conf; +<para> +&apt-get; &apt-cache; &apt-conf; &sources-list; </RefSect1> &manbugs; &manauthor; - + </refentry> |