[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: apt_preferences man page



Because this matter was mentioned in the 26 November Debian
Weekly News, it seems appropriate to post an update.

Susan Kleinmann took the bull by the horns and rewrote
the page from scratch.  I have proposed some revisions
and hopefully we'll have a finished product soon.  I
append the latest version I have, in the hopes that
people will point out any remaining errors.

--
Thomas Hood

APT_PREFERENCES(5)                             APT_PREFERENCES(5)



NAME
       apt_preferences - Preference control file for APT

DESCRIPTION
       The  APT preferences file /etc/apt/preferences can be used
       to control which version of a package will be selected for
       installation.

       Several versions of a package may be available for instal­
       lation when the sources.list(5) file  contains  references
       to  more  than  one release (for example, stable and test­
       ing), and several instances of the same version of a pack­
       age  may be available when the file contains references to
       more than one download site for a particular release.  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(5).)
       Subject to dependency constraints,  apt-get  installs  the
       instance with the highest priority.

       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.

   APT'S DEFAULT PRIORITY ASSIGNMENTS
       If  there  is no preferences file, or if there is no entry
       in the file that applies to a  particular  instance,  then
       the  priority  assigned  to  an  instance  is the priority
       assigned to the release to which  that  instance  belongs.
       It is possible to single out a release, called the "target
       release", which receives  a  higher  priority  than  other
       releases.   The  target  release can be set on the apt-get
       command  line   or   in   the   APT   configuration   file
       /etc/apt/apt.conf.  For example,

       # Command to install the version of some-pkg from the testing
release
       apt-get install -t testing some-pkg

       # Configuration setting to make stable the target release
       APT::Default-Release "stable";

       If  a target release has been specified, then APT uses the
       following algorithm to set the priorities of the instances
       of a package.  Assign:

       priority 100
              to  the  instance  of  a  package  that  is already
              installed (if any).

       priority 500
              to  the  instances  of  a  package  that  are   not
              installed  and do not belong to the target release.

       priority 990
              to  the  instances  of  a  package  that  are   not
              installed and belong to the target release.

       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.

       APT  then  applies  the following rules to determine which
       instance of a package to install:

       · Never downgrade an installed package unless the priority
         of  an  available  instance of the package exceeds 1000.
         (Note that none of APT's default priorities exceeds this
         threshold;  such  high priorities can only be set in the
         preferences file.)

       · Always  install  or  upgrade  to  the  highest  priority
         instance of a package.

       · If two or more instances of a package have the same pri­
         ority, install or upgrade to the most recent one.

       In a typical situation, the installed instance of a  pack­
       age  (priority  100)  is  not  as  recent  as  one  of the
       instances available from the sites and releases listed  in
       the  sources.list(5) file (priority 500 or 990).  Then the
       package will be upgraded with the command: apt-get install
       or apt-get dist-upgrade.

       Rarely, the installed instance of a package is more recent
       than any of the other available instances.   This  package
       will not be downgraded.

       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
       release.  Such a package will indeed be upgraded,  because
       at  least one of the available instances has a higher pri­
       ority than the installed instance.

   THE EFFECT OF APT PREFERENCES
       The APT preferences file allows the  system  administrator
       to customize priorities.  The preferences file consists of
       one or more multi-line records separated by  blank  lines.
       Records can have one of two forms:

       · The  first  form pins a priority (a "Pin-Priority") to a
         named  package  version.   For  example,  the  following
         record  pins a high priority to all versions of the perl
         package whose version name begins with "5.8":

         Package: perl
         Pin: version 5.8*
         Pin-Priority: 1001

       · The second form pins a priority to all  of  the  package
         versions  in  a  given release (that is, to all the ver­
         sions of packages that are listed in a Release file), or
         to all of the package instances coming from a particular
         Internet site.

         A note of caution: the keyword used in the  APT  prefer­
         ences  file to select the source site is "origin".  This
         may lead one to confuse the source site with  the  "Ori­
         gin:"  of  a  release  as  specified  in a Release file.
         Recall that what follows the "Origin:" tag in a  Release
         file  generally  is  not an Internet site address but an
         author or vendor name, such as "Debian" or "Ximian".

         This second-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:

         Package: *
         Pin: origin ""
         Pin-Priority: 999

         The following record causes APT to assign a low priority
         to all package versions belonging to any  release  whose
         "Archive" (a) name is "unstable":

         Package: *
         Pin: release a=unstable
         Pin-Priority: 50

         The  following record causes APT to assign a high prior­
         ity to all package versions  belonging  to  any  release
         whose  "Archive"  (a) name is "stable" and whose release
         "Version" (v) name is "3.0":

         Package: *
         Pin: release a=unstable, v=3.0
         Pin-Priority: 50

   HOW APT INTERPRETS PRIORITIES
       Priorities (P) assigned in the APT preferences  file  must
       be positive or negative integers.  They are interpreted as
       follows (roughly speaking):

       P > 1000
              causes an instance to be  installed  even  if  this
              constitutes a downgrade of the installed package

       990 < P <=1000
              causes  an instance to be installed even if it does
              not  come  from  the  target  release,  unless  the
              installed instance is more recent

       500 < P <=990
              causes  an instance to be installed unless there is
              an  instance  available  belonging  to  the  target
              release or the installed version is more recent

       100 < P <=500
              causes  an instance to be installed unless there is
              an  instance  available  belonging  to  some  other
              release or the installed version is more recent

       0 <= P <=100
              causes an instance to be installed only if there is
              no installed instance of the package

       P < 0  prevents the instance from being installed

       If one of the records of the first  form  described  above
       matches  an  available  package instance, then that record
       determines the priority of the instance.  If  two  records
       of  the  first  form match an available instance, then the
       first record encountered determines the priority.  If  two
       records  of  the  second form match an available instance,
       then the first record encountered determines the priority.

       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
         name 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  avail­
         able  from  the  local system and belongs to an unstable
         release has priority over the version  from  the  target
         release.

       · An  instance  of a package whose source is not the local
         system but some other site  listed  in  sources.list(5),
         and  which  belongs  to  an  unstable  release,  is only
         installed if it is  selected  for  installation  and  no
         instance of the package is already installed.

   DETERMINATION OF PACKAGE VERSION AND RELEASE PROPERTIES
       The sites listed in a system's sources.list(5) file should
       provide Packages and Release files to describe the package
       instances available in each directory at that site.

       The  Packages  file is normally found in the directory
       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 name for the named package

       The  Release  file  is normally found in the directory 
       for  example,      .../dists/stable/Release,            or
       .../dists/woody/Release.   It  consists of a single multi-
       line record which applies to all of the package  instances
       in  the directory tree below its parent.  Unlike the Pack­
       ages 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  package
              instances in the directory tree belong.  For  exam­
              ple, the line Archive: stable specifies that all of
              the packages in the directory tree below the parent
              of  the  Release  file  are  in the 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 pack­
              age instances in the tree might  belong  to  Debian
              GNU/Linux   version  3.0.   There  is  normally  no
              version name  for  releases  of  the  "testing"  or
              "unstable"  archive.   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
              package instances in  the  directory  tree  of  the
              Release  file.   For  example,  the line Component:
              main specifies that all the instances in the direc­
              tory tree are from the main component, meaning that
              they are licensed under terms listed in the  Debian
              Free  Software  Guidelines.  Specifying this compo­
              nent in the APT preferences file would require  the
              line:

              Pin: release c=main

       the Origin: line
              names  the producer of the package instances 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
              seems redundant.  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 sites
       listed  in the sources.list(5) file are kept in the direc­
       tory /var/lib/apt/lists, or in the file named by the vari­
       able Dir::State::Lists in the apt.conf file.  For example,
       the   file   debian.lcs.mit.edu_debian_dists_unstable_con­
       trib_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 release.

   OPTIONAL LINES IN AN APT PREFERENCES RECORD
       Each record in the APT  preferences  file  can  optionally
       begin  with  a  line beginning with the word Explanation:.
       This provides an opportunity to comment on the record.

       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 release and a pro­
       hibitively low priority to package versions  belonging  to
       other Debian releases.

       Package: *
       Pin: release a=stable
       Pin-Priority: 900

       Explanation: Do not install any Debian-originated package
instances
       Explanation: other than those listed above
       Package: *
       Pin: release o=Debian
       Pin-Priority: -10

       With  a typical sources.list(5) file and the above prefer­
       ences 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 speci­
       fied package  to  the  latest  version  from  the  testing
       release;  further  upgrades  will not occur automatically,
       however:

       apt-get install package/testing

   TRACKING TESTING
       The following APT  preferences  file  will  cause  APT  to
       assign  a high priority to package versions from the test­
       ing release, a lesser priority to  package  versions  from
       the  unstable release, and a prohibitively low priority to
       package versions from other Debian releases.

       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 the above preferences file, any of the following com­
       mands will cause APT to upgrade to the latest testing ver­
       sion(s).

       apt-get install package-name
       apt-get upgrade
       apt-get dist-upgrade

       The following command will cause APT to upgrade the speci­
       fied  package  to  the  latest  version  from the unstable
       release.  Thereafter, apt-get dist-upgrade and the  others
       will  cause  upgrade of the package to the latest unstable
       version.

       apt-get install package/unstable

SEE ALSO
       apt-get(8) apt-cache(8) apt.conf(5) sources.list(5)

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

AUTHOR
       APT was written by the APT team <apt@packages.debian.org>.



                         08 December 2002      APT_PREFERENCES(5)




Reply to: