X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/fce69e7a0f38299c57ef96ae1c1dd9a5379bfd5a..bc7a59dded57338e9b5e523726b246dbdd4e0935:/doc/apt.conf.5.xml diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml index bfc43ba29..2bb814257 100644 --- 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" [ - -<!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> @@ -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> + <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> @@ -177,6 +173,15 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";}; </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', @@ -298,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. + 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> @@ -309,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 - 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> @@ -321,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 - 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 - 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> @@ -338,6 +349,16 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";}; </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 @@ -381,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. - 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> @@ -583,9 +604,95 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";}; </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> + <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 @@ -599,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 - 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 @@ -623,7 +731,7 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";}; <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 @@ -632,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>. + If you want to prefix only relative paths, set <literal>Dir</literal> instead. </para> <para> @@ -707,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> - <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 (< for upgrades, > 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>- < 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 @@ -1175,6 +1308,18 @@ DPkg::TriggersPending "true";</literallayout></para> </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>