Re: Request for Review: Three new APT transport manpages
David Kalnischkies wrote:
> the apt team introduced a bunch of new manpages in the form of the
> attached docbook sources of apt-transport-http, -https and
> -mirror. It would be nice if they could be reviewed to remove my
> probably countless typos & incorrect germanisms.
It turns out to be not only a countable set but a finite one. Okay,
here are some commented diffs.
--- apt-transport-http.1.xml
+++ apt-transport-http.1.xml.jbr
@@ -35,30 +35,30 @@
a user but used by APT tools based on user configuration.</para>
<para>HTTP is an unencrypted transport protocol meaning that the
whole communication with the remote server (or proxy) can be observed by a
-sufficiently capable attacker referred to commonly as man in the middle (MITM).
-Such an attacker can <emphasis>not</emphasis> modify the communication to compromise
-the security of your system through as APTs data security model is independent of the
-chosen transport method. This is explained in detail in &apt-secure;. An overview over
+sufficiently capable attacker commonly referred to as a "man in the middle" (MITM).
(Or should I be using some sort of <quote> markup?)
+However, such an attacker can <emphasis>not</emphasis> modify the communication to compromise
I'm assuming "through" is a typo for "though".
+the security of your system, as APT's data security model is independent of the
+chosen transport method. This is explained in detail in &apt-secure;. An overview of
available transport methods is given in &sources-list;.</para>
</refsect1>
(I've also added quite a few commas, though I haven't standardised on
serial comma.)
<refsect1><title>Options</title>
-<para>Various options are available to modify its behaviour which can be set in
-an &apt-conf; file ranging from proxy configuration to workaround for specific
-server insufficiencies.</para>
+<para>Various options can be set in an &apt-conf; file to modify its behavior,
+ranging from proxy configuration to workarounds for specific
+server limitations.</para>
s/behaviour/behavior/, since elsewhere the APT docs seem to be using
en_US.
<refsect2><title>Proxy Configuration</title>
<para>The environment variable <envar>http_proxy</envar> is supported for system wide configuration.
-Proxies specific to apt can be configured via the option <literal>Acquire::http::Proxy</literal>.
+Proxies specific to APT can be configured via the option <literal>Acquire::http::Proxy</literal>.
My rule of thumb is that the APT system as a whole is uppercase,
although the package (the thing that gets version numbers) is
lowercase.
Proxies which should be used only for certain hosts can be specified via
<literal>Acquire::http::Proxy::<replaceable>host</replaceable></literal>. Even more finegrained control
-can be achieved via proxy autodetection detailed further below.
+can be achieved via proxy autodetection, detailed further below.
All these options use the URI format <literal><replaceable>scheme</replaceable>://[[<replaceable>user</replaceable>][:<replaceable>pass</replaceable>]@]<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/</literal>.
Supported URI schemes are <literal>socks5h</literal> (SOCKS5 with remote DNS resolution), <literal>http</literal> and <literal>https</literal>.
-Authentification details can be supplied via &apt-authconf; instead of including it in the URI directly.</para>
+Authentication details can be supplied via &apt-authconf; instead of including it in the URI directly.</para>
No need for authentificisating.
<para>The various APT configuration options support the special value <literal>DIRECT</literal> meaning that
-no proxy should be used. The environment variable <envar>no_proxy</envar> with the same propose is also supported.</para>
-<para>Further more there are three settings provided for cache control with HTTP/1.1 compliant proxy caches:
+no proxy should be used. The environment variable <envar>no_proxy</envar> is also supported for the same purpose.</para>
+<para>Furthermore, there are three settings provided for cache control with HTTP/1.1 compliant proxy caches:
<literal>Acquire::http::No-Cache</literal> tells the proxy not to use its
cached response under any circumstances.
<literal>Acquire::http::Max-Age</literal> sets the allowed maximum age (in
s/propose/purpose/ (there's another one later).
@@ -70,8 +70,8 @@
<refsect2><title>Automatic Proxy Configuration</title>
<para><literal>Acquire::http::Proxy-Auto-Detect</literal> can be used to
-specify an external command to discover the http proxy to use. The first
-and only parameter is an URI denoting the host to be contacted to allow
+specify an external command to discover the HTTP proxy to use. The first
The protocol is uppercase, the APT method is lowercase.
+and only parameter is a URI denoting the host to be contacted, to allow
"URL" is debatable, but "URI" always begins with a consonant.
for host-specific configuration. APT expects the command to output the
proxy on stdout as a single line in the previously specified URI format
or the word <literal>DIRECT</literal> if no proxy should be used. No output
@@ -93,8 +93,8 @@
<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.
-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
+APT tries to detect and work around misbehaving webservers and proxies at runtime, but
+if you know that yours does not conform to the HTTP/1.1 specification, pipelining can
Noun "workaround", verb "work around".
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>
@@ -102,7 +102,7 @@
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::SendAccept</literal> is enabled by default and
-sends a <literal>Accept: text/*</literal> header field to the server for
+sends an <literal>Accept: text/*</literal> header field to the server for
requests without file extensions to prevent the server from attempting content
negotiation.</para>
</refsect2>
--- apt-transport-https.1.xml
+++ apt-transport-https.1.xml.jbr
@@ -30,21 +30,21 @@
<refsect1><title>Description</title>
<para>This APT transport allows the use of repositories accessed via the
-HTTP Secure protocol (HTTPS) also referred to as HTTP over TLS. It is available
-by default since apt 1.5 and was before that available in a <package>apt-transport-https</package>
-package. Note that a transport is never called directly by
+HTTP Secure protocol (HTTPS), also referred to as HTTP over TLS. It is available
+by default since apt 1.5 and was available before that in the package
+<package>apt-transport-https</package>. Note that a transport is never called directly by
a user but used by APT tools based on user configuration.</para>
<para>HTTP is by itself an unencrypted transport protocol (compare &apt-transport-http;),
-which, as indicated by the appended S is wrapped in an encrypted layer known as
-Transport Layer Security (TLS) which provides end-to-end encryption.
+which, as indicated by the appended S, is wrapped in an encrypted layer known as
+Transport Layer Security (TLS) to provide end-to-end encryption.
A sufficiently capable attacker can still observe the communication partners
and deeper analyse of the encrypted communcation might still reveal important details.
An overview over available alternative transport methods is given in &sources-list;.</para>
</refsect1>
<refsect1><title>Options</title>
-<para>The HTTPS protocol is based on the HTTP protocol and as such this implementation
-has the same relation meaning that all options supported by &apt-transport-http; are also
+<para>The HTTPS protocol is based on the HTTP protocol, so
+all options supported by &apt-transport-http; are also
This sentence is unnecessarily convoluted, so I've just trimmed it
slightly.
available via <literal>Acquire::https</literal> and will default to the same values specified
for <literal>Acquire::http</literal>. This manpage will only document the options
<emphasis>unique to https</emphasis>.</para>
@@ -55,26 +55,26 @@
the server certificate. An alternative certificate authority (CA) can be
configured with the <literal>Acquire::https::CAInfo</literal> option and its
host-specific option <literal>Acquire::https::CAInfo::<replaceable>host</replaceable></literal>.
-The option specifies a file is made of the concatenation of the CA certificates
-(in PEM format) creating the chain used for the verification of the path
-from the root (self signed one). If the remote server provides the
+The CAInfo option specifies a file made up of CA certificates (in PEM format)
+concatenated together to create the chain which APT should use to verify the
+path from your self-signed root certificate. If the remote server provides the
I hope I'm interpreting that correctly.
whole chain during the exchange, the file need only contain the root
certificate. Otherwise, the whole chain is required. If you need to support
multiple authorities, the only way is to concatenate everything.</para>
<para>A custom certificate revocation list (CRL) can be configured with the options
<literal>Acquire::https::CRLFile</literal> and
-<literal>Acquire::https::CRLFile::<replaceable>host</replaceable></literal> respectively.
-Like the previous option a file in PEM format needs to be specified.</para>
+<literal>Acquire::https::CRLFile::<replaceable>host</replaceable></literal>.
+As with the previous option, a file in PEM format needs to be specified.</para>
</refsect2>
I've thrown out a Useless Use Of Respectively.
<refsect2><title>Disabling security</title>
-<para>When authenticating the server, if the certificate verification fails
-for some reason (expired, revoked, man in the middle, …), the connection fails.
+<para>During server authentication, if certificate verification fails
+for some reason (expired, revoked, man in the middle, etc.), the connection fails.
This is obviously what you want in all cases and what the default value (true)
of the option <literal>Acquire::https::Verify-Peer</literal> and its host-specific
variant provides. If you know <emphasis>exactly</emphasis> what you are doing,
-setting this option to "false" allows you to skip peer certificate verification and
-make the exchange succeed. Again, this option is for debugging or testing purpose
+setting this option to <literal>"false"</literal> allows you to skip peer certificate verification and
+make the exchange succeed. Again, this option is for debugging or testing purposes
only as it removes all security provided by the use of HTTPS.</para>
<para>Similarly the option <literal>Acquire::https::Verify-Host</literal> and its
host-specific variant can be used to deactivate a security feature: The certificate
Adding a <literal>; it's not clear whether I should throw out the
quotes.
@@ -83,13 +83,13 @@
mirror is checked against the identity found in the certificate. This default behavior
is safe and should not be changed, but if you know that the server you are using has a
DNS name which does not match the identity in its certificate, you can set the option to
-"false", which will prevent the comparison to be done.</para>
+<literal>"false"</literal>, which will prevent the comparison from being performed.</para>
</refsect2>
Ditto.
<refsect2><title>Client authentication</title>
-<para>Beside the password based authentication available (see &apt-authconf;) HTTPS supports
-authentication based on client certificates as well via <literal>Acquire::https::SSLCert</literal>
-and <literal>Acquire::https::SSLKey</literal>. They respectively should be set to the filename of
+<para>Besides supporting password-based authentication (see &apt-authconf;) HTTPS also supports
+authentication based on client certificates via <literal>Acquire::https::SSLCert</literal>
+and <literal>Acquire::https::SSLKey</literal>. These should be set respectively to the filename of
the X.509 client certificate and the associated (unencrypted) private key, both in PEM format.
In practice the use of the host-specific variants of both options is highly recommended.</para>
</refsect2>
At least this time there really are two lists (even if they're each
only two items long), so it's meaningful to use "respectively" to
reassure readers that we aren't scrambling them into different orders
for some reason.
--- apt-transport-mirror.1.xml
+++ apt-transport-mirror.1.xml.jbr
@@ -31,44 +31,44 @@
<refsect1><title>Description</title>
<para>This APT transport isn't implementing a protocol to access local or remote repositories
on its own, but acquires a mirrorlist and redirects all requests to the mirror(s) picked from
-this list access via other transports like &apt-transport-http;. The basic functionality is
-available since apt 0.7.24, but was undocumented until apt 1.6 which contained a complete
+this list, accessing them via other transports like &apt-transport-http;. The basic functionality has
+been available since apt 0.7.24, but was undocumented until apt 1.6 which contained a complete
rework of the transport and its supported features. Note that a transport is never called directly
by a user but used by APT tools based on user configuration.</para>
-<para>If the acquisition of a file via a mirror fails the method ensures that automatically
-another possible mirror of the list is tried until either the file is retrieved or no mirror is
-left in the list handling transparently server downtimes and similar problems.</para>
-<para>The security implications of the transport are based on the security considerations
+<para>If the acquisition of a file via a mirror fails, the method ensures that another possible mirror
+from the list is automatically tried until either the file is retrieved or no mirror is
+left in the list, transparently handling server downtimes and similar problems.</para>
+<para>The security implications of the transport depend on the security considerations
associated with the transport used to acquire the mirrorlist and the transports involved in
accessing the chosen mirror(s) by the transport.</para>
</refsect1>
Some adverb-shuffling.
<refsect1><title>Options</title>
<para>This transport has no configuration options at present. The mirror selection is
-based entirely on the mirrors offered in the mirrorlist and the files apt needs to
+based entirely on the mirrors offered in the mirrorlist and the files APT needs to
acquire.</para>
<refsect2><title>Mirrorlist format</title>
-<para>A mirrorlist contains at least one line each specifying an URI for a mirror.
-Empty lines and those starting with a hash key (<literal>#</literal>) are ignored.
-An URI always starts with a URI scheme which defines the transport used for this
-mirror. If the URI e.g. starts with <literal>http:</literal> the responsible transport
+<para>A mirrorlist contains one or more lines each specifying a URI for a mirror.
+Empty lines and those starting with a hash character (<literal>#</literal>) are ignored.
Unless you're talking about associative arrays, "hash keys" are the
buttons you press, not the things that go into files.
+A URI always starts with a URI scheme which defines the transport used for this
+mirror. If for example the URI starts with <literal>http:</literal>, the responsible transport
is &apt-transport-http; which might have specific requirements for the format of
the remaining part of the URI.</para>
-<para>An URI can optionally be separated from metadata about the mirror by a tab.
"Optionally" would mean I'm allowed to omit the separator.
-Multiple datapoints in the provided metadata can itself be separated by spaces for tabs.
"Itself"? "Spaces for tabs"? I *think* this should be:
+<para>Metadata about a mirror can be given on the same line, separated from the URI by a tab.
+Multiple items of metadata can themselves be separated by either tabs or spaces.
(This is an advanced feature only available with apt >= 1.6. Earlier apt versions will
-fail to parse mirrorlists using this feature)</para>
-<para>Since apt 1.6 the usage of compressed mirrorlists is also supported.
-Note that the filename of the mirrorlist must specify the compression algorithm used,
-there is no auto-detection based on file content performed.</para>
+fail to parse mirrorlists using this feature.)</para>
+<para>Since apt 1.6 the use of compressed mirrorlists is also supported.
+Note that the filename of the mirrorlist must specify the compression algorithm used;
+there is no auto-detection based on file contents.</para>
</refsect2>
<refsect2><title>Mirror selection by metadata</title>
-<para>As specified in the format a mirror can have additional metadata attached to
+<para>As specified in the format, a mirror can have additional metadata attached to
prevent a mirror from being selected for acquiring a file not matching this metadata.
This way the mirrorlist can e.g. contain partial mirrors serving only certain
-architectures and apt will automatically choose a different mirror for files requiring
+architectures and APT will automatically choose a different mirror for files requiring
an unlisted architecture. Supported are limits for the architecture (<literal>arch</literal>),
codename of the release (<literal>codename</literal>), component of the repository
the file is in (<literal>component</literal>), language the file applies to (<literal>lang</literal>),
@@ -76,18 +76,18 @@
</refsect2>
<refsect2><title>Fallback order for mirrors</title>
-<para>If no priority is given via the metadata key <literal>priority</literal> for a
-mirror the order in which mirrors are contacted is random. If a certain set of mirrors
-should be tried first before any of another set is tried a priority can be explicitly
+<para>If no priority is given for a mirror via the metadata key <literal>priority</literal>,
+the order in which mirrors are contacted is random. If a certain set of mirrors
+should be tried first before any of another set is tried, a priority can be explicitly
set. The mirrors with the lowest number are tried first. Mirrors which have no explicit
priority set default to the highest possible number and are therefore tried last. The
choice between mirrors with the same priority is again random.</para>
</refsect2>
<refsect2><title>Allowed transports in a mirrorlist</title>
-<para>The availability and choice of transports in a mirrorlist is limited by how the apt
+<para>The availability and choice of transports in a mirrorlist is limited by how the APT
client is accessing the mirrorlist. If a local transport like <literal>file</literal>
-or <literal>copy</literal> is used the mirrorlist can also include local sources while a
+or <literal>copy</literal> is used, the mirrorlist can also include local sources, while a
mirrorlist accessed via <literal>http</literal> can not. Additionally, a mirrorlist can
not contain a mirrorlist or other wrapping transports (like <package>apt-transport-tor</package>).
See the documentation of these transports on how to use them with the mirror method.</para>
@@ -109,9 +109,9 @@
<literallayout>
deb mirror+file:/etc/apt/mirrorlist.txt &debian-stable-codename; main
</literallayout>
-<para>All versions of the mirror method support a mirrorlist accessible via http, so assuming
+<para>All versions of the mirror method support a mirrorlist accessible via HTTP, so assuming
it is available at <literal>http://apt.example.org/mirror.lst</literal> the sources.list entry
-from above could be written instead as:</para>
+from above could instead be written as:</para>
<literallayout>
deb mirror://apt.example.org/mirror.lst &debian-stable-codename; main
</literallayout>
@@ -120,10 +120,10 @@
</refsect2>
<refsect2><title>Example with metadata-enhanced mirror selection</title>
<para>As explained in the format definition apt versions before 1.6 do not support this and
-will fail parsing the mirrorlist. The example mirrorlist is proposefully complicated to show some
-aspects of the selection. The following setup is assumed: The first mirror is local mirror
+will fail parsing the mirrorlist. The example mirrorlist is intentionally complicated to show some
Another misuse of "propose"; this time I switch to a different word.
+aspects of the selection. The following setup is assumed: The first mirror is a local mirror
accessible via the file method, but potentially incomplete. The second mirror has a great
-connection, but is a partial mirror in sofar as it only contains files related
+connection, but is a partial mirror insofar as it only contains files related
to the architectures <literal>amd64</literal> and <literal>all</literal>. The remaining mirrors
are average mirrors which should be contacted only if the earlier ones didn't work.
</para>
@@ -136,8 +136,8 @@
</literallayout>
<para>In this setup with this mirrorlist the first mirror will be used to download all
index files assuming the mirrorlist itself is accessed via a local transport like
-<literal>file</literal>. If it isn't, the mirror is otherwise inaccessible or does not
-contain the requested file another mirror will be used to acquire the file, which one
+<literal>file</literal>. If it isn't, if the mirror is otherwise inaccessible or if it does not
+contain the requested file another mirror will be used to acquire the file, chosen
depending on the type of the file: An index file will be served by the last
mirror in the list, while a package of architecture <literal>amd64</literal> is served by
the second and those of e.g. architecture <literal>i386</literal> by one of the last three.</para>
Clarify the structure of the conditional.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
--- apt-transport-http.1.xml 2018-01-03 22:52:22.422980268 +0000
+++ apt-transport-http.1.xml.jbr 2018-01-04 11:51:58.695027424 +0000
@@ -35,30 +35,30 @@
a user but used by APT tools based on user configuration.</para>
<para>HTTP is an unencrypted transport protocol meaning that the
whole communication with the remote server (or proxy) can be observed by a
-sufficiently capable attacker referred to commonly as man in the middle (MITM).
-Such an attacker can <emphasis>not</emphasis> modify the communication to compromise
-the security of your system through as APTs data security model is independent of the
-chosen transport method. This is explained in detail in &apt-secure;. An overview over
+sufficiently capable attacker commonly referred to as a "man in the middle" (MITM).
+However, such an attacker can <emphasis>not</emphasis> modify the communication to compromise
+the security of your system, as APT's data security model is independent of the
+chosen transport method. This is explained in detail in &apt-secure;. An overview of
available transport methods is given in &sources-list;.</para>
</refsect1>
<refsect1><title>Options</title>
-<para>Various options are available to modify its behaviour which can be set in
-an &apt-conf; file ranging from proxy configuration to workaround for specific
-server insufficiencies.</para>
+<para>Various options can be set in an &apt-conf; file to modify its behavior,
+ranging from proxy configuration to workarounds for specific
+server limitations.</para>
<refsect2><title>Proxy Configuration</title>
<para>The environment variable <envar>http_proxy</envar> is supported for system wide configuration.
-Proxies specific to apt can be configured via the option <literal>Acquire::http::Proxy</literal>.
+Proxies specific to APT can be configured via the option <literal>Acquire::http::Proxy</literal>.
Proxies which should be used only for certain hosts can be specified via
<literal>Acquire::http::Proxy::<replaceable>host</replaceable></literal>. Even more finegrained control
-can be achieved via proxy autodetection detailed further below.
+can be achieved via proxy autodetection, detailed further below.
All these options use the URI format <literal><replaceable>scheme</replaceable>://[[<replaceable>user</replaceable>][:<replaceable>pass</replaceable>]@]<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/</literal>.
Supported URI schemes are <literal>socks5h</literal> (SOCKS5 with remote DNS resolution), <literal>http</literal> and <literal>https</literal>.
-Authentification details can be supplied via &apt-authconf; instead of including it in the URI directly.</para>
+Authentication details can be supplied via &apt-authconf; instead of including it in the URI directly.</para>
<para>The various APT configuration options support the special value <literal>DIRECT</literal> meaning that
-no proxy should be used. The environment variable <envar>no_proxy</envar> with the same propose is also supported.</para>
-<para>Further more there are three settings provided for cache control with HTTP/1.1 compliant proxy caches:
+no proxy should be used. The environment variable <envar>no_proxy</envar> is also supported for the same purpose.</para>
+<para>Furthermore, there are three settings provided for cache control with HTTP/1.1 compliant proxy caches:
<literal>Acquire::http::No-Cache</literal> tells the proxy not to use its
cached response under any circumstances.
<literal>Acquire::http::Max-Age</literal> sets the allowed maximum age (in
@@ -70,8 +70,8 @@
<refsect2><title>Automatic Proxy Configuration</title>
<para><literal>Acquire::http::Proxy-Auto-Detect</literal> can be used to
-specify an external command to discover the http proxy to use. The first
-and only parameter is an URI denoting the host to be contacted to allow
+specify an external command to discover the HTTP proxy to use. The first
+and only parameter is a URI denoting the host to be contacted, to allow
for host-specific configuration. APT expects the command to output the
proxy on stdout as a single line in the previously specified URI format
or the word <literal>DIRECT</literal> if no proxy should be used. No output
@@ -93,8 +93,8 @@
<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.
-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
+APT tries to detect and work around 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>
@@ -102,7 +102,7 @@
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::SendAccept</literal> is enabled by default and
-sends a <literal>Accept: text/*</literal> header field to the server for
+sends an <literal>Accept: text/*</literal> header field to the server for
requests without file extensions to prevent the server from attempting content
negotiation.</para>
</refsect2>
<?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;
]>
<refentry>
<refentryinfo>
&apt-author.team;
&apt-email;
&apt-product;
<!-- The last update date -->
<date>2017-11-22T00:00:00Z</date>
</refentryinfo>
<refmeta>
<refentrytitle>apt-transport-http</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">APT</refmiscinfo>
</refmeta>
<!-- Man page title -->
<refnamediv>
<refname>apt-transport-http</refname>
<refpurpose>APT transport for downloading via the Hypertext Transfer Protocol (HTTP)</refpurpose>
</refnamediv>
<refsect1><title>Description</title>
<para>This APT transport allows the use of repositories accessed via the
Hypertext Transfer Protocol (HTTP). It is available by default and probably the
most used of all transports. Note that a transport is never called directly by
a user but used by APT tools based on user configuration.</para>
<para>HTTP is an unencrypted transport protocol meaning that the
whole communication with the remote server (or proxy) can be observed by a
sufficiently capable attacker commonly referred to as a "man in the middle" (MITM).
However, such an attacker can <emphasis>not</emphasis> modify the communication to compromise
the security of your system, as APT's data security model is independent of the
chosen transport method. This is explained in detail in &apt-secure;. An overview of
available transport methods is given in &sources-list;.</para>
</refsect1>
<refsect1><title>Options</title>
<para>Various options can be set in an &apt-conf; file to modify its behavior,
ranging from proxy configuration to workarounds for specific
server limitations.</para>
<refsect2><title>Proxy Configuration</title>
<para>The environment variable <envar>http_proxy</envar> is supported for system wide configuration.
Proxies specific to APT can be configured via the option <literal>Acquire::http::Proxy</literal>.
Proxies which should be used only for certain hosts can be specified via
<literal>Acquire::http::Proxy::<replaceable>host</replaceable></literal>. Even more finegrained control
can be achieved via proxy autodetection, detailed further below.
All these options use the URI format <literal><replaceable>scheme</replaceable>://[[<replaceable>user</replaceable>][:<replaceable>pass</replaceable>]@]<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/</literal>.
Supported URI schemes are <literal>socks5h</literal> (SOCKS5 with remote DNS resolution), <literal>http</literal> and <literal>https</literal>.
Authentication details can be supplied via &apt-authconf; instead of including it in the URI directly.</para>
<para>The various APT configuration options support the special value <literal>DIRECT</literal> meaning that
no proxy should be used. The environment variable <envar>no_proxy</envar> is also supported for the same purpose.</para>
<para>Furthermore, there are three settings provided for cache control with HTTP/1.1 compliant proxy caches:
<literal>Acquire::http::No-Cache</literal> tells the proxy not to use its
cached response under any circumstances.
<literal>Acquire::http::Max-Age</literal> sets the allowed maximum age (in
seconds) of an index file in the cache of the proxy.
<literal>Acquire::http::No-Store</literal> specifies that the proxy should not
store the requested archive files in its cache, which can be used to prevent
the proxy from polluting its cache with (big) .deb files.</para>
</refsect2>
<refsect2><title>Automatic Proxy Configuration</title>
<para><literal>Acquire::http::Proxy-Auto-Detect</literal> can be used to
specify an external command to discover the HTTP proxy to use. The first
and only parameter is a URI denoting the host to be contacted, to allow
for host-specific configuration. APT expects the command to output the
proxy on stdout as a single line in the previously specified URI format
or the word <literal>DIRECT</literal> if no proxy should be used. No output
indicates that the generic proxy settings should be used.</para>
<para>Note that auto-detection will not be used for a host if a host-specific proxy
configuration is already set via <literal>Acquire::http::Proxy::<replaceable>host</replaceable></literal>.</para>
<para>See the &squid-deb-proxy-client; and &auto-apt-proxy; packages for example implementations.</para>
<para>This option takes precedence over the legacy option name <literal>Acquire::http::ProxyAutoDetect</literal>.</para>
</refsect2>
<refsect2><title>Connection Configuration</title>
<para>The option <literal>Acquire::http::Timeout</literal> sets the timeout timer used by the method;
this value applies to the connection as well as the data timeout.</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>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.
APT tries to detect and work around 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::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::SendAccept</literal> is enabled by default and
sends an <literal>Accept: text/*</literal> header field to the server for
requests without file extensions to prevent the server from attempting content
negotiation.</para>
</refsect2>
</refsect1>
<refsect1><title>Examples</title>
<literallayout>
Acquire::http {
Proxy::example.org "DIRECT";
Proxy "socks5h://apt:pass@localhost:9050";
Proxy-Auto-Detect "/usr/local/bin/apt-http-proxy-auto-detect";
No-Cache "true";
Max-Age "3600";
No-Store "true";
Timeout "10";
Dl-Limit "42";
Pipeline-Depth "0";
AllowRedirect "false";
User-Agent "My APT-HTTP";
SendAccept "false";
};
</literallayout>
</refsect1>
<refsect1>
<title>See Also</title>
<para>&apt-conf; &apt-authconf; &sources-list;
</para>
</refsect1>
&manbugs;
</refentry>
--- apt-transport-https.1.xml 2018-01-03 22:52:25.466884860 +0000
+++ apt-transport-https.1.xml.jbr 2018-01-04 01:09:25.828660400 +0000
@@ -30,21 +30,21 @@
<refsect1><title>Description</title>
<para>This APT transport allows the use of repositories accessed via the
-HTTP Secure protocol (HTTPS) also referred to as HTTP over TLS. It is available
-by default since apt 1.5 and was before that available in a <package>apt-transport-https</package>
-package. Note that a transport is never called directly by
+HTTP Secure protocol (HTTPS), also referred to as HTTP over TLS. It is available
+by default since apt 1.5 and was available before that in the package
+<package>apt-transport-https</package>. Note that a transport is never called directly by
a user but used by APT tools based on user configuration.</para>
<para>HTTP is by itself an unencrypted transport protocol (compare &apt-transport-http;),
-which, as indicated by the appended S is wrapped in an encrypted layer known as
-Transport Layer Security (TLS) which provides end-to-end encryption.
+which, as indicated by the appended S, is wrapped in an encrypted layer known as
+Transport Layer Security (TLS) to provide end-to-end encryption.
A sufficiently capable attacker can still observe the communication partners
and deeper analyse of the encrypted communcation might still reveal important details.
An overview over available alternative transport methods is given in &sources-list;.</para>
</refsect1>
<refsect1><title>Options</title>
-<para>The HTTPS protocol is based on the HTTP protocol and as such this implementation
-has the same relation meaning that all options supported by &apt-transport-http; are also
+<para>The HTTPS protocol is based on the HTTP protocol, so
+all options supported by &apt-transport-http; are also
available via <literal>Acquire::https</literal> and will default to the same values specified
for <literal>Acquire::http</literal>. This manpage will only document the options
<emphasis>unique to https</emphasis>.</para>
@@ -55,26 +55,26 @@
the server certificate. An alternative certificate authority (CA) can be
configured with the <literal>Acquire::https::CAInfo</literal> option and its
host-specific option <literal>Acquire::https::CAInfo::<replaceable>host</replaceable></literal>.
-The option specifies a file is made of the concatenation of the CA certificates
-(in PEM format) creating the chain used for the verification of the path
-from the root (self signed one). If the remote server provides the
+The CAInfo option specifies a file made up of CA certificates (in PEM format)
+concatenated together to create the chain which APT should use to verify the
+path from your self-signed root certificate. If the remote server provides the
whole chain during the exchange, the file need only contain the root
certificate. Otherwise, the whole chain is required. If you need to support
multiple authorities, the only way is to concatenate everything.</para>
<para>A custom certificate revocation list (CRL) can be configured with the options
<literal>Acquire::https::CRLFile</literal> and
-<literal>Acquire::https::CRLFile::<replaceable>host</replaceable></literal> respectively.
-Like the previous option a file in PEM format needs to be specified.</para>
+<literal>Acquire::https::CRLFile::<replaceable>host</replaceable></literal>.
+As with the previous option, a file in PEM format needs to be specified.</para>
</refsect2>
<refsect2><title>Disabling security</title>
-<para>When authenticating the server, if the certificate verification fails
-for some reason (expired, revoked, man in the middle, …), the connection fails.
+<para>During server authentication, if certificate verification fails
+for some reason (expired, revoked, man in the middle, etc.), the connection fails.
This is obviously what you want in all cases and what the default value (true)
of the option <literal>Acquire::https::Verify-Peer</literal> and its host-specific
variant provides. If you know <emphasis>exactly</emphasis> what you are doing,
-setting this option to "false" allows you to skip peer certificate verification and
-make the exchange succeed. Again, this option is for debugging or testing purpose
+setting this option to <literal>"false"</literal> allows you to skip peer certificate verification and
+make the exchange succeed. Again, this option is for debugging or testing purposes
only as it removes all security provided by the use of HTTPS.</para>
<para>Similarly the option <literal>Acquire::https::Verify-Host</literal> and its
host-specific variant can be used to deactivate a security feature: The certificate
@@ -83,13 +83,13 @@
mirror is checked against the identity found in the certificate. This default behavior
is safe and should not be changed, but if you know that the server you are using has a
DNS name which does not match the identity in its certificate, you can set the option to
-"false", which will prevent the comparison to be done.</para>
+<literal>"false"</literal>, which will prevent the comparison from being performed.</para>
</refsect2>
<refsect2><title>Client authentication</title>
-<para>Beside the password based authentication available (see &apt-authconf;) HTTPS supports
-authentication based on client certificates as well via <literal>Acquire::https::SSLCert</literal>
-and <literal>Acquire::https::SSLKey</literal>. They respectively should be set to the filename of
+<para>Besides supporting password-based authentication (see &apt-authconf;) HTTPS also supports
+authentication based on client certificates via <literal>Acquire::https::SSLCert</literal>
+and <literal>Acquire::https::SSLKey</literal>. These should be set respectively to the filename of
the X.509 client certificate and the associated (unencrypted) private key, both in PEM format.
In practice the use of the host-specific variants of both options is highly recommended.</para>
</refsect2>
<?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;
]>
<refentry>
<refentryinfo>
&apt-author.team;
&apt-email;
&apt-product;
<!-- The last update date -->
<date>2017-11-22T00:00:00Z</date>
</refentryinfo>
<refmeta>
<refentrytitle>apt-transport-https</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">APT</refmiscinfo>
</refmeta>
<!-- Man page title -->
<refnamediv>
<refname>apt-transport-https</refname>
<refpurpose>APT transport for downloading via the HTTP Secure protocol (HTTPS)</refpurpose>
</refnamediv>
<refsect1><title>Description</title>
<para>This APT transport allows the use of repositories accessed via the
HTTP Secure protocol (HTTPS), also referred to as HTTP over TLS. It is available
by default since apt 1.5 and was available before that in the package
<package>apt-transport-https</package>. Note that a transport is never called directly by
a user but used by APT tools based on user configuration.</para>
<para>HTTP is by itself an unencrypted transport protocol (compare &apt-transport-http;),
which, as indicated by the appended S, is wrapped in an encrypted layer known as
Transport Layer Security (TLS) to provide end-to-end encryption.
A sufficiently capable attacker can still observe the communication partners
and deeper analyse of the encrypted communcation might still reveal important details.
An overview over available alternative transport methods is given in &sources-list;.</para>
</refsect1>
<refsect1><title>Options</title>
<para>The HTTPS protocol is based on the HTTP protocol, so
all options supported by &apt-transport-http; are also
available via <literal>Acquire::https</literal> and will default to the same values specified
for <literal>Acquire::http</literal>. This manpage will only document the options
<emphasis>unique to https</emphasis>.</para>
<refsect2><title>Server credentials</title>
<para>By default all certificates trusted by the system (see
<package>ca-certificates</package> package) are used for the verification of
the server certificate. An alternative certificate authority (CA) can be
configured with the <literal>Acquire::https::CAInfo</literal> option and its
host-specific option <literal>Acquire::https::CAInfo::<replaceable>host</replaceable></literal>.
The CAInfo option specifies a file made up of CA certificates (in PEM format)
concatenated together to create the chain which APT should use to verify the
path from your self-signed root certificate. If the remote server provides the
whole chain during the exchange, the file need only contain the root
certificate. Otherwise, the whole chain is required. If you need to support
multiple authorities, the only way is to concatenate everything.</para>
<para>A custom certificate revocation list (CRL) can be configured with the options
<literal>Acquire::https::CRLFile</literal> and
<literal>Acquire::https::CRLFile::<replaceable>host</replaceable></literal>.
As with the previous option, a file in PEM format needs to be specified.</para>
</refsect2>
<refsect2><title>Disabling security</title>
<para>During server authentication, if certificate verification fails
for some reason (expired, revoked, man in the middle, etc.), the connection fails.
This is obviously what you want in all cases and what the default value (true)
of the option <literal>Acquire::https::Verify-Peer</literal> and its host-specific
variant provides. If you know <emphasis>exactly</emphasis> what you are doing,
setting this option to <literal>"false"</literal> allows you to skip peer certificate verification and
make the exchange succeed. Again, this option is for debugging or testing purposes
only as it removes all security provided by the use of HTTPS.</para>
<para>Similarly the option <literal>Acquire::https::Verify-Host</literal> and its
host-specific variant can be used to deactivate a security feature: The certificate
provided by the server includes the identity of the server which should match the
DNS name used to access it. By default, as requested by RFC 2818, the name of the
mirror is checked against the identity found in the certificate. This default behavior
is safe and should not be changed, but if you know that the server you are using has a
DNS name which does not match the identity in its certificate, you can set the option to
<literal>"false"</literal>, which will prevent the comparison from being performed.</para>
</refsect2>
<refsect2><title>Client authentication</title>
<para>Besides supporting password-based authentication (see &apt-authconf;) HTTPS also supports
authentication based on client certificates via <literal>Acquire::https::SSLCert</literal>
and <literal>Acquire::https::SSLKey</literal>. These should be set respectively to the filename of
the X.509 client certificate and the associated (unencrypted) private key, both in PEM format.
In practice the use of the host-specific variants of both options is highly recommended.</para>
</refsect2>
</refsect1>
<refsect1><title>Examples</title>
<literallayout>
Acquire::https {
Proxy::example.org "DIRECT";
Proxy "socks5h://apt:pass@localhost:9050";
Proxy-Auto-Detect "/usr/local/bin/apt-https-proxy-auto-detect";
No-Cache "true";
Max-Age "3600";
No-Store "true";
Timeout "10";
Dl-Limit "42";
Pipeline-Depth "0";
AllowRedirect "false";
User-Agent "My APT-HTTPS";
SendAccept "false";
CAInfo "/path/to/ca/certs.pem";
CRLFile "/path/to/all/crl.pem";
Verify-Peer "true";
Verify-Host::broken.example.org "false";
SSLCert::example.org "/path/to/client/cert.pem";
SSLKey::example.org "/path/to/client/key.pem"
};
</literallayout>
</refsect1>
<refsect1>
<title>See Also</title>
<para>&apt-transport-http; &apt-conf; &apt-authconf; &sources-list;
</para>
</refsect1>
&manbugs;
</refentry>
--- apt-transport-mirror.1.xml 2018-01-03 22:52:28.418792334 +0000
+++ apt-transport-mirror.1.xml.jbr 2018-01-04 01:31:39.950659811 +0000
@@ -31,44 +31,44 @@
<refsect1><title>Description</title>
<para>This APT transport isn't implementing a protocol to access local or remote repositories
on its own, but acquires a mirrorlist and redirects all requests to the mirror(s) picked from
-this list access via other transports like &apt-transport-http;. The basic functionality is
-available since apt 0.7.24, but was undocumented until apt 1.6 which contained a complete
+this list, accessing them via other transports like &apt-transport-http;. The basic functionality has
+been available since apt 0.7.24, but was undocumented until apt 1.6 which contained a complete
rework of the transport and its supported features. Note that a transport is never called directly
by a user but used by APT tools based on user configuration.</para>
-<para>If the acquisition of a file via a mirror fails the method ensures that automatically
-another possible mirror of the list is tried until either the file is retrieved or no mirror is
-left in the list handling transparently server downtimes and similar problems.</para>
-<para>The security implications of the transport are based on the security considerations
+<para>If the acquisition of a file via a mirror fails, the method ensures that another possible mirror
+from the list is automatically tried until either the file is retrieved or no mirror is
+left in the list, transparently handling server downtimes and similar problems.</para>
+<para>The security implications of the transport depend on the security considerations
associated with the transport used to acquire the mirrorlist and the transports involved in
accessing the chosen mirror(s) by the transport.</para>
</refsect1>
<refsect1><title>Options</title>
<para>This transport has no configuration options at present. The mirror selection is
-based entirely on the mirrors offered in the mirrorlist and the files apt needs to
+based entirely on the mirrors offered in the mirrorlist and the files APT needs to
acquire.</para>
<refsect2><title>Mirrorlist format</title>
-<para>A mirrorlist contains at least one line each specifying an URI for a mirror.
-Empty lines and those starting with a hash key (<literal>#</literal>) are ignored.
-An URI always starts with a URI scheme which defines the transport used for this
-mirror. If the URI e.g. starts with <literal>http:</literal> the responsible transport
+<para>A mirrorlist contains one or more lines each specifying a URI for a mirror.
+Empty lines and those starting with a hash character (<literal>#</literal>) are ignored.
+A URI always starts with a URI scheme which defines the transport used for this
+mirror. If for example the URI starts with <literal>http:</literal>, the responsible transport
is &apt-transport-http; which might have specific requirements for the format of
the remaining part of the URI.</para>
-<para>An URI can optionally be separated from metadata about the mirror by a tab.
-Multiple datapoints in the provided metadata can itself be separated by spaces for tabs.
+<para>Metadata about a mirror can be given on the same line, separated from the URI by a tab.
+Multiple items of metadata can themselves be separated by either tabs or spaces.
(This is an advanced feature only available with apt >= 1.6. Earlier apt versions will
-fail to parse mirrorlists using this feature)</para>
-<para>Since apt 1.6 the usage of compressed mirrorlists is also supported.
-Note that the filename of the mirrorlist must specify the compression algorithm used,
-there is no auto-detection based on file content performed.</para>
+fail to parse mirrorlists using this feature.)</para>
+<para>Since apt 1.6 the use of compressed mirrorlists is also supported.
+Note that the filename of the mirrorlist must specify the compression algorithm used;
+there is no auto-detection based on file contents.</para>
</refsect2>
<refsect2><title>Mirror selection by metadata</title>
-<para>As specified in the format a mirror can have additional metadata attached to
+<para>As specified in the format, a mirror can have additional metadata attached to
prevent a mirror from being selected for acquiring a file not matching this metadata.
This way the mirrorlist can e.g. contain partial mirrors serving only certain
-architectures and apt will automatically choose a different mirror for files requiring
+architectures and APT will automatically choose a different mirror for files requiring
an unlisted architecture. Supported are limits for the architecture (<literal>arch</literal>),
codename of the release (<literal>codename</literal>), component of the repository
the file is in (<literal>component</literal>), language the file applies to (<literal>lang</literal>),
@@ -76,18 +76,18 @@
</refsect2>
<refsect2><title>Fallback order for mirrors</title>
-<para>If no priority is given via the metadata key <literal>priority</literal> for a
-mirror the order in which mirrors are contacted is random. If a certain set of mirrors
-should be tried first before any of another set is tried a priority can be explicitly
+<para>If no priority is given for a mirror via the metadata key <literal>priority</literal>,
+the order in which mirrors are contacted is random. If a certain set of mirrors
+should be tried first before any of another set is tried, a priority can be explicitly
set. The mirrors with the lowest number are tried first. Mirrors which have no explicit
priority set default to the highest possible number and are therefore tried last. The
choice between mirrors with the same priority is again random.</para>
</refsect2>
<refsect2><title>Allowed transports in a mirrorlist</title>
-<para>The availability and choice of transports in a mirrorlist is limited by how the apt
+<para>The availability and choice of transports in a mirrorlist is limited by how the APT
client is accessing the mirrorlist. If a local transport like <literal>file</literal>
-or <literal>copy</literal> is used the mirrorlist can also include local sources while a
+or <literal>copy</literal> is used, the mirrorlist can also include local sources, while a
mirrorlist accessed via <literal>http</literal> can not. Additionally, a mirrorlist can
not contain a mirrorlist or other wrapping transports (like <package>apt-transport-tor</package>).
See the documentation of these transports on how to use them with the mirror method.</para>
@@ -109,9 +109,9 @@
<literallayout>
deb mirror+file:/etc/apt/mirrorlist.txt &debian-stable-codename; main
</literallayout>
-<para>All versions of the mirror method support a mirrorlist accessible via http, so assuming
+<para>All versions of the mirror method support a mirrorlist accessible via HTTP, so assuming
it is available at <literal>http://apt.example.org/mirror.lst</literal> the sources.list entry
-from above could be written instead as:</para>
+from above could instead be written as:</para>
<literallayout>
deb mirror://apt.example.org/mirror.lst &debian-stable-codename; main
</literallayout>
@@ -120,10 +120,10 @@
</refsect2>
<refsect2><title>Example with metadata-enhanced mirror selection</title>
<para>As explained in the format definition apt versions before 1.6 do not support this and
-will fail parsing the mirrorlist. The example mirrorlist is proposefully complicated to show some
-aspects of the selection. The following setup is assumed: The first mirror is local mirror
+will fail parsing the mirrorlist. The example mirrorlist is intentionally complicated to show some
+aspects of the selection. The following setup is assumed: The first mirror is a local mirror
accessible via the file method, but potentially incomplete. The second mirror has a great
-connection, but is a partial mirror in sofar as it only contains files related
+connection, but is a partial mirror insofar as it only contains files related
to the architectures <literal>amd64</literal> and <literal>all</literal>. The remaining mirrors
are average mirrors which should be contacted only if the earlier ones didn't work.
</para>
@@ -136,8 +136,8 @@
</literallayout>
<para>In this setup with this mirrorlist the first mirror will be used to download all
index files assuming the mirrorlist itself is accessed via a local transport like
-<literal>file</literal>. If it isn't, the mirror is otherwise inaccessible or does not
-contain the requested file another mirror will be used to acquire the file, which one
+<literal>file</literal>. If it isn't, if the mirror is otherwise inaccessible or if it does not
+contain the requested file another mirror will be used to acquire the file, chosen
depending on the type of the file: An index file will be served by the last
mirror in the list, while a package of architecture <literal>amd64</literal> is served by
the second and those of e.g. architecture <literal>i386</literal> by one of the last three.</para>
<?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;
]>
<refentry>
<refentryinfo>
&apt-author.team;
&apt-email;
&apt-product;
<!-- The last update date -->
<date>2017-12-09T00:00:00Z</date>
</refentryinfo>
<refmeta>
<refentrytitle>apt-transport-mirror</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">APT</refmiscinfo>
</refmeta>
<!-- Man page title -->
<refnamediv>
<refname>apt-transport-mirror</refname>
<refpurpose>APT transport for more automated mirror selection</refpurpose>
</refnamediv>
<refsect1><title>Description</title>
<para>This APT transport isn't implementing a protocol to access local or remote repositories
on its own, but acquires a mirrorlist and redirects all requests to the mirror(s) picked from
this list, accessing them via other transports like &apt-transport-http;. The basic functionality has
been available since apt 0.7.24, but was undocumented until apt 1.6 which contained a complete
rework of the transport and its supported features. Note that a transport is never called directly
by a user but used by APT tools based on user configuration.</para>
<para>If the acquisition of a file via a mirror fails, the method ensures that another possible mirror
from the list is automatically tried until either the file is retrieved or no mirror is
left in the list, transparently handling server downtimes and similar problems.</para>
<para>The security implications of the transport depend on the security considerations
associated with the transport used to acquire the mirrorlist and the transports involved in
accessing the chosen mirror(s) by the transport.</para>
</refsect1>
<refsect1><title>Options</title>
<para>This transport has no configuration options at present. The mirror selection is
based entirely on the mirrors offered in the mirrorlist and the files APT needs to
acquire.</para>
<refsect2><title>Mirrorlist format</title>
<para>A mirrorlist contains one or more lines each specifying a URI for a mirror.
Empty lines and those starting with a hash character (<literal>#</literal>) are ignored.
A URI always starts with a URI scheme which defines the transport used for this
mirror. If for example the URI starts with <literal>http:</literal>, the responsible transport
is &apt-transport-http; which might have specific requirements for the format of
the remaining part of the URI.</para>
<para>Metadata about a mirror can be given on the same line, separated from the URI by a tab.
Multiple items of metadata can themselves be separated by either tabs or spaces.
(This is an advanced feature only available with apt >= 1.6. Earlier apt versions will
fail to parse mirrorlists using this feature.)</para>
<para>Since apt 1.6 the use of compressed mirrorlists is also supported.
Note that the filename of the mirrorlist must specify the compression algorithm used;
there is no auto-detection based on file contents.</para>
</refsect2>
<refsect2><title>Mirror selection by metadata</title>
<para>As specified in the format, a mirror can have additional metadata attached to
prevent a mirror from being selected for acquiring a file not matching this metadata.
This way the mirrorlist can e.g. contain partial mirrors serving only certain
architectures and APT will automatically choose a different mirror for files requiring
an unlisted architecture. Supported are limits for the architecture (<literal>arch</literal>),
codename of the release (<literal>codename</literal>), component of the repository
the file is in (<literal>component</literal>), language the file applies to (<literal>lang</literal>),
suite name of the release (<literal>suite</literal>) and type of the file (<literal>type</literal>).</para>
</refsect2>
<refsect2><title>Fallback order for mirrors</title>
<para>If no priority is given for a mirror via the metadata key <literal>priority</literal>,
the order in which mirrors are contacted is random. If a certain set of mirrors
should be tried first before any of another set is tried, a priority can be explicitly
set. The mirrors with the lowest number are tried first. Mirrors which have no explicit
priority set default to the highest possible number and are therefore tried last. The
choice between mirrors with the same priority is again random.</para>
</refsect2>
<refsect2><title>Allowed transports in a mirrorlist</title>
<para>The availability and choice of transports in a mirrorlist is limited by how the APT
client is accessing the mirrorlist. If a local transport like <literal>file</literal>
or <literal>copy</literal> is used, the mirrorlist can also include local sources, while a
mirrorlist accessed via <literal>http</literal> can not. Additionally, a mirrorlist can
not contain a mirrorlist or other wrapping transports (like <package>apt-transport-tor</package>).
See the documentation of these transports on how to use them with the mirror method.</para>
<para>Note that apt versions before 1.6 do not support any other transport than <literal>http</literal>.</para>
</refsect2>
</refsect1>
<refsect1><title>Examples</title>
<refsect2><title>Basic example</title>
<para>A basic mirrorlist example supported by all apt versions with a mirror method
(>= 0.7.24) in which the client will pick any of the three mirrors:</para>
<literallayout>
http://ftp.de.debian.org/debian/
http://ftp.us.debian.org/debian/
http://deb.debian.org/debian/
</literallayout>
<para>Assuming a file with this content is stored as <filename>/etc/apt/mirrorlist.txt</filename>
on your machine it can be used like this in &sources-list; (since apt 1.6):</para>
<literallayout>
deb mirror+file:/etc/apt/mirrorlist.txt &debian-stable-codename; main
</literallayout>
<para>All versions of the mirror method support a mirrorlist accessible via HTTP, so assuming
it is available at <literal>http://apt.example.org/mirror.lst</literal> the sources.list entry
from above could instead be written as:</para>
<literallayout>
deb mirror://apt.example.org/mirror.lst &debian-stable-codename; main
</literallayout>
<para>Note that since apt 1.6 the use of <literal>mirror+http</literal> should
be preferred over <literal>mirror</literal> for uniformity. The functionality is the same.</para>
</refsect2>
<refsect2><title>Example with metadata-enhanced mirror selection</title>
<para>As explained in the format definition apt versions before 1.6 do not support this and
will fail parsing the mirrorlist. The example mirrorlist is intentionally complicated to show some
aspects of the selection. The following setup is assumed: The first mirror is a local mirror
accessible via the file method, but potentially incomplete. The second mirror has a great
connection, but is a partial mirror insofar as it only contains files related
to the architectures <literal>amd64</literal> and <literal>all</literal>. The remaining mirrors
are average mirrors which should be contacted only if the earlier ones didn't work.
</para>
<literallayout>
file:/srv/local/debian/mirror/ priority:1 type:index
http://partial.example.org/mirror/ priority:2 arch:amd64 arch:all type:deb
http://ftp.us.debian.org/debian/ type:deb
http://ftp.de.debian.org/debian/ type:deb
https://deb.debian.org/debian/
</literallayout>
<para>In this setup with this mirrorlist the first mirror will be used to download all
index files assuming the mirrorlist itself is accessed via a local transport like
<literal>file</literal>. If it isn't, if the mirror is otherwise inaccessible or if it does not
contain the requested file another mirror will be used to acquire the file, chosen
depending on the type of the file: An index file will be served by the last
mirror in the list, while a package of architecture <literal>amd64</literal> is served by
the second and those of e.g. architecture <literal>i386</literal> by one of the last three.</para>
</refsect2>
</refsect1>
&manbugs;
</refentry>
Reply to: