<refentryinfo>
&apt-author.jgunthorpe;
&apt-author.team;
+ <author>
+ <firstname>Daniel</firstname>
+ <surname>Burrows</surname>
+ <contrib>Initial documentation of Debug::*.</contrib>
+ <email>dburrows@debian.org</email>
+ </author>
&apt-email;
&apt-product;
<!-- The last update date -->
- <date>29 February 2004</date>
+ <date>10 December 2008</date>
</refentryinfo>
<refmeta>
parent groups.</para>
<para>Syntactically the configuration language is modeled after what the ISC tools
- such as bind and dhcp use. Lines starting with
- <literal>//</literal> are treated as comments (ignored).
+ such as bind and dhcp use. Lines starting with
+ <literal>//</literal> are treated as comments (ignored), as well as all text
+ between <literal>/*</literal> and <literal>*/</literal>, just like C/C++ comments.
Each line is of the form
<literal>APT::Get::Assume-Yes "true";</literal> The trailing
semicolon is required and the quotes are optional. A new scope can be
</programlisting></informalexample>
<para>with newlines placed to make it more readable. Lists can be created by
- opening a scope and including a single word enclosed in quotes followed by a
+ opening a scope and including a single string enclosed in quotes followed by a
semicolon. Multiple entries can be included, each separated by a semicolon.</para>
<informalexample><programlisting>
<filename>&docdir;examples/apt.conf</filename> &configureindex;
is a good guide for how it should look.</para>
+ <para>The names of the configuration items are not case-sensitive. So in the previous example
+ you could use <literal>dpkg::pre-install-pkgs</literal>.</para>
+
<para>Two specials are allowed, <literal>#include</literal> and <literal>#clear</literal>
<literal>#include</literal> will include the given file, unless the filename
ends in a slash, then the whole directory is included.
- <literal>#clear</literal> is used to erase a list of names.</para>
+ <literal>#clear</literal> is used to erase a part of the configuration tree. The
+ specified element and all its descendents are erased.</para>
<para>All of the APT tools take a -o option which allows an arbitrary configuration
directive to be specified on the command line. The syntax is a full option
compiled for.</para></listitem>
</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>
+ </varlistentry>
+
<varlistentry><term>Ignore-Hold</term>
<listitem><para>Ignore Held packages; This global option causes the problem resolver to
ignore held packages in its decision making.</para></listitem>
and the URI handlers.
<variablelist>
+ <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
+ by default.</para></listitem>
+ </varlistentry>
+
<varlistentry><term>Queue-Mode</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
standard form of <literal>http://[[user][:pass]@]host[:port]/</literal>. Per
host proxies can also be specified by using the form
<literal>http::Proxy::<host></literal> with the special keyword <literal>DIRECT</literal>
- meaning to use no proxies. The <envar>http_proxy</envar> environment variable
- will override all settings.</para>
+ meaning to use no proxies. If no one of the above settings is specified,
+ <envar>http_proxy</envar> environment variable
+ will be used.</para>
<para>Three settings are provided for cache control with HTTP/1.1 compliant
proxy caches. <literal>No-Cache</literal> tells the proxy to not use its cached
require this are in violation of RFC 2068.</para></listitem>
</varlistentry>
+ <varlistentry><term>https</term>
+ <listitem><para>HTTPS URIs. Cache-control and proxy options are the same as for
+ <literal>http</literal> method.
+ <literal>Pipeline-Depth</literal> option is not supported yet.</para>
+
+ <para><literal>CaInfo</literal> suboption specifies place of file that
+ holds info about trusted certificates.
+ <literal><host>::CaInfo</literal> is corresponding per-host option.
+ <literal>Verify-Peer</literal> boolean suboption determines whether verify
+ server's host certificate against trusted certificates or not.
+ <literal><host>::Verify-Peer</literal> is corresponding per-host option.
+ <literal>Verify-Host</literal> boolean suboption determines whether verify
+ server's hostname or not.
+ <literal><host>::Verify-Host</literal> is corresponding per-host option.
+ <literal>SslCert</literal> determines what certificate to use for client
+ authentication. <literal><host>::SslCert</literal> is corresponding per-host option.
+ <literal>SslKey</literal> determines what private key to use for client
+ authentication. <literal><host>::SslKey</literal> is corresponding per-host option.
+ <literal>SslForceVersion</literal> overrides default SSL version to use.
+ Can contain 'TLSv1' or 'SSLv3' string.
+ <literal><host>::SslForceVersion</literal> is corresponding per-host option.
+ </para></listitem></varlistentry>
+
<varlistentry><term>ftp</term>
- <listitem><para>FTP URIs; ftp::Proxy is the default proxy server to use. It is in the
- standard form of <literal>ftp://[[user][:pass]@]host[:port]/</literal> and is
- overridden by the <envar>ftp_proxy</envar> environment variable. To use a ftp
+ <listitem><para>FTP URIs; ftp::Proxy is the default ftp proxy to use. It is in the
+ standard form of <literal>ftp://[[user][:pass]@]host[:port]/</literal>. Per
+ host proxies can also be specified by using the form
+ <literal>ftp::Proxy::<host></literal> with the special keyword <literal>DIRECT</literal>
+ meaning to use no proxies. If no one of the above settings is specified,
+ <envar>ftp_proxy</envar> environment variable
+ will be used. To use a ftp
proxy you will have to set the <literal>ftp::ProxyLogin</literal> script in the
configuration file. This entry specifies the commands to send to tell
the proxy server what to connect to. Please see
</para></listitem>
</varlistentry>
+ <varlistentry><term>CompressionTypes</term>
+ <listitem><para>List of compression types which are understood by the acquire methods.
+ Files like <filename>Packages</filename> can be available in various compression formats.
+ This list defines in which order the acquire methods will try to download these files.
+ Per default <command>bzip2</command> compressed files will be prefered over
+ <command>lzma</command>, <command>gzip</command> and uncompressed files. The syntax for
+ the configuration fileentry is
+ <synopsis>Acquire::CompressionTypes::<replaceable>FileExtension</replaceable> "<replaceable>Methodname</replaceable>";</synopsis>
+ e.g. <synopsis>Acquire::CompressionTypes::bz2 "bzip2";</synopsis>
+ Note that at runtime the <literal>Dir::Bin::<replaceable>Methodname</replaceable></literal> will
+ be checked: If this setting exists the method will only be used if this file exists, e.g. for
+ the bzip2 method above (the inbuilt) setting is <literallayout>Dir::Bin::bzip2 "/bin/bzip2";</literallayout>
+ </para></listitem>
+ </varlistentry>
</variablelist>
</para>
</refsect1>
<para>Binary programs are pointed to by <literal>Dir::Bin</literal>. <literal>Dir::Bin::Methods</literal>
specifies the location of the method handlers and <literal>gzip</literal>,
+ <literal>bzip2</literal>, <literal>lzma</literal>,
<literal>dpkg</literal>, <literal>apt-get</literal> <literal>dpkg-source</literal>
<literal>dpkg-buildpackage</literal> and <literal>apt-cache</literal> specify the location
of the respective programs.</para>
</variablelist>
</refsect1>
- <refsect1><title>Debug options</title>
- <para>Most of the options in the <literal>debug</literal> section are not interesting to
- the normal user, however <literal>Debug::pkgProblemResolver</literal> shows
- interesting output about the decisions dist-upgrade makes.
- <literal>Debug::NoLocking</literal> disables file locking so APT can do some
- operations as non-root and <literal>Debug::pkgDPkgPM</literal> will print out the
- command line for each dpkg invokation. <literal>Debug::IdentCdrom</literal> will
- disable the inclusion of statfs data in CDROM IDs.
- <literal>Debug::Acquire::gpgv</literal> Debugging of the gpgv method.
+ <refsect1>
+ <title>Periodic and Archives options</title>
+ <para><literal>APT::Periodic</literal> and <literal>APT::Archives</literal>
+ groups of options configure behavior of apt periodic updates, which is
+ done by <literal>/etc/cron.daily/apt</literal> script. See header of
+ this script for the brief documentation of these options.
</para>
</refsect1>
+
+ <refsect1>
+ <title>Debug options</title>
+ <para>
+ Enabling options in the <literal>Debug::</literal> section will
+ cause debugging information to be sent to the standard error
+ stream of the program utilizing the <literal>apt</literal>
+ libraries, or enable special program modes that are primarily
+ useful for debugging the behavior of <literal>apt</literal>.
+ Most of these options are not interesting to a normal user, but a
+ few may be:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>Debug::pkgProblemResolver</literal> enables output
+ about the decisions made by
+ <literal>dist-upgrade, upgrade, install, remove, purge</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>Debug::NoLocking</literal> disables all file
+ locking. This can be used to run some operations (for
+ instance, <literal>apt-get -s install</literal>) as a
+ non-root user.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>Debug::pkgDPkgPM</literal> prints out the actual
+ command line each time that <literal>apt</literal> invokes
+ &dpkg;.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>Debug::IdentCdrom</literal> disables the inclusion
+ of statfs data in CDROM IDs. <!-- TODO: provide a
+ motivating example, except I haven't a clue why you'd want
+ to do this. -->
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ A full list of debugging options to apt follows.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>Debug::Acquire::cdrom</literal></term>
+
+ <listitem>
+ <para>
+ Print information related to accessing
+ <literal>cdrom://</literal> sources.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::Acquire::ftp</literal></term>
+
+ <listitem>
+ <para>
+ Print information related to downloading packages using
+ FTP.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::Acquire::http</literal></term>
+
+ <listitem>
+ <para>
+ Print information related to downloading packages using
+ HTTP.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::Acquire::https</literal></term>
+
+ <listitem>
+ <para>
+ Print information related to downloading packages using
+ HTTPS.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::Acquire::gpgv</literal></term>
+
+ <listitem>
+ <para>
+ Print information related to verifying cryptographic
+ signatures using <literal>gpg</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::aptcdrom</literal></term>
+
+ <listitem>
+ <para>
+ Output information about the process of accessing
+ collections of packages stored on CD-ROMs.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::BuildDeps</literal></term>
+ <listitem>
+ <para>
+ Describes the process of resolving build-dependencies in
+ &apt-get;.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::Hashes</literal></term>
+ <listitem>
+ <para>
+ Output each cryptographic hash that is generated by the
+ <literal>apt</literal> libraries.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::IdentCDROM</literal></term>
+ <listitem>
+ <para>
+ Do not include information from <literal>statfs</literal>,
+ namely the number of used and free blocks on the CD-ROM
+ filesystem, when generating an ID for a CD-ROM.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::NoLocking</literal></term>
+ <listitem>
+ <para>
+ Disable all file locking. For instance, this will allow
+ two instances of <quote><literal>apt-get
+ update</literal></quote> to run at the same time.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgAcquire</literal></term>
+
+ <listitem>
+ <para>
+ Log when items are added to or removed from the global
+ download queue.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgAcquire::Auth</literal></term>
+ <listitem>
+ <para>
+ Output status messages and errors related to verifying
+ checksums and cryptographic signatures of downloaded files.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgAcquire::Diffs</literal></term>
+ <listitem>
+ <para>
+ Output information about downloading and applying package
+ index list diffs, and errors relating to package index list
+ diffs.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgAcquire::RRed</literal></term>
+
+ <listitem>
+ <para>
+ Output information related to patching apt package lists
+ when downloading index diffs instead of full indices.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgAcquire::Worker</literal></term>
+
+ <listitem>
+ <para>
+ Log all interactions with the sub-processes that actually
+ perform downloads.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgAutoRemove</literal></term>
+
+ <listitem>
+ <para>
+ Log events related to the automatically-installed status of
+ packages and to the removal of unused packages.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgDepCache::AutoInstall</literal></term>
+ <listitem>
+ <para>
+ Generate debug messages describing which packages are being
+ automatically installed to resolve dependencies. This
+ corresponds to the initial auto-install pass performed in,
+ e.g., <literal>apt-get install</literal>, and not to the
+ full <literal>apt</literal> dependency resolver; see
+ <literal>Debug::pkgProblemResolver</literal> for that.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgDepCache::Marker</literal></term>
+ <listitem>
+ <para>
+ Generate debug messages describing which package is marked
+ as keep/install/remove while the ProblemResolver does his work.
+ Each addition or deletion may trigger additional actions;
+ they are shown indented two additional space under the original entry.
+ The format for each line is <literal>MarkKeep</literal>,
+ <literal>MarkDelete</literal> or <literal>MarkInstall</literal> followed by
+ <literal>package-name <a.b.c -> d.e.f | x.y.z> (section)</literal>
+ where <literal>a.b.c</literal> is the current version of the package,
+ <literal>d.e.f</literal> is the version considered for installation and
+ <literal>x.y.z</literal> is a newer version, but not considered for installation
+ (because of a low pin score). The later two can be omitted if there is none or if
+ it is the same version as the installed.
+ <literal>section</literal> is the name of the section the package appears in.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <!-- Question: why doesn't this do anything? The code says it should. -->
+ <varlistentry>
+ <term><literal>Debug::pkgInitConfig</literal></term>
+ <listitem>
+ <para>
+ Dump the default configuration to standard error on
+ startup.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgDPkgPM</literal></term>
+ <listitem>
+ <para>
+ When invoking &dpkg;, output the precise command line with
+ which it is being invoked, with arguments separated by a
+ single space character.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgDPkgProgressReporting</literal></term>
+ <listitem>
+ <para>
+ Output all the data received from &dpkg; on the status file
+ descriptor and any errors encountered while parsing it.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgOrderList</literal></term>
+
+ <listitem>
+ <para>
+ Generate a trace of the algorithm that decides the order in
+ which <literal>apt</literal> should pass packages to
+ &dpkg;.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgPackageManager</literal></term>
+
+ <listitem>
+ <para>
+ Output status messages tracing the steps performed when
+ invoking &dpkg;.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgPolicy</literal></term>
+
+ <listitem>
+ <para>
+ Output the priority of each package list on startup.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgProblemResolver</literal></term>
+
+ <listitem>
+ <para>
+ Trace the execution of the dependency resolver (this
+ applies only to what happens when a complex dependency
+ problem is encountered).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::pkgProblemResolver::ShowScores</literal></term>
+ <listitem>
+ <para>
+ Display a list of all installed packages with their calculated score
+ used by the pkgProblemResolver. The description of the package
+ is the same as described in <literal>Debug::pkgDepCache::Marker</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug::sourceList</literal></term>
+
+ <listitem>
+ <para>
+ Print information about the vendors read from
+ <filename>/etc/apt/vendors.list</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+<!-- 2009/07/11 Currently used nowhere. The corresponding code
+is commented.
+ <varlistentry>
+ <term><literal>Debug::Vendor</literal></term>
+
+ <listitem>
+ <para>
+ Print information about each vendor.
+ </para>
+ </listitem>
+ </varlistentry>
+-->
+ </variablelist>
+ </refsect1>
<refsect1><title>Examples</title>
<para>&configureindex; is a
</refsect1>
<refsect1><title>Files</title>
- <para><filename>/etc/apt/apt.conf</filename></para>
+ <variablelist>
+ <varlistentry><term><filename>/etc/apt/apt.conf</filename></term>
+ <listitem><para>APT configuration file.
+ Configuration Item: <literal>Dir::Etc::Main</literal>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term><filename>/etc/apt/apt.conf.d/</filename></term>
+ <listitem><para>APT configuration file fragments.
+ Configuration Item: <literal>Dir::Etc::Parts</literal>.</para></listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1><title>See Also</title>
projects / apt.git / blobdiff