Merge branch 'debian/sid' into debian/experimental

[apt.git] / doc / apt.conf.5.xml

diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml
index 6a61acd2d4728948fbbc5f9759941771e0e71af4..0f98a6fe935b1b3250250705aa254d9ab38e2ab2 100644 (file)
--- a/doc/apt.conf.5.xml
+++ b/doc/apt.conf.5.xml
@@ -1,13 +1,9 @@
 <?xml version="1.0" encoding="utf-8" standalone="no"?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 <?xml version="1.0" encoding="utf-8" standalone="no"?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

-
-<!ENTITY % aptent SYSTEM "apt.ent">
-%aptent;
-
-<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent">
-%aptverbatiment;
-
+<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;

 ]>
 
 <refentry>
 ]>
 
 <refentry>


@@ -98,8 +94,7 @@ APT {
 DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
 </programlisting></informalexample>
 
 DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
 </programlisting></informalexample>
 

-   <para>In general the sample configuration file in 
-   <filename>&docdir;examples/apt.conf</filename> &configureindex;
+   <para>In general the sample configuration file &configureindex;

    is a good guide for how it should look.</para>
 
    <para>Case is not significant in names of configuration items, so in the
    is a good guide for how it should look.</para>
 
    <para>Case is not significant in names of configuration items, so in the


@@ -176,6 +171,15 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      </para></listitem>
      </varlistentry>
 
      </para></listitem>
      </varlistentry>
 

+     <varlistentry><term><option>Build-Profiles</option></term>
+     <listitem><para>
+     List of all build profiles enabled for build-dependency resolution,
+     without the "<literal>profile.</literal>" namespace prefix.
+     By default this list is empty. The <envar>DEB_BUILD_PROFILES</envar>
+     as used by &dpkg-buildpackage; overrides the list notation.
+     </para></listitem>
+     </varlistentry>
+

      <varlistentry><term><option>Default-Release</option></term>
      <listitem><para>Default release to install packages from if more than one
      version is available. Contains release name, codename or release version. Examples: 'stable', 'testing',
      <varlistentry><term><option>Default-Release</option></term>
      <listitem><para>Default release to install packages from if more than one
      version is available. Contains release name, codename or release version. Examples: 'stable', 'testing',


@@ -380,21 +384,37 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      <para>The setting <literal>Acquire::http::Pipeline-Depth</literal> can be used to
      enable HTTP pipelining (RFC 2616 section 8.1.2.2) which can be beneficial e.g. on
      high-latency connections. It specifies how many requests are sent in a pipeline.
      <para>The setting <literal>Acquire::http::Pipeline-Depth</literal> can be used to
      enable HTTP pipelining (RFC 2616 section 8.1.2.2) which can be beneficial e.g. on
      high-latency connections. It specifies how many requests are sent in a pipeline.

-     Previous APT versions had a default of 10 for this setting, but the default value
-     is now 0 (= disabled) to avoid problems with the ever-growing amount of webservers
-     and proxies which choose to not conform to the HTTP/1.1 specification.</para>
+     APT tries to detect and workaround misbehaving webservers and proxies at runtime, but
+     if you know that yours does not conform to the HTTP/1.1 specification pipelining can
+     be disabled by setting the value to 0. It is enabled by default with the value 10.</para>

 
      <para><literal>Acquire::http::AllowRedirect</literal> controls whether APT will follow
      redirects, which is enabled by default.</para>
 
 
      <para><literal>Acquire::http::AllowRedirect</literal> controls whether APT will follow
      redirects, which is enabled by default.</para>
 

-     <para>The used bandwidth can be limited with <literal>Acquire::http::Dl-Limit</literal>
-     which accepts integer values in kilobytes. The default value is 0 which deactivates
-     the limit and tries to use all available bandwidth (note that this option implicitly
-     disables downloading from multiple servers at the same time.)</para>
+     <para>The used bandwidth can be limited with
+     <literal>Acquire::http::Dl-Limit</literal> which accepts integer
+     values in kilobytes per second. The default value is 0 which
+     deactivates the limit and tries to use all available bandwidth.
+     Note that this option implicitly disables downloading from
+     multiple servers at the same time.</para>

 
      <para><literal>Acquire::http::User-Agent</literal> can be used to set a different
      User-Agent for the http download method as some proxies allow access for clients
      only if the client uses a known identifier.</para>
 
      <para><literal>Acquire::http::User-Agent</literal> can be used to set a different
      User-Agent for the http download method as some proxies allow access for clients
      only if the client uses a known identifier.</para>

+
+     <para><literal>Acquire::http::Proxy-Auto-Detect</literal> can be used to
+     specify an external command to discover the http proxy to use. Apt expects
+     the command to output the proxy on stdout in the style
+     <literal>http://proxy:port/</literal>. This will override the
+     generic <literal>Acquire::http::Proxy</literal> but not any specific
+     host proxy configuration set via 
+     <literal>Acquire::http::Proxy::$HOST</literal>.
+
+     See the &squid-deb-proxy-client; package for an example implementation that
+     uses avahi. This option takes precedence over the legacy option name 
+     <literal>ProxyAutoDetect</literal>.
+     </para>
+

      </listitem>
      </varlistentry>
 
      </listitem>
      </varlistentry>
 


@@ -554,6 +574,18 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      </listitem>
      </varlistentry>
 
      </listitem>
      </varlistentry>
 

+     <varlistentry><term><option>ForceIPv4</option></term>
+        <listitem><para>
+         When downloading, force to use only the IPv4 protocol.
+        </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>ForceIPv6</option></term>
+        <listitem><para>
+         When downloading, force to use only the IPv6 protocol.
+        </para></listitem>
+     </varlistentry>
+

    </variablelist>
  </refsect1>
 
    </variablelist>
  </refsect1>
 


@@ -570,10 +602,11 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
    information, such as the two package caches <literal>srcpkgcache</literal> and 
    <literal>pkgcache</literal> as well as the location to place downloaded archives, 
    <literal>Dir::Cache::archives</literal>. Generation of caches can be turned off
    information, such as the two package caches <literal>srcpkgcache</literal> and 
    <literal>pkgcache</literal> as well as the location to place downloaded archives, 
    <literal>Dir::Cache::archives</literal>. Generation of caches can be turned off

-   by setting their names to the empty string. This will slow down startup but
-   save disk space. It is probably preferable to turn off the pkgcache rather
-   than the srcpkgcache. Like <literal>Dir::State</literal> the default
-   directory is contained in <literal>Dir::Cache</literal></para>
+   by setting <literal>pkgcache</literal> or <literal>srcpkgcache</literal> to
+   <literal>""</literal>.  This will slow down startup but save disk space. It
+   is probably preferable to turn off the pkgcache rather than the srcpkgcache.
+   Like <literal>Dir::State</literal> the default directory is contained in
+   <literal>Dir::Cache</literal></para>

 
    <para><literal>Dir::Etc</literal> contains the location of configuration files, 
    <literal>sourcelist</literal> gives the location of the sourcelist and 
 
    <para><literal>Dir::Etc</literal> contains the location of configuration files, 
    <literal>sourcelist</literal> gives the location of the sourcelist and 


@@ -675,13 +708,28 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      <literal>options</literal> this must be specified in list notation. The commands
      are invoked in order using <filename>/bin/sh</filename>; should any fail APT 
      will abort. APT will pass the filenames of all .deb files it is going to
      <literal>options</literal> this must be specified in list notation. The commands
      are invoked in order using <filename>/bin/sh</filename>; should any fail APT 
      will abort. APT will pass the filenames of all .deb files it is going to

-     install to the commands, one per line on standard input.</para>
+     install to the commands, one per line on the requested file descriptor, defaulting
+     to standard input.</para>

 
 

-     <para>Version 2 of this protocol dumps more information, including the 
+     <para>Version 2 of this protocol dumps more information, including the

      protocol version, the APT configuration space and the packages, files
      protocol version, the APT configuration space and the packages, files

-     and versions being changed. Version 2 is enabled by setting 
-     <literal>DPkg::Tools::options::cmd::Version</literal> to 2. <literal>cmd</literal> is a
-     command given to <literal>Pre-Install-Pkgs</literal>.</para></listitem>
+     and versions being changed. Version 3 adds the architecture and <literal>MultiArch</literal>
+     flag to each version being dumped.</para>
+
+     <para>The version of the protocol to be used for the command
+     <literal><replaceable>cmd</replaceable></literal> can be chosen by setting
+     <literal>DPkg::Tools::options::<replaceable>cmd</replaceable>::Version</literal>
+     accordingly, the default being version 1. If APT isn't supporting the requested
+     version it will send the information in the highest version it has support for instead.
+     </para>
+
+     <para>The file descriptor to be used to send the information can be requested with
+     <literal>DPkg::Tools::options::<replaceable>cmd</replaceable>::InfoFD</literal>
+     which defaults to <literal>0</literal> for standard input and is available since
+     version 0.9.11. Support for the option can be detected by looking for the environment
+     variable <envar>APT_HOOK_INFO_FD</envar> which contains the number of the used
+     file descriptor as a confirmation.</para>
+     </listitem>

      </varlistentry>
 
      <varlistentry><term><option>Run-Directory</option></term>
      </varlistentry>
 
      <varlistentry><term><option>Run-Directory</option></term>


@@ -1131,6 +1179,18 @@ DPkg::TriggersPending "true";</literallayout></para>
        </listitem>
      </varlistentry>
 
        </listitem>
      </varlistentry>
 

+     <varlistentry>
+       <term><option>Debug::RunScripts</option></term>
+       <listitem>
+        <para>
+          Display the external commands that are called by apt hooks.
+          This includes e.g. the config options
+          <literal>DPkg::{Pre,Post}-Invoke</literal> or
+          <literal>APT::Update::{Pre,Post}-Invoke</literal>.
+        </para>
+       </listitem>
+     </varlistentry>
+

 <!-- 2009/07/11 Currently used nowhere. The corresponding code
 is commented.
      <varlistentry>
 <!-- 2009/07/11 Currently used nowhere. The corresponding code
 is commented.
      <varlistentry>