You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

1360 lines
64 KiB

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