enforce a slightly more sensible default header

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

diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml
index 78f6a27a26823efe5d2f0447e126cb5b3b8fa509..2bb81425717c2c3fdcb709a5d98f90fa908d1b49 100644 (file)
--- a/doc/apt.conf.5.xml
+++ b/doc/apt.conf.5.xml
@@ -1,15 +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 % aptvendor SYSTEM "apt-vendor.ent">
-%aptvendor;
+<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;

 ]>
 
 <refentry>
 ]>
 
 <refentry>


@@ -60,6 +54,8 @@
         configuration list - in which case it will be silently ignored.</para></listitem>
       <listitem><para>the main configuration file specified by
         <literal>Dir::Etc::main</literal></para></listitem>
         configuration list - in which case it will be silently ignored.</para></listitem>
       <listitem><para>the main configuration file specified by
         <literal>Dir::Etc::main</literal></para></listitem>

+      <listitem><para>all options set in the binary specific configuration
+           subtree are moved into the root of the tree.</para></listitem>

       <listitem><para>the command line options are applied to override the
         configuration directives or to load even more configuration files.</para></listitem>
    </orderedlist>
       <listitem><para>the command line options are applied to override the
         configuration directives or to load even more configuration files.</para></listitem>
    </orderedlist>


@@ -307,6 +303,8 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      <literal>Valid-Until</literal> header, but if they don't or a
      stricter value is desired the <literal>Max-ValidTime</literal>
      option below can be used.
      <literal>Valid-Until</literal> header, but if they don't or a
      stricter value is desired the <literal>Max-ValidTime</literal>
      option below can be used.

+     The <option>Check-Valid-Until</option> option of &sources-list; entries should be
+     preferred to disable the check selectively instead of using this global override.

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


@@ -318,7 +316,8 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
         the earlier date of the two is used as the expiration date.
         The default value is <literal>0</literal> which stands for "valid forever".
         Archive specific settings can be made by appending the label of the archive
         the earlier date of the two is used as the expiration date.
         The default value is <literal>0</literal> which stands for "valid forever".
         Archive specific settings can be made by appending the label of the archive

-        to the option name.
+        to the option name. Preferably, the same can be achieved for specific
+        &sources-list; entries by using the <option>Valid-Until-Max</option> option there.

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


@@ -330,14 +329,17 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
         frequently updated archive with a <literal>Valid-Until</literal> header
         instead of completely disabling the expiration date checking.
         Archive specific settings can and should be used by appending the label of
         frequently updated archive with a <literal>Valid-Until</literal> header
         instead of completely disabling the expiration date checking.
         Archive specific settings can and should be used by appending the label of

-        the archive to the option name.
+        the archive to the option name. Preferably, the same can be achieved for specific
+        &sources-list; entries by using the <option>Valid-Until-Min</option> option there.

         </para></listitem>
      </varlistentry>
 
      <varlistentry><term><option>PDiffs</option></term>
         <listitem><para>Try to download deltas called <literal>PDiffs</literal> for
         </para></listitem>
      </varlistentry>
 
      <varlistentry><term><option>PDiffs</option></term>
         <listitem><para>Try to download deltas called <literal>PDiffs</literal> for

-        indexes (like <filename>Packages</filename> files) instead of downloading
-        whole ones. True by default.</para>
+        indexes (like <filename>Packages</filename> files) instead of
+        downloading whole ones. True by default. Preferably, this can be set
+        for specific &sources-list; entries or index files by using the
+        <option>PDiffs</option> option there.</para>

         <para>Two sub-options to limit the use of PDiffs are also available:
         <literal>FileLimit</literal> can be used to specify a maximum number of
         PDiff files should be downloaded to update a file. <literal>SizeLimit</literal>
         <para>Two sub-options to limit the use of PDiffs are also available:
         <literal>FileLimit</literal> can be used to specify a maximum number of
         PDiff files should be downloaded to update a file. <literal>SizeLimit</literal>


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

