doc/apt.conf.5.xml

   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" [
   4
   5 <!ENTITY % aptent SYSTEM "apt.ent">
   6 %aptent;
   7
   8 ]>
   9
  10 <refentry>
  11
  12  <refentryinfo>
  13    &apt-author.jgunthorpe;
  14    &apt-author.team;
  15    <author>
  16      <firstname>Daniel</firstname>
  17      <surname>Burrows</surname>
  18      <contrib>Initial documentation of Debug::*.</contrib>
  19      <email>dburrows@debian.org</email>
  20    </author>
  21    &apt-email;
  22    &apt-product;
  23    <!-- The last update date -->
  24    <date>18 September 2009</date>
  25  </refentryinfo>
  26
  27  <refmeta>
  28    <refentrytitle>apt.conf</refentrytitle>
  29    <manvolnum>5</manvolnum>
  30    <refmiscinfo class="manual">APT</refmiscinfo>
  31  </refmeta>
  32
  33  <!-- Man page title -->
  34  <refnamediv>
  35     <refname>apt.conf</refname>
  36     <refpurpose>Configuration file for APT</refpurpose>
  37  </refnamediv>
  38
  39  <refsect1><title>Description</title>
  40    <para><filename>apt.conf</filename> is the main configuration file for the APT suite of
  41    tools, all tools make use of the configuration file and a common command line
  42    parser to provide a uniform environment. When an APT tool starts up it will
  43    read the configuration specified by the <envar>APT_CONFIG</envar> environment
  44    variable (if any) and then read the files in <literal>Dir::Etc::Parts</literal>
  45    then read the main configuration file specified by
  46    <literal>Dir::Etc::main</literal> then finally apply the
  47    command line options to override the configuration directives, possibly
  48    loading even more config files.</para>
  49
  50    <para>The configuration file is organized in a tree with options organized into
  51    functional groups. option specification is given with a double colon
  52    notation, for instance <literal>APT::Get::Assume-Yes</literal> is an option within
  53    the APT tool group, for the Get tool. options do not inherit from their
  54    parent groups.</para>
  55
  56    <para>Syntactically the configuration language is modeled after what the ISC tools
  57    such as bind and dhcp use. Lines starting with
  58    <literal>//</literal> are treated as comments (ignored), as well as all text
  59    between <literal>/*</literal> and <literal>*/</literal>, just like C/C++ comments.
  60    Each line is of the form
  61    <literal>APT::Get::Assume-Yes "true";</literal> The trailing
  62    semicolon and the quotes are required. The value must be on one line, and
  63    there is no kind of string concatenation. It must not include inside quotes.
  64    The behavior of the backslash "\" and escaped characters inside a value is
  65    undefined and it should not be used. An option name may include
  66    alphanumerical characters and the "/-:._+" characters. A new scope can
  67    be opened with curly braces, like:</para>
  68
  69 <informalexample><programlisting>
  70 APT {
  71   Get {
  72     Assume-Yes "true";
  73     Fix-Broken "true";
  74   };
  75 };
  76 </programlisting></informalexample>
  77
  78    <para>with newlines placed to make it more readable. Lists can be created by
  79    opening a scope and including a single string enclosed in quotes followed by a
  80    semicolon. Multiple entries can be included, each separated by a semicolon.</para>
  81
  82 <informalexample><programlisting>
  83 DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
  84 </programlisting></informalexample>
  85
  86    <para>In general the sample configuration file in
  87    <filename>&docdir;examples/apt.conf</filename> &configureindex;
  88    is a good guide for how it should look.</para>
  89
  90    <para>The names of the configuration items are not case-sensitive. So in the previous example
  91    you could use <literal>dpkg::pre-install-pkgs</literal>.</para>
  92
  93    <para>Names for the configuration items are optional if a list is defined as it can be see in
  94    the <literal>DPkg::Pre-Install-Pkgs</literal> example above. If you don't specify a name a
  95    new entry will simply add a new option to the list. If you specify a name you can override
  96    the option as every other option by reassigning a new value to the option.</para>
  97
  98    <para>Two specials are allowed, <literal>#include</literal> (which is deprecated
  99    and not supported by alternative implementations) and <literal>#clear</literal>:
 100    <literal>#include</literal> will include the given file, unless the filename
 101    ends in a slash, then the whole directory is included.
 102    <literal>#clear</literal> is used to erase a part of the configuration tree. The
 103    specified element and all its descendants are erased.
 104    (Note that these lines also need to end with a semicolon.)</para>
 105
 106    <para>The #clear command is the only way to delete a list or a complete scope.
 107    Reopening a scope or the ::-style described below will <emphasis>not</emphasis>
 108    override previously written entries. Only options can be overridden by addressing a new
 109    value to it - lists and scopes can't be overridden, only cleared.</para>
 110
 111    <para>All of the APT tools take a -o option which allows an arbitrary configuration
 112    directive to be specified on the command line. The syntax is a full option
 113    name (<literal>APT::Get::Assume-Yes</literal> for instance) followed by an equals
 114    sign then the new value of the option. Lists can be appended too by adding
 115    a trailing :: to the list name. (As you might suspect: The scope syntax can't be used
 116    on the command line.)</para>
 117
 118    <para>Note that you can use :: only for appending one item per line to a list and
 119    that you should not use it in combination with the scope syntax.
 120    (The scope syntax implicit insert ::) Using both syntaxes together will trigger a bug
 121    which some users unfortunately relay on: An option with the unusual name "<literal>::</literal>"
 122    which acts like every other option with a name. These introduces many problems
 123    including that a user who writes multiple lines in this <emphasis>wrong</emphasis> syntax in
 124    the hope to append to a list will gain the opposite as only the last assignment for this option
 125    "<literal>::</literal>" will be used. Upcoming APT versions will raise errors and
 126    will stop working if they encounter this misuse, so please correct such statements now
 127    as long as APT doesn't complain explicit about them.</para>
 128  </refsect1>
 129
 130  <refsect1><title>The APT Group</title>
 131    <para>This group of options controls general APT behavior as well as holding the
 132    options for all of the tools.</para>
 133
 134    <variablelist>
 135      <varlistentry><term>Architecture</term>
 136      <listitem><para>System Architecture; sets the architecture to use when fetching files and
 137      parsing package lists. The internal default is the architecture apt was
 138      compiled for.</para></listitem>
 139      </varlistentry>
 140
 141      <varlistentry><term>Default-Release</term>
 142          <listitem><para>Default release to install packages from if more than one
 143          version available. Contains release name, codename or release version. Examples: 'stable', 'testing', 'unstable', 'lenny', 'squeeze', '4.0', '5.0*'. See also &apt-preferences;.</para></listitem>
 144      </varlistentry>
 145
 146      <varlistentry><term>Ignore-Hold</term>
 147      <listitem><para>Ignore Held packages; This global option causes the problem resolver to
 148      ignore held packages in its decision making.</para></listitem>
 149      </varlistentry>
 150
 151      <varlistentry><term>Clean-Installed</term>
 152      <listitem><para>Defaults to on. When turned on the autoclean feature will remove any packages
 153      which can no longer be downloaded from the cache. If turned off then
 154      packages that are locally installed are also excluded from cleaning - but
 155      note that APT provides no direct means to reinstall them.</para></listitem>
 156      </varlistentry>
 157
 158      <varlistentry><term>Immediate-Configure</term>
 159      <listitem><para>Disable Immediate Configuration; This dangerous option disables some
 160      of APT's ordering code to cause it to make fewer dpkg calls. Doing
 161      so may be necessary on some extremely slow single user systems but
 162      is very dangerous and may cause package install scripts to fail or worse.
 163      Use at your own risk.</para></listitem>
 164      </varlistentry>
 165
 166      <varlistentry><term>Force-LoopBreak</term>
 167      <listitem><para>Never Enable this option unless you -really- know what you are doing. It
 168      permits APT to temporarily remove an essential package to break a
 169      Conflicts/Conflicts or Conflicts/Pre-Depend loop between two essential
 170      packages. SUCH A LOOP SHOULD NEVER EXIST AND IS A GRAVE BUG. This option
 171      will work if the essential packages are not tar, gzip, libc, dpkg, bash or
 172      anything that those packages depend on.</para></listitem>
 173      </varlistentry>
 174
 175      <varlistentry><term>Cache-Limit</term>
 176      <listitem><para>APT uses a fixed size memory mapped cache file to store the 'available'
 177      information. This sets the size of that cache (in bytes).</para></listitem>
 178      </varlistentry>
 179
 180      <varlistentry><term>Build-Essential</term>
 181      <listitem><para>Defines which package(s) are considered essential build dependencies.</para></listitem>
 182      </varlistentry>
 183
 184      <varlistentry><term>Get</term>
 185      <listitem><para>The Get subsection controls the &apt-get; tool, please see its
 186      documentation for more information about the options here.</para></listitem>
 187      </varlistentry>
 188
 189      <varlistentry><term>Cache</term>
 190      <listitem><para>The Cache subsection controls the &apt-cache; tool, please see its
 191      documentation for more information about the options here.</para></listitem>
 192      </varlistentry>
 193
 194      <varlistentry><term>CDROM</term>
 195      <listitem><para>The CDROM subsection controls the &apt-cdrom; tool, please see its
 196      documentation for more information about the options here.</para></listitem>
 197      </varlistentry>
 198    </variablelist>
 199  </refsect1>
 200
 201  <refsect1><title>The Acquire Group</title>
 202    <para>The <literal>Acquire</literal> group of options controls the download of packages
 203    and the URI handlers.
 204
 205    <variablelist>
 206      <varlistentry><term>PDiffs</term>
 207          <listitem><para>Try to download deltas called <literal>PDiffs</literal> for
 208          Packages or Sources files instead of downloading whole ones. True
 209          by default.</para></listitem>
 210      </varlistentry>
 211
 212      <varlistentry><term>Queue-Mode</term>
 213      <listitem><para>Queuing mode; <literal>Queue-Mode</literal> can be one of <literal>host</literal> or
 214      <literal>access</literal> which determines how  APT parallelizes outgoing
 215      connections. <literal>host</literal> means that one connection per target host
 216      will be opened, <literal>access</literal> means that one connection per URI type
 217      will be opened.</para></listitem>
 218      </varlistentry>
 219
 220      <varlistentry><term>Retries</term>
 221      <listitem><para>Number of retries to perform. If this is non-zero APT will retry failed
 222      files the given number of times.</para></listitem>
 223      </varlistentry>
 224
 225      <varlistentry><term>Source-Symlinks</term>
 226      <listitem><para>Use symlinks for source archives. If set to true then source archives will
 227      be symlinked when possible instead of copying. True is the default.</para></listitem>
 228      </varlistentry>
 229
 230      <varlistentry><term>http</term>
 231      <listitem><para>HTTP URIs; http::Proxy is the default http proxy to use. It is in the
 232      standard form of <literal>http://[[user][:pass]@]host[:port]/</literal>. Per
 233      host proxies can also be specified by using the form
 234      <literal>http::Proxy::&lt;host&gt;</literal> with the special keyword <literal>DIRECT</literal>
 235          meaning to use no proxies. If no one of the above settings is specified,
 236          <envar>http_proxy</envar> environment variable
 237          will be used.</para>
 238
 239      <para>Three settings are provided for cache control with HTTP/1.1 compliant
 240      proxy caches. <literal>No-Cache</literal> tells the proxy to not use its cached
 241      response under any circumstances, <literal>Max-Age</literal> is sent only for
 242      index files and tells the cache to refresh its object if it is older than
 243      the given number of seconds. Debian updates its index files daily so the
 244      default is 1 day. <literal>No-Store</literal> specifies that the cache should never
 245      store this request, it is only set for archive files. This may be useful
 246      to prevent polluting a proxy cache with very large .deb files. Note:
 247      Squid 2.0.2 does not support any of these options.</para>
 248
 249      <para>The option <literal>timeout</literal> sets the timeout timer used by the method,
 250      this applies to all things including connection timeout and data timeout.</para>
 251
 252      <para>One setting is provided to control the pipeline depth in cases where the
 253      remote server is not RFC conforming or buggy (such as Squid 2.0.2)
 254      <literal>Acquire::http::Pipeline-Depth</literal> can be a value from 0 to 5
 255      indicating how many outstanding requests APT should send. A value of
 256      zero MUST be specified if the remote host does not properly linger
 257      on TCP connections - otherwise data corruption will occur. Hosts which
 258      require this are in violation of RFC 2068.</para>
 259
 260      <para>The used bandwidth can be limited with <literal>Acquire::http::Dl-Limit</literal>
 261      which accepts integer values in kilobyte. The default value is 0 which deactivates
 262      the limit and tries uses as much as possible of the bandwidth (Note that this option implicit
 263      deactivates the download from multiple servers at the same time.)</para></listitem>
 264      </varlistentry>
 265
 266      <varlistentry><term>https</term>
 267          <listitem><para>HTTPS URIs. Cache-control and proxy options are the same as for
 268          <literal>http</literal> method.
 269          <literal>Pipeline-Depth</literal> option is not supported yet.</para>
 270
 271          <para><literal>CaInfo</literal> suboption specifies place of file that
 272          holds info about trusted certificates.
 273          <literal>&lt;host&gt;::CaInfo</literal> is corresponding per-host option.
 274          <literal>Verify-Peer</literal> boolean suboption determines whether verify
 275          server's host certificate against trusted certificates or not.
 276          <literal>&lt;host&gt;::Verify-Peer</literal> is corresponding per-host option.
 277          <literal>Verify-Host</literal> boolean suboption determines whether verify
 278          server's hostname or not.
 279          <literal>&lt;host&gt;::Verify-Host</literal> is corresponding per-host option.
 280          <literal>SslCert</literal> determines what certificate to use for client
 281          authentication. <literal>&lt;host&gt;::SslCert</literal> is corresponding per-host option.
 282          <literal>SslKey</literal> determines what private key to use for client
 283          authentication. <literal>&lt;host&gt;::SslKey</literal> is corresponding per-host option.
 284          <literal>SslForceVersion</literal> overrides default SSL version to use.
 285          Can contain 'TLSv1' or 'SSLv3' string.
 286          <literal>&lt;host&gt;::SslForceVersion</literal> is corresponding per-host option.
 287          </para></listitem></varlistentry>
 288
 289      <varlistentry><term>ftp</term>
 290      <listitem><para>FTP URIs; ftp::Proxy is the default ftp proxy to use. It is in the
 291      standard form of <literal>ftp://[[user][:pass]@]host[:port]/</literal>. Per
 292      host proxies can also be specified by using the form
 293      <literal>ftp::Proxy::&lt;host&gt;</literal> with the special keyword <literal>DIRECT</literal>
 294          meaning to use no proxies. If no one of the above settings is specified,
 295          <envar>ftp_proxy</envar> environment variable
 296          will be used. To use a ftp
 297      proxy you will have to set the <literal>ftp::ProxyLogin</literal> script in the
 298      configuration file. This entry specifies the commands to send to tell
 299      the proxy server what to connect to. Please see
 300      &configureindex; for an example of
 301      how to do this. The substitution variables available are
 302      <literal>$(PROXY_USER)</literal> <literal>$(PROXY_PASS)</literal> <literal>$(SITE_USER)</literal>
 303      <literal>$(SITE_PASS)</literal> <literal>$(SITE)</literal> and <literal>$(SITE_PORT)</literal>
 304      Each is taken from it's respective URI component.</para>
 305
 306      <para>The option <literal>timeout</literal> sets the timeout timer used by the method,
 307      this applies to all things including connection timeout and data timeout.</para>
 308
 309      <para>Several settings are provided to control passive mode. Generally it is
 310      safe to leave passive mode on, it works in nearly every environment.
 311      However some situations require that passive mode be disabled and port
 312      mode ftp used instead. This can be done globally, for connections that
 313      go through a proxy or for a specific host (See the sample config file
 314      for examples).</para>
 315
 316      <para>It is possible to proxy FTP over HTTP by setting the <envar>ftp_proxy</envar>
 317      environment variable to a http url - see the discussion of the http method
 318      above for syntax. You cannot set this in the configuration file and it is
 319      not recommended to use FTP over HTTP due to its low efficiency.</para>
 320
 321      <para>The setting <literal>ForceExtended</literal> controls the use of RFC2428
 322      <literal>EPSV</literal> and <literal>EPRT</literal> commands. The default is false, which means
 323      these commands are only used if the control connection is IPv6. Setting this
 324      to true forces their use even on IPv4 connections. Note that most FTP servers
 325      do not support RFC2428.</para></listitem>
 326      </varlistentry>
 327
 328      <varlistentry><term>cdrom</term>
 329      <listitem><para>CDROM URIs; the only setting for CDROM URIs is the mount point,
 330      <literal>cdrom::Mount</literal> which must be the mount point for the CDROM drive
 331      as specified in <filename>/etc/fstab</filename>. It is possible to provide
 332      alternate mount and unmount commands if your mount point cannot be listed
 333      in the fstab (such as an SMB mount and old mount packages). The syntax
 334      is to put <literallayout>/cdrom/::Mount "foo";</literallayout> within
 335      the cdrom block. It is important to have the trailing slash. Unmount
 336      commands can be specified using UMount.</para></listitem>
 337      </varlistentry>
 338
 339      <varlistentry><term>gpgv</term>
 340      <listitem><para>GPGV URIs; the only option for GPGV URIs is the option to pass additional parameters to gpgv.
 341      <literal>gpgv::Options</literal> Additional options passed to gpgv.
 342      </para></listitem>
 343      </varlistentry>
 344
 345      <varlistentry><term>CompressionTypes</term>
 346      <listitem><para>List of compression types which are understood by the acquire methods.
 347      Files like <filename>Packages</filename> can be available in various compression formats.
 348      Per default the acquire methods can decompress <command>bzip2</command>, <command>lzma</command>
 349      and <command>gzip</command> compressed files, with this setting more formats can be added
 350      on the fly or the used method can be changed. The syntax for this is:
 351      <synopsis>Acquire::CompressionTypes::<replaceable>FileExtension</replaceable> "<replaceable>Methodname</replaceable>";</synopsis>
 352      </para><para>Also the <literal>Order</literal> subgroup can be used to define in which order
 353      the acquire system will try to download the compressed files. The acquire system will try the first
 354      and proceed with the next compression type in this list on error, so to prefer one over the other type
 355      simple add the preferred type at first - not already added default types will be added at run time
 356      to the end of the list, so e.g. <synopsis>Acquire::CompressionTypes::Order:: "gz";</synopsis> can
 357      be used to prefer <command>gzip</command> compressed files over <command>bzip2</command> and <command>lzma</command>.
 358      If <command>lzma</command> should be preferred over <command>gzip</command> and <command>bzip2</command> the
 359      configure setting should look like this <synopsis>Acquire::CompressionTypes::Order { "lzma"; "gz"; };</synopsis>
 360      It is not needed to add <literal>bz2</literal> explicit to the list as it will be added automatic.</para>
 361      <para>Note that at run time the <literal>Dir::Bin::<replaceable>Methodname</replaceable></literal> will
 362      be checked: If this setting exists the method will only be used if this file exists, e.g. for
 363      the bzip2 method (the inbuilt) setting is <literallayout>Dir::Bin::bzip2 "/bin/bzip2";</literallayout>
 364      Note also that list entries specified on the command line will be added at the end of the list
 365      specified in the configuration files, but before the default entries. To prefer a type in this case
 366      over the ones specified in in the configuration files you can set the option direct - not in list style.
 367      This will not override the defined list, it will only prefix the list with this type.</para>
 368      <para>While it is possible to add an empty compression type to the order list, but APT in its current
 369      version doesn't understand it correctly and will display many warnings about not downloaded files -
 370      these warnings are most of the time false negatives. Future versions will maybe include a way to
 371      really prefer uncompressed files to support the usage of local mirrors.</para></listitem>
 372      </varlistentry>
 373    </variablelist>
 374   </para>
 375  </refsect1>
 376
 377  <refsect1><title>Directories</title>
 378
 379    <para>The <literal>Dir::State</literal> section has directories that pertain to local
 380    state information. <literal>lists</literal> is the directory to place downloaded
 381    package lists in and <literal>status</literal> is the name of the dpkg status file.
 382    <literal>preferences</literal> is the name of the APT preferences file.
 383    <literal>Dir::State</literal> contains the default directory to prefix on all sub
 384    items if they do not start with <filename>/</filename> or <filename>./</filename>.</para>
 385
 386    <para><literal>Dir::Cache</literal> contains locations pertaining to local cache
 387    information, such as the two package caches <literal>srcpkgcache</literal> and
 388    <literal>pkgcache</literal> as well as the location to place downloaded archives,
 389    <literal>Dir::Cache::archives</literal>. Generation of caches can be turned off
 390    by setting their names to be blank. This will slow down startup but
 391    save disk space. It is probably preferred to turn off the pkgcache rather
 392    than the srcpkgcache. Like <literal>Dir::State</literal> the default
 393    directory is contained in <literal>Dir::Cache</literal></para>
 394
 395    <para><literal>Dir::Etc</literal> contains the location of configuration files,
 396    <literal>sourcelist</literal> gives the location of the sourcelist and
 397    <literal>main</literal> is the default configuration file (setting has no effect,
 398    unless it is done from the config file specified by
 399    <envar>APT_CONFIG</envar>).</para>
 400
 401    <para>The <literal>Dir::Parts</literal> setting reads in all the config fragments in
 402    lexical order from the directory specified. After this is done then the
 403    main config file is loaded.</para>
 404
 405    <para>Binary programs are pointed to by <literal>Dir::Bin</literal>. <literal>Dir::Bin::Methods</literal>
 406    specifies the location of the method handlers and <literal>gzip</literal>,
 407    <literal>bzip2</literal>, <literal>lzma</literal>,
 408    <literal>dpkg</literal>, <literal>apt-get</literal> <literal>dpkg-source</literal>
 409    <literal>dpkg-buildpackage</literal> and <literal>apt-cache</literal> specify the location
 410    of the respective programs.</para>
 411
 412    <para>
 413      The configuration item <literal>RootDir</literal> has a special
 414      meaning.  If set, all paths in <literal>Dir::</literal> will be
 415      relative to <literal>RootDir</literal>, <emphasis>even paths that
 416      are specified absolutely</emphasis>.  So, for instance, if
 417      <literal>RootDir</literal> is set to
 418      <filename>/tmp/staging</filename> and
 419      <literal>Dir::State::status</literal> is set to
 420      <filename>/var/lib/dpkg/status</filename>, then the status file
 421      will be looked up in
 422      <filename>/tmp/staging/var/lib/dpkg/status</filename>.
 423    </para>
 424  </refsect1>
 425
 426  <refsect1><title>APT in DSelect</title>
 427    <para>
 428    When APT is used as a &dselect; method several configuration directives
 429    control the default behaviour. These are in the <literal>DSelect</literal> section.</para>
 430
 431    <variablelist>
 432      <varlistentry><term>Clean</term>
 433      <listitem><para>Cache Clean mode; this value may be one of always, prompt, auto,
 434      pre-auto and never.  always and prompt will remove all packages from
 435      the cache after upgrading, prompt (the default) does so conditionally.
 436      auto removes only those packages which are no longer downloadable
 437      (replaced with a new version for instance).  pre-auto performs this
 438      action before downloading new packages.</para></listitem>
 439      </varlistentry>
 440
 441      <varlistentry><term>options</term>
 442      <listitem><para>The contents of this variable is passed to &apt-get; as command line
 443      options when it is run for the install phase.</para></listitem>
 444      </varlistentry>
 445
 446      <varlistentry><term>Updateoptions</term>
 447      <listitem><para>The contents of this variable is passed to &apt-get; as command line
 448      options when it is run for the update phase.</para></listitem>
 449      </varlistentry>
 450
 451      <varlistentry><term>PromptAfterUpdate</term>
 452      <listitem><para>If true the [U]pdate operation in &dselect; will always prompt to continue.
 453      The default is to prompt only on error.</para></listitem>
 454      </varlistentry>
 455    </variablelist>
 456  </refsect1>
 457
 458  <refsect1><title>How APT calls dpkg</title>
 459    <para>Several configuration directives control how APT invokes &dpkg;. These are
 460    in the <literal>DPkg</literal> section.</para>
 461
 462    <variablelist>
 463      <varlistentry><term>options</term>
 464      <listitem><para>This is a list of options to pass to dpkg. The options must be specified
 465      using the list notation and each list item is passed as a single argument
 466      to &dpkg;.</para></listitem>
 467      </varlistentry>
 468
 469      <varlistentry><term>Pre-Invoke</term><term>Post-Invoke</term>
 470      <listitem><para>This is a list of shell commands to run before/after invoking &dpkg;.
 471      Like <literal>options</literal> this must be specified in list notation. The
 472      commands are invoked in order using <filename>/bin/sh</filename>, should any
 473      fail APT will abort.</para></listitem>
 474      </varlistentry>
 475
 476      <varlistentry><term>Pre-Install-Pkgs</term>
 477      <listitem><para>This is a list of shell commands to run before invoking dpkg. Like
 478      <literal>options</literal> this must be specified in list notation. The commands
 479      are invoked in order using <filename>/bin/sh</filename>, should any fail APT
 480      will abort. APT will pass to the commands on standard input the
 481      filenames of all .deb files it is going to install, one per line.</para>
 482
 483      <para>Version 2 of this protocol dumps more information, including the
 484      protocol version, the APT configuration space and the packages, files
 485      and versions being changed. Version 2 is enabled by setting
 486      <literal>DPkg::Tools::options::cmd::Version</literal> to 2. <literal>cmd</literal> is a
 487      command given to <literal>Pre-Install-Pkgs</literal>.</para></listitem>
 488      </varlistentry>
 489
 490      <varlistentry><term>Run-Directory</term>
 491      <listitem><para>APT chdirs to this directory before invoking dpkg, the default is
 492      <filename>/</filename>.</para></listitem>
 493      </varlistentry>
 494
 495      <varlistentry><term>Build-options</term>
 496      <listitem><para>These options are passed to &dpkg-buildpackage; when compiling packages,
 497      the default is to disable signing and produce all binaries.</para></listitem>
 498      </varlistentry>
 499    </variablelist>
 500
 501    <refsect2><title>dpkg trigger usage (and related options)</title>
 502      <para>APT can call dpkg in a way so it can make aggressive use of triggers over
 503      multiply calls of dpkg. Without further options dpkg will use triggers only in between his
 504      own run. Activating these options can therefore decrease the time needed to perform the
 505      install / upgrade. Note that it is intended to activate these options per default in the
 506      future, but as it changes the way APT calling dpkg drastically it needs a lot more testing.
 507      <emphasis>These options are therefore currently experimental and should not be used in
 508      productive environments.</emphasis> Also it breaks the progress reporting so all frontends will
 509      currently stay around half (or more) of the time in the 100% state while it actually configures
 510      all packages.</para>
 511      <para>Note that it is not guaranteed that APT will support these options or that these options will
 512      not cause (big) trouble in the future. If you have understand the current risks and problems with
 513      these options, but are brave enough to help testing them create a new configuration file and test a
 514      combination of options. Please report any bugs, problems and improvements you encounter and make sure
 515      to note which options you have used in your reports. Asking dpkg for help could also be useful for
 516      debugging proposes, see e.g. <command>dpkg --audit</command>. A defensive option combination would be
 517 <literallayout>DPkg::NoTriggers "true";
 518 PackageManager::Configure "smart";
 519 DPkg::ConfigurePending "true";
 520 DPkg::TriggersPending "true";</literallayout></para>
 521
 522      <variablelist>
 523        <varlistentry><term>DPkg::NoTriggers</term>
 524        <listitem><para>Add the no triggers flag to all dpkg calls (expect the ConfigurePending call).
 525        See &dpkg; if you are interested in what this actually means. In short: dpkg will not run the
 526        triggers then this flag is present unless it is explicit called to do so in an extra call.
 527        Note that this option exists (undocumented) also in older apt versions with a slightly different
 528        meaning: Previously these option only append --no-triggers to the configure calls to dpkg -
 529        now apt will add these flag also to the unpack and remove calls.</para></listitem>
 530        </varlistentry>
 531        <varlistentry><term>PackageManager::Configure</term>
 532        <listitem><para>Valid values are "<literal>all</literal>", "<literal>smart</literal>" and "<literal>no</literal>".
 533        "<literal>all</literal>" is the default value and causes APT to configure all packages explicit.
 534        The "<literal>smart</literal>" way is it to configure only packages which need to be configured before
 535        another package can be unpacked (Pre-Depends) and let the rest configure by dpkg with a call generated
 536        by the next option. "<literal>no</literal>" on the other hand will not configure anything and totally
 537        relay on dpkg for configuration (which will at the moment fail if a Pre-Depends is encountered).
 538        Setting this option to another than the all value will implicit activate also the next option per
 539        default as otherwise the system could end in an unconfigured status which could be unbootable!
 540        </para></listitem>
 541        </varlistentry>
 542        <varlistentry><term>DPkg::ConfigurePending</term>
 543        <listitem><para>If this option is set apt will call <command>dpkg --configure --pending</command>
 544        to let dpkg handle all required configurations and triggers. This option is activated automatic
 545        per default if the previous option is not set to <literal>all</literal>, but deactivating could be useful
 546        if you want to run APT multiple times in a row - e.g. in an installer. In this sceneries you could
 547        deactivate this option in all but the last run.</para></listitem>
 548        </varlistentry>
 549        <varlistentry><term>DPkg::TriggersPending</term>
 550        <listitem><para>Useful for <literal>smart</literal> configuration as a package which has pending
 551        triggers is not considered as <literal>installed</literal> and dpkg treats them as <literal>unpacked</literal>
 552        currently which is a dealbreaker for Pre-Dependencies (see debbugs #526774). Note that this will
 553        process all triggers, not only the triggers needed to configure this package.</para></listitem>
 554        </varlistentry>
 555        <varlistentry><term>PackageManager::UnpackAll</term>
 556        <listitem><para>As the configuration can be deferred to be done at the end by dpkg it can be
 557        tried to order the unpack series only by critical needs, e.g. by Pre-Depends. Default is true
 558        and therefore the "old" method of ordering in various steps by everything. While both method
 559        were present in earlier APT versions the <literal>OrderCritical</literal> method was unused, so
 560        this method is very experimental and needs further improvements before becoming really useful.
 561        </para></listitem>
 562        </varlistentry>
 563        <varlistentry><term>OrderList::Score::Immediate</term>
 564        <listitem><para>Essential packages (and there dependencies) should be configured immediately
 565        after unpacking. It will be a good idea to do this quite early in the upgrade process as these
 566        these configure calls require currently also <literal>DPkg::TriggersPending</literal> which
 567        will run quite a few triggers (which maybe not needed). Essentials get per default a high score
 568        but the immediate flag is relatively low (a package which has a Pre-Depends is higher rated).
 569        These option and the others in the same group can be used to change the scoring. The following
 570        example shows the settings with there default values.
 571        <literallayout>OrderList::Score {
 572         Delete 500;
 573         Essential 200;
 574         Immediate 10;
 575         PreDepends 50;
 576 };</literallayout>
 577        </para></listitem>
 578        </varlistentry>
 579      </variablelist>
 580    </refsect2>
 581  </refsect1>
 582
 583  <refsect1>
 584    <title>Periodic and Archives options</title>
 585    <para><literal>APT::Periodic</literal> and <literal>APT::Archives</literal>
 586    groups of options configure behavior of apt periodic updates, which is
 587    done by <literal>/etc/cron.daily/apt</literal> script. See header of
 588    this script for the brief documentation of these options.
 589    </para>
 590  </refsect1>
 591
 592  <refsect1>
 593    <title>Debug options</title>
 594    <para>
 595      Enabling options in the <literal>Debug::</literal> section will
 596      cause debugging information to be sent to the standard error
 597      stream of the program utilizing the <literal>apt</literal>
 598      libraries, or enable special program modes that are primarily
 599      useful for debugging the behavior of <literal>apt</literal>.
 600      Most of these options are not interesting to a normal user, but a
 601      few may be:
 602
 603      <itemizedlist>
 604        <listitem>
 605          <para>
 606            <literal>Debug::pkgProblemResolver</literal> enables output
 607            about the decisions made by
 608            <literal>dist-upgrade, upgrade, install, remove, purge</literal>.
 609          </para>
 610        </listitem>
 611
 612        <listitem>
 613          <para>
 614            <literal>Debug::NoLocking</literal> disables all file
 615            locking.  This can be used to run some operations (for
 616            instance, <literal>apt-get -s install</literal>) as a
 617            non-root user.
 618          </para>
 619        </listitem>
 620
 621        <listitem>
 622          <para>
 623            <literal>Debug::pkgDPkgPM</literal> prints out the actual
 624            command line each time that <literal>apt</literal> invokes
 625            &dpkg;.
 626          </para>
 627        </listitem>
 628
 629        <listitem>
 630          <para>
 631            <literal>Debug::IdentCdrom</literal> disables the inclusion
 632            of statfs data in CDROM IDs.  <!-- TODO: provide a
 633            motivating example, except I haven't a clue why you'd want
 634            to do this. -->
 635          </para>
 636        </listitem>
 637      </itemizedlist>
 638    </para>
 639
 640    <para>
 641      A full list of debugging options to apt follows.
 642    </para>
 643
 644    <variablelist>
 645      <varlistentry>
 646        <term><literal>Debug::Acquire::cdrom</literal></term>
 647
 648        <listitem>
 649          <para>
 650            Print information related to accessing
 651            <literal>cdrom://</literal> sources.
 652          </para>
 653        </listitem>
 654      </varlistentry>
 655
 656      <varlistentry>
 657        <term><literal>Debug::Acquire::ftp</literal></term>
 658
 659        <listitem>
 660          <para>
 661            Print information related to downloading packages using
 662            FTP.
 663          </para>
 664        </listitem>
 665      </varlistentry>
 666
 667      <varlistentry>
 668        <term><literal>Debug::Acquire::http</literal></term>
 669
 670        <listitem>
 671          <para>
 672            Print information related to downloading packages using
 673            HTTP.
 674          </para>
 675        </listitem>
 676      </varlistentry>
 677
 678      <varlistentry>
 679        <term><literal>Debug::Acquire::https</literal></term>
 680
 681        <listitem>
 682          <para>
 683            Print information related to downloading packages using
 684            HTTPS.
 685          </para>
 686        </listitem>
 687      </varlistentry>
 688
 689      <varlistentry>
 690        <term><literal>Debug::Acquire::gpgv</literal></term>
 691
 692        <listitem>
 693          <para>
 694            Print information related to verifying cryptographic
 695            signatures using <literal>gpg</literal>.
 696          </para>
 697        </listitem>
 698      </varlistentry>
 699
 700      <varlistentry>
 701        <term><literal>Debug::aptcdrom</literal></term>
 702
 703        <listitem>
 704          <para>
 705            Output information about the process of accessing
 706            collections of packages stored on CD-ROMs.
 707          </para>
 708        </listitem>
 709      </varlistentry>
 710
 711      <varlistentry>
 712        <term><literal>Debug::BuildDeps</literal></term>
 713        <listitem>
 714          <para>
 715            Describes the process of resolving build-dependencies in
 716            &apt-get;.
 717          </para>
 718        </listitem>
 719      </varlistentry>
 720
 721      <varlistentry>
 722        <term><literal>Debug::Hashes</literal></term>
 723        <listitem>
 724          <para>
 725            Output each cryptographic hash that is generated by the
 726            <literal>apt</literal> libraries.
 727          </para>
 728        </listitem>
 729      </varlistentry>
 730
 731      <varlistentry>
 732        <term><literal>Debug::IdentCDROM</literal></term>
 733        <listitem>
 734          <para>
 735            Do not include information from <literal>statfs</literal>,
 736            namely the number of used and free blocks on the CD-ROM
 737            filesystem, when generating an ID for a CD-ROM.
 738          </para>
 739        </listitem>
 740      </varlistentry>
 741
 742      <varlistentry>
 743        <term><literal>Debug::NoLocking</literal></term>
 744        <listitem>
 745          <para>
 746            Disable all file locking.  For instance, this will allow
 747            two instances of <quote><literal>apt-get
 748            update</literal></quote> to run at the same time.
 749          </para>
 750        </listitem>
 751      </varlistentry>
 752
 753      <varlistentry>
 754        <term><literal>Debug::pkgAcquire</literal></term>
 755
 756        <listitem>
 757          <para>
 758            Log when items are added to or removed from the global
 759            download queue.
 760          </para>
 761        </listitem>
 762      </varlistentry>
 763
 764      <varlistentry>
 765        <term><literal>Debug::pkgAcquire::Auth</literal></term>
 766        <listitem>
 767          <para>
 768            Output status messages and errors related to verifying
 769            checksums and cryptographic signatures of downloaded files.
 770          </para>
 771        </listitem>
 772      </varlistentry>
 773
 774      <varlistentry>
 775        <term><literal>Debug::pkgAcquire::Diffs</literal></term>
 776        <listitem>
 777          <para>
 778            Output information about downloading and applying package
 779            index list diffs, and errors relating to package index list
 780            diffs.
 781          </para>
 782        </listitem>
 783      </varlistentry>
 784
 785      <varlistentry>
 786        <term><literal>Debug::pkgAcquire::RRed</literal></term>
 787
 788        <listitem>
 789          <para>
 790            Output information related to patching apt package lists
 791            when downloading index diffs instead of full indices.
 792          </para>
 793        </listitem>
 794      </varlistentry>
 795
 796      <varlistentry>
 797        <term><literal>Debug::pkgAcquire::Worker</literal></term>
 798
 799        <listitem>
 800          <para>
 801            Log all interactions with the sub-processes that actually
 802            perform downloads.
 803          </para>
 804        </listitem>
 805      </varlistentry>
 806
 807      <varlistentry>
 808        <term><literal>Debug::pkgAutoRemove</literal></term>
 809
 810        <listitem>
 811          <para>
 812            Log events related to the automatically-installed status of
 813            packages and to the removal of unused packages.
 814          </para>
 815        </listitem>
 816      </varlistentry>
 817
 818      <varlistentry>
 819        <term><literal>Debug::pkgDepCache::AutoInstall</literal></term>
 820        <listitem>
 821          <para>
 822            Generate debug messages describing which packages are being
 823            automatically installed to resolve dependencies.  This
 824            corresponds to the initial auto-install pass performed in,
 825            e.g., <literal>apt-get install</literal>, and not to the
 826            full <literal>apt</literal> dependency resolver; see
 827            <literal>Debug::pkgProblemResolver</literal> for that.
 828          </para>
 829        </listitem>
 830      </varlistentry>
 831
 832      <varlistentry>
 833        <term><literal>Debug::pkgDepCache::Marker</literal></term>
 834        <listitem>
 835         <para>
 836            Generate debug messages describing which package is marked
 837           as keep/install/remove while the ProblemResolver does his work.
 838           Each addition or deletion may trigger additional actions;
 839           they are shown indented two additional space under the original entry.
 840           The format for each line is <literal>MarkKeep</literal>,
 841           <literal>MarkDelete</literal> or <literal>MarkInstall</literal> followed by
 842           <literal>package-name &lt;a.b.c -&gt; d.e.f | x.y.z&gt; (section)</literal>
 843           where <literal>a.b.c</literal> is the current version of the package,
 844           <literal>d.e.f</literal> is the version considered for installation and
 845           <literal>x.y.z</literal> is a newer version, but not considered for installation
 846           (because of a low pin score). The later two can be omitted if there is none or if
 847           it is the same version as the installed.
 848           <literal>section</literal> is the name of the section the package appears in.
 849         </para>
 850        </listitem>
 851      </varlistentry>
 852
 853      <!-- Question: why doesn't this do anything?  The code says it should. -->
 854      <varlistentry>
 855        <term><literal>Debug::pkgInitConfig</literal></term>
 856        <listitem>
 857          <para>
 858            Dump the default configuration to standard error on
 859            startup.
 860          </para>
 861        </listitem>
 862      </varlistentry>
 863
 864      <varlistentry>
 865        <term><literal>Debug::pkgDPkgPM</literal></term>
 866        <listitem>
 867          <para>
 868            When invoking &dpkg;, output the precise command line with
 869            which it is being invoked, with arguments separated by a
 870            single space character.
 871          </para>
 872        </listitem>
 873      </varlistentry>
 874
 875      <varlistentry>
 876        <term><literal>Debug::pkgDPkgProgressReporting</literal></term>
 877        <listitem>
 878          <para>
 879            Output all the data received from &dpkg; on the status file
 880            descriptor and any errors encountered while parsing it.
 881          </para>
 882        </listitem>
 883      </varlistentry>
 884
 885      <varlistentry>
 886        <term><literal>Debug::pkgOrderList</literal></term>
 887
 888        <listitem>
 889          <para>
 890            Generate a trace of the algorithm that decides the order in
 891            which <literal>apt</literal> should pass packages to
 892            &dpkg;.
 893          </para>
 894        </listitem>
 895      </varlistentry>
 896
 897      <varlistentry>
 898        <term><literal>Debug::pkgPackageManager</literal></term>
 899
 900        <listitem>
 901          <para>
 902            Output status messages tracing the steps performed when
 903            invoking &dpkg;.
 904          </para>
 905        </listitem>
 906      </varlistentry>
 907
 908      <varlistentry>
 909        <term><literal>Debug::pkgPolicy</literal></term>
 910
 911        <listitem>
 912          <para>
 913            Output the priority of each package list on startup.
 914          </para>
 915        </listitem>
 916      </varlistentry>
 917
 918      <varlistentry>
 919        <term><literal>Debug::pkgProblemResolver</literal></term>
 920
 921        <listitem>
 922          <para>
 923            Trace the execution of the dependency resolver (this
 924            applies only to what happens when a complex dependency
 925            problem is encountered).
 926          </para>
 927        </listitem>
 928      </varlistentry>
 929
 930      <varlistentry>
 931        <term><literal>Debug::pkgProblemResolver::ShowScores</literal></term>
 932        <listitem>
 933         <para>
 934           Display a list of all installed packages with their calculated score
 935           used by the pkgProblemResolver. The description of the package
 936           is the same as described in <literal>Debug::pkgDepCache::Marker</literal>
 937         </para>
 938        </listitem>
 939      </varlistentry>
 940
 941      <varlistentry>
 942        <term><literal>Debug::sourceList</literal></term>
 943
 944        <listitem>
 945          <para>
 946            Print information about the vendors read from
 947            <filename>/etc/apt/vendors.list</filename>.
 948          </para>
 949        </listitem>
 950      </varlistentry>
 951
 952 <!-- 2009/07/11 Currently used nowhere. The corresponding code
 953 is commented.
 954      <varlistentry>
 955        <term><literal>Debug::Vendor</literal></term>
 956
 957        <listitem>
 958          <para>
 959            Print information about each vendor.
 960          </para>
 961        </listitem>
 962      </varlistentry>
 963 -->
 964    </variablelist>
 965  </refsect1>
 966
 967  <refsect1><title>Examples</title>
 968    <para>&configureindex; is a
 969    configuration file showing example values for all possible
 970    options.</para>
 971  </refsect1>
 972
 973  <refsect1><title>Files</title>
 974    <variablelist>
 975       &file-aptconf;
 976    </variablelist>
 977  </refsect1>
 978
 979  <refsect1><title>See Also</title>
 980    <para>&apt-cache;, &apt-config;<!-- ? reading apt.conf -->, &apt-preferences;.</para>
 981  </refsect1>
 982
 983  &manbugs;
 984
 985 </refentry>
 986