16
16
&apt-author.jgunthorpe;
19
<firstname>Daniel</firstname>
20
<surname>Burrows</surname>
21
20
<contrib>Initial documentation of Debug::*.</contrib>
22
<email>dburrows@debian.org</email>
26
24
<!-- The last update date -->
27
<date>16 January 2010</date>
25
<date>2012-05-21T00:00:00Z</date>
127
125
<para>All of the APT tools take a -o option which allows an arbitrary configuration
128
126
directive to be specified on the command line. The syntax is a full option
129
127
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>
128
sign then the new value of the option. To append a new element to a list, add a
129
trailing :: to the name of the list. (As you might suspect: The scope syntax can't
130
be used on the command line.)</para>
134
132
<para>Note that you can use :: only for appending one item per line to a list and
135
133
that you should not use it in combination with the scope syntax.
136
134
(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>"
135
which some users unfortunately depend on: An option with the unusual name "<literal>::</literal>"
138
136
which acts like every other option with a name. These introduces many problems
139
137
including that a user who writes multiple lines in this <emphasis>wrong</emphasis> syntax in
140
138
the hope to append to a list will gain the opposite as only the last assignment for this option
148
146
options for all of the tools.</para>
151
<varlistentry><term>Architecture</term>
149
<varlistentry><term><option>Architecture</option></term>
152
150
<listitem><para>System Architecture; sets the architecture to use when fetching files and
153
151
parsing package lists. The internal default is the architecture apt was
154
152
compiled for.</para></listitem>
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
155
<varlistentry><term><option>Architectures</option></term>
156
<listitem><para>All Architectures the system supports. Processors implementing the
157
<literal>amd64</literal> (also called <literal>x86-64</literal>) instruction set are
158
e.g. also able to execute binaries compiled for the <literal>i386</literal>
159
(<literal>x86</literal>) instruction set; This list is use when fetching files and
160
160
parsing package lists. The internal default is always the native architecture (<literal>APT::Architecture</literal>)
161
161
and all foreign architectures it can retrieve by calling <command>dpkg --print-foreign-architectures</command>.
162
162
</para></listitem>
165
<varlistentry><term>Default-Release</term>
165
<varlistentry><term><option>Default-Release</option></term>
166
166
<listitem><para>Default release to install packages from if more than one
167
167
version available. Contains release name, codename or release version. Examples: 'stable', 'testing',
168
168
'unstable', '&stable-codename;', '&testing-codename;', '4.0', '5.0*'. See also &apt-preferences;.</para></listitem>
171
<varlistentry><term>Ignore-Hold</term>
171
<varlistentry><term><option>Ignore-Hold</option></term>
172
172
<listitem><para>Ignore Held packages; This global option causes the problem resolver to
173
173
ignore held packages in its decision making.</para></listitem>
176
<varlistentry><term>Clean-Installed</term>
176
<varlistentry><term><option>Clean-Installed</option></term>
177
177
<listitem><para>Defaults to on. When turned on the autoclean feature will remove any packages
178
178
which can no longer be downloaded from the cache. If turned off then
179
179
packages that are locally installed are also excluded from cleaning - but
180
180
note that APT provides no direct means to reinstall them.</para></listitem>
183
<varlistentry><term>Immediate-Configure</term>
183
<varlistentry><term><option>Immediate-Configure</option></term>
184
184
<listitem><para>Defaults to on which will cause APT to install essential and important packages
185
185
as fast as possible in the install/upgrade operation. This is done to limit the effect of a failing
186
186
&dpkg; call: If this option is disabled APT does treat an important package in the same way as
203
203
improving or correcting the upgrade process.</para></listitem>
206
<varlistentry><term>Force-LoopBreak</term>
206
<varlistentry><term><option>Force-LoopBreak</option></term>
207
207
<listitem><para>Never Enable this option unless you -really- know what you are doing. It
208
208
permits APT to temporarily remove an essential package to break a
209
209
Conflicts/Conflicts or Conflicts/Pre-Depend loop between two essential
212
212
anything that those packages depend on.</para></listitem>
215
<varlistentry><term>Cache-Start, Cache-Grow and Cache-Limit</term>
215
<varlistentry><term><option>Cache-Start</option></term><term><option>Cache-Grow</option></term><term><option>Cache-Limit</option></term>
216
216
<listitem><para>APT uses since version 0.7.26 a resizable memory mapped cache file to store the 'available'
217
217
information. <literal>Cache-Start</literal> acts as a hint to which size the Cache will grow
218
218
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
219
20971520 bytes (~20 MB). Note that this amount of space needs to be available for APT
220
otherwise it will likely fail ungracefully, so for memory restricted devices this value should
221
be lowered while on systems with a lot of configured sources it should be increased.
222
<literal>Cache-Grow</literal> defines in bytes with the default of 1048576 (~1 MB) how much
223
223
the Cache size will be increased in the event the space defined by <literal>Cache-Start</literal>
224
224
is not enough. These value will be applied again and again until either the cache is big
225
225
enough to store all information or the size of the cache reaches the <literal>Cache-Limit</literal>.
228
228
</para></listitem>
231
<varlistentry><term>Build-Essential</term>
231
<varlistentry><term><option>Build-Essential</option></term>
232
232
<listitem><para>Defines which package(s) are considered essential build dependencies.</para></listitem>
235
<varlistentry><term>Get</term>
235
<varlistentry><term><option>Get</option></term>
236
236
<listitem><para>The Get subsection controls the &apt-get; tool, please see its
237
237
documentation for more information about the options here.</para></listitem>
240
<varlistentry><term>Cache</term>
240
<varlistentry><term><option>Cache</option></term>
241
241
<listitem><para>The Cache subsection controls the &apt-cache; tool, please see its
242
242
documentation for more information about the options here.</para></listitem>
245
<varlistentry><term>CDROM</term>
245
<varlistentry><term><option>CDROM</option></term>
246
246
<listitem><para>The CDROM subsection controls the &apt-cdrom; tool, please see its
247
247
documentation for more information about the options here.</para></listitem>
254
254
and the URI handlers.
257
<varlistentry><term>Check-Valid-Until</term>
257
<varlistentry><term><option>Check-Valid-Until</option></term>
258
258
<listitem><para>Security related option defaulting to true as an
259
259
expiring validation for a Release file prevents longtime replay attacks
260
260
and can e.g. also help users to identify no longer updated mirrors -
265
265
</para></listitem>
268
<varlistentry><term>Max-ValidTime</term>
268
<varlistentry><term><option>Max-ValidTime</option></term>
269
269
<listitem><para>Seconds the Release file should be considered valid after
270
270
it was created (indicated by the <literal>Date</literal> header).
271
271
If the Release file itself includes a <literal>Valid-Until</literal> header
272
272
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".
273
The default value is <literal>0</literal> which stands for "for ever valid".
274
274
Archive specific settings can be made by appending the label of the archive
275
275
to the option name.
276
276
</para></listitem>
279
<varlistentry><term>Min-ValidTime</term>
279
<varlistentry><term><option>Min-ValidTime</option></term>
280
280
<listitem><para>Minimum of seconds the Release file should be considered
281
281
valid after it was created (indicated by the <literal>Date</literal> header).
282
282
Use this if you need to use a seldomly updated (local) mirror of a more
287
287
</para></listitem>
290
<varlistentry><term>PDiffs</term>
290
<varlistentry><term><option>PDiffs</option></term>
291
291
<listitem><para>Try to download deltas called <literal>PDiffs</literal> for
292
292
Packages or Sources files instead of downloading whole ones. True
293
293
by default.</para>
294
294
<para>Two sub-options to limit the use of PDiffs are also available:
295
295
With <literal>FileLimit</literal> can be specified how many PDiff files
296
are downloaded at most to patch a file. <literal>SizeLimit</literal>
296
are downloaded at most to update a file. <literal>SizeLimit</literal>
297
297
on the other hand is the maximum percentage of the size of all patches
298
298
compared to the size of the targeted file. If one of these limits is
299
299
exceeded the complete file is downloaded instead of the patches.
300
300
</para></listitem>
303
<varlistentry><term>Queue-Mode</term>
303
<varlistentry><term><option>Queue-Mode</option></term>
304
304
<listitem><para>Queuing mode; <literal>Queue-Mode</literal> can be one of <literal>host</literal> or
305
305
<literal>access</literal> which determines how APT parallelizes outgoing
306
306
connections. <literal>host</literal> means that one connection per target host
308
308
will be opened.</para></listitem>
311
<varlistentry><term>Retries</term>
311
<varlistentry><term><option>Retries</option></term>
312
312
<listitem><para>Number of retries to perform. If this is non-zero APT will retry failed
313
313
files the given number of times.</para></listitem>
316
<varlistentry><term>Source-Symlinks</term>
316
<varlistentry><term><option>Source-Symlinks</option></term>
317
317
<listitem><para>Use symlinks for source archives. If set to true then source archives will
318
318
be symlinked when possible instead of copying. True is the default.</para></listitem>
321
<varlistentry><term>http</term>
321
<varlistentry><term><option>http</option></term>
322
322
<listitem><para>HTTP URIs; http::Proxy is the default http proxy to use. It is in the
323
323
standard form of <literal>http://[[user][:pass]@]host[:port]/</literal>. Per
324
324
host proxies can also be specified by using the form
340
340
<para>The option <literal>timeout</literal> sets the timeout timer used by the method,
341
341
this applies to all things including connection timeout and data timeout.</para>
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>
343
<para>The setting <literal>Acquire::http::Pipeline-Depth</literal> can be used to
344
enabled HTTP pipeling (RFC 2616 section 8.1.2.2) which can be beneficial e.g. on
345
high-latency connections. It specifies how many requests are send in a pipeline.
346
Previous APT versions had a default of 10 for this setting, but the default value
347
is now 0 (= disabled) to avoid problems with the ever-growing amount of webservers
348
and proxies which choose to not conform to the HTTP/1.1 specification.</para>
350
<para><literal>Acquire::http::AllowRedirect</literal> controls if APT will follow
351
redirects, which is enabled by default.</para>
351
353
<para>The used bandwidth can be limited with <literal>Acquire::http::Dl-Limit</literal>
352
354
which accepts integer values in kilobyte. The default value is 0 which deactivates
362
<varlistentry><term>https</term>
364
<varlistentry><term><option>https</option></term>
363
365
<listitem><para>HTTPS URIs. Cache-control, Timeout, AllowRedirect, Dl-Limit and
364
366
proxy options are the same as for <literal>http</literal> method and will also
365
367
default to the options from the <literal>http</literal> method if they are not
384
386
<literal><host>::SslForceVersion</literal> is corresponding per-host option.
385
387
</para></listitem></varlistentry>
387
<varlistentry><term>ftp</term>
389
<varlistentry><term><option>ftp</option></term>
388
390
<listitem><para>FTP URIs; ftp::Proxy is the default ftp proxy to use. It is in the
389
391
standard form of <literal>ftp://[[user][:pass]@]host[:port]/</literal>. Per
390
392
host proxies can also be specified by using the form
423
425
do not support RFC2428.</para></listitem>
426
<varlistentry><term>cdrom</term>
428
<varlistentry><term><option>cdrom</option></term>
427
429
<listitem><para>CDROM URIs; the only setting for CDROM URIs is the mount point,
428
430
<literal>cdrom::Mount</literal> which must be the mount point for the CDROM drive
429
431
as specified in <filename>/etc/fstab</filename>. It is possible to provide
434
436
commands can be specified using UMount.</para></listitem>
437
<varlistentry><term>gpgv</term>
439
<varlistentry><term><option>gpgv</option></term>
438
440
<listitem><para>GPGV URIs; the only option for GPGV URIs is the option to pass additional parameters to gpgv.
439
441
<literal>gpgv::Options</literal> Additional options passed to gpgv.
440
442
</para></listitem>
443
<varlistentry><term>CompressionTypes</term>
445
<varlistentry><term><option>CompressionTypes</option></term>
444
446
<listitem><para>List of compression types which are understood by the acquire methods.
445
447
Files like <filename>Packages</filename> can be available in various compression formats.
446
448
Per default the acquire methods can decompress <command>bzip2</command>, <command>lzma</command>
468
470
useable for local mirrors.</para></listitem>
471
<varlistentry><term>GzipIndexes</term>
473
<varlistentry><term><option>GzipIndexes</option></term>
473
475
When downloading <literal>gzip</literal> compressed indexes (Packages, Sources, or
474
476
Translations), keep them gzip compressed locally instead of unpacking
477
479
</para></listitem>
480
<varlistentry><term>Languages</term>
482
<varlistentry><term><option>Languages</option></term>
481
483
<listitem><para>The Languages subsection controls which <filename>Translation</filename> files are downloaded
482
484
and in which order APT tries to display the Description-Translations. APT will try to display the first
483
485
available Description in the Language which is listed at first. Languages can be defined with their
494
496
actually use them if the environment doesn't specify this languages. So the following example configuration will
495
497
result in the order "en, de" in an english and in "de, en" in a german localization. Note that "fr" is downloaded,
496
498
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>
499
<programlisting>Acquire::Languages { "environment"; "de"; "en"; "none"; "fr"; };</programlisting></para>
500
<para>Note: To prevent problems resulting from APT being executed in different environments
501
(e.g. by different users or by other programs) all Translation files which are found in
502
<filename>/var/lib/apt/lists/</filename> will be added to the end of the list
503
(after an implicit "<literal>none</literal>").</para>
506
513
<para>The <literal>Dir::State</literal> section has directories that pertain to local
507
514
state information. <literal>lists</literal> is the directory to place downloaded
508
515
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.
516
<literal>preferences</literal> is the name of the APT <filename>preferences</filename> file.
510
517
<literal>Dir::State</literal> contains the default directory to prefix on all sub
511
518
items if they do not start with <filename>/</filename> or <filename>./</filename>.</para>
565
572
control the default behaviour. These are in the <literal>DSelect</literal> section.</para>
568
<varlistentry><term>Clean</term>
575
<varlistentry><term><option>Clean</option></term>
569
576
<listitem><para>Cache Clean mode; this value may be one of always, prompt, auto,
570
577
pre-auto and never. always and prompt will remove all packages from
571
578
the cache after upgrading, prompt (the default) does so conditionally.
574
581
action before downloading new packages.</para></listitem>
577
<varlistentry><term>options</term>
584
<varlistentry><term><option>options</option></term>
578
585
<listitem><para>The contents of this variable is passed to &apt-get; as command line
579
586
options when it is run for the install phase.</para></listitem>
582
<varlistentry><term>Updateoptions</term>
589
<varlistentry><term><option>Updateoptions</option></term>
583
590
<listitem><para>The contents of this variable is passed to &apt-get; as command line
584
591
options when it is run for the update phase.</para></listitem>
587
<varlistentry><term>PromptAfterUpdate</term>
594
<varlistentry><term><option>PromptAfterUpdate</option></term>
588
595
<listitem><para>If true the [U]pdate operation in &dselect; will always prompt to continue.
589
596
The default is to prompt only on error.</para></listitem>
596
603
in the <literal>DPkg</literal> section.</para>
599
<varlistentry><term>options</term>
606
<varlistentry><term><option>options</option></term>
600
607
<listitem><para>This is a list of options to pass to dpkg. The options must be specified
601
608
using the list notation and each list item is passed as a single argument
602
609
to &dpkg;.</para></listitem>
605
<varlistentry><term>Pre-Invoke</term><term>Post-Invoke</term>
612
<varlistentry><term><option>Pre-Invoke</option></term><term><option>Post-Invoke</option></term>
606
613
<listitem><para>This is a list of shell commands to run before/after invoking &dpkg;.
607
614
Like <literal>options</literal> this must be specified in list notation. The
608
615
commands are invoked in order using <filename>/bin/sh</filename>, should any
609
616
fail APT will abort.</para></listitem>
612
<varlistentry><term>Pre-Install-Pkgs</term>
619
<varlistentry><term><option>Pre-Install-Pkgs</option></term>
613
620
<listitem><para>This is a list of shell commands to run before invoking dpkg. Like
614
621
<literal>options</literal> this must be specified in list notation. The commands
615
622
are invoked in order using <filename>/bin/sh</filename>, should any fail APT
623
630
command given to <literal>Pre-Install-Pkgs</literal>.</para></listitem>
626
<varlistentry><term>Run-Directory</term>
633
<varlistentry><term><option>Run-Directory</option></term>
627
634
<listitem><para>APT chdirs to this directory before invoking dpkg, the default is
628
635
<filename>/</filename>.</para></listitem>
631
<varlistentry><term>Build-options</term>
638
<varlistentry><term><option>Build-options</option></term>
632
639
<listitem><para>These options are passed to &dpkg-buildpackage; when compiling packages,
633
640
the default is to disable signing and produce all binaries.</para></listitem>
656
663
DPkg::TriggersPending "true";</literallayout></para>
659
<varlistentry><term>DPkg::NoTriggers</term>
666
<varlistentry><term><option>DPkg::NoTriggers</option></term>
660
667
<listitem><para>Add the no triggers flag to all dpkg calls (except the ConfigurePending call).
661
668
See &dpkg; if you are interested in what this actually means. In short: dpkg will not run the
662
669
triggers when this flag is present unless it is explicitly called to do so in an extra call.
664
671
meaning: Previously these option only append --no-triggers to the configure calls to dpkg -
665
672
now apt will add these flag also to the unpack and remove calls.</para></listitem>
667
<varlistentry><term>PackageManager::Configure</term>
674
<varlistentry><term><option>PackageManager::Configure</option></term>
668
675
<listitem><para>Valid values are "<literal>all</literal>", "<literal>smart</literal>" and "<literal>no</literal>".
669
676
"<literal>all</literal>" is the default value and causes APT to configure all packages explicit.
670
677
The "<literal>smart</literal>" way is it to configure only packages which need to be configured before
675
682
default as otherwise the system could end in an unconfigured status which could be unbootable!
676
683
</para></listitem>
678
<varlistentry><term>DPkg::ConfigurePending</term>
685
<varlistentry><term><option>DPkg::ConfigurePending</option></term>
679
686
<listitem><para>If this option is set apt will call <command>dpkg --configure --pending</command>
680
687
to let dpkg handle all required configurations and triggers. This option is activated automatic
681
688
per default if the previous option is not set to <literal>all</literal>, but deactivating could be useful
682
689
if you want to run APT multiple times in a row - e.g. in an installer. In these sceneries you could
683
690
deactivate this option in all but the last run.</para></listitem>
685
<varlistentry><term>DPkg::TriggersPending</term>
692
<varlistentry><term><option>DPkg::TriggersPending</option></term>
686
693
<listitem><para>Useful for <literal>smart</literal> configuration as a package which has pending
687
694
triggers is not considered as <literal>installed</literal> and dpkg treats them as <literal>unpacked</literal>
688
695
currently which is a dealbreaker for Pre-Dependencies (see debbugs #526774). Note that this will
689
696
process all triggers, not only the triggers needed to configure this package.</para></listitem>
691
<varlistentry><term>PackageManager::UnpackAll</term>
698
<varlistentry><term><option>PackageManager::UnpackAll</option></term>
692
699
<listitem><para>As the configuration can be deferred to be done at the end by dpkg it can be
693
700
tried to order the unpack series only by critical needs, e.g. by Pre-Depends. Default is true
694
701
and therefore the "old" method of ordering in various steps by everything. While both method
696
703
this method is very experimental and needs further improvements before becoming really useful.
697
704
</para></listitem>
699
<varlistentry><term>OrderList::Score::Immediate</term>
706
<varlistentry><term><option>OrderList::Score::Immediate</option></term>
700
707
<listitem><para>Essential packages (and there dependencies) should be configured immediately
701
708
after unpacking. It will be a good idea to do this quite early in the upgrade process as these
702
709
these configure calls require currently also <literal>DPkg::TriggersPending</literal> which