* apt-pkg/contrib/fileutl.cc:

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

diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml
index e568baa35655efd30a1a468818ae62efdaa99841..0cf4bb663d639d17f658b758522736d10ec4e84b 100644 (file)
--- a/doc/apt.conf.5.xml
+++ b/doc/apt.conf.5.xml
@@ -21,7 +21,7 @@
    &apt-email;
    &apt-product;
    <!-- The last update date -->
-   <date>18 September 2009</date>
+   <date>16 January 2010</date>
  </refentryinfo>
  
  <refmeta>
@@ -37,16 +37,27 @@
  </refnamediv>
  
  <refsect1><title>Description</title>
-   <para><filename>apt.conf</filename> is the main configuration file for the APT suite of
-   tools, all tools make use of the configuration file and a common command line
-   parser to provide a uniform environment. When an APT tool starts up it will
-   read the configuration specified by the <envar>APT_CONFIG</envar> environment 
-   variable (if any) and then read the files in <literal>Dir::Etc::Parts</literal> 
-   then read the main configuration file specified by 
-   <literal>Dir::Etc::main</literal> then finally apply the
-   command line options to override the configuration directives, possibly 
-   loading even more config files.</para>
-
+ <para><filename>apt.conf</filename> is the main configuration file for
+   the APT suite of tools, but by far not the only place changes to options
+   can be made. All tools therefore share the configuration files and also
+   use a common command line parser to provide a uniform environment.</para>
+   <orderedlist>
+      <para>When an APT tool starts up it will read the configuration files
+      in the following order:</para>
+      <listitem><para>the file specified by the <envar>APT_CONFIG</envar>
+        environment variable (if any)</para></listitem>
+      <listitem><para>all files in <literal>Dir::Etc::Parts</literal> in
+        alphanumeric ascending order which have no or "<literal>conf</literal>"
+        as filename extension and which only contain alphanumeric,
+        hyphen (-), underscore (_) and period (.) characters -
+        otherwise they will be silently ignored.</para></listitem>
+      <listitem><para>the main configuration file specified by
+        <literal>Dir::Etc::main</literal></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>
+   </refsect1>
+   <refsect1><title>Syntax</title>
    <para>The configuration file is organized in a tree with options organized into
    functional groups. Option specification is given with a double colon
    notation, for instance <literal>APT::Get::Assume-Yes</literal> is an option within 
@@ -139,8 +150,9 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      </varlistentry>
      
      <varlistentry><term>Default-Release</term>
-        <listitem><para>Default release to install packages from if more than one
-        version available. Contains release name, codename or release version. Examples: 'stable', 'testing', 'unstable', 'lenny', 'squeeze', '4.0', '5.0*'. See also &apt-preferences;.</para></listitem>
+     <listitem><para>Default release to install packages from if more than one
+     version available. Contains release name, codename or release version. Examples: 'stable', 'testing',
+     'unstable', '&stable-codename;', '&testing-codename;', '4.0', '5.0*'. See also &apt-preferences;.</para></listitem>
      </varlistentry>
 
      <varlistentry><term>Ignore-Hold</term>
@@ -218,6 +230,30 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
    and the URI handlers. 
 
    <variablelist>
+     <varlistentry><term>Check-Valid-Until</term>
+        <listitem><para>Security related option defaulting to true as an
+        expiring validation for a Release file prevents longtime replay attacks
+        and can e.g. also help users to identify no longer updated mirrors -
+        but the feature depends on the correctness of the time on the user system.
+        Archive maintainers are encouraged to create Release files with the
+        <literal>Valid-Until</literal> header, but if they don't or a stricter value
+        is volitional the following <literal>Max-ValidTime</literal> option can be used.
+        </para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>Max-ValidTime</term>
+        <listitem><para>Seconds the Release file should be considered valid after
+        it was created. The default is "for ever" (0) if the Release file of the
+        archive doesn't include a <literal>Valid-Until</literal> header.
+        If it does then this date is the default. The date from the Release file or
+        the date specified by the creation time of the Release file
+        (<literal>Date</literal> header) plus the seconds specified with this
+        options are used to check if the validation of a file has expired by using
+        the earlier date of the two. Archive specific settings can be made by
+        appending the label of the archive to the option name.
+        </para></listitem>
+     </varlistentry>
+
      <varlistentry><term>PDiffs</term>
         <listitem><para>Try to download deltas called <literal>PDiffs</literal> for
         Packages or Sources files instead of downloading whole ones. True