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.
 
 
 
 
 
 

1339 lines
63 KiB

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