<?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>