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