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