Commit | Line | Data |
---|---|---|
24f6490f AL |
1 | <?xml version="1.0" encoding="utf-8" standalone="no"?> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ | |
b2e465d6 AL |
4 | |
5 | <!ENTITY % aptent SYSTEM "apt.ent"> | |
6 | %aptent; | |
7 | ||
0c1a7101 DK |
8 | <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> |
9 | %aptverbatiment; | |
10 | ||
b2e465d6 AL |
11 | ]> |
12 | ||
13 | <refentry> | |
ec2853a7 | 14 | |
5e80de29 AL |
15 | <refentryinfo> |
16 | &apt-author.team; | |
17 | &apt-email; | |
18 | &apt-product; | |
19 | <!-- The last update date --> | |
d9dedf30 | 20 | <date>16 February 2010</date> |
5e80de29 AL |
21 | </refentryinfo> |
22 | ||
b2e465d6 | 23 | <refmeta> |
24f6490f AL |
24 | <refentrytitle>apt_preferences</refentrytitle> |
25 | <manvolnum>5</manvolnum> | |
f0599b9c | 26 | <refmiscinfo class="manual">APT</refmiscinfo> |
b2e465d6 | 27 | </refmeta> |
ec2853a7 | 28 | |
b2e465d6 AL |
29 | <!-- Man page title --> |
30 | <refnamediv> | |
24f6490f AL |
31 | <refname>apt_preferences</refname> |
32 | <refpurpose>Preference control file for APT</refpurpose> | |
b2e465d6 | 33 | </refnamediv> |
b2e465d6 | 34 | |
24f6490f AL |
35 | <refsect1> |
36 | <title>Description</title> | |
37 | <para>The APT preferences file <filename>/etc/apt/preferences</filename> | |
daa4aa52 DK |
38 | and the fragment files in the <filename>/etc/apt/preferences.d/</filename> |
39 | folder can be used to control which versions of packages will be selected | |
24f6490f | 40 | for installation.</para> |
ec2853a7 | 41 | |
24f6490f | 42 | <para>Several versions of a package may be available for installation when |
ec2853a7 | 43 | the &sources-list; file contains references to more than one distribution |
5b9d504e AL |
44 | (for example, <literal>stable</literal> and <literal>testing</literal>). |
45 | APT assigns a priority to each version that is available. | |
46 | Subject to dependency constraints, <command>apt-get</command> selects the | |
408a8e0a | 47 | version with the highest priority for installation. |
5b9d504e AL |
48 | The APT preferences file overrides the priorities that APT assigns to |
49 | package versions by default, thus giving the user control over which | |
24f6490f AL |
50 | one is selected for installation.</para> |
51 | ||
52 | <para>Several instances of the same version of a package may be available when | |
408a8e0a AL |
53 | the &sources-list; file contains references to more than one source. |
54 | In this case <command>apt-get</command> downloads the instance listed | |
5b9d504e | 55 | earliest in the &sources-list; file. |
408a8e0a | 56 | The APT preferences file does not affect the choice of instance, only |
24f6490f | 57 | the choice of version.</para> |
ec2853a7 | 58 | |
d9dedf30 DK |
59 | <para>Preferences are a strong power in the hands of a system administrator |
60 | but they can become also their biggest nightmare if used without care! | |
61 | APT will not questioning the preferences so wrong settings will therefore | |
62 | lead to uninstallable packages or wrong decisions while upgrading packages. | |
63 | Even more problems will arise if multiply distribution releases are mixed | |
64 | without a good understanding of the following paragraphs. | |
37049546 DK |
65 | Packages included in a specific release aren't tested in and |
66 | therefore doesn't always work as expected in older or newer releases or | |
67 | together with other packages from different releases. | |
d9dedf30 DK |
68 | You have been warned.</para> |
69 | ||
e29a6bb1 DK |
70 | <para>Note that the files in the <filename>/etc/apt/preferences.d</filename> |
71 | directory are parsed in alphanumeric ascending order and need to obey the | |
72 | following naming convention: The files have no or "<literal>pref</literal>" | |
73 | as filename extension and which only contain alphanumeric, hyphen (-), | |
7376837d DK |
74 | underscore (_) and period (.) characters. |
75 | Otherwise APT will print a notice that it has ignored a file if the file | |
76 | doesn't match a pattern in the <literal>Dir::Ignore-Files-Silently</literal> | |
77 | configuration list - in this case it will be silently ignored.</para> | |
e29a6bb1 | 78 | |
24f6490f | 79 | <refsect2><title>APT's Default Priority Assignments</title> |
ec2853a7 | 80 | |
24f6490f | 81 | <para>If there is no preferences file or if there is no entry in the file |
408a8e0a AL |
82 | that applies to a particular version then the priority assigned to that |
83 | version is the priority of the distribution to which that version | |
84 | belongs. It is possible to single out a distribution, "the target release", | |
85 | which receives a higher priority than other distributions do by default. | |
86 | The target release can be set on the <command>apt-get</command> command | |
87 | line or in the APT configuration file <filename>/etc/apt/apt.conf</filename>. | |
99fc3e08 LB |
88 | Note that this has precedence over any general priority you set in the |
89 | <filename>/etc/apt/preferences</filename> file described later, but not | |
90 | over specifically pinned packages. | |
408a8e0a | 91 | For example, |
24f6490f | 92 | |
408a8e0a AL |
93 | <programlisting> |
94 | <command>apt-get install -t testing <replaceable>some-package</replaceable></command> | |
95 | </programlisting> | |
96 | <programlisting> | |
97 | APT::Default-Release "stable"; | |
98 | </programlisting> | |
ec2853a7 AL |
99 | </para> |
100 | ||
24f6490f | 101 | <para>If the target release has been specified then APT uses the following |
408a8e0a | 102 | algorithm to set the priorities of the versions of a package. Assign: |
24f6490f | 103 | |
ec2853a7 | 104 | <variablelist> |
10df254b DK |
105 | <varlistentry> |
106 | <term>priority 1</term> | |
107 | <listitem><simpara>to the versions coming from archives which in their <filename>Release</filename> | |
108 | files are marked as "NotAutomatic: yes" like the debian experimental archive.</simpara></listitem> | |
109 | </varlistentry> | |
110 | ||
ec2853a7 AL |
111 | <varlistentry> |
112 | <term>priority 100</term> | |
5b9d504e | 113 | <listitem><simpara>to the version that is already installed (if any).</simpara></listitem> |
ec2853a7 | 114 | </varlistentry> |
24f6490f | 115 | |
ec2853a7 AL |
116 | <varlistentry> |
117 | <term>priority 500</term> | |
5b9d504e | 118 | <listitem><simpara>to the versions that are not installed and do not belong to the target release.</simpara></listitem> |
ec2853a7 | 119 | </varlistentry> |
24f6490f | 120 | |
ec2853a7 AL |
121 | <varlistentry> |
122 | <term>priority 990</term> | |
5b9d504e | 123 | <listitem><simpara>to the versions that are not installed and belong to the target release.</simpara></listitem> |
ec2853a7 AL |
124 | </varlistentry> |
125 | </variablelist> | |
126 | </para> | |
127 | ||
24f6490f | 128 | <para>If the target release has not been specified then APT simply assigns |
5b9d504e | 129 | priority 100 to all installed package versions and priority 500 to all |
10df254b DK |
130 | uninstalled package versions, expect versions coming from archives which |
131 | in their <filename>Release</filename> files are marked as "NotAutomatic: yes" - | |
132 | these versions get the priority 1.</para> | |
ec2853a7 | 133 | |
24f6490f | 134 | <para>APT then applies the following rules, listed in order of precedence, |
5b9d504e | 135 | to determine which version of a package to install. |
ec2853a7 | 136 | <itemizedlist> |
5b9d504e AL |
137 | <listitem><simpara>Never downgrade unless the priority of an available |
138 | version exceeds 1000. ("Downgrading" is installing a less recent version | |
139 | of a package in place of a more recent version. Note that none of APT's | |
140 | default priorities exceeds 1000; such high priorities can only be set in | |
141 | the preferences file. Note also that downgrading a package | |
142 | can be risky.)</simpara></listitem> | |
143 | <listitem><simpara>Install the highest priority version.</simpara></listitem> | |
144 | <listitem><simpara>If two or more versions have the same priority, | |
145 | install the most recent one (that is, the one with the higher version | |
146 | number).</simpara></listitem> | |
147 | <listitem><simpara>If two or more versions have the same priority and | |
148 | version number but either the packages differ in some of their metadata or the | |
24f6490f | 149 | <literal>--reinstall</literal> option is given, install the uninstalled one.</simpara></listitem> |
ec2853a7 AL |
150 | </itemizedlist> |
151 | </para> | |
152 | ||
24f6490f | 153 | <para>In a typical situation, the installed version of a package (priority 100) |
5b9d504e AL |
154 | is not as recent as one of the versions available from the sources listed in |
155 | the &sources-list; file (priority 500 or 990). Then the package will be upgraded | |
156 | when <command>apt-get install <replaceable>some-package</replaceable></command> | |
157 | or <command>apt-get upgrade</command> is executed. | |
ec2853a7 AL |
158 | </para> |
159 | ||
24f6490f | 160 | <para>More rarely, the installed version of a package is <emphasis>more</emphasis> recent |
5b9d504e AL |
161 | than any of the other available versions. The package will not be downgraded |
162 | when <command>apt-get install <replaceable>some-package</replaceable></command> | |
24f6490f | 163 | or <command>apt-get upgrade</command> is executed.</para> |
ec2853a7 | 164 | |
24f6490f | 165 | <para>Sometimes the installed version of a package is more recent than the |
ec2853a7 | 166 | version belonging to the target release, but not as recent as a version |
5b9d504e AL |
167 | belonging to some other distribution. Such a package will indeed be upgraded |
168 | when <command>apt-get install <replaceable>some-package</replaceable></command> | |
169 | or <command>apt-get upgrade</command> is executed, | |
24f6490f AL |
170 | because at least <emphasis>one</emphasis> of the available versions has a higher |
171 | priority than the installed version.</para> | |
172 | </refsect2> | |
ec2853a7 | 173 | |
24f6490f | 174 | <refsect2><title>The Effect of APT Preferences</title> |
ec2853a7 | 175 | |
24f6490f | 176 | <para>The APT preferences file allows the system administrator to control the |
5b9d504e AL |
177 | assignment of priorities. The file consists of one or more multi-line records |
178 | separated by blank lines. Records can have one of two forms, a specific form | |
179 | and a general form. | |
ec2853a7 AL |
180 | <itemizedlist> |
181 | <listitem> | |
1c62ab24 MV |
182 | <simpara>The specific form assigns a priority (a "Pin-Priority") to one or more |
183 | specified packages and specified version or version range. For example, | |
5b9d504e | 184 | the following record assigns a high priority to all versions of |
1c62ab24 MV |
185 | the <filename>perl</filename> package whose version number begins with "<literal>5.8</literal>". |
186 | Multiple packages can be separated by spaces.</simpara> | |
ec2853a7 AL |
187 | |
188 | <programlisting> | |
189 | Package: perl | |
190 | Pin: version 5.8* | |
191 | Pin-Priority: 1001 | |
192 | </programlisting> | |
193 | </listitem> | |
194 | ||
24f6490f | 195 | <listitem><simpara>The general form assigns a priority to all of the package versions in a |
ec2853a7 | 196 | given distribution (that is, to all the versions of packages that are |
24f6490f | 197 | listed in a certain <filename>Release</filename> file) or to all of the package |
5b9d504e | 198 | versions coming from a particular Internet site, as identified by the |
24f6490f | 199 | site's fully qualified domain name.</simpara> |
ec2853a7 | 200 | |
24f6490f | 201 | <simpara>This general-form entry in the APT preferences file applies only |
5b9d504e | 202 | to groups of packages. For example, the following record assigns a high |
24f6490f | 203 | priority to all package versions available from the local site.</simpara> |
ec2853a7 AL |
204 | |
205 | <programlisting> | |
206 | Package: * | |
207 | Pin: origin "" | |
208 | Pin-Priority: 999 | |
209 | </programlisting> | |
210 | ||
4fb6fdaf DK |
211 | <simpara>A note of caution: the keyword used here is "<literal>origin</literal>" |
212 | which can be used to match a hostname. The following record will assign a high priority | |
213 | to all versions available from the server identified by the hostname "ftp.de.debian.org"</simpara> | |
214 | <programlisting> | |
215 | Package: * | |
216 | Pin: origin "ftp.de.debian.org" | |
217 | Pin-Priority: 999 | |
218 | </programlisting> | |
219 | <simpara>This should <emphasis>not</emphasis> be confused with the Origin of a distribution as | |
24f6490f AL |
220 | specified in a <filename>Release</filename> file. What follows the "Origin:" tag |
221 | in a <filename>Release</filename> file is not an Internet address | |
222 | but an author or vendor name, such as "Debian" or "Ximian".</simpara> | |
ec2853a7 | 223 | |
24f6490f AL |
224 | <simpara>The following record assigns a low priority to all package versions |
225 | belonging to any distribution whose Archive name is "<literal>unstable</literal>".</simpara> | |
ec2853a7 AL |
226 | |
227 | <programlisting> | |
228 | Package: * | |
229 | Pin: release a=unstable | |
704c39d6 | 230 | Pin-Priority: 50 |
ec2853a7 AL |
231 | </programlisting> |
232 | ||
efc487fb | 233 | <simpara>The following record assigns a high priority to all package versions |
e1dd65c9 | 234 | belonging to any distribution whose Codename is "<literal>&testing-codename;</literal>".</simpara> |
efc487fb DK |
235 | |
236 | <programlisting> | |
237 | Package: * | |
e1dd65c9 | 238 | Pin: release n=&testing-codename; |
efc487fb DK |
239 | Pin-Priority: 900 |
240 | </programlisting> | |
241 | ||
24f6490f AL |
242 | <simpara>The following record assigns a high priority to all package versions |
243 | belonging to any release whose Archive name is "<literal>stable</literal>" | |
244 | and whose release Version number is "<literal>3.0</literal>".</simpara> | |
ec2853a7 AL |
245 | |
246 | <programlisting> | |
247 | Package: * | |
0493db1e MZ |
248 | Pin: release a=stable, v=3.0 |
249 | Pin-Priority: 500 | |
ec2853a7 AL |
250 | </programlisting> |
251 | </listitem> | |
252 | </itemizedlist> | |
253 | </para> | |
254 | ||
24f6490f | 255 | </refsect2> |
ec2853a7 | 256 | |
24f6490f AL |
257 | <refsect2> |
258 | <title>How APT Interprets Priorities</title> | |
ec2853a7 | 259 | |
5b9d504e AL |
260 | <para> |
261 | Priorities (P) assigned in the APT preferences file must be positive | |
ec2853a7 AL |
262 | or negative integers. They are interpreted as follows (roughly speaking): |
263 | ||
264 | <variablelist> | |
5b9d504e AL |
265 | <varlistentry> |
266 | <term>P > 1000</term> | |
267 | <listitem><simpara>causes a version to be installed even if this | |
268 | constitutes a downgrade of the package</simpara></listitem> | |
ec2853a7 | 269 | </varlistentry> |
5b9d504e AL |
270 | <varlistentry> |
271 | <term>990 < P <=1000</term> | |
272 | <listitem><simpara>causes a version to be installed | |
ec2853a7 | 273 | even if it does not come from the target release, |
5b9d504e | 274 | unless the installed version is more recent</simpara></listitem> |
ec2853a7 | 275 | </varlistentry> |
5b9d504e AL |
276 | <varlistentry> |
277 | <term>500 < P <=990</term> | |
278 | <listitem><simpara>causes a version to be installed | |
279 | unless there is a version available belonging to the target release | |
280 | or the installed version is more recent</simpara></listitem> | |
ec2853a7 | 281 | </varlistentry> |
5b9d504e AL |
282 | <varlistentry> |
283 | <term>100 < P <=500</term> | |
284 | <listitem><simpara>causes a version to be installed | |
285 | unless there is a version available belonging to some other | |
286 | distribution or the installed version is more recent</simpara></listitem> | |
24f6490f | 287 | </varlistentry> |
5b9d504e | 288 | <varlistentry> |
56298634 | 289 | <term>0 < P <=100</term> |
5b9d504e AL |
290 | <listitem><simpara>causes a version to be installed |
291 | only if there is no installed version of the package</simpara></listitem> | |
ec2853a7 | 292 | </varlistentry> |
5b9d504e AL |
293 | <varlistentry> |
294 | <term>P < 0</term> | |
295 | <listitem><simpara>prevents the version from being installed</simpara></listitem> | |
ec2853a7 AL |
296 | </varlistentry> |
297 | </variablelist> | |
298 | </para> | |
299 | ||
24f6490f | 300 | <para>If any specific-form records match an available package version then the |
5b9d504e AL |
301 | first such record determines the priority of the package version. |
302 | Failing that, | |
303 | if any general-form records match an available package version then the | |
24f6490f | 304 | first such record determines the priority of the package version.</para> |
ec2853a7 | 305 | |
24f6490f AL |
306 | <para>For example, suppose the APT preferences file contains the three |
307 | records presented earlier:</para> | |
ec2853a7 AL |
308 | |
309 | <programlisting> | |
310 | Package: perl | |
311 | Pin: version 5.8* | |
b2e465d6 | 312 | Pin-Priority: 1001 |
ec2853a7 | 313 | |
b2e465d6 | 314 | Package: * |
ec2853a7 AL |
315 | Pin: origin "" |
316 | Pin-Priority: 999 | |
317 | ||
318 | Package: * | |
319 | Pin: release unstable | |
320 | Pin-Priority: 50 | |
321 | </programlisting> | |
322 | ||
24f6490f | 323 | <para>Then: |
ec2853a7 | 324 | <itemizedlist> |
24f6490f | 325 | <listitem><simpara>The most recent available version of the <literal>perl</literal> |
ec2853a7 | 326 | package will be installed, so long as that version's version number begins |
24f6490f AL |
327 | with "<literal>5.8</literal>". If <emphasis>any</emphasis> 5.8* version of <literal>perl</literal> is |
328 | available and the installed version is 5.9*, then <literal>perl</literal> will be | |
ec2853a7 | 329 | downgraded.</simpara></listitem> |
24f6490f | 330 | <listitem><simpara>A version of any package other than <literal>perl</literal> |
5b9d504e AL |
331 | that is available from the local system has priority over other versions, |
332 | even versions belonging to the target release. | |
ec2853a7 | 333 | </simpara></listitem> |
5b9d504e AL |
334 | <listitem><simpara>A version of a package whose origin is not the local |
335 | system but some other site listed in &sources-list; and which belongs to | |
24f6490f | 336 | an <literal>unstable</literal> distribution is only installed if it is selected |
5b9d504e | 337 | for installation and no version of the package is already installed. |
ec2853a7 AL |
338 | </simpara></listitem> |
339 | </itemizedlist> | |
340 | </para> | |
24f6490f | 341 | </refsect2> |
ec2853a7 | 342 | |
24f6490f AL |
343 | <refsect2> |
344 | <title>Determination of Package Version and Distribution Properties</title> | |
ec2853a7 | 345 | |
24f6490f | 346 | <para>The locations listed in the &sources-list; file should provide |
ec2853a7 | 347 | <filename>Packages</filename> and <filename>Release</filename> files |
24f6490f | 348 | to describe the packages available at that location. </para> |
ec2853a7 | 349 | |
24f6490f | 350 | <para>The <filename>Packages</filename> file is normally found in the directory |
ec2853a7 AL |
351 | <filename>.../dists/<replaceable>dist-name</replaceable>/<replaceable>component</replaceable>/<replaceable>arch</replaceable></filename>: |
352 | for example, <filename>.../dists/stable/main/binary-i386/Packages</filename>. | |
353 | It consists of a series of multi-line records, one for each package available | |
354 | in that directory. Only two lines in each record are relevant for setting | |
355 | APT priorities: | |
356 | <variablelist> | |
357 | <varlistentry> | |
24f6490f | 358 | <term>the <literal>Package:</literal> line</term> |
ec2853a7 AL |
359 | <listitem><simpara>gives the package name</simpara></listitem> |
360 | </varlistentry> | |
361 | <varlistentry> | |
24f6490f | 362 | <term>the <literal>Version:</literal> line</term> |
ec2853a7 AL |
363 | <listitem><simpara>gives the version number for the named package</simpara></listitem> |
364 | </varlistentry> | |
365 | </variablelist> | |
366 | </para> | |
367 | ||
24f6490f | 368 | <para>The <filename>Release</filename> file is normally found in the directory |
ec2853a7 AL |
369 | <filename>.../dists/<replaceable>dist-name</replaceable></filename>: |
370 | for example, <filename>.../dists/stable/Release</filename>, | |
e1dd65c9 | 371 | or <filename>.../dists/&stable-codename;/Release</filename>. |
24f6490f | 372 | It consists of a single multi-line record which applies to <emphasis>all</emphasis> of |
5b9d504e | 373 | the packages in the directory tree below its parent. Unlike the |
24f6490f | 374 | <filename>Packages</filename> file, nearly all of the lines in a <filename>Release</filename> |
ec2853a7 AL |
375 | file are relevant for setting APT priorities: |
376 | ||
377 | <variablelist> | |
378 | <varlistentry> | |
efc487fb | 379 | <term>the <literal>Archive:</literal> or <literal>Suite:</literal> line</term> |
5b9d504e | 380 | <listitem><simpara>names the archive to which all the packages |
ec2853a7 | 381 | in the directory tree belong. For example, the line |
efc487fb DK |
382 | "Archive: stable" or |
383 | "Suite: stable" | |
5b9d504e | 384 | specifies that all of the packages in the directory |
24f6490f AL |
385 | tree below the parent of the <filename>Release</filename> file are in a |
386 | <literal>stable</literal> archive. Specifying this value in the APT preferences file | |
ec2853a7 AL |
387 | would require the line: |
388 | </simpara> | |
ec2853a7 AL |
389 | <programlisting> |
390 | Pin: release a=stable | |
391 | </programlisting> | |
392 | </listitem> | |
393 | </varlistentry> | |
394 | ||
efc487fb DK |
395 | <varlistentry> |
396 | <term>the <literal>Codename:</literal> line</term> | |
397 | <listitem><simpara>names the codename to which all the packages | |
398 | in the directory tree belong. For example, the line | |
e1dd65c9 | 399 | "Codename: &testing-codename;" |
efc487fb DK |
400 | specifies that all of the packages in the directory |
401 | tree below the parent of the <filename>Release</filename> file belong to a version named | |
e1dd65c9 | 402 | <literal>&testing-codename;</literal>. Specifying this value in the APT preferences file |
efc487fb DK |
403 | would require the line: |
404 | </simpara> | |
405 | <programlisting> | |
e1dd65c9 | 406 | Pin: release n=&testing-codename; |
efc487fb DK |
407 | </programlisting> |
408 | </listitem> | |
409 | </varlistentry> | |
410 | ||
ec2853a7 | 411 | <varlistentry> |
24f6490f | 412 | <term>the <literal>Version:</literal> line</term> |
ec2853a7 | 413 | <listitem><simpara>names the release version. For example, the |
5b9d504e AL |
414 | packages in the tree might belong to Debian GNU/Linux release |
415 | version 3.0. Note that there is normally no version number for the | |
24f6490f | 416 | <literal>testing</literal> and <literal>unstable</literal> distributions because they |
5b9d504e AL |
417 | have not been released yet. Specifying this in the APT preferences |
418 | file would require one of the following lines. | |
ec2853a7 AL |
419 | </simpara> |
420 | ||
421 | <programlisting> | |
422 | Pin: release v=3.0 | |
f6271220 | 423 | Pin: release a=stable, v=3.0 |
ec2853a7 AL |
424 | Pin: release 3.0 |
425 | </programlisting> | |
426 | ||
427 | </listitem> | |
428 | </varlistentry> | |
429 | ||
430 | <varlistentry> | |
24f6490f | 431 | <term>the <literal>Component:</literal> line</term> |
ec2853a7 | 432 | <listitem><simpara>names the licensing component associated with the |
24f6490f | 433 | packages in the directory tree of the <filename>Release</filename> file. |
5b9d504e | 434 | For example, the line "Component: main" specifies that |
24f6490f | 435 | all the packages in the directory tree are from the <literal>main</literal> |
5b9d504e AL |
436 | component, which entails that they are licensed under terms listed |
437 | in the Debian Free Software Guidelines. Specifying this component | |
438 | in the APT preferences file would require the line: | |
ec2853a7 | 439 | </simpara> |
ec2853a7 AL |
440 | <programlisting> |
441 | Pin: release c=main | |
442 | </programlisting> | |
443 | </listitem> | |
444 | </varlistentry> | |
445 | ||
446 | <varlistentry> | |
24f6490f | 447 | <term>the <literal>Origin:</literal> line</term> |
5b9d504e | 448 | <listitem><simpara>names the originator of the packages in the |
24f6490f AL |
449 | directory tree of the <filename>Release</filename> file. Most commonly, this is |
450 | <literal>Debian</literal>. Specifying this origin in the APT preferences file | |
ec2853a7 AL |
451 | would require the line: |
452 | </simpara> | |
ec2853a7 AL |
453 | <programlisting> |
454 | Pin: release o=Debian | |
455 | </programlisting> | |
456 | </listitem> | |
457 | </varlistentry> | |
458 | ||
459 | <varlistentry> | |
24f6490f | 460 | <term>the <literal>Label:</literal> line</term> |
5b9d504e | 461 | <listitem><simpara>names the label of the packages in the directory tree |
24f6490f AL |
462 | of the <filename>Release</filename> file. Most commonly, this is |
463 | <literal>Debian</literal>. Specifying this label in the APT preferences file | |
ec2853a7 AL |
464 | would require the line: |
465 | </simpara> | |
ec2853a7 AL |
466 | <programlisting> |
467 | Pin: release l=Debian | |
468 | </programlisting> | |
469 | </listitem> | |
470 | </varlistentry> | |
471 | </variablelist> | |
472 | </para> | |
473 | ||
24f6490f | 474 | <para>All of the <filename>Packages</filename> and <filename>Release</filename> |
5b9d504e | 475 | files retrieved from locations listed in the &sources-list; file are stored |
ec2853a7 | 476 | in the directory <filename>/var/lib/apt/lists</filename>, or in the file named |
24f6490f | 477 | by the variable <literal>Dir::State::Lists</literal> in the <filename>apt.conf</filename> file. |
ec2853a7 AL |
478 | For example, the file |
479 | <filename>debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release</filename> | |
480 | contains the <filename>Release</filename> file retrieved from the site | |
24f6490f AL |
481 | <literal>debian.lcs.mit.edu</literal> for <literal>binary-i386</literal> architecture |
482 | files from the <literal>contrib</literal> component of the <literal>unstable</literal> | |
483 | distribution.</para> | |
484 | </refsect2> | |
ec2853a7 | 485 | |
24f6490f AL |
486 | <refsect2> |
487 | <title>Optional Lines in an APT Preferences Record</title> | |
ec2853a7 | 488 | |
24f6490f AL |
489 | <para>Each record in the APT preferences file can optionally begin with |
490 | one or more lines beginning with the word <literal>Explanation:</literal>. | |
491 | This provides a place for comments.</para> | |
24f6490f AL |
492 | </refsect2> |
493 | </refsect1> | |
ec2853a7 | 494 | |
24f6490f AL |
495 | <refsect1> |
496 | <title>Examples</title> | |
497 | <refsect2> | |
498 | <title>Tracking Stable</title> | |
ec2853a7 | 499 | |
24f6490f | 500 | <para>The following APT preferences file will cause APT to assign a |
ec2853a7 | 501 | priority higher than the default (500) to all package versions belonging |
24f6490f AL |
502 | to a <literal>stable</literal> distribution and a prohibitively low priority to |
503 | package versions belonging to other <literal>Debian</literal> distributions. | |
ec2853a7 AL |
504 | |
505 | <programlisting> | |
5b9d504e AL |
506 | Explanation: Uninstall or do not install any Debian-originated |
507 | Explanation: package versions other than those in the stable distro | |
ec2853a7 AL |
508 | Package: * |
509 | Pin: release a=stable | |
510 | Pin-Priority: 900 | |
511 | ||
ec2853a7 AL |
512 | Package: * |
513 | Pin: release o=Debian | |
514 | Pin-Priority: -10 | |
515 | </programlisting> | |
516 | </para> | |
517 | ||
24f6490f | 518 | <para>With a suitable &sources-list; file and the above preferences file, |
ec2853a7 | 519 | any of the following commands will cause APT to upgrade to the |
24f6490f | 520 | latest <literal>stable</literal> version(s). |
ec2853a7 AL |
521 | |
522 | <programlisting> | |
523 | apt-get install <replaceable>package-name</replaceable> | |
524 | apt-get upgrade | |
525 | apt-get dist-upgrade | |
526 | </programlisting> | |
527 | </para> | |
528 | ||
24f6490f AL |
529 | <para>The following command will cause APT to upgrade the specified |
530 | package to the latest version from the <literal>testing</literal> distribution; | |
5b9d504e AL |
531 | the package will not be upgraded again unless this command is given |
532 | again. | |
ec2853a7 AL |
533 | |
534 | <programlisting> | |
535 | apt-get install <replaceable>package</replaceable>/testing | |
536 | </programlisting> | |
24f6490f AL |
537 | </para> |
538 | </refsect2> | |
ec2853a7 | 539 | |
24f6490f AL |
540 | <refsect2> |
541 | <title>Tracking Testing or Unstable</title> | |
ec2853a7 | 542 | |
24f6490f AL |
543 | <para>The following APT preferences file will cause APT to assign |
544 | a high priority to package versions from the <literal>testing</literal> | |
5b9d504e | 545 | distribution, a lower priority to package versions from the |
24f6490f AL |
546 | <literal>unstable</literal> distribution, and a prohibitively low priority |
547 | to package versions from other <literal>Debian</literal> distributions. | |
ec2853a7 AL |
548 | |
549 | <programlisting> | |
550 | Package: * | |
551 | Pin: release a=testing | |
552 | Pin-Priority: 900 | |
553 | ||
554 | Package: * | |
555 | Pin: release a=unstable | |
556 | Pin-Priority: 800 | |
557 | ||
558 | Package: * | |
559 | Pin: release o=Debian | |
560 | Pin-Priority: -10 | |
561 | </programlisting> | |
562 | </para> | |
563 | ||
24f6490f | 564 | <para>With a suitable &sources-list; file and the above preferences file, |
5b9d504e | 565 | any of the following commands will cause APT to upgrade to the latest |
24f6490f | 566 | <literal>testing</literal> version(s). |
ec2853a7 AL |
567 | |
568 | <programlisting> | |
569 | apt-get install <replaceable>package-name</replaceable> | |
570 | apt-get upgrade | |
571 | apt-get dist-upgrade | |
572 | </programlisting> | |
573 | </para> | |
574 | ||
575 | <para>The following command will cause APT to upgrade the specified | |
24f6490f | 576 | package to the latest version from the <literal>unstable</literal> distribution. |
5b9d504e | 577 | Thereafter, <command>apt-get upgrade</command> will upgrade |
24f6490f | 578 | the package to the most recent <literal>testing</literal> version if that is |
5b9d504e | 579 | more recent than the installed version, otherwise, to the most recent |
24f6490f | 580 | <literal>unstable</literal> version if that is more recent than the installed |
5b9d504e | 581 | version. |
ec2853a7 AL |
582 | |
583 | <programlisting> | |
584 | apt-get install <replaceable>package</replaceable>/unstable | |
585 | </programlisting> | |
586 | </para> | |
efc487fb DK |
587 | </refsect2> |
588 | ||
589 | ||
590 | <refsect2> | |
591 | <title>Tracking the evolution of a codename release</title> | |
592 | ||
593 | <para>The following APT preferences file will cause APT to assign a | |
594 | priority higher than the default (500) to all package versions belonging | |
595 | to a specified codename of a distribution and a prohibitively low priority to | |
596 | package versions belonging to other <literal>Debian</literal> distributions, | |
597 | codenames and archives. | |
598 | Note that with this APT preference APT will follow the migration of a release | |
599 | from the archive <literal>testing</literal> to <literal>stable</literal> and | |
600 | later <literal>oldstable</literal>. If you want to follow for example the progress | |
601 | in <literal>testing</literal> notwithstanding the codename changes you should use | |
602 | the example configurations above. | |
603 | ||
604 | <programlisting> | |
605 | Explanation: Uninstall or do not install any Debian-originated package versions | |
e1dd65c9 | 606 | Explanation: other than those in the distribution codenamed with &testing-codename; or sid |
efc487fb | 607 | Package: * |
e1dd65c9 | 608 | Pin: release n=&testing-codename; |
efc487fb DK |
609 | Pin-Priority: 900 |
610 | ||
611 | Explanation: Debian unstable is always codenamed with sid | |
612 | Package: * | |
4a2bb9e6 | 613 | Pin: release n=sid |
efc487fb DK |
614 | Pin-Priority: 800 |
615 | ||
616 | Package: * | |
617 | Pin: release o=Debian | |
618 | Pin-Priority: -10 | |
619 | </programlisting> | |
620 | </para> | |
621 | ||
622 | <para>With a suitable &sources-list; file and the above preferences file, | |
623 | any of the following commands will cause APT to upgrade to the | |
e1dd65c9 | 624 | latest version(s) in the release codenamed with <literal>&testing-codename;</literal>. |
efc487fb DK |
625 | |
626 | <programlisting> | |
627 | apt-get install <replaceable>package-name</replaceable> | |
628 | apt-get upgrade | |
629 | apt-get dist-upgrade | |
630 | </programlisting> | |
631 | </para> | |
632 | ||
633 | <para>The following command will cause APT to upgrade the specified | |
634 | package to the latest version from the <literal>sid</literal> distribution. | |
635 | Thereafter, <command>apt-get upgrade</command> will upgrade | |
e1dd65c9 | 636 | the package to the most recent <literal>&testing-codename;</literal> version if that is |
efc487fb DK |
637 | more recent than the installed version, otherwise, to the most recent |
638 | <literal>sid</literal> version if that is more recent than the installed | |
639 | version. | |
ec2853a7 | 640 | |
efc487fb DK |
641 | <programlisting> |
642 | apt-get install <replaceable>package</replaceable>/sid | |
643 | </programlisting> | |
644 | </para> | |
24f6490f AL |
645 | </refsect2> |
646 | </refsect1> | |
ec2853a7 | 647 | |
daa4aa52 DK |
648 | <refsect1> |
649 | <title>Files</title> | |
650 | <variablelist> | |
651 | &file-preferences; | |
652 | </variablelist> | |
653 | </refsect1> | |
654 | ||
24f6490f AL |
655 | <refsect1> |
656 | <title>See Also</title> | |
5e80de29 | 657 | <para>&apt-get; &apt-cache; &apt-conf; &sources-list; |
5b9d504e | 658 | </para> |
24f6490f | 659 | </refsect1> |
b2e465d6 AL |
660 | |
661 | &manbugs; | |
ec2853a7 | 662 | |
b2e465d6 | 663 | </refentry> |