diff options
Diffstat (limited to 'doc/apt-transport-mirror.1.xml')
| -rw-r--r-- | doc/apt-transport-mirror.1.xml | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/doc/apt-transport-mirror.1.xml b/doc/apt-transport-mirror.1.xml new file mode 100644 index 0000000..7e95420 --- /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, 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> |