| 1 | <!-- -*- mode: sgml; mode: fold -*- --> |
| 2 | <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ |
| 3 | |
| 4 | <!ENTITY % aptent SYSTEM "apt.ent"> |
| 5 | %aptent; |
| 6 | |
| 7 | ]> |
| 8 | |
| 9 | <refentry> |
| 10 | &apt-docinfo; |
| 11 | |
| 12 | <refmeta> |
| 13 | <refentrytitle>apt_preferences</> |
| 14 | <manvolnum>5</> |
| 15 | </refmeta> |
| 16 | |
| 17 | <!-- Man page title --> |
| 18 | <refnamediv> |
| 19 | <refname>apt_preferences</> |
| 20 | <refpurpose>Preference control file for APT</> |
| 21 | </refnamediv> |
| 22 | |
| 23 | <RefSect1><Title>Description</> |
| 24 | <para> |
| 25 | The APT preferences file <filename>/etc/apt/preferences</> |
| 26 | can be used to control which version of a package will be selected |
| 27 | for installation. |
| 28 | </para> |
| 29 | |
| 30 | <para>Several versions of a package may be available for installation when |
| 31 | the &sources-list; file contains references to more than one distribution |
| 32 | (for example, <literal>stable</literal> and <literal>testing</literal>); |
| 33 | furthermore, several instances of the same version of a package may be |
| 34 | available when the file contains references to more than one download site |
| 35 | for a particular distribution. APT assigns a "priority" to each instance |
| 36 | that is available. (In what follows, an "instance" will be an instance of |
| 37 | a package that is available according to &sources-list;.) |
| 38 | Subject to dependency constraints, <command>apt-get</command> installs the |
| 39 | instance with the highest priority. If two instances have the same |
| 40 | priority then it installs the more recent one, that is, the one with the |
| 41 | higher version number. |
| 42 | </para> |
| 43 | |
| 44 | <para>The APT preferences file overrides the priorities that APT assigns |
| 45 | to package instances by default, thus giving the user control over which |
| 46 | one is selected for installation. |
| 47 | </para> |
| 48 | |
| 49 | <RefSect2><Title>APT's Default Priority Assignments</> |
| 50 | |
| 51 | <para>If there is no preferences file, or if there is no entry in the file |
| 52 | that applies to a particular instance, then the priority assigned to that |
| 53 | instance is the priority of the distribution to which that instance |
| 54 | belongs. It is possible to single out a distribution, called the |
| 55 | "target release", which receives a higher priority than other distributions. |
| 56 | The target release can be set on the <command>apt-get</command> command |
| 57 | line or in the APT configuration file <filename>/etc/apt/apt.conf</filename>. |
| 58 | For example, |
| 59 | |
| 60 | <programlisting> |
| 61 | # Command to install the <literal/testing/ version of <replaceable>some-package</replaceable> |
| 62 | <command>apt-get install -t testing <replaceable>some-package</replaceable></command> |
| 63 | </programlisting> |
| 64 | |
| 65 | <programlisting> |
| 66 | # Configuration setting to make <literal/stable/ the target release |
| 67 | APT::Default-Release "stable"; |
| 68 | </programlisting> |
| 69 | </para> |
| 70 | |
| 71 | <para>If a target release has been specified then APT uses the following |
| 72 | algorithm to set the priorities of the instances of a package. Assign: |
| 73 | |
| 74 | <variablelist> |
| 75 | <varlistentry> |
| 76 | <term>priority 100</term> |
| 77 | <listitem><simpara>to the instance that is already installed (if any). |
| 78 | </simpara></listitem> |
| 79 | </varlistentry> |
| 80 | <varlistentry> |
| 81 | <term>priority 500</term> |
| 82 | <listitem><simpara>to the instances that are not installed |
| 83 | and do not belong to the target release. |
| 84 | </simpara></listitem> |
| 85 | </varlistentry> |
| 86 | <varlistentry> |
| 87 | <term>priority 990</term> |
| 88 | <listitem><simpara>to the instances that are not installed |
| 89 | and belong to the target release. |
| 90 | </simpara></listitem> |
| 91 | </varlistentry> |
| 92 | </variablelist> |
| 93 | </para> |
| 94 | |
| 95 | <para>If no target release has been specified then APT simply assigns |
| 96 | priority 100 to all installed package instances and priority 500 to all |
| 97 | uninstalled package instances. |
| 98 | </para> |
| 99 | |
| 100 | <para>APT then applies the following rules, listed in order of precedence, |
| 101 | to determine which instance of a package to install. |
| 102 | |
| 103 | <itemizedlist> |
| 104 | <listitem><simpara>Never downgrade unless the priority of an available instance |
| 105 | exceeds 1000. ("Downgrading" is installing a less recent version of a package |
| 106 | in place of a more recent version. Note that none of APT's default priorities |
| 107 | exceeds 1000; such high priorities can only be set in the preferences file.) |
| 108 | </simpara></listitem> |
| 109 | <listitem><simpara>Install the highest priority instance. |
| 110 | </simpara></listitem> |
| 111 | <listitem><simpara>If two or more instances have the same priority, |
| 112 | install the most recent one. |
| 113 | </simpara></listitem> |
| 114 | <listitem><simpara>If two or more instances have the same version number, |
| 115 | install the one whose source is listed earliest in &sources-list;. |
| 116 | (The installed instance, if there is one, is always preferred in such a |
| 117 | comparison unless <command>apt-get --reinstall</command> is used.) |
| 118 | </simpara></listitem> |
| 119 | </itemizedlist> |
| 120 | </para> |
| 121 | |
| 122 | <para>In a typical situation, the installed instance of a package (priority 100) |
| 123 | is not as recent as one of the instances available from the sources listed in |
| 124 | the &sources-list; file (priority 500 or 990). Then the package will be |
| 125 | upgraded with the command: |
| 126 | <command>apt-get install</command> or <command>apt-get dist-upgrade</command>. |
| 127 | </para> |
| 128 | |
| 129 | <para>Rarely, the installed instance of a package is <emphasis/more/ recent |
| 130 | than any of the other available instances. The package will not be downgraded. |
| 131 | </para> |
| 132 | |
| 133 | <para>Sometimes the installed instance of a package is more recent than the |
| 134 | version belonging to the target release, but not as recent as a version |
| 135 | belonging to some other distribution. Such a package will indeed be upgraded, |
| 136 | because at least <emphasis/one/ of the available instances has a higher |
| 137 | priority than the installed instance. |
| 138 | </para> |
| 139 | |
| 140 | </RefSect2> |
| 141 | |
| 142 | <RefSect2><Title>The Effect of APT Preferences</> |
| 143 | |
| 144 | <para>The APT preferences file allows the system administrator to customize |
| 145 | priorities. The file consists of one or more multi-line records separated |
| 146 | by blank lines. Records can have one of two forms, a specific form and a |
| 147 | general form. |
| 148 | <itemizedlist> |
| 149 | <listitem> |
| 150 | <simpara>The "specific" form pins a priority (a "Pin-Priority") to a |
| 151 | specified package and specified version or version range. For |
| 152 | example, the following record pins a high priority to all versions of |
| 153 | the <filename/perl/ package whose version number begins with |
| 154 | "<literal/5.8/". |
| 155 | </simpara> |
| 156 | |
| 157 | <programlisting> |
| 158 | Package: perl |
| 159 | Pin: version 5.8* |
| 160 | Pin-Priority: 1001 |
| 161 | </programlisting> |
| 162 | </listitem> |
| 163 | |
| 164 | <listitem><simpara> |
| 165 | The "general" form pins a priority to all of the package versions in a |
| 166 | given distribution (that is, to all the versions of packages that are |
| 167 | listed in a certain <filename/Release/ file), or to all of the package |
| 168 | instances coming from a particular Internet site, as identified by its |
| 169 | fully qualified domain name. |
| 170 | </simpara> |
| 171 | |
| 172 | <simpara>This general-form entry in the APT preferences file applies only |
| 173 | to groups of packages. For example, the following record causes APT to |
| 174 | assign a high priority to all package instances available from the local |
| 175 | site. |
| 176 | </simpara> |
| 177 | |
| 178 | <programlisting> |
| 179 | Package: * |
| 180 | Pin: origin "" |
| 181 | Pin-Priority: 999 |
| 182 | </programlisting> |
| 183 | |
| 184 | <simpara>A note of caution: the keyword used here is "<literal/origin/". |
| 185 | This should not be confused with the "Origin:" of a distribution as |
| 186 | specified in a <filename/Release/ file. What follows the "Origin:" tag |
| 187 | in a <filename/Release/ file is usually not an Internet site address |
| 188 | but an author or vendor name, such as "Debian" or "Ximian". |
| 189 | </simpara> |
| 190 | |
| 191 | <simpara>The following record causes APT to assign a low priority to all |
| 192 | package versions belonging to any distribution whose "Archive" |
| 193 | (<literal/a/) name is "<literal/unstable/". |
| 194 | </simpara> |
| 195 | |
| 196 | <programlisting> |
| 197 | Package: * |
| 198 | Pin: release a=unstable |
| 199 | Pin-Priority: 50 |
| 200 | </programlisting> |
| 201 | |
| 202 | <simpara>The following record causes APT to assign a high priority to all |
| 203 | package versions belonging to any release whose "Archive" (<literal/a/) |
| 204 | name is "<literal/stable/" and whose release "Version" (<literal/v/) |
| 205 | number is "<literal/3.0/". |
| 206 | </simpara> |
| 207 | |
| 208 | <programlisting> |
| 209 | Package: * |
| 210 | Pin: release a=unstable, v=3.0 |
| 211 | Pin-Priority: 50 |
| 212 | </programlisting> |
| 213 | </listitem> |
| 214 | </itemizedlist> |
| 215 | </para> |
| 216 | |
| 217 | </RefSect2> |
| 218 | |
| 219 | <RefSect2><Title>How APT Interprets Priorities</Title> |
| 220 | |
| 221 | <para>Priorities (P) assigned in the APT preferences file must be positive |
| 222 | or negative integers. They are interpreted as follows (roughly speaking): |
| 223 | |
| 224 | <variablelist> |
| 225 | <varlistentry><term>P > 1000</term> |
| 226 | <listitem><simpara>causes an instance to be installed |
| 227 | even if this constitutes a downgrade of the package |
| 228 | </simpara></listitem> |
| 229 | </varlistentry> |
| 230 | <varlistentry><term>990 < P <=1000</term> |
| 231 | <listitem><simpara>causes an instance to be installed |
| 232 | even if it does not come from the target release, |
| 233 | unless the installed instance is more recent |
| 234 | </simpara></listitem> |
| 235 | </varlistentry> |
| 236 | <varlistentry><term>500 < P <=990</term> |
| 237 | <listitem><simpara>causes an instance to be installed |
| 238 | unless there is an instance available belonging to the target release |
| 239 | or the installed version is more recent |
| 240 | </simpara></listitem> |
| 241 | </varlistentry> |
| 242 | <varlistentry><term>100 < P <=500</term> |
| 243 | <listitem><simpara>causes an instance to be installed |
| 244 | unless there is an instance available belonging to some other |
| 245 | distribution or the installed version is more recent |
| 246 | </simpara></listitem> |
| 247 | <varlistentry><term>0 <= P <=100</term> |
| 248 | <listitem><simpara>causes an instance to be installed |
| 249 | only if there is no installed instance of the package |
| 250 | </simpara></listitem> |
| 251 | </varlistentry> |
| 252 | <varlistentry><term>P < 0</term> |
| 253 | <listitem><simpara>prevents the instance from being installed |
| 254 | </simpara></listitem> |
| 255 | </varlistentry> |
| 256 | </variablelist> |
| 257 | </para> |
| 258 | |
| 259 | <para>If one of the specific-form records described above matches an |
| 260 | available package instance, then that record determines the priority of |
| 261 | the instance. If two specific-form records match an available instance, |
| 262 | then the first record encountered determines the priority. If two |
| 263 | general-form records match an available instance, then the first record |
| 264 | encountered determines the priority. |
| 265 | </para> |
| 266 | |
| 267 | <para>For example, suppose the APT preferences file contains the three |
| 268 | records presented earlier: |
| 269 | |
| 270 | <programlisting> |
| 271 | Package: perl |
| 272 | Pin: version 5.8* |
| 273 | Pin-Priority: 1001 |
| 274 | |
| 275 | Package: * |
| 276 | Pin: origin "" |
| 277 | Pin-Priority: 999 |
| 278 | |
| 279 | Package: * |
| 280 | Pin: release unstable |
| 281 | Pin-Priority: 50 |
| 282 | </programlisting> |
| 283 | |
| 284 | Then: |
| 285 | |
| 286 | <itemizedlist> |
| 287 | <listitem><simpara>The most recent available version of the <literal/perl/ |
| 288 | package will be installed, so long as that version's version number begins |
| 289 | with "<literal/5.8/". If <emphasis/any/ 5.8* version of <literal/perl/ is |
| 290 | available and the installed version is 5.9*, then <literal/perl/ will be |
| 291 | downgraded.</simpara></listitem> |
| 292 | <listitem><simpara>An instance of any package other than <literal/perl/ |
| 293 | that is available from the local system has priority over other instances, |
| 294 | even instances belonging to the target release. |
| 295 | </simpara></listitem> |
| 296 | <listitem><simpara>An instance of a package whose origin is not the local |
| 297 | system but some other site listed in &sources-list;, and which belongs to |
| 298 | an "<literal/unstable/" distribution, is only installed if it is selected |
| 299 | for installation and no instance of the package is already installed. |
| 300 | </simpara></listitem> |
| 301 | </itemizedlist> |
| 302 | </para> |
| 303 | </RefSect2> |
| 304 | |
| 305 | <RefSect2><Title>Determination of Package Version and Distribution Properties</Title> |
| 306 | |
| 307 | <para>The locations listed in a system's &sources-list; file should provide |
| 308 | <filename>Packages</filename> and <filename>Release</filename> files |
| 309 | to describe the package instances available at that location. |
| 310 | </para> |
| 311 | |
| 312 | <para>The <filename>Packages</filename> file is normally found in the directory |
| 313 | <filename>.../dists/<replaceable>dist-name</replaceable>/<replaceable>component</replaceable>/<replaceable>arch</replaceable></filename>: |
| 314 | for example, <filename>.../dists/stable/main/binary-i386/Packages</filename>. |
| 315 | It consists of a series of multi-line records, one for each package available |
| 316 | in that directory. Only two lines in each record are relevant for setting |
| 317 | APT priorities: |
| 318 | <variablelist> |
| 319 | <varlistentry> |
| 320 | <term>the <literal/Package:/ line</term> |
| 321 | <listitem><simpara>gives the package name</simpara></listitem> |
| 322 | </varlistentry> |
| 323 | <varlistentry> |
| 324 | <term>the <literal/Version:/ line</term> |
| 325 | <listitem><simpara>gives the version number for the named package</simpara></listitem> |
| 326 | </varlistentry> |
| 327 | </variablelist> |
| 328 | </para> |
| 329 | |
| 330 | <para>The <filename>Release</filename> file is normally found in the directory |
| 331 | <filename>.../dists/<replaceable>dist-name</replaceable></filename>: |
| 332 | for example, <filename>.../dists/stable/Release</filename>, |
| 333 | or <filename>.../dists/woody/Release</filename>. |
| 334 | It consists of a single multi-line record which applies to <emphasis/all/ of |
| 335 | the package instances in the directory tree below its parent. Unlike the |
| 336 | <filename/Packages/ file, nearly all of the lines in a <filename/Release/ |
| 337 | file are relevant for setting APT priorities: |
| 338 | |
| 339 | <variablelist> |
| 340 | <varlistentry> |
| 341 | <term>the <literal/Archive:/ line</term> |
| 342 | <listitem><simpara>names the archive to which all the package instances |
| 343 | in the directory tree belong. For example, the line |
| 344 | <literal/Archive: stable/ specifies that all of the packages in the directory |
| 345 | tree below the parent of the <filename/Release/ file are in the |
| 346 | <literal/stable/ archive. Specifying this value in the APT preferences file |
| 347 | would require the line: |
| 348 | </simpara> |
| 349 | |
| 350 | <programlisting> |
| 351 | Pin: release a=stable |
| 352 | </programlisting> |
| 353 | </listitem> |
| 354 | </varlistentry> |
| 355 | |
| 356 | <varlistentry> |
| 357 | <term>the <literal/Version:/ line</term> |
| 358 | <listitem><simpara>names the release version. For example, the |
| 359 | package instances in the tree might belong to Debian GNU/Linux release |
| 360 | version 3.0. There is normally no version number for the "testing" and |
| 361 | "unstable" distributions because they have not yet been released. |
| 362 | Specifying this in the APT preferences file would require one of the |
| 363 | following lines. |
| 364 | </simpara> |
| 365 | |
| 366 | <programlisting> |
| 367 | Pin: release v=3.0 |
| 368 | Pin: release a=stable v=3.0 |
| 369 | Pin: release 3.0 |
| 370 | </programlisting> |
| 371 | |
| 372 | </listitem> |
| 373 | </varlistentry> |
| 374 | |
| 375 | <varlistentry> |
| 376 | <term>the <literal/Component:/ line</term> |
| 377 | <listitem><simpara>names the licensing component associated with the |
| 378 | package instances in the directory tree of the <filename/Release/ |
| 379 | file. For example, the line <literal/Component: main/ specifies that |
| 380 | all the instances in the directory tree are from the <literal/main/ |
| 381 | component, meaning that they are licensed under terms listed in the |
| 382 | Debian Free Software Guidelines. Specifying this component in the |
| 383 | APT preferences file would require the line: |
| 384 | </simpara> |
| 385 | |
| 386 | <programlisting> |
| 387 | Pin: release c=main |
| 388 | </programlisting> |
| 389 | </listitem> |
| 390 | </varlistentry> |
| 391 | |
| 392 | <varlistentry> |
| 393 | <term>the <literal/Origin:/ line</term> |
| 394 | <listitem><simpara>names the producer of the package instances in the |
| 395 | directory tree of the <filename/Release/ file. Most commonly, this is |
| 396 | <literal/Debian/. Specifying this origin in the APT preferences file |
| 397 | would require the line: |
| 398 | </simpara> |
| 399 | |
| 400 | <programlisting> |
| 401 | Pin: release o=Debian |
| 402 | </programlisting> |
| 403 | </listitem> |
| 404 | </varlistentry> |
| 405 | |
| 406 | <varlistentry> |
| 407 | <term>the <literal/Label:/ line</term> |
| 408 | <listitem><simpara>seems redundant. Most commonly, this is |
| 409 | <literal/Debian/. Specifying this label in the APT preferences file |
| 410 | would require the line: |
| 411 | </simpara> |
| 412 | |
| 413 | <programlisting> |
| 414 | Pin: release l=Debian |
| 415 | </programlisting> |
| 416 | </listitem> |
| 417 | </varlistentry> |
| 418 | </variablelist> |
| 419 | </para> |
| 420 | |
| 421 | <para>All of the <filename>Packages</filename> and <filename>Release</filename> |
| 422 | files retrieved from locations listed in the &sources-list; file are kept |
| 423 | in the directory <filename>/var/lib/apt/lists</filename>, or in the file named |
| 424 | by the variable <literal/Dir::State::Lists/ in the <filename/apt.conf/ file. |
| 425 | For example, the file |
| 426 | <filename>debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release</filename> |
| 427 | contains the <filename>Release</filename> file retrieved from the site |
| 428 | <literal/debian.lcs.mit.edu/ for <literal/binary-i386/ architecture |
| 429 | files from the <literal/contrib/ component of the <literal/unstable/ |
| 430 | distribution. |
| 431 | </para> |
| 432 | |
| 433 | </RefSect2> |
| 434 | |
| 435 | <RefSect2><Title>Optional Lines in an APT Preferences Record</Title> |
| 436 | |
| 437 | <para>Each record in the APT preferences file can optionally begin with |
| 438 | one or more lines beginning with the word <literal/Explanation:/. |
| 439 | This provides an opportunity to comment on the record. |
| 440 | </para> |
| 441 | |
| 442 | <para>The <literal/Pin-Priority:/ line in each APT preferences record is |
| 443 | optional. If omitted, APT assigs a priority of 1 less than the last value |
| 444 | specified on a line beginning with <literal/Pin-Priority: release .../. |
| 445 | </para> |
| 446 | </RefSect2> |
| 447 | </RefSect1> |
| 448 | |
| 449 | <RefSect1><Title>Examples</> |
| 450 | <RefSect2><Title>Tracking Stable</Title> |
| 451 | |
| 452 | <para>The following APT preferences file will cause APT to assign a |
| 453 | priority higher than the default (500) to all package versions belonging |
| 454 | to a <literal/stable/ distribution and a prohibitively low priority to |
| 455 | package versions belonging to other <literal/Debian/ distributions. |
| 456 | |
| 457 | <programlisting> |
| 458 | Package: * |
| 459 | Pin: release a=stable |
| 460 | Pin-Priority: 900 |
| 461 | |
| 462 | Explanation: Uninstall or do not install any Debian-originated |
| 463 | Explanation: instances other than those in the stable distro |
| 464 | Package: * |
| 465 | Pin: release o=Debian |
| 466 | Pin-Priority: -10 |
| 467 | </programlisting> |
| 468 | </para> |
| 469 | |
| 470 | <para> |
| 471 | With a suitable &sources-list; file and the above preferences file, |
| 472 | any of the following commands will cause APT to upgrade to the |
| 473 | latest <literal/stable/ version(s). |
| 474 | |
| 475 | <programlisting> |
| 476 | apt-get install <replaceable>package-name</replaceable> |
| 477 | apt-get upgrade |
| 478 | apt-get dist-upgrade |
| 479 | </programlisting> |
| 480 | </para> |
| 481 | |
| 482 | <para>The following command will cause APT to upgrade the specified |
| 483 | package to the latest version from the <literal/testing/ distribution; |
| 484 | further upgrades will not occur automatically, however. |
| 485 | |
| 486 | <programlisting> |
| 487 | apt-get install <replaceable>package</replaceable>/testing |
| 488 | </programlisting> |
| 489 | </RefSect2> |
| 490 | |
| 491 | <RefSect2><Title>Tracking Testing</Title> |
| 492 | |
| 493 | <para>The following APT preferences file will cause APT to assign |
| 494 | a high priority to package versions from the <literal/testing/ |
| 495 | distribution, a lesser priority to package versions from the |
| 496 | <literal/unstable/ distribution, and a prohibitively low priority |
| 497 | to package versions from other <literal/Debian/ distributions. |
| 498 | |
| 499 | <programlisting> |
| 500 | Package: * |
| 501 | Pin: release a=testing |
| 502 | Pin-Priority: 900 |
| 503 | |
| 504 | Package: * |
| 505 | Pin: release a=unstable |
| 506 | Pin-Priority: 800 |
| 507 | |
| 508 | Package: * |
| 509 | Pin: release o=Debian |
| 510 | Pin-Priority: -10 |
| 511 | </programlisting> |
| 512 | </para> |
| 513 | |
| 514 | <para> |
| 515 | With the above APT preferences file, any of the |
| 516 | following commands will cause APT to upgrade to the latest |
| 517 | <literal/testing/ version(s). |
| 518 | |
| 519 | <programlisting> |
| 520 | apt-get install <replaceable>package-name</replaceable> |
| 521 | apt-get upgrade |
| 522 | apt-get dist-upgrade |
| 523 | </programlisting> |
| 524 | </para> |
| 525 | |
| 526 | <para>The following command will cause APT to upgrade the specified |
| 527 | package to the latest version from the <literal/unstable/ distribution. |
| 528 | Thereafter, <command>apt-get dist-upgrade</command> and the others |
| 529 | <emphasis/will/ cause upgrade of the package to the latest |
| 530 | <literal/unstable/ version. |
| 531 | |
| 532 | <programlisting> |
| 533 | apt-get install <replaceable>package</replaceable>/unstable |
| 534 | </programlisting> |
| 535 | </para> |
| 536 | |
| 537 | </RefSect2> |
| 538 | </RefSect1> |
| 539 | |
| 540 | <RefSect1><Title>See Also</> |
| 541 | <para> |
| 542 | &apt-get; &apt-cache; &apt-conf; &sources-list; |
| 543 | </RefSect1> |
| 544 | |
| 545 | &manbugs; |
| 546 | &manauthor; |
| 547 | |
| 548 | </refentry> |