diff options
| -rw-r--r-- | debian/apt.install | 1 | ||||
| -rw-r--r-- | doc/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | doc/apt-transport-mirror.1.xml | 150 | ||||
| -rw-r--r-- | doc/po4a.conf | 1 |
4 files changed, 153 insertions, 0 deletions
diff --git a/debian/apt.install b/debian/apt.install index fc5a97133..705ea12d2 100644 --- a/debian/apt.install +++ b/debian/apt.install @@ -37,6 +37,7 @@ usr/share/man/*/apt-mark.* usr/share/man/*/apt-secure.* usr/share/man/*/apt-transport-http.* usr/share/man/*/apt-transport-https.* +usr/share/man/*/apt-transport-mirror.* usr/share/man/*/apt.* usr/share/man/*/apt_auth.* usr/share/man/*/apt_preferences.* 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 |