Provided by: apt_0.6.43.3ubuntu2_i386 bug

NAME

       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(5)   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(5) file contains  references  to  more  than  one
       source.  In this case apt-get downloads the instance listed earliest in
       the sources.list(5) file. The APT preferences file does not affect  the
       choice of instance, only the choice of version.

   APTs 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(5)  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=stable, v=3.0
          Pin-Priority: 500

   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(5)  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(5)  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(5)   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(5) 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(5) 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(8)  apt-cache(8)  apt.conf(5)  sources.list(5)

BUGS

       APT bug page: http://bugs.debian.org/src:apt. If you wish to  report  a
       bug  in  APT, please see /usr/share/doc/debian/bug-reporting.txt or the
       reportbug(1) command.

AUTHOR

       APT team.