« back to all changes in this revision
Viewing changes to doc/apt.conf.5.xml
- browse files at revision 183
- compare with another revision
- download diff
- download tarball
- view history from revision 183
- Committer: Package Import Robot
- Author(s): Steve Langasek, Michael Vogt, Steve Langasek
- Date: 2012-06-11 22:36:16 UTC
- mfrom: (1.4.47 sid)
- Revision ID: package-import@ubuntu.com-20120611223616-1cctfc7qrxrx4vcu
Tags: 0.9.6ubuntu1
[ Michael Vogt ]
* merged from Debian, remaining changes:
- use ubuntu keyring and ubuntu archive keyring in apt-key
- run update-apt-xapian-index in apt.cron
- support apt-key net-update and verify keys against master-keyring
- run apt-key net-update in cron.daily
- different example sources.list
- APT::pkgPackageManager::MaxLoopCount set to 5000
- apport pkgfailure handling
- ubuntu changelog download handling
- patch for apt cross-building, see http://bugs.debian.org/666772
[ Steve Langasek ]
* Drop upgrade handling for obsolete conffile /etc/apt/apt.conf.d/01ubuntu,
removed in previous LTS.
* prepare-release: declare the packages needed as source build deps.
* merged from Debian, remaining changes:
- use ubuntu keyring and ubuntu archive keyring in apt-key
- run update-apt-xapian-index in apt.cron
- support apt-key net-update and verify keys against master-keyring
- run apt-key net-update in cron.daily
- different example sources.list
- APT::pkgPackageManager::MaxLoopCount set to 5000
- apport pkgfailure handling
- ubuntu changelog download handling
- patch for apt cross-building, see http://bugs.debian.org/666772
[ Steve Langasek ]
* Drop upgrade handling for obsolete conffile /etc/apt/apt.conf.d/01ubuntu,
removed in previous LTS.
* prepare-release: declare the packages needed as source build deps.
- files added:
- debian/libapt-inst1.5.install.in
- files removed:
- apt-inst/database.cc
- files modified:
- COMPILING
added
removed
doc/apt.conf.5.xml
1
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" [
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
5
5
<!ENTITY % aptent SYSTEM "apt.ent">
6
6
%aptent;
16
16
&apt-author.jgunthorpe;
17
17
&apt-author.team;
18
18
<author>
19
<firstname>Daniel</firstname>
20
<surname>Burrows</surname>
19
&apt-name.dburrows;
21
20
<contrib>Initial documentation of Debug::*.</contrib>
22
21
<email>dburrows@debian.org</email>
23
22
</author>
24
23
&apt-email;
25
24
&apt-product;
26
25
<!-- The last update date -->
27
<date>16 January 2010</date>
26
<date>2012-06-09T00:00:00Z</date>
28
27
</refentryinfo>
29
28
30
29
<refmeta>
38
37
<refname>apt.conf</refname>
39
38
<refpurpose>Configuration file for APT</refpurpose>
40
39
</refnamediv>
41
40
42
41
<refsect1><title>Description</title>
43
<para><filename>apt.conf</filename> is the main configuration file for
44
the APT suite of tools, but by far not the only place changes to options
45
can be made. All tools therefore share the configuration files and also
46
use a common command line parser to provide a uniform environment.</para>
42
<para><filename>/etc/apt/apt.conf</filename> is the main configuration
43
file shared by all the tools in the APT suite of tools, though it is by
44
no means the only place options can be set. The suite also shares a common
45
command line parser to provide a uniform environment.</para>
46
47
47
<orderedlist>
48
48
<para>When an APT tool starts up it will read the configuration files
49
49
in the following order:</para>
53
53
alphanumeric ascending order which have either no or "<literal>conf</literal>"
54
54
as filename extension and which only contain alphanumeric,
55
55
hyphen (-), underscore (_) and period (.) characters.
56
Otherwise APT will print a notice that it has ignored a file if the file
57
doesn't match a pattern in the <literal>Dir::Ignore-Files-Silently</literal>
58
configuration list - in this case it will be silently ignored.</para></listitem>
56
Otherwise APT will print a notice that it has ignored a file, unless that
57
file matches a pattern in the <literal>Dir::Ignore-Files-Silently</literal>
58
configuration list - in which case it will be silently ignored.</para></listitem>
59
59
<listitem><para>the main configuration file specified by
60
60
<literal>Dir::Etc::main</literal></para></listitem>
61
61
<listitem><para>the command line options are applied to override the
65
65
<refsect1><title>Syntax</title>
66
66
<para>The configuration file is organized in a tree with options organized into
67
67
functional groups. Option specification is given with a double colon
68
notation, for instance <literal>APT::Get::Assume-Yes</literal> is an option within
68
notation; for instance <literal>APT::Get::Assume-Yes</literal> is an option within
69
69
the APT tool group, for the Get tool. Options do not inherit from their
70
70
parent groups.</para>
71
71
74
74
<literal>//</literal> are treated as comments (ignored), as well as all text
75
75
between <literal>/*</literal> and <literal>*/</literal>, just like C/C++ comments.
76
76
Each line is of the form
77
<literal>APT::Get::Assume-Yes "true";</literal>. The trailing
78
semicolon and the quotes are required. The value must be on one line, and
79
there is no kind of string concatenation. It must not include inside quotes.
80
The behavior of the backslash "\" and escaped characters inside a value is
81
undefined and it should not be used. An option name may include
82
alphanumerical characters and the "/-:._+" characters. A new scope can
83
be opened with curly braces, like:</para>
77
<literal>APT::Get::Assume-Yes "true";</literal>.
78
The quotation marks and trailing semicolon are required.
79
The value must be on one line, and there is no kind of string concatenation.
80
Values must not include backslashes or extra quotation marks.
81
Option names are made up of alphanumeric characters and the characters "/-:._+".
82
A new scope can be opened with curly braces, like this:</para>
84
83
85
84
<informalexample><programlisting>
86
85
APT {
93
92
94
93
<para>with newlines placed to make it more readable. Lists can be created by
95
94
opening a scope and including a single string enclosed in quotes followed by a
96
semicolon. Multiple entries can be included, each separated by a semicolon.</para>
95
semicolon. Multiple entries can be included, separated by a semicolon.</para>
97
96
98
97
<informalexample><programlisting>
99
98
DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
103
102
<filename>&docdir;examples/apt.conf</filename> &configureindex;
104
103
is a good guide for how it should look.</para>
105
104
106
<para>The names of the configuration items are not case-sensitive. So in the previous example
107
you could use <literal>dpkg::pre-install-pkgs</literal>.</para>
105
<para>Case is not significant in names of configuration items, so in the
106
previous example you could use <literal>dpkg::pre-install-pkgs</literal>.</para>
108
107
109
<para>Names for the configuration items are optional if a list is defined as it can be see in
108
<para>Names for the configuration items are optional if a list is defined as can be seen in
110
109
the <literal>DPkg::Pre-Install-Pkgs</literal> example above. If you don't specify a name a
111
110
new entry will simply add a new option to the list. If you specify a name you can override
112
the option as every other option by reassigning a new value to the option.</para>
111
the option in the same way as any other option by reassigning a new value to the option.</para>
113
112
114
<para>Two specials are allowed, <literal>#include</literal> (which is deprecated
115
and not supported by alternative implementations) and <literal>#clear</literal>:
116
<literal>#include</literal> will include the given file, unless the filename
117
ends in a slash, then the whole directory is included.
113
<para>Two special commands are defined: <literal>#include</literal> (which is
114
deprecated and not supported by alternative implementations) and
115
<literal>#clear</literal>. <literal>#include</literal> will include the
116
given file, unless the filename ends in a slash, in which case the whole
117
directory is included.
118
118
<literal>#clear</literal> is used to erase a part of the configuration tree. The
119
119
specified element and all its descendants are erased.
120
120
(Note that these lines also need to end with a semicolon.)</para>
121
121
122
<para>The #clear command is the only way to delete a list or a complete scope.
123
Reopening a scope or the ::-style described below will <emphasis>not</emphasis>
124
override previously written entries. Only options can be overridden by addressing a new
125
value to it - lists and scopes can't be overridden, only cleared.</para>
122
<para>
123
The <literal>#clear</literal> command is the only way to delete a list or
124
a complete scope. Reopening a scope (or using the syntax described below
125
with an appended <literal>::</literal>) will <emphasis>not</emphasis>
126
override previously written entries. Options can only be overridden by
127
addressing a new value to them - lists and scopes can't be overridden,
128
only cleared.
129
</para>
126
130
127
<para>All of the APT tools take a -o option which allows an arbitrary configuration
131
<para>All of the APT tools take an -o option which allows an arbitrary configuration
128
132
directive to be specified on the command line. The syntax is a full option
129
133
name (<literal>APT::Get::Assume-Yes</literal> for instance) followed by an equals
130
sign then the new value of the option. Lists can be appended too by adding
131
a trailing :: to the list name. (As you might suspect: The scope syntax can't be used
132
on the command line.)</para>
134
sign then the new value of the option. To append a new element to a list, add a
135
trailing <literal>::</literal> to the name of the list.
136
(As you might suspect, the scope syntax can't be used on the command line.)</para>
133
137
134
<para>Note that you can use :: only for appending one item per line to a list and
135
that you should not use it in combination with the scope syntax.
136
(The scope syntax implicit insert ::) Using both syntaxes together will trigger a bug
137
which some users unfortunately relay on: An option with the unusual name "<literal>::</literal>"
138
which acts like every other option with a name. These introduces many problems
139
including that a user who writes multiple lines in this <emphasis>wrong</emphasis> syntax in
140
the hope to append to a list will gain the opposite as only the last assignment for this option
141
"<literal>::</literal>" will be used. Upcoming APT versions will raise errors and
142
will stop working if they encounter this misuse, so please correct such statements now
143
as long as APT doesn't complain explicit about them.</para>
138
<para>
139
Note that appending items to a list using <literal>::</literal> only works
140
for one item per line, and that you should not use it in combination with
141
the scope syntax (which adds <literal>::</literal> implicitly). Using both
142
syntaxes together will trigger a bug which some users unfortunately depend
143
on: an option with the unusual name "<literal>::</literal>" which acts
144
like every other option with a name. This introduces many problems; for
145
one thing, users who write multiple lines in this
146
<emphasis>wrong</emphasis> syntax in the hope of appending to a list will
147
achieve the opposite, as only the last assignment for this option
148
"<literal>::</literal>" will be used. Future versions of APT will raise
149
errors and stop working if they encounter this misuse, so please correct
150
such statements now while APT doesn't explicitly complain about them.
151
</para>
144
152
</refsect1>
145
153
146
154
<refsect1><title>The APT Group</title>
148
156
options for all of the tools.</para>
149
157
150
158
<variablelist>
151
<varlistentry><term>Architecture</term>
159
<varlistentry><term><option>Architecture</option></term>
152
160
<listitem><para>System Architecture; sets the architecture to use when fetching files and
153
161
parsing package lists. The internal default is the architecture apt was
154
162
compiled for.</para></listitem>
155
163
</varlistentry>
156
164
157
<varlistentry><term>Architectures</term>
158
<listitem><para>All Architectures the system supports. Processors implementing the <literal>amd64</literal>
159
are e.g. also able to execute binaries compiled for <literal>i386</literal>; This list is use when fetching files and
160
parsing package lists. The internal default is always the native architecture (<literal>APT::Architecture</literal>)
161
and all foreign architectures it can retrieve by calling <command>dpkg --print-foreign-architectures</command>.
165
<varlistentry><term><option>Architectures</option></term>
166
<listitem><para>
167
All Architectures the system supports. For instance, CPUs implementing
168
the <literal>amd64</literal> (also called <literal>x86-64</literal>)
169
instruction set are also able to execute binaries compiled for the
170
<literal>i386</literal> (<literal>x86</literal>) instruction set. This
171
list is used when fetching files and parsing package lists. The
172
initial default is always the system's native architecture
173
(<literal>APT::Architecture</literal>), and foreign architectures are
174
added to the default list when they are registered via
175
<command>dpkg --add-architecture</command>.
162
176
</para></listitem>
163
177
</varlistentry>
164
178
165
<varlistentry><term>Default-Release</term>
179
<varlistentry><term><option>Default-Release</option></term>
166
180
<listitem><para>Default release to install packages from if more than one
167
version available. Contains release name, codename or release version. Examples: 'stable', 'testing',
181
version is available. Contains release name, codename or release version. Examples: 'stable', 'testing',
168
182
'unstable', '&stable-codename;', '&testing-codename;', '4.0', '5.0*'. See also &apt-preferences;.</para></listitem>
169
183
</varlistentry>
170
184
171
<varlistentry><term>Ignore-Hold</term>
172
<listitem><para>Ignore Held packages; This global option causes the problem resolver to
185
<varlistentry><term><option>Ignore-Hold</option></term>
186
<listitem><para>Ignore held packages; this global option causes the problem resolver to
173
187
ignore held packages in its decision making.</para></listitem>
174
188
</varlistentry>
175
189
176
<varlistentry><term>Clean-Installed</term>
190
<varlistentry><term><option>Clean-Installed</option></term>
177
191
<listitem><para>Defaults to on. When turned on the autoclean feature will remove any packages
178
192
which can no longer be downloaded from the cache. If turned off then
179
193
packages that are locally installed are also excluded from cleaning - but
180
194
note that APT provides no direct means to reinstall them.</para></listitem>
181
195
</varlistentry>
182
196
183
<varlistentry><term>Immediate-Configure</term>
184
<listitem><para>Defaults to on which will cause APT to install essential and important packages
185
as fast as possible in the install/upgrade operation. This is done to limit the effect of a failing
186
&dpkg; call: If this option is disabled APT does treat an important package in the same way as
187
an extra package: Between the unpacking of the important package A and his configuration can then
188
be many other unpack or configuration calls, e.g. for package B which has no relation to A, but
189
causes the dpkg call to fail (e.g. because maintainer script of package B generates an error) which results
190
in a system state in which package A is unpacked but unconfigured - each package depending on A is now no
191
longer guaranteed to work as their dependency on A is not longer satisfied. The immediate configuration marker
192
is also applied to all dependencies which can generate a problem if the dependencies e.g. form a circle
193
as a dependency with the immediate flag is comparable with a Pre-Dependency. So in theory it is possible
194
that APT encounters a situation in which it is unable to perform immediate configuration, errors out and
195
refers to this option so the user can deactivate the immediate configuration temporarily to be able to perform
196
an install/upgrade again. Note the use of the word "theory" here as this problem was only encountered by now
197
in real world a few times in non-stable distribution versions and was caused by wrong dependencies of the package
198
in question or by a system in an already broken state, so you should not blindly disable this option as
199
the mentioned scenario above is not the only problem immediate configuration can help to prevent in the first place.
200
Before a big operation like <literal>dist-upgrade</literal> is run with this option disabled it should be tried to
201
explicitly <literal>install</literal> the package APT is unable to configure immediately, but please make sure to
202
report your problem also to your distribution and to the APT team with the buglink below so they can work on
203
improving or correcting the upgrade process.</para></listitem>
204
</varlistentry>
205
206
<varlistentry><term>Force-LoopBreak</term>
207
<listitem><para>Never Enable this option unless you -really- know what you are doing. It
208
permits APT to temporarily remove an essential package to break a
209
Conflicts/Conflicts or Conflicts/Pre-Depend loop between two essential
210
packages. SUCH A LOOP SHOULD NEVER EXIST AND IS A GRAVE BUG. This option
211
will work if the essential packages are not tar, gzip, libc, dpkg, bash or
212
anything that those packages depend on.</para></listitem>
213
</varlistentry>
214
215
<varlistentry><term>Cache-Start, Cache-Grow and Cache-Limit</term>
216
<listitem><para>APT uses since version 0.7.26 a resizable memory mapped cache file to store the 'available'
217
information. <literal>Cache-Start</literal> acts as a hint to which size the Cache will grow
197
<varlistentry><term><option>Immediate-Configure</option></term>
198
<listitem><para>
199
Defaults to on, which will cause APT to install essential and important
200
packages as soon as possible in an install/upgrade operation, in order
201
to limit the effect of a failing &dpkg; call. If this option is
202
disabled, APT treats an important package in the same way as an extra
203
package: between the unpacking of the package A and its configuration
204
there can be many other unpack or configuration calls for other
205
unrelated packages B, C etc. If these cause the &dpkg; call to fail
206
(e.g. because package B's maintainer scripts generate an error), this
207
results in a system state in which package A is unpacked but
208
unconfigured - so any package depending on A is now no longer
209
guaranteed to work, as its dependency on A is no longer satisfied.
210
</para><para>
211
The immediate configuration marker is also applied in the potentially
212
problematic case of circular dependencies, since a dependency with the
213
immediate flag is equivalent to a Pre-Dependency. In theory this allows
214
APT to recognise a situation in which it is unable to perform immediate
215
configuration, abort, and suggest to the user that the option should be
216
temporarily deactivated in order to allow the operation to proceed.
217
Note the use of the word "theory" here; in the real world this problem
218
has rarely been encountered, in non-stable distribution versions, and
219
was caused by wrong dependencies of the package in question or by a
220
system in an already broken state; so you should not blindly disable
221
this option, as the scenario mentioned above is not the only problem it
222
can help to prevent in the first place.
223
</para><para>
224
Before a big operation like <literal>dist-upgrade</literal> is run
225
with this option disabled you should try to explicitly
226
<literal>install</literal> the package APT is unable to configure
227
immediately; but please make sure you also report your problem to your
228
distribution and to the APT team with the buglink below, so they can
229
work on improving or correcting the upgrade process.
230
</para></listitem>
231
</varlistentry>
232
233
<varlistentry><term><option>Force-LoopBreak</option></term>
234
<listitem><para>
235
Never enable this option unless you <emphasis>really</emphasis> know
236
what you are doing. It permits APT to temporarily remove an essential
237
package to break a Conflicts/Conflicts or Conflicts/Pre-Depends loop
238
between two essential packages. <emphasis>Such a loop should never exist
239
and is a grave bug</emphasis>. This option will work if the essential
240
packages are not <command>tar</command>, <command>gzip</command>,
241
<command>libc</command>, <command>dpkg</command>, <command>dash</command>
242
or anything that those packages depend on.
243
</para></listitem>
244
</varlistentry>
245
246
<varlistentry><term><option>Cache-Start</option></term><term><option>Cache-Grow</option></term><term><option>Cache-Limit</option></term>
247
<listitem><para>APT uses since version 0.7.26 a resizable memory mapped cache file to store the available
248
information. <literal>Cache-Start</literal> acts as a hint of the size the cache will grow to,
218
249
and is therefore the amount of memory APT will request at startup. The default value is
219
20971520 bytes (~20 MB). Note that these amount of space need to be available for APT
220
otherwise it will likely fail ungracefully, so for memory restricted devices these value should
221
be lowered while on systems with a lot of configured sources this might be increased.
222
<literal>Cache-Grow</literal> defines in byte with the default of 1048576 (~1 MB) how much
223
the Cache size will be increased in the event the space defined by <literal>Cache-Start</literal>
224
is not enough. These value will be applied again and again until either the cache is big
250
20971520 bytes (~20 MB). Note that this amount of space needs to be available for APT;
251
otherwise it will likely fail ungracefully, so for memory restricted devices this value should
252
be lowered while on systems with a lot of configured sources it should be increased.
253
<literal>Cache-Grow</literal> defines in bytes with the default of 1048576 (~1 MB) how much
254
the cache size will be increased in the event the space defined by <literal>Cache-Start</literal>
255
is not enough. This value will be applied again and again until either the cache is big
225
256
enough to store all information or the size of the cache reaches the <literal>Cache-Limit</literal>.
226
257
The default of <literal>Cache-Limit</literal> is 0 which stands for no limit.
227
If <literal>Cache-Grow</literal> is set to 0 the automatic grow of the cache is disabled.
258
If <literal>Cache-Grow</literal> is set to 0 the automatic growth of the cache is disabled.
228
259
</para></listitem>
229
260
</varlistentry>
230
261
231
<varlistentry><term>Build-Essential</term>
232
<listitem><para>Defines which package(s) are considered essential build dependencies.</para></listitem>
233
</varlistentry>
234
235
<varlistentry><term>Get</term>
236
<listitem><para>The Get subsection controls the &apt-get; tool, please see its
237
documentation for more information about the options here.</para></listitem>
238
</varlistentry>
239
240
<varlistentry><term>Cache</term>
241
<listitem><para>The Cache subsection controls the &apt-cache; tool, please see its
242
documentation for more information about the options here.</para></listitem>
243
</varlistentry>
244
245
<varlistentry><term>CDROM</term>
246
<listitem><para>The CDROM subsection controls the &apt-cdrom; tool, please see its
262
<varlistentry><term><option>Build-Essential</option></term>
263
<listitem><para>Defines which packages are considered essential build dependencies.</para></listitem>
264
</varlistentry>
265
266
<varlistentry><term><option>Get</option></term>
267
<listitem><para>The Get subsection controls the &apt-get; tool; please see its
268
documentation for more information about the options here.</para></listitem>
269
</varlistentry>
270
271
<varlistentry><term><option>Cache</option></term>
272
<listitem><para>The Cache subsection controls the &apt-cache; tool; please see its
273
documentation for more information about the options here.</para></listitem>
274
</varlistentry>
275
276
<varlistentry><term><option>CDROM</option></term>
277
<listitem><para>The CDROM subsection controls the &apt-cdrom; tool; please see its
247
278
documentation for more information about the options here.</para></listitem>
248
279
</varlistentry>
249
280
</variablelist>
250
281
</refsect1>
251
282
252
283
<refsect1><title>The Acquire Group</title>
253
<para>The <literal>Acquire</literal> group of options controls the download of packages
254
and the URI handlers.
284
<para>The <literal>Acquire</literal> group of options controls the
285
download of packages as well as the various "acquire methods" responsible
286
for the download itself (see also &sources-list;).</para>
255
287
256
288
<variablelist>
257
<varlistentry><term>Check-Valid-Until</term>
258
<listitem><para>Security related option defaulting to true as an
259
expiring validation for a Release file prevents longtime replay attacks
260
and can e.g. also help users to identify no longer updated mirrors -
261
but the feature depends on the correctness of the time on the user system.
262
Archive maintainers are encouraged to create Release files with the
263
<literal>Valid-Until</literal> header, but if they don't or a stricter value
264
is volitional the following <literal>Max-ValidTime</literal> option can be used.
265
</para></listitem>
289
<varlistentry><term><option>Check-Valid-Until</option></term>
290
<listitem><para>
291
Security related option defaulting to true, as giving a Release file's
292
validation an expiration date prevents replay attacks over a long
293
timescale, and can also for example help users to identify mirrors
294
that are no longer updated - but the feature depends on the
295
correctness of the clock on the user system. Archive maintainers are
296
encouraged to create Release files with the
297
<literal>Valid-Until</literal> header, but if they don't or a
298
stricter value is desired the <literal>Max-ValidTime</literal>
299
option below can be used.
300
</para></listitem>
266
301
</varlistentry>
267
302
268
<varlistentry><term>Max-ValidTime</term>
269
<listitem><para>Seconds the Release file should be considered valid after
270
it was created (indicated by the <literal>Date</literal> header).
303
<varlistentry><term><option>Max-ValidTime</option></term>
304
<listitem><para>Maximum time (in seconds) after its creation (as indicated
305
by the <literal>Date</literal> header) that the <filename>Release</filename>
306
file should be considered valid.
271
307
If the Release file itself includes a <literal>Valid-Until</literal> header
272
308
the earlier date of the two is used as the expiration date.
273
The default value is <literal>0</literal> which stands for "for ever".
309
The default value is <literal>0</literal> which stands for "valid forever".
274
310
Archive specific settings can be made by appending the label of the archive
275
311
to the option name.
276
312
</para></listitem>
277
313
</varlistentry>
278
314
279
<varlistentry><term>Min-ValidTime</term>
280
<listitem><para>Minimum of seconds the Release file should be considered
281
valid after it was created (indicated by the <literal>Date</literal> header).
282
Use this if you need to use a seldomly updated (local) mirror of a more
283
regular updated archive with a <literal>Valid-Until</literal> header
315
<varlistentry><term><option>Min-ValidTime</option></term>
316
<listitem><para>Minimum time (in seconds) after its creation (as indicated
317
by the <literal>Date</literal> header) that the <filename>Release</filename>
318
file should be considered valid.
319
Use this if you need to use a seldom updated (local) mirror of a more
320
frequently updated archive with a <literal>Valid-Until</literal> header
284
321
instead of completely disabling the expiration date checking.
285
322
Archive specific settings can and should be used by appending the label of
286
323
the archive to the option name.
287
324
</para></listitem>
288
325
</varlistentry>
289
326
290
<varlistentry><term>PDiffs</term>
327
<varlistentry><term><option>PDiffs</option></term>
291
328
<listitem><para>Try to download deltas called <literal>PDiffs</literal> for
292
Packages or Sources files instead of downloading whole ones. True
293
by default.</para>
329
indexes (like <filename>Packages</filename> files) instead of downloading
330
whole ones. True by default.</para>
294
331
<para>Two sub-options to limit the use of PDiffs are also available:
295
With <literal>FileLimit</literal> can be specified how many PDiff files
296
are downloaded at most to patch a file. <literal>SizeLimit</literal>
332
<literal>FileLimit</literal> can be used to specify a maximum number of
333
PDiff files should be downloaded to update a file. <literal>SizeLimit</literal>
297
334
on the other hand is the maximum percentage of the size of all patches
298
335
compared to the size of the targeted file. If one of these limits is
299
336
exceeded the complete file is downloaded instead of the patches.
300
337
</para></listitem>
301
338
</varlistentry>
302
339
303
<varlistentry><term>Queue-Mode</term>
340
<varlistentry><term><option>Queue-Mode</option></term>
304
341
<listitem><para>Queuing mode; <literal>Queue-Mode</literal> can be one of <literal>host</literal> or
305
342
<literal>access</literal> which determines how APT parallelizes outgoing
306
343
connections. <literal>host</literal> means that one connection per target host
308
345
will be opened.</para></listitem>
309
346
</varlistentry>
310
347
311
<varlistentry><term>Retries</term>
348
<varlistentry><term><option>Retries</option></term>
312
349
<listitem><para>Number of retries to perform. If this is non-zero APT will retry failed
313
350
files the given number of times.</para></listitem>
314
351
</varlistentry>
315
352
316
<varlistentry><term>Source-Symlinks</term>
353
<varlistentry><term><option>Source-Symlinks</option></term>
317
354
<listitem><para>Use symlinks for source archives. If set to true then source archives will
318
355
be symlinked when possible instead of copying. True is the default.</para></listitem>
319
356
</varlistentry>
320
357
321
<varlistentry><term>http</term>
322
<listitem><para>HTTP URIs; http::Proxy is the default http proxy to use. It is in the
323
standard form of <literal>http://[[user][:pass]@]host[:port]/</literal>. Per
324
host proxies can also be specified by using the form
358
<varlistentry><term><option>http</option></term>
359
<listitem><para><literal>http::Proxy</literal> sets the default proxy to use for HTTP
360
URIs. It is in the standard form of <literal>http://[[user][:pass]@]host[:port]/</literal>.
361
Per host proxies can also be specified by using the form
325
362
<literal>http::Proxy::<host></literal> with the special keyword <literal>DIRECT</literal>
326
363
meaning to use no proxies. If no one of the above settings is specified,
327
364
<envar>http_proxy</envar> environment variable
328
365
will be used.</para>
329
366
330
<para>Three settings are provided for cache control with HTTP/1.1 compliant
331
proxy caches. <literal>No-Cache</literal> tells the proxy to not use its cached
332
response under any circumstances, <literal>Max-Age</literal> is sent only for
333
index files and tells the cache to refresh its object if it is older than
334
the given number of seconds. Debian updates its index files daily so the
335
default is 1 day. <literal>No-Store</literal> specifies that the cache should never
336
store this request, it is only set for archive files. This may be useful
337
to prevent polluting a proxy cache with very large .deb files. Note:
338
Squid 2.0.2 does not support any of these options.</para>
339
340
<para>The option <literal>timeout</literal> sets the timeout timer used by the method,
341
this applies to all things including connection timeout and data timeout.</para>
342
343
<para>One setting is provided to control the pipeline depth in cases where the
344
remote server is not RFC conforming or buggy (such as Squid 2.0.2).
345
<literal>Acquire::http::Pipeline-Depth</literal> can be a value from 0 to 5
346
indicating how many outstanding requests APT should send. A value of
347
zero MUST be specified if the remote host does not properly linger
348
on TCP connections - otherwise data corruption will occur. Hosts which
349
require this are in violation of RFC 2068.</para>
367
<para>Three settings are provided for cache control with HTTP/1.1 compliant
368
proxy caches.
369
<literal>No-Cache</literal> tells the proxy not to use its cached
370
response under any circumstances.
371
<literal>Max-Age</literal> sets the allowed maximum age (in seconds) of
372
an index file in the cache of the proxy.
373
<literal>No-Store</literal> specifies that the proxy should not store
374
the requested archive files in its cache, which can be used to prevent
375
the proxy from polluting its cache with (big) .deb files.</para>
376
377
<para>The option <literal>timeout</literal> sets the timeout timer used by the method;
378
this value applies to the connection as well as the data timeout.</para>
379
380
<para>The setting <literal>Acquire::http::Pipeline-Depth</literal> can be used to
381
enable HTTP pipelining (RFC 2616 section 8.1.2.2) which can be beneficial e.g. on
382
high-latency connections. It specifies how many requests are sent in a pipeline.
383
Previous APT versions had a default of 10 for this setting, but the default value
384
is now 0 (= disabled) to avoid problems with the ever-growing amount of webservers
385
and proxies which choose to not conform to the HTTP/1.1 specification.</para>
386
387
<para><literal>Acquire::http::AllowRedirect</literal> controls whether APT will follow
388
redirects, which is enabled by default.</para>
350
389
351
390
<para>The used bandwidth can be limited with <literal>Acquire::http::Dl-Limit</literal>
352
which accepts integer values in kilobyte. The default value is 0 which deactivates
353
the limit and tries uses as much as possible of the bandwidth (Note that this option implicit
354
deactivates the download from multiple servers at the same time.)</para>
391
which accepts integer values in kilobytes. The default value is 0 which deactivates
392
the limit and tries to use all available bandwidth (note that this option implicitly
393
disables downloading from multiple servers at the same time.)</para>
355
394
356
395
<para><literal>Acquire::http::User-Agent</literal> can be used to set a different
357
396
User-Agent for the http download method as some proxies allow access for clients
359
398
</listitem>
360
399
</varlistentry>
361
400
362
<varlistentry><term>https</term>
363
<listitem><para>HTTPS URIs. Cache-control, Timeout, AllowRedirect, Dl-Limit and
364
proxy options are the same as for <literal>http</literal> method and will also
365
default to the options from the <literal>http</literal> method if they are not
366
explicitly set for https. <literal>Pipeline-Depth</literal> option is not
367
supported yet.</para>
401
<varlistentry><term><option>https</option></term>
402
<listitem><para>
403
The <literal>Cache-control</literal>, <literal>Timeout</literal>,
404
<literal>AllowRedirect</literal>, <literal>Dl-Limit</literal> and
405
<literal>proxy</literal> options work for HTTPS URIs in the same way
406
as for the <literal>http</literal> method, and default to the same
407
values if they are not explicitly set. The
408
<literal>Pipeline-Depth</literal> option is not yet supported.
409
</para>
368
410
369
411
<para><literal>CaInfo</literal> suboption specifies place of file that
370
412
holds info about trusted certificates.
371
<literal><host>::CaInfo</literal> is corresponding per-host option.
372
<literal>Verify-Peer</literal> boolean suboption determines whether verify
373
server's host certificate against trusted certificates or not.
374
<literal><host>::Verify-Peer</literal> is corresponding per-host option.
375
<literal>Verify-Host</literal> boolean suboption determines whether verify
376
server's hostname or not.
377
<literal><host>::Verify-Host</literal> is corresponding per-host option.
413
<literal><host>::CaInfo</literal> is the corresponding per-host option.
414
<literal>Verify-Peer</literal> boolean suboption determines whether or not the
415
server's host certificate should be verified against trusted certificates.
416
<literal><host>::Verify-Peer</literal> is the corresponding per-host option.
417
<literal>Verify-Host</literal> boolean suboption determines whether or not the
418
server's hostname should be verified.
419
<literal><host>::Verify-Host</literal> is the corresponding per-host option.
378
420
<literal>SslCert</literal> determines what certificate to use for client
379
authentication. <literal><host>::SslCert</literal> is corresponding per-host option.
421
authentication. <literal><host>::SslCert</literal> is the corresponding per-host option.
380
422
<literal>SslKey</literal> determines what private key to use for client
381
authentication. <literal><host>::SslKey</literal> is corresponding per-host option.
423
authentication. <literal><host>::SslKey</literal> is the corresponding per-host option.
382
424
<literal>SslForceVersion</literal> overrides default SSL version to use.
383
Can contain 'TLSv1' or 'SSLv3' string.
384
<literal><host>::SslForceVersion</literal> is corresponding per-host option.
425
It can contain either of the strings '<literal>TLSv1</literal>' or
426
'<literal>SSLv3</literal>'.
427
<literal><host>::SslForceVersion</literal> is the corresponding per-host option.
385
428
</para></listitem></varlistentry>
386
429
387
<varlistentry><term>ftp</term>
388
<listitem><para>FTP URIs; ftp::Proxy is the default ftp proxy to use. It is in the
389
standard form of <literal>ftp://[[user][:pass]@]host[:port]/</literal>. Per
390
host proxies can also be specified by using the form
430
<varlistentry><term><option>ftp</option></term>
431
<listitem><para>
432
<literal>ftp::Proxy</literal> sets the default proxy to use for FTP URIs.
433
It is in the standard form of <literal>ftp://[[user][:pass]@]host[:port]/</literal>.
434
Per host proxies can also be specified by using the form
391
435
<literal>ftp::Proxy::<host></literal> with the special keyword <literal>DIRECT</literal>
392
436
meaning to use no proxies. If no one of the above settings is specified,
393
437
<envar>ftp_proxy</envar> environment variable
394
will be used. To use a ftp
438
will be used. To use an FTP
395
439
proxy you will have to set the <literal>ftp::ProxyLogin</literal> script in the
396
440
configuration file. This entry specifies the commands to send to tell
397
441
the proxy server what to connect to. Please see
398
442
&configureindex; for an example of
399
how to do this. The substitution variables available are
400
<literal>$(PROXY_USER)</literal> <literal>$(PROXY_PASS)</literal> <literal>$(SITE_USER)</literal>
401
<literal>$(SITE_PASS)</literal> <literal>$(SITE)</literal> and <literal>$(SITE_PORT)</literal>
402
Each is taken from it's respective URI component.</para>
443
how to do this. The substitution variables representing the corresponding
444
URI component are <literal>$(PROXY_USER)</literal>,
445
<literal>$(PROXY_PASS)</literal>, <literal>$(SITE_USER)</literal>,
446
<literal>$(SITE_PASS)</literal>, <literal>$(SITE)</literal> and
447
<literal>$(SITE_PORT)</literal>.</para>
403
448
404
<para>The option <literal>timeout</literal> sets the timeout timer used by the method,
405
this applies to all things including connection timeout and data timeout.</para>
449
<para>The option <literal>timeout</literal> sets the timeout timer used by the method;
450
this value applies to the connection as well as the data timeout.</para>
406
451
407
452
<para>Several settings are provided to control passive mode. Generally it is
408
safe to leave passive mode on, it works in nearly every environment.
409
However some situations require that passive mode be disabled and port
410
mode ftp used instead. This can be done globally, for connections that
411
go through a proxy or for a specific host (See the sample config file
453
safe to leave passive mode on; it works in nearly every environment.
454
However, some situations require that passive mode be disabled and port
455
mode FTP used instead. This can be done globally or for connections that
456
go through a proxy or for a specific host (see the sample config file
412
457
for examples).</para>
413
458
414
459
<para>It is possible to proxy FTP over HTTP by setting the <envar>ftp_proxy</envar>
415
environment variable to a http url - see the discussion of the http method
460
environment variable to an HTTP URL - see the discussion of the http method
416
461
above for syntax. You cannot set this in the configuration file and it is
417
462
not recommended to use FTP over HTTP due to its low efficiency.</para>
418
463
423
468
do not support RFC2428.</para></listitem>
424
469
</varlistentry>
425
470
426
<varlistentry><term>cdrom</term>
427
<listitem><para>CDROM URIs; the only setting for CDROM URIs is the mount point,
428
<literal>cdrom::Mount</literal> which must be the mount point for the CDROM drive
429
as specified in <filename>/etc/fstab</filename>. It is possible to provide
430
alternate mount and unmount commands if your mount point cannot be listed
431
in the fstab (such as an SMB mount and old mount packages). The syntax
432
is to put <literallayout>/cdrom/::Mount "foo";</literallayout> within
433
the cdrom block. It is important to have the trailing slash. Unmount
434
commands can be specified using UMount.</para></listitem>
435
</varlistentry>
436
437
<varlistentry><term>gpgv</term>
438
<listitem><para>GPGV URIs; the only option for GPGV URIs is the option to pass additional parameters to gpgv.
439
<literal>gpgv::Options</literal> Additional options passed to gpgv.
440
</para></listitem>
441
</varlistentry>
442
443
<varlistentry><term>CompressionTypes</term>
471
<varlistentry><term><option>cdrom</option></term>
472
<listitem><para>
473
For URIs using the <literal>cdrom</literal> method, the only configurable
474
option is the mount point, <literal>cdrom::Mount</literal>, which must be
475
the mount point for the CD-ROM (or DVD, or whatever) drive as specified in
476
<filename>/etc/fstab</filename>. It is possible to provide alternate mount
477
and unmount commands if your mount point cannot be listed in the fstab.
478
The syntax is to put <literallayout>/cdrom/::Mount "foo";</literallayout> within
479
the <literal>cdrom</literal> block. It is important to have the trailing slash.
480
Unmount commands can be specified using UMount.
481
</para></listitem>
482
</varlistentry>
483
484
<varlistentry><term><option>gpgv</option></term>
485
<listitem><para>
486
For GPGV URIs the only configurable option is <literal>gpgv::Options</literal>,
487
which passes additional parameters to gpgv.
488
</para></listitem>
489
</varlistentry>
490
491
<varlistentry><term><option>CompressionTypes</option></term>
444
492
<listitem><para>List of compression types which are understood by the acquire methods.
445
493
Files like <filename>Packages</filename> can be available in various compression formats.
446
Per default the acquire methods can decompress <command>bzip2</command>, <command>lzma</command>
447
and <command>gzip</command> compressed files, with this setting more formats can be added
494
By default the acquire methods can decompress <command>bzip2</command>, <command>lzma</command>
495
and <command>gzip</command> compressed files; with this setting more formats can be added
448
496
on the fly or the used method can be changed. The syntax for this is:
449
497
<synopsis>Acquire::CompressionTypes::<replaceable>FileExtension</replaceable> "<replaceable>Methodname</replaceable>";</synopsis>
450
</para><para>Also the <literal>Order</literal> subgroup can be used to define in which order
498
</para><para>Also, the <literal>Order</literal> subgroup can be used to define in which order
451
499
the acquire system will try to download the compressed files. The acquire system will try the first
452
500
and proceed with the next compression type in this list on error, so to prefer one over the other type
453
simple add the preferred type at first - not already added default types will be added at run time
501
simply add the preferred type first - default types not already added will be implicitly appended
454
502
to the end of the list, so e.g. <synopsis>Acquire::CompressionTypes::Order:: "gz";</synopsis> can
455
503
be used to prefer <command>gzip</command> compressed files over <command>bzip2</command> and <command>lzma</command>.
456
504
If <command>lzma</command> should be preferred over <command>gzip</command> and <command>bzip2</command> the
457
configure setting should look like this <synopsis>Acquire::CompressionTypes::Order { "lzma"; "gz"; };</synopsis>
458
It is not needed to add <literal>bz2</literal> explicit to the list as it will be added automatic.</para>
459
<para>Note that at run time the <literal>Dir::Bin::<replaceable>Methodname</replaceable></literal> will
460
be checked: If this setting exists the method will only be used if this file exists, e.g. for
461
the bzip2 method (the inbuilt) setting is: <literallayout>Dir::Bin::bzip2 "/bin/bzip2";</literallayout>
505
configure setting should look like this: <synopsis>Acquire::CompressionTypes::Order { "lzma"; "gz"; };</synopsis>
506
It is not needed to add <literal>bz2</literal> to the list explicitly as it will be added automatically.</para>
507
<para>Note that the
508
<literal>Dir::Bin::<replaceable>Methodname</replaceable></literal>
509
will be checked at run time. If this option has been set, the
510
method will only be used if this file exists; e.g. for the
511
<literal>bzip2</literal> method (the inbuilt) setting is:
512
<literallayout>Dir::Bin::bzip2 "/bin/bzip2";</literallayout>
462
513
Note also that list entries specified on the command line will be added at the end of the list
463
514
specified in the configuration files, but before the default entries. To prefer a type in this case
464
515
over the ones specified in the configuration files you can set the option direct - not in list style.
465
This will not override the defined list, it will only prefix the list with this type.</para>
516
This will not override the defined list; it will only prefix the list with this type.</para>
466
517
<para>The special type <literal>uncompressed</literal> can be used to give uncompressed files a
467
518
preference, but note that most archives don't provide uncompressed files so this is mostly only
468
519
useable for local mirrors.</para></listitem>
469
520
</varlistentry>
470
521
471
<varlistentry><term>GzipIndexes</term>
522
<varlistentry><term><option>GzipIndexes</option></term>
472
523
<listitem><para>
473
524
When downloading <literal>gzip</literal> compressed indexes (Packages, Sources, or
474
525
Translations), keep them gzip compressed locally instead of unpacking
477
528
</para></listitem>
478
529
</varlistentry>
479
530
480
<varlistentry><term>Languages</term>
531
<varlistentry><term><option>Languages</option></term>
481
532
<listitem><para>The Languages subsection controls which <filename>Translation</filename> files are downloaded
482
and in which order APT tries to display the Description-Translations. APT will try to display the first
483
available Description in the Language which is listed at first. Languages can be defined with their
484
short or long Languagecodes. Note that not all archives provide <filename>Translation</filename>
485
files for every Language - especially the long Languagecodes are rare, so please
486
inform you which ones are available before you set here impossible values.</para>
533
and in which order APT tries to display the description-translations. APT will try to display the first
534
available description in the language which is listed first. Languages can be defined with their
535
short or long language codes. Note that not all archives provide <filename>Translation</filename>
536
files for every language - the long language codes are especially rare.</para>
487
537
<para>The default list includes "environment" and "en". "<literal>environment</literal>" has a special meaning here:
488
It will be replaced at runtime with the languagecodes extracted from the <literal>LC_MESSAGES</literal> environment variable.
538
it will be replaced at runtime with the language codes extracted from the <literal>LC_MESSAGES</literal> environment variable.
489
539
It will also ensure that these codes are not included twice in the list. If <literal>LC_MESSAGES</literal>
490
540
is set to "C" only the <filename>Translation-en</filename> file (if available) will be used.
491
To force apt to use no Translation file use the setting <literal>Acquire::Languages=none</literal>. "<literal>none</literal>"
492
is another special meaning code which will stop the search for a fitting <filename>Translation</filename> file.
493
This can be used by the system administrator to let APT know that it should download also this files without
494
actually use them if the environment doesn't specify this languages. So the following example configuration will
495
result in the order "en, de" in an english and in "de, en" in a german localization. Note that "fr" is downloaded,
496
but not used if APT is not used in a french localization, in such an environment the order would be "fr, de, en".
497
<programlisting>Acquire::Languages { "environment"; "de"; "en"; "none"; "fr"; };</programlisting></para></listitem>
541
To force APT to use no Translation file use the setting <literal>Acquire::Languages=none</literal>. "<literal>none</literal>"
542
is another special meaning code which will stop the search for a suitable <filename>Translation</filename> file.
543
This tells APT to download these translations too, without actually
544
using them unless the environment specifies the languages. So the
545
following example configuration will result in the order "en, de" in an
546
English locale or "de, en" in a German one. Note that "fr" is
547
downloaded, but not used unless APT is used in a French locale (where
548
the order would be "fr, de, en").
549
<programlisting>Acquire::Languages { "environment"; "de"; "en"; "none"; "fr"; };</programlisting></para>
550
<para>Note: To prevent problems resulting from APT being executed in different environments
551
(e.g. by different users or by other programs) all Translation files which are found in
552
<filename>/var/lib/apt/lists/</filename> will be added to the end of the list
553
(after an implicit "<literal>none</literal>").</para>
554
</listitem>
498
555
</varlistentry>
499
556
500
557
</variablelist>
501
</para>
502
558
</refsect1>
503
559
504
560
<refsect1><title>Directories</title>
505
561
506
562
<para>The <literal>Dir::State</literal> section has directories that pertain to local
507
563
state information. <literal>lists</literal> is the directory to place downloaded
508
package lists in and <literal>status</literal> is the name of the dpkg status file.
509
<literal>preferences</literal> is the name of the APT preferences file.
510
<literal>Dir::State</literal> contains the default directory to prefix on all sub
511
items if they do not start with <filename>/</filename> or <filename>./</filename>.</para>
564
package lists in and <literal>status</literal> is the name of the &dpkg; status file.
565
<literal>preferences</literal> is the name of the APT <filename>preferences</filename> file.
566
<literal>Dir::State</literal> contains the default directory to prefix on all
567
sub-items if they do not start with <filename>/</filename> or <filename>./</filename>.</para>
512
568
513
569
<para><literal>Dir::Cache</literal> contains locations pertaining to local cache
514
570
information, such as the two package caches <literal>srcpkgcache</literal> and
515
571
<literal>pkgcache</literal> as well as the location to place downloaded archives,
516
572
<literal>Dir::Cache::archives</literal>. Generation of caches can be turned off
517
by setting their names to be blank. This will slow down startup but
518
save disk space. It is probably preferred to turn off the pkgcache rather
573
by setting their names to the empty string. This will slow down startup but
574
save disk space. It is probably preferable to turn off the pkgcache rather
519
575
than the srcpkgcache. Like <literal>Dir::State</literal> the default
520
576
directory is contained in <literal>Dir::Cache</literal></para>
521
577
562
618
<refsect1><title>APT in DSelect</title>
563
619
<para>
564
620
When APT is used as a &dselect; method several configuration directives
565
control the default behaviour. These are in the <literal>DSelect</literal> section.</para>
621
control the default behavior. These are in the <literal>DSelect</literal> section.</para>
566
622
567
623
<variablelist>
568
<varlistentry><term>Clean</term>
569
<listitem><para>Cache Clean mode; this value may be one of always, prompt, auto,
570
pre-auto and never. always and prompt will remove all packages from
571
the cache after upgrading, prompt (the default) does so conditionally.
572
auto removes only those packages which are no longer downloadable
573
(replaced with a new version for instance). pre-auto performs this
574
action before downloading new packages.</para></listitem>
624
<varlistentry><term><option>Clean</option></term>
625
<listitem><para>Cache Clean mode; this value may be one of
626
<literal>always</literal>, <literal>prompt</literal>,
627
<literal>auto</literal>, <literal>pre-auto</literal> and
628
<literal>never</literal>.
629
<literal>always</literal> and <literal>prompt</literal> will remove
630
all packages from the cache after upgrading, <literal>prompt</literal>
631
(the default) does so conditionally.
632
<literal>auto</literal> removes only those packages which are no longer
633
downloadable (replaced with a new version for instance).
634
<literal>pre-auto</literal> performs this action before downloading
635
new packages.</para></listitem>
575
636
</varlistentry>
576
637
577
<varlistentry><term>options</term>
578
<listitem><para>The contents of this variable is passed to &apt-get; as command line
638
<varlistentry><term><option>options</option></term>
639
<listitem><para>The contents of this variable are passed to &apt-get; as command line
579
640
options when it is run for the install phase.</para></listitem>
580
641
</varlistentry>
581
642
582
<varlistentry><term>Updateoptions</term>
583
<listitem><para>The contents of this variable is passed to &apt-get; as command line
643
<varlistentry><term><option>Updateoptions</option></term>
644
<listitem><para>The contents of this variable are passed to &apt-get; as command line
584
645
options when it is run for the update phase.</para></listitem>
585
646
</varlistentry>
586
647
587
<varlistentry><term>PromptAfterUpdate</term>
648
<varlistentry><term><option>PromptAfterUpdate</option></term>
588
649
<listitem><para>If true the [U]pdate operation in &dselect; will always prompt to continue.
589
650
The default is to prompt only on error.</para></listitem>
590
651
</varlistentry>
591
652
</variablelist>
592
653
</refsect1>
593
654
594
<refsect1><title>How APT calls dpkg</title>
655
<refsect1><title>How APT calls &dpkg;</title>
595
656
<para>Several configuration directives control how APT invokes &dpkg;. These are
596
657
in the <literal>DPkg</literal> section.</para>
597
658
598
659
<variablelist>
599
<varlistentry><term>options</term>
600
<listitem><para>This is a list of options to pass to dpkg. The options must be specified
660
<varlistentry><term><option>options</option></term>
661
<listitem><para>This is a list of options to pass to &dpkg;. The options must be specified
601
662
using the list notation and each list item is passed as a single argument
602
663
to &dpkg;.</para></listitem>
603
664
</varlistentry>
604
665
605
<varlistentry><term>Pre-Invoke</term><term>Post-Invoke</term>
666
<varlistentry><term><option>Pre-Invoke</option></term><term><option>Post-Invoke</option></term>
606
667
<listitem><para>This is a list of shell commands to run before/after invoking &dpkg;.
607
668
Like <literal>options</literal> this must be specified in list notation. The
608
commands are invoked in order using <filename>/bin/sh</filename>, should any
669
commands are invoked in order using <filename>/bin/sh</filename>; should any
609
670
fail APT will abort.</para></listitem>
610
671
</varlistentry>
611
672
612
<varlistentry><term>Pre-Install-Pkgs</term>
613
<listitem><para>This is a list of shell commands to run before invoking dpkg. Like
673
<varlistentry><term><option>Pre-Install-Pkgs</option></term>
674
<listitem><para>This is a list of shell commands to run before invoking &dpkg;. Like
614
675
<literal>options</literal> this must be specified in list notation. The commands
615
are invoked in order using <filename>/bin/sh</filename>, should any fail APT
616
will abort. APT will pass to the commands on standard input the
617
filenames of all .deb files it is going to install, one per line.</para>
676
are invoked in order using <filename>/bin/sh</filename>; should any fail APT
677
will abort. APT will pass the filenames of all .deb files it is going to
678
install to the commands, one per line on standard input.</para>
618
679
619
680
<para>Version 2 of this protocol dumps more information, including the
620
681
protocol version, the APT configuration space and the packages, files
623
684
command given to <literal>Pre-Install-Pkgs</literal>.</para></listitem>
624
685
</varlistentry>
625
686
626
<varlistentry><term>Run-Directory</term>
627
<listitem><para>APT chdirs to this directory before invoking dpkg, the default is
687
<varlistentry><term><option>Run-Directory</option></term>
688
<listitem><para>APT chdirs to this directory before invoking &dpkg;, the default is
628
689
<filename>/</filename>.</para></listitem>
629
690
</varlistentry>
630
691
631
<varlistentry><term>Build-options</term>
632
<listitem><para>These options are passed to &dpkg-buildpackage; when compiling packages,
692
<varlistentry><term><option>Build-options</option></term>
693
<listitem><para>These options are passed to &dpkg-buildpackage; when compiling packages;
633
694
the default is to disable signing and produce all binaries.</para></listitem>
634
695
</varlistentry>
635
696
</variablelist>
636
697
637
698
<refsect2><title>dpkg trigger usage (and related options)</title>
638
<para>APT can call dpkg in a way so it can make aggressive use of triggers over
639
multiple calls of dpkg. Without further options dpkg will use triggers only in between his
640
own run. Activating these options can therefore decrease the time needed to perform the
641
install / upgrade. Note that it is intended to activate these options per default in the
642
future, but as it changes the way APT calling dpkg drastically it needs a lot more testing.
699
<para>APT can call &dpkg; in such a way as to let it make aggressive use of triggers over
700
multiple calls of &dpkg;. Without further options &dpkg; will use triggers once each time it runs.
701
Activating these options can therefore decrease the time needed to perform the
702
install or upgrade. Note that it is intended to activate these options per default in the
703
future, but as it drastically changes the way APT calls &dpkg; it needs a lot more testing.
643
704
<emphasis>These options are therefore currently experimental and should not be used in
644
productive environments.</emphasis> Also it breaks the progress reporting so all frontends will
705
production environments.</emphasis> It also breaks progress reporting such that all front-ends will
645
706
currently stay around half (or more) of the time in the 100% state while it actually configures
646
707
all packages.</para>
647
708
<para>Note that it is not guaranteed that APT will support these options or that these options will
648
709
not cause (big) trouble in the future. If you have understand the current risks and problems with
649
these options, but are brave enough to help testing them create a new configuration file and test a
710
these options, but are brave enough to help testing them, create a new configuration file and test a
650
711
combination of options. Please report any bugs, problems and improvements you encounter and make sure
651
to note which options you have used in your reports. Asking dpkg for help could also be useful for
712
to note which options you have used in your reports. Asking &dpkg; for help could also be useful for
652
713
debugging proposes, see e.g. <command>dpkg --audit</command>. A defensive option combination would be
653
714
<literallayout>DPkg::NoTriggers "true";
654
715
PackageManager::Configure "smart";
656
717
DPkg::TriggersPending "true";</literallayout></para>
657
718
658
719
<variablelist>
659
<varlistentry><term>DPkg::NoTriggers</term>
660
<listitem><para>Add the no triggers flag to all dpkg calls (except the ConfigurePending call).
661
See &dpkg; if you are interested in what this actually means. In short: dpkg will not run the
720
<varlistentry><term><option>DPkg::NoTriggers</option></term>
721
<listitem><para>Add the no triggers flag to all &dpkg; calls (except the ConfigurePending call).
722
See &dpkg; if you are interested in what this actually means. In short: &dpkg; will not run the
662
723
triggers when this flag is present unless it is explicitly called to do so in an extra call.
663
Note that this option exists (undocumented) also in older apt versions with a slightly different
664
meaning: Previously these option only append --no-triggers to the configure calls to dpkg -
665
now apt will add these flag also to the unpack and remove calls.</para></listitem>
666
</varlistentry>
667
<varlistentry><term>PackageManager::Configure</term>
668
<listitem><para>Valid values are "<literal>all</literal>", "<literal>smart</literal>" and "<literal>no</literal>".
669
"<literal>all</literal>" is the default value and causes APT to configure all packages explicit.
670
The "<literal>smart</literal>" way is it to configure only packages which need to be configured before
671
another package can be unpacked (Pre-Depends) and let the rest configure by dpkg with a call generated
672
by the next option. "<literal>no</literal>" on the other hand will not configure anything and totally
673
rely on dpkg for configuration (which will at the moment fail if a Pre-Depends is encountered).
674
Setting this option to another than the all value will implicitly activate also the next option per
675
default as otherwise the system could end in an unconfigured status which could be unbootable!
676
</para></listitem>
677
</varlistentry>
678
<varlistentry><term>DPkg::ConfigurePending</term>
679
<listitem><para>If this option is set apt will call <command>dpkg --configure --pending</command>
680
to let dpkg handle all required configurations and triggers. This option is activated automatic
681
per default if the previous option is not set to <literal>all</literal>, but deactivating could be useful
724
Note that this option exists (undocumented) also in older APT versions with a slightly different
725
meaning: Previously these option only append --no-triggers to the configure calls to &dpkg; -
726
now APT will also add this flag to the unpack and remove calls.</para></listitem>
727
</varlistentry>
728
<varlistentry><term><option>PackageManager::Configure</option></term>
729
<listitem><para>Valid values are "<literal>all</literal>",
730
"<literal>smart</literal>" and "<literal>no</literal>".
731
The default value is "<literal>all</literal>", which causes APT to
732
configure all packages. The "<literal>smart</literal>" way is to
733
configure only packages which need to be configured before another
734
package can be unpacked (Pre-Depends), and let the rest be configured
735
by &dpkg; with a call generated by the ConfigurePending option (see
736
below). On the other hand, "<literal>no</literal>" will not configure
737
anything, and totally relies on &dpkg; for configuration (which at the
738
moment will fail if a Pre-Depends is encountered). Setting this option
739
to any value other than <literal>all</literal> will implicitly also
740
activate the next option by default, as otherwise the system could end
741
in an unconfigured and potentially unbootable state.</para></listitem>
742
</varlistentry>
743
<varlistentry><term><option>DPkg::ConfigurePending</option></term>
744
<listitem><para>If this option is set APT will call <command>dpkg --configure --pending</command>
745
to let &dpkg; handle all required configurations and triggers. This option is activated automatically
746
per default if the previous option is not set to <literal>all</literal>, but deactivating it could be useful
682
747
if you want to run APT multiple times in a row - e.g. in an installer. In these sceneries you could
683
748
deactivate this option in all but the last run.</para></listitem>
684
749
</varlistentry>
685
<varlistentry><term>DPkg::TriggersPending</term>
686
<listitem><para>Useful for <literal>smart</literal> configuration as a package which has pending
687
triggers is not considered as <literal>installed</literal> and dpkg treats them as <literal>unpacked</literal>
688
currently which is a dealbreaker for Pre-Dependencies (see debbugs #526774). Note that this will
750
<varlistentry><term><option>DPkg::TriggersPending</option></term>
751
<listitem><para>Useful for the <literal>smart</literal> configuration as a package which has pending
752
triggers is not considered as <literal>installed</literal>, and &dpkg; treats them as <literal>unpacked</literal>
753
currently which is a showstopper for Pre-Dependencies (see debbugs #526774). Note that this will
689
754
process all triggers, not only the triggers needed to configure this package.</para></listitem>
690
755
</varlistentry>
691
<varlistentry><term>PackageManager::UnpackAll</term>
692
<listitem><para>As the configuration can be deferred to be done at the end by dpkg it can be
693
tried to order the unpack series only by critical needs, e.g. by Pre-Depends. Default is true
694
and therefore the "old" method of ordering in various steps by everything. While both method
695
were present in earlier APT versions the <literal>OrderCritical</literal> method was unused, so
696
this method is very experimental and needs further improvements before becoming really useful.
697
</para></listitem>
698
</varlistentry>
699
<varlistentry><term>OrderList::Score::Immediate</term>
700
<listitem><para>Essential packages (and there dependencies) should be configured immediately
701
after unpacking. It will be a good idea to do this quite early in the upgrade process as these
702
these configure calls require currently also <literal>DPkg::TriggersPending</literal> which
703
will run quite a few triggers (which maybe not needed). Essentials get per default a high score
704
but the immediate flag is relatively low (a package which has a Pre-Depends is higher rated).
756
<varlistentry><term><option>OrderList::Score::Immediate</option></term>
757
<listitem><para>Essential packages (and their dependencies) should be configured immediately
758
after unpacking. It is a good idea to do this quite early in the upgrade process as these
759
configure calls also currently require <literal>DPkg::TriggersPending</literal> which
760
will run quite a few triggers (which may not be needed). Essentials get per default a high score
761
but the immediate flag is relatively low (a package which has a Pre-Depends is rated higher).
705
762
These option and the others in the same group can be used to change the scoring. The following
706
example shows the settings with there default values.
763
example shows the settings with their default values.
707
764
<literallayout>OrderList::Score {
708
765
Delete 500;
709
766
Essential 200;
720
777
<title>Periodic and Archives options</title>
721
778
<para><literal>APT::Periodic</literal> and <literal>APT::Archives</literal>
722
779
groups of options configure behavior of apt periodic updates, which is
723
done by <literal>/etc/cron.daily/apt</literal> script. See header of
780
done by the <literal>/etc/cron.daily/apt</literal> script. See the top of
724
781
this script for the brief documentation of these options.
725
782
</para>
726
783
</refsect1>
765
822
<listitem>
766
823
<para>
767
824
<literal>Debug::IdentCdrom</literal> disables the inclusion
768
of statfs data in CDROM IDs. <!-- TODO: provide a
825
of statfs data in CD-ROM IDs. <!-- TODO: provide a
769
826
motivating example, except I haven't a clue why you'd want
770
827
to do this. -->
771
828
</para>
779
836
780
837
<variablelist>
781
838
<varlistentry>
782
<term><literal>Debug::Acquire::cdrom</literal></term>
839
<term><option>Debug::Acquire::cdrom</option></term>
783
840
784
841
<listitem>
785
842
<para>
790
847
</varlistentry>
791
848
792
849
<varlistentry>
793
<term><literal>Debug::Acquire::ftp</literal></term>
850
<term><option>Debug::Acquire::ftp</option></term>
794
851
795
852
<listitem>
796
853
<para>
801
858
</varlistentry>
802
859
803
860
<varlistentry>
804
<term><literal>Debug::Acquire::http</literal></term>
861
<term><option>Debug::Acquire::http</option></term>
805
862
806
863
<listitem>
807
864
<para>
812
869
</varlistentry>
813
870
814
871
<varlistentry>
815
<term><literal>Debug::Acquire::https</literal></term>
872
<term><option>Debug::Acquire::https</option></term>
816
873
817
874
<listitem>
818
875
<para>
823
880
</varlistentry>
824
881
825
882
<varlistentry>
826
<term><literal>Debug::Acquire::gpgv</literal></term>
883
<term><option>Debug::Acquire::gpgv</option></term>
827
884
828
885
<listitem>
829
886
<para>
834
891
</varlistentry>
835
892
836
893
<varlistentry>
837
<term><literal>Debug::aptcdrom</literal></term>
894
<term><option>Debug::aptcdrom</option></term>
838
895
839
896
<listitem>
840
897
<para>
845
902
</varlistentry>
846
903
847
904
<varlistentry>
848
<term><literal>Debug::BuildDeps</literal></term>
905
<term><option>Debug::BuildDeps</option></term>
849
906
<listitem>
850
907
<para>
851
908
Describes the process of resolving build-dependencies in
855
912
</varlistentry>
856
913
857
914
<varlistentry>
858
<term><literal>Debug::Hashes</literal></term>
915
<term><option>Debug::Hashes</option></term>
859
916
<listitem>
860
917
<para>
861
918
Output each cryptographic hash that is generated by the
865
922
</varlistentry>
866
923
867
924
<varlistentry>
868
<term><literal>Debug::IdentCDROM</literal></term>
925
<term><option>Debug::IdentCDROM</option></term>
869
926
<listitem>
870
927
<para>
871
928
Do not include information from <literal>statfs</literal>,
876
933
</varlistentry>
877
934
878
935
<varlistentry>
879
<term><literal>Debug::NoLocking</literal></term>
936
<term><option>Debug::NoLocking</option></term>
880
937
<listitem>
881
938
<para>
882
939
Disable all file locking. For instance, this will allow
887
944
</varlistentry>
888
945
889
946
<varlistentry>
890
<term><literal>Debug::pkgAcquire</literal></term>
947
<term><option>Debug::pkgAcquire</option></term>
891
948
892
949
<listitem>
893
950
<para>
898
955
</varlistentry>
899
956
900
957
<varlistentry>
901
<term><literal>Debug::pkgAcquire::Auth</literal></term>
958
<term><option>Debug::pkgAcquire::Auth</option></term>
902
959
<listitem>
903
960
<para>
904
961
Output status messages and errors related to verifying
908
965
</varlistentry>
909
966
910
967
<varlistentry>
911
<term><literal>Debug::pkgAcquire::Diffs</literal></term>
968
<term><option>Debug::pkgAcquire::Diffs</option></term>
912
969
<listitem>
913
970
<para>
914
971
Output information about downloading and applying package
919
976
</varlistentry>
920
977
921
978
<varlistentry>
922
<term><literal>Debug::pkgAcquire::RRed</literal></term>
979
<term><option>Debug::pkgAcquire::RRed</option></term>
923
980
924
981
<listitem>
925
982
<para>
930
987
</varlistentry>
931
988
932
989
<varlistentry>
933
<term><literal>Debug::pkgAcquire::Worker</literal></term>
990
<term><option>Debug::pkgAcquire::Worker</option></term>
934
991
935
992
<listitem>
936
993
<para>
941
998
</varlistentry>
942
999
943
1000
<varlistentry>
944
<term><literal>Debug::pkgAutoRemove</literal></term>
1001
<term><option>Debug::pkgAutoRemove</option></term>
945
1002
946
1003
<listitem>
947
1004
<para>
952
1009
</varlistentry>
953
1010
954
1011
<varlistentry>
955
<term><literal>Debug::pkgDepCache::AutoInstall</literal></term>
1012
<term><option>Debug::pkgDepCache::AutoInstall</option></term>
956
1013
<listitem>
957
1014
<para>
958
1015
Generate debug messages describing which packages are being
966
1023
</varlistentry>
967
1024
968
1025
<varlistentry>
969
<term><literal>Debug::pkgDepCache::Marker</literal></term>
1026
<term><option>Debug::pkgDepCache::Marker</option></term>
970
1027
<listitem>
971
1028
<para>
972
Generate debug messages describing which package is marked
1029
Generate debug messages describing which packages are marked
973
1030
as keep/install/remove while the ProblemResolver does his work.
974
1031
Each addition or deletion may trigger additional actions;
975
they are shown indented two additional space under the original entry.
1032
they are shown indented two additional spaces under the original entry.
976
1033
The format for each line is <literal>MarkKeep</literal>,
977
1034
<literal>MarkDelete</literal> or <literal>MarkInstall</literal> followed by
978
1035
<literal>package-name <a.b.c -> d.e.f | x.y.z> (section)</literal>
980
1037
<literal>d.e.f</literal> is the version considered for installation and
981
1038
<literal>x.y.z</literal> is a newer version, but not considered for installation
982
1039
(because of a low pin score). The later two can be omitted if there is none or if
983
it is the same version as the installed.
1040
it is the same as the installed version.
984
1041
<literal>section</literal> is the name of the section the package appears in.
985
1042
</para>
986
1043
</listitem>
987
1044
</varlistentry>
988
1045
989
<!-- Question: why doesn't this do anything? The code says it should. -->
990
<varlistentry>
991
<term><literal>Debug::pkgInitConfig</literal></term>
992
<listitem>
993
<para>
994
Dump the default configuration to standard error on
995
startup.
996
</para>
997
</listitem>
998
</varlistentry>
999
1000
<varlistentry>
1001
<term><literal>Debug::pkgDPkgPM</literal></term>
1046
<varlistentry>
1047
<term><option>Debug::pkgDPkgPM</option></term>
1002
1048
<listitem>
1003
1049
<para>
1004
1050
When invoking &dpkg;, output the precise command line with
1009
1055
</varlistentry>
1010
1056
1011
1057
<varlistentry>
1012
<term><literal>Debug::pkgDPkgProgressReporting</literal></term>
1058
<term><option>Debug::pkgDPkgProgressReporting</option></term>
1013
1059
<listitem>
1014
1060
<para>
1015
1061
Output all the data received from &dpkg; on the status file
1019
1065
</varlistentry>
1020
1066
1021
1067
<varlistentry>
1022
<term><literal>Debug::pkgOrderList</literal></term>
1068
<term><option>Debug::pkgOrderList</option></term>
1023
1069
1024
1070
<listitem>
1025
1071
<para>
1031
1077
</varlistentry>
1032
1078
1033
1079
<varlistentry>
1034
<term><literal>Debug::pkgPackageManager</literal></term>
1080
<term><option>Debug::pkgPackageManager</option></term>
1035
1081
1036
1082
<listitem>
1037
1083
<para>
1042
1088
</varlistentry>
1043
1089
1044
1090
<varlistentry>
1045
<term><literal>Debug::pkgPolicy</literal></term>
1091
<term><option>Debug::pkgPolicy</option></term>
1046
1092
1047
1093
<listitem>
1048
1094
<para>
1052
1098
</varlistentry>
1053
1099
1054
1100
<varlistentry>
1055
<term><literal>Debug::pkgProblemResolver</literal></term>
1101
<term><option>Debug::pkgProblemResolver</option></term>
1056
1102
1057
1103
<listitem>
1058
1104
<para>
1064
1110
</varlistentry>
1065
1111
1066
1112
<varlistentry>
1067
<term><literal>Debug::pkgProblemResolver::ShowScores</literal></term>
1113
<term><option>Debug::pkgProblemResolver::ShowScores</option></term>
1068
1114
<listitem>
1069
1115
<para>
1070
1116
Display a list of all installed packages with their calculated score
1075
1121
</varlistentry>
1076
1122
1077
1123
<varlistentry>
1078
<term><literal>Debug::sourceList</literal></term>
1124
<term><option>Debug::sourceList</option></term>
1079
1125
1080
1126
<listitem>
1081
1127
<para>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1