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

Re: Some myths regarding apt pinning



Bruno Diniz de Paula <diniz () cs ! rutgers ! edu> wrote:
> But before looking at the priority, it looks at the version
> of the packages.

No, it is the other way around, I believe.  First priority,
then version.

I include an updated edition of the apt preferences(5)
manual page; it hasn't yet been uploaded.  Some of the
formatting may be out of whack, but here goes.
                                               // 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
       installation when the  file contains references to more
       than  one  distribution  (for example, stable and test­
       ing); furthermore, several instances of the  same  ver­
       sion  of  a package may be available when the file con­
       tains 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 .)  Subject to  dependency  con­
       straints,  apt-get installs the instance with the high­
       est priority.  If two instances have the same  priority
       then  it installs the more recent one, that is, the one
       with the higher version number.
                                                                
       The APT preferences file overrides the priorities  that
       APT  assigns to package instances by default, thus giv­
       ing the user control over which  one  is  selected  for
       installation.

   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 that instance
       is the priority  of  the  distribution  to  which  that
       instance  belongs.  It is possible to single out a dis­
       tribution, called the "target release", which  receives
       a higher priority than other distributions.  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 testing version of some-package
       apt-get install -t testing some-package
                                                                
       # Config 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 that is  already  installed  (if
              any).
                                                                
       priority 500
              to  the  instances that are not installed and do
              not belong to the target release.
                                                                
       priority 990
              to the instances  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, listed  in  order
       of precedence, to determine which instance of a package
       to install.
                                                                
       · 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 pri­
         orities exceeds 1000; such high priorities  can  only
         be set in the preferences file.)
                                                                
       · Install the highest priority instance.
                                                                
       · If  two  or  more  instances  have the same priority,
         install the most recent one.
                                                                
       · If two or more instances have the same  version  num­
         ber,  install the one whose source is listed earliest
         in .  (The installed instance, if there  is  one,  is
         always  preferred in such a comparison unless apt-get
         --reinstall is used.)
                                                                
       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
       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.   The
       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 distribution.  Such a package will indeed be
       upgraded,   because  at  least  one  of  the  available
       instances has a  higher  priority  than  the  installed
       instance.
                                                                
   THE EFFECT OF APT PREFERENCES
       The  APT preferences file allows the system administra­
       tor 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.
                                                                
       · The  "specific"  form  pins a priority (a "Pin-Prior­
         ity") to a specified package and specified version or
         version  range.   For  example,  the following record
         pins 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  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 Release file),  or  to  all  of  the  package
         instances  coming from a particular Internet site, as
         identified by its fully qualified domain name.


         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.
                                                                
         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 usu­
         ally not an Internet site address but  an  author  or
         vendor name, such as "Debian" or "Ximian".
                                                                
         The  following record causes APT to assign a low pri­
         ority to all package versions belonging to  any  dis­
         tribution whose "Archive" (a) name is "unstable".
                                                                
         Package: *
         Pin: release a=unstable
         Pin-Priority: 50
                                                                
         The following record causes APT to assign a high pri­
         ority  to  all  package  versions  belonging  to  any
         release  whose  "Archive"  (a)  name  is "stable" and
         whose release "Version" (v) number 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 inter­
       preted as follows (roughly speaking):
                                                                
       P > 1000
              causes an instance to be installed even if  this
              constitutes a downgrade of the 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
              distribution  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  specific-form records described above
       matches an available package instance, then that record
       determines  the  priority of the instance.  If two spe­
       cific-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.

       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.
                                                                
       · An  instance  of  any package other than perl that is
         available from the local  system  has  priority  over
         other instances, even instances belonging to the tar­
         get release.
                                                                
       · An instance of a package  whose  origin  is  not  the
         local  system  but  some  other  site listed in , and
         which belongs to an "unstable" distribution, is  only
         installed  if  it is selected for installation and no
         instance of the package is already installed.

   DETERMINATION OF VERSION AND DISTRIBUTION PROPERTIES
       The locations listed in a system's  file should provide
       Packages and Release  files  to  describe  the  package
       instances available at that location.
                                                                
       The  Packages  file  is normally found in the directory
       for  example,   .../dists/stable/main/binary-i386/Pack­
       ages.   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 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 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  package
              instances  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 the stable
              archive.  Specifying this value in the APT pref­
              erences file would require the line:
                                                                
              Pin: release a=stable

       the Version: line
              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  fol­
              lowing 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 Compo­
              nent: main specifies that all the  instances  in
              the  directory tree are from the 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:
                                                                
              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 ori­
              gin 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
       locations listed in the  file are kept in the directory
       /var/lib/apt/lists,  or  in the file named by the vari­
       able Dir::State::Lists in the apt.conf file.  For exam­
       ple,  the  file  debian.lcs.mit.edu_debian_dists_unsta­
       ble_contrib_binary-i386_Release  contains  the  Release
       file  retrieved  from  the  site debian.lcs.mit.edu for
       binary-i386 architecture files from the contrib  compo­
       nent 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 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 distribution and
       a  prohibitively  low  priority  to  package   versions
       belonging to other Debian distributions.
                                                                
       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
                                                                
       With  a  suitable  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  test­
       ing distribution; further upgrades will not occur auto­
       matically, 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
       testing distribution, a lesser priority to package ver­
       sions  from  the  unstable  distribution,  and  a  pro­
       hibitively 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 the above APT preferences file, any of the follow­
       ing 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 unsta­
       ble distribution.  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
                        26 January 2003     APT_PREFERENCES(5)


-- 
Thomas Hood <jdthood@yahoo.co.uk>



Reply to: