123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637 |
- <?xml version="1.0" encoding="utf-8" standalone="no"?>
- <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY % aptent SYSTEM "apt.ent">
- %aptent;
- ]>
- <refentry>
- <refentryinfo>
- &apt-author.team;
- &apt-email;
- &apt-product;
- <!-- The last update date -->
- <date>04 May 2009</date>
- </refentryinfo>
- <refmeta>
- <refentrytitle>apt_preferences</refentrytitle>
- <manvolnum>5</manvolnum>
- <refmiscinfo class="manual">APT</refmiscinfo>
- </refmeta>
- <!-- Man page title -->
- <refnamediv>
- <refname>apt_preferences</refname>
- <refpurpose>Preference control file for APT</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <para>The APT preferences file <filename>/etc/apt/preferences</filename>
- and the fragment files in the <filename>/etc/apt/preferences.d/</filename>
- folder can be used to control which versions of packages 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>).
- APT assigns a priority to each version that is available.
- Subject to dependency constraints, <command>apt-get</command> 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.</para>
- <para>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 <command>apt-get</command> 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.</para>
- <para>Note that the files in the <filename>/etc/apt/preferences.d</filename>
- directory are parsed in alphanumeric ascending order and need to obey the
- following naming convention: The files have no or "<literal>pref</literal>"
- as filename extension and which only contain alphanumeric, hyphen (-),
- underscore (_) and period (.) characters - otherwise they will be silently
- ignored.</para>
- <refsect2><title>APT's Default Priority Assignments</title>
- <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>.
- Note that this has precedence over any general priority you set in the
- <filename>/etc/apt/preferences</filename> file described later, but not
- over specifically pinned packages.
- 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</literal> 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</emphasis> 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</emphasis> of the available versions has a higher
- priority than the installed version.</para>
- </refsect2>
- <refsect2><title>The Effect of APT Preferences</title>
- <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 one or more
- specified packages and specified version or version range. For example,
- the following record assigns a high priority to all versions of
- the <filename>perl</filename> package whose version number begins with "<literal>5.8</literal>".
- Multiple packages can be separated by spaces.</simpara>
- <programlisting>
- Package: perl
- Pin: version 5.8*
- Pin-Priority: 1001
- </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</filename> 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: origin ""
- Pin-Priority: 999
- </programlisting>
- <simpara>A note of caution: the keyword used here is "<literal>origin</literal>".
- This should not be confused with the Origin of a distribution as
- specified in a <filename>Release</filename> file. What follows the "Origin:" tag
- in a <filename>Release</filename> 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</literal>".</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 distribution whose Codename is "<literal>squeeze</literal>".</simpara>
- <programlisting>
- Package: *
- Pin: release n=squeeze
- Pin-Priority: 900
- </programlisting>
- <simpara>The following record assigns a high priority to all package versions
- belonging to any release whose Archive name is "<literal>stable</literal>"
- and whose release Version number is "<literal>3.0</literal>".</simpara>
- <programlisting>
- Package: *
- Pin: release a=stable, v=3.0
- Pin-Priority: 500
- </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 a version to be installed even if this
- constitutes a downgrade of the package</simpara></listitem>
- </varlistentry>
- <varlistentry>
- <term>990 < P <=1000</term>
- <listitem><simpara>causes a version to be installed
- even if it does not come from the target release,
- unless the installed version is more recent</simpara></listitem>
- </varlistentry>
- <varlistentry>
- <term>500 < P <=990</term>
- <listitem><simpara>causes a version to be installed
- unless there is a version 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 a version to be installed
- unless there is a version available belonging to some other
- distribution or the installed version is more recent</simpara></listitem>
- </varlistentry>
- <varlistentry>
- <term>0 < P <=100</term>
- <listitem><simpara>causes a version to be installed
- only if there is no installed version of the package</simpara></listitem>
- </varlistentry>
- <varlistentry>
- <term>P < 0</term>
- <listitem><simpara>prevents the version from being installed</simpara></listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>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.</para>
- <para>For example, suppose the APT preferences file contains the three
- records presented earlier:</para>
- <programlisting>
- Package: perl
- Pin: version 5.8*
- Pin-Priority: 1001
- Package: *
- Pin: origin ""
- Pin-Priority: 999
- Package: *
- Pin: release unstable
- Pin-Priority: 50
- </programlisting>
- <para>Then:
- <itemizedlist>
- <listitem><simpara>The most recent available version of the <literal>perl</literal>
- package will be installed, so long as that version's version number begins
- with "<literal>5.8</literal>". If <emphasis>any</emphasis> 5.8* version of <literal>perl</literal> is
- available and the installed version is 5.9*, then <literal>perl</literal> will be
- downgraded.</simpara></listitem>
- <listitem><simpara>A version of any package other than <literal>perl</literal>
- that is available from the local system has priority over other versions,
- even versions belonging to the target release.
- </simpara></listitem>
- <listitem><simpara>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 <literal>unstable</literal> distribution is only installed if it is selected
- for installation and no version 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 the &sources-list; file should provide
- <filename>Packages</filename> and <filename>Release</filename> files
- to describe the packages 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:</literal> line</term>
- <listitem><simpara>gives the package name</simpara></listitem>
- </varlistentry>
- <varlistentry>
- <term>the <literal>Version:</literal> 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</emphasis> of
- the packages in the directory tree below its parent. Unlike the
- <filename>Packages</filename> file, nearly all of the lines in a <filename>Release</filename>
- file are relevant for setting APT priorities:
- <variablelist>
- <varlistentry>
- <term>the <literal>Archive:</literal> or <literal>Suite:</literal> line</term>
- <listitem><simpara>names the archive to which all the packages
- in the directory tree belong. For example, the line
- "Archive: stable" or
- "Suite: stable"
- specifies that all of the packages in the directory
- tree below the parent of the <filename>Release</filename> file are in a
- <literal>stable</literal> 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>Codename:</literal> line</term>
- <listitem><simpara>names the codename to which all the packages
- in the directory tree belong. For example, the line
- "Codename: squeeze"
- specifies that all of the packages in the directory
- tree below the parent of the <filename>Release</filename> file belong to a version named
- <literal>squeeze</literal>. Specifying this value in the APT preferences file
- would require the line:
- </simpara>
- <programlisting>
- Pin: release n=squeeze
- </programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>the <literal>Version:</literal> line</term>
- <listitem><simpara>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
- <literal>testing</literal> and <literal>unstable</literal> distributions because they
- have not been released yet. 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:</literal> line</term>
- <listitem><simpara>names the licensing component associated with the
- packages in the directory tree of the <filename>Release</filename> file.
- For example, the line "Component: main" specifies that
- all the packages in the directory tree are from the <literal>main</literal>
- 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:
- </simpara>
- <programlisting>
- Pin: release c=main
- </programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>the <literal>Origin:</literal> line</term>
- <listitem><simpara>names the originator of the packages in the
- directory tree of the <filename>Release</filename> file. Most commonly, this is
- <literal>Debian</literal>. 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:</literal> line</term>
- <listitem><simpara>names the label of the packages in the directory tree
- of the <filename>Release</filename> file. Most commonly, this is
- <literal>Debian</literal>. 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 stored
- in the directory <filename>/var/lib/apt/lists</filename>, or in the file named
- by the variable <literal>Dir::State::Lists</literal> in the <filename>apt.conf</filename> 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</literal> for <literal>binary-i386</literal> architecture
- files from the <literal>contrib</literal> component of the <literal>unstable</literal>
- 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:</literal>.
- This provides a place for comments.</para>
- <para>The <literal>Pin-Priority:</literal> line in each APT preferences record is
- optional. If omitted, APT assigns a priority of 1 less than the last value
- specified on a line beginning with <literal>Pin-Priority: release ...</literal>.</para>
- </refsect2>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <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</literal> distribution and a prohibitively low priority to
- package versions belonging to other <literal>Debian</literal> distributions.
- <programlisting>
- 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
- </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</literal> 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</literal> distribution;
- the package will not be upgraded again unless this command is given
- again.
- <programlisting>
- apt-get install <replaceable>package</replaceable>/testing
- </programlisting>
- </para>
- </refsect2>
- <refsect2>
- <title>Tracking Testing or Unstable</title>
- <para>The following APT preferences file will cause APT to assign
- a high priority to package versions from the <literal>testing</literal>
- distribution, a lower priority to package versions from the
- <literal>unstable</literal> distribution, and a prohibitively low priority
- to package versions from other <literal>Debian</literal> 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 a suitable &sources-list; file and the above preferences file,
- any of the following commands will cause APT to upgrade to the latest
- <literal>testing</literal> 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</literal> distribution.
- Thereafter, <command>apt-get upgrade</command> will upgrade
- the package to the most recent <literal>testing</literal> version if that is
- more recent than the installed version, otherwise, to the most recent
- <literal>unstable</literal> version if that is more recent than the installed
- version.
- <programlisting>
- apt-get install <replaceable>package</replaceable>/unstable
- </programlisting>
- </para>
- </refsect2>
- <refsect2>
- <title>Tracking the evolution of a codename release</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 specified codename of a distribution and a prohibitively low priority to
- package versions belonging to other <literal>Debian</literal> distributions,
- codenames and archives.
- Note that with this APT preference APT will follow the migration of a release
- from the archive <literal>testing</literal> to <literal>stable</literal> and
- later <literal>oldstable</literal>. If you want to follow for example the progress
- in <literal>testing</literal> notwithstanding the codename changes you should use
- the example configurations above.
- <programlisting>
- Explanation: Uninstall or do not install any Debian-originated package versions
- Explanation: other than those in the distribution codenamed with squeeze or sid
- Package: *
- Pin: release n=squeeze
- Pin-Priority: 900
- Explanation: Debian unstable is always codenamed with sid
- Package: *
- Pin: release a=sid
- Pin-Priority: 800
- 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 version(s) in the release codenamed with <literal>squeeze</literal>.
- <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>sid</literal> distribution.
- Thereafter, <command>apt-get upgrade</command> will upgrade
- the package to the most recent <literal>squeeze</literal> version if that is
- more recent than the installed version, otherwise, to the most recent
- <literal>sid</literal> version if that is more recent than the installed
- version.
- <programlisting>
- apt-get install <replaceable>package</replaceable>/sid
- </programlisting>
- </para>
- </refsect2>
- </refsect1>
- <refsect1>
- <title>Files</title>
- <variablelist>
- &file-preferences;
- </variablelist>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>&apt-get; &apt-cache; &apt-conf; &sources-list;
- </para>
- </refsect1>
- &manbugs;
- </refentry>
|