add apt-transport-mirror manpage

The mirror method is undocumented since 0.7.24, now with the
reimplementation it is high time to get something written about it.

3 files changed, 152 insertions, 0 deletions

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index cb2fe892c..7cca4cf81 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -86,6 +86,7 @@ add_docbook(apt-man MANPAGE ALL
         apt-sortpkgs.1.xml
         apt-transport-http.1.xml
         apt-transport-https.1.xml
+        apt-transport-mirror.1.xml
         sources.list.5.xml
     DEPENDS ${ENTITIES}
     TRANSLATED_ENTITIES ${TRANSLATED_ENTITIES}
diff --git a/doc/apt-transport-mirror.1.xml b/doc/apt-transport-mirror.1.xml
new file mode 100644
index 000000000..72001fad5
--- /dev/null
+++ b/doc/apt-transport-mirror.1.xml
@@ -0,0 +1,150 @@
+<?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 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
+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
+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 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
+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.
+(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>
+</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 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
+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 be written instead 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 proposefully complicated to show some
+aspects of the selection. The following setup is assumed: The first mirror is 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
+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, the mirror is otherwise inaccessible or does not
+contain the requested file another mirror will be used to acquire the file, which one
+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>
diff --git a/doc/po4a.conf b/doc/po4a.conf
index f1fe4cb0c..587215abc 100644
--- a/doc/po4a.conf
+++ b/doc/po4a.conf
@@ -29,6 +29,7 @@
 [type: manpage] apt_auth.conf.5.xml $lang:$lang/apt_auth.conf.$lang.5.xml add_$lang:xml.add
 [type: manpage] apt-transport-http.1.xml $lang:$lang/apt-transport-http.$lang.1.xml add_$lang:xml.add
 [type: manpage] apt-transport-https.1.xml $lang:$lang/apt-transport-https.$lang.1.xml add_$lang:xml.add
+[type: manpage] apt-transport-mirror.1.xml $lang:$lang/apt-transport-mirror.$lang.1.xml add_$lang:xml.add
 
 [type: docbook] guide.dbk $lang:$lang/guide.$lang.dbk
 #                add_$lang::$lang/addendum/docbook_$lang.add