+     <varlistentry><term><option>By-Hash</option></term>
+        <listitem><para>Try to download indexes via an URI constructed from a
+        hashsum of the expected file rather than downloaded via a well-known
+        stable filename. True by default, but automatically disabled if the
+        source indicates no support for it. Usage can be forced with the special
+        value "force". Preferably, this can be set for specific &sources-list; entries
+        or index files by using the <option>By-Hash</option> option there.
+        </para></listitem>
+     </varlistentry>
+

      <varlistentry><term><option>Queue-Mode</option></term>
      <listitem><para>Queuing mode; <literal>Queue-Mode</literal> can be one of <literal>host</literal> or 
      <literal>access</literal> which determines how  APT parallelizes outgoing 
      <varlistentry><term><option>Queue-Mode</option></term>
      <listitem><para>Queuing mode; <literal>Queue-Mode</literal> can be one of <literal>host</literal> or 
      <literal>access</literal> which determines how  APT parallelizes outgoing 


@@ -390,9 +402,9 @@ 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>


@@ -592,9 +604,95 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
         </para></listitem>
      </varlistentry>
 
         </para></listitem>
      </varlistentry>
 

+     <varlistentry><term><option>MaxReleaseFileSize</option></term>
+        <listitem><para>
+           The maximum file size of Release/Release.gpg/InRelease files.
+           The default is 10MB.
+        </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>EnableSrvRecords</option></term>
+        <listitem><para>
+           This option controls if apt will use the DNS SRV server record
+           as specified in RFC 2782 to select an alternative server to
+           connect to.
+           The default is "true".
+        </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>AllowInsecureRepositories</option></term>
+        <listitem><para>
+           Allow the update operation to load data files from
+           a repository without a trusted signature. If enabled this
+           option no data files will be loaded and the update
+           operation fails with a error for this source. The default
+           is false for backward compatibility. This will be changed
+           in the future.
+        </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>AllowDowngradeToInsecureRepositories</option></term>
+        <listitem><para>
+           Allow that a repository that was previously gpg signed to become
+           unsigned durign a update operation. When there is no valid signature
+           of a perviously trusted repository apt will refuse the update. This
+           option can be used to override this protection. You almost certainly
+           never want to enable this. The default is false.
+
+           Note that apt will still consider packages from this source
+           untrusted and warn about them if you try to install
+           them.
+         </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>Changelogs::URI</option> scope</term>
+       <listitem><para>
+         Acquiring changelogs can only be done if an URI is known from where to get them.
+         Preferable the Release file indicates this in a 'Changelogs' field. If this isn't
+         available the Label/Origin field of the Release file is used to check if a
+         <literal>Acquire::Changelogs::URI::Label::<replaceable>LABEL</replaceable></literal> or
+         <literal>Acquire::Changelogs::URI::Origin::<replaceable>ORIGIN</replaceable></literal> option
+         exists and if so this value is taken. The value in the Release file can be overridden
+         with <literal>Acquire::Changelogs::URI::Override::Label::<replaceable>LABEL</replaceable></literal>
+         or <literal>Acquire::Changelogs::URI::Override::Origin::<replaceable>ORIGIN</replaceable></literal>.
+
+         The value should be a normal URI to a text file, expect that package specific data is
+         replaced with the placeholder <literal>CHANGEPATH</literal>. The
+         value for it is: 1. if the package is from a component (e.g. <literal>main</literal>)
+         this is the first part otherwise it is omitted, 2. the first letter of source package name,
+         expect if the source package name starts with '<literal>lib</literal>' in which case it will
+         be the first four letters. 3. The complete source package name. 4. the complete name again and
+         5. the source version.
+         The first (if present), second, third and fourth part are separated by a slash ('<literal>/</literal>')
+         and between the fourth and fifth part is an underscore ('<literal>_</literal>').
+
+         The special value '<literal>no</literal>' is available for this option indicating that
+         this source can't be used to acquire changelog files from. Another source will be tried
+         if available in this case.
+       </para></listitem>
+    </varlistentry>
+

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

+ <refsect1><title>Binary specific configuration</title>
+    <para>Especially with the introduction of the <command>apt</command> binary
+       it can be useful to set certain options only for a specific binary as
+       even options which look like they would effect only a certain binary like
+       <option>APT::Get::Show-Versions</option> effect
+       <command>apt-get</command> as well as <command>apt</command>.
+    </para>
+    <para>Setting an option for a specific binary only can be achieved by
+       setting the option inside the
+       <option>Binary::<replaceable>specific-binary</replaceable></option>
+       scope. Setting the option <option>APT::Get::Show-Versions</option> for
+       the <command>apt</command> only can e.g. by done by setting
+       <option>Binary::apt::APT::Get::Show-Versions</option> instead.</para>
+    <para>Note that as seen in the DESCRIPTION section further above you can't
+       set binary-specific options on the commandline itself nor in
+       configuration files loaded via the commandline.</para>
+ </refsect1>
+

  <refsect1><title>Directories</title>
 
    <para>The <literal>Dir::State</literal> section has directories that pertain to local 
  <refsect1><title>Directories</title>
 
    <para>The <literal>Dir::State</literal> section has directories that pertain to local 


@@ -608,10 +706,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 


@@ -632,7 +731,7 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
 
    <para>
      The configuration item <literal>RootDir</literal> has a special
 
    <para>
      The configuration item <literal>RootDir</literal> has a special

-     meaning.  If set, all paths in <literal>Dir::</literal> will be
+     meaning.  If set, all paths will be

      relative to <literal>RootDir</literal>, <emphasis>even paths that
      are specified absolutely</emphasis>.  So, for instance, if
      <literal>RootDir</literal> is set to
      relative to <literal>RootDir</literal>, <emphasis>even paths that
      are specified absolutely</emphasis>.  So, for instance, if
      <literal>RootDir</literal> is set to


@@ -641,6 +740,7 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      <filename>/var/lib/dpkg/status</filename>, then the status file
      will be looked up in
      <filename>/tmp/staging/var/lib/dpkg/status</filename>.
      <filename>/var/lib/dpkg/status</filename>, then the status file
      will be looked up in
      <filename>/tmp/staging/var/lib/dpkg/status</filename>.

+     If you want to prefix only relative paths, set <literal>Dir</literal> instead.

    </para>
 
    <para>
    </para>
 
    <para>


@@ -716,10 +816,34 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      install to the commands, one per line on the requested file descriptor, defaulting
      to 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
-     protocol version, the APT configuration space and the packages, files
-     and versions being changed. Version 3 adds the architecture and <literal>MultiArch</literal>
-     flag to each version being dumped.</para>
+     <para>Version 2 of this protocol sends more information through the requested
+     file descriptor: a line with the text <literal>VERSION 2</literal>,
+     the APT configuration space, and a list of package actions with filename
+     and version information.</para>
+
+     <para>Each configuration directive line has the form
+     <literal>key=value</literal>.  Special characters (equal signs, newlines,
+     nonprintable characters, quotation marks, and percent signs in
+     <literal>key</literal> and newlines, nonprintable characters, and percent
+     signs in <literal>value</literal>) are %-encoded. Lists are represented
+     by multiple <literal>key::=value</literal> lines with the same key. The
+     configuration section ends with a blank line.</para>
+
+     <para>Package action lines consist of five fields in Version 2: old version, direction
+     of version change (&lt; for upgrades, &gt; for downgrades, = for no
+     change), new version, action. The version fields are "-" for no version
+     at all (for example when installing a package for the first time; no
+     version is treated as earlier than any real version, so that is an
+     upgrade, indicated as <literal>- &lt; 1.23.4</literal>). The action field
+     is "**CONFIGURE**" if the package is being configured, "**REMOVE**" if it
+     is being removed, or the filename of a .deb file if it is being
+     unpacked.</para>
+
+     <para>In Version 3 after each version field follows the architecture
+     of this version, which is "-" if there is no version, and a field showing
+     the MultiArch type "same", foreign", "allowed" or "none". Note that "none"
+     is an incorrect typename which is just kept to remain compatible, it
+     should be read as "no" and users are encouraged to support both.</para>

 
      <para>The version of the protocol to be used for the command
      <literal><replaceable>cmd</replaceable></literal> can be chosen by setting
 
      <para>The version of the protocol to be used for the command
      <literal><replaceable>cmd</replaceable></literal> can be chosen by setting


@@ -1184,6 +1308,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>