You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

151 lines
8.0 KiB

  1. <?xml version="1.0" encoding="utf-8" standalone="no"?>
  2. <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  3. "" [
  4. <!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
  5. <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
  6. <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
  7. ]>
  8. <refentry>
  9. <refentryinfo>
  10. &;
  11. &apt-email;
  12. &apt-product;
  13. <!-- The last update date -->
  14. <date>2017-12-09T00:00:00Z</date>
  15. </refentryinfo>
  16. <refmeta>
  17. <refentrytitle>apt-transport-mirror</refentrytitle>
  18. <manvolnum>1</manvolnum>
  19. <refmiscinfo class="manual">APT</refmiscinfo>
  20. </refmeta>
  21. <!-- Man page title -->
  22. <refnamediv>
  23. <refname>apt-transport-mirror</refname>
  24. <refpurpose>APT transport for more automated mirror selection</refpurpose>
  25. </refnamediv>
  26. <refsect1><title>Description</title>
  27. <para>This APT transport isn't implementing a protocol to access local or remote repositories
  28. on its own, but acquires a mirrorlist and redirects all requests to the mirror(s) picked from
  29. this list, accessing them via other transports like &apt-transport-http;. The basic functionality has
  30. been available since apt 0.7.24, but was undocumented until apt 1.6 which contained a complete
  31. rework of the transport and its supported features. Note that a transport is never called directly
  32. by a user but used by APT tools based on user configuration.</para>
  33. <para>If the acquisition of a file via a mirror fails, the method ensures that another possible mirror
  34. from the list is automatically tried until either the file is retrieved or no mirror is
  35. left in the list, transparently handling server downtimes and similar problems.</para>
  36. <para>The security implications of the transport depend on the security considerations
  37. associated with the transport used to acquire the mirrorlist and the transports involved in
  38. accessing the chosen mirror(s) by the transport.</para>
  39. </refsect1>
  40. <refsect1><title>Options</title>
  41. <para>This transport has no configuration options at present. The mirror selection is
  42. based entirely on the mirrors offered in the mirrorlist and the files APT needs to
  43. acquire.</para>
  44. <refsect2><title>Mirrorlist format</title>
  45. <para>A mirrorlist contains one or more lines each specifying a URI for a mirror.
  46. Empty lines and those starting with a hash character (<literal>#</literal>) are ignored.
  47. A URI always starts with a URI scheme which defines the transport used for this
  48. mirror. If for example the URI starts with <literal>http:</literal>, the responsible transport
  49. is &apt-transport-http; which might have specific requirements for the format of
  50. the remaining part of the URI.</para>
  51. <para>Metadata about a mirror can be given on the same line, separated from the URI by a tab.
  52. Multiple items of metadata can themselves be separated by either tabs or spaces.
  53. (This is an advanced feature only available with apt >= 1.6. Earlier apt versions will
  54. fail to parse mirrorlists using this feature.)</para>
  55. <para>Since apt 1.6 the use of compressed mirrorlists is also supported.
  56. Note that the filename of the mirrorlist must specify the compression algorithm used;
  57. there is no auto-detection based on file contents.</para>
  58. </refsect2>
  59. <refsect2><title>Mirror selection by metadata</title>
  60. <para>As specified in the format, a mirror can have additional metadata attached to
  61. prevent a mirror from being selected for acquiring a file not matching this metadata.
  62. This way the mirrorlist can e.g. contain partial mirrors serving only certain
  63. architectures and APT will automatically choose a different mirror for files requiring
  64. an unlisted architecture. Supported are limits for the architecture (<literal>arch</literal>),
  65. codename of the release (<literal>codename</literal>), component of the repository
  66. the file is in (<literal>component</literal>), language the file applies to (<literal>lang</literal>),
  67. suite name of the release (<literal>suite</literal>) and type of the file (<literal>type</literal>).</para>
  68. </refsect2>
  69. <refsect2><title>Fallback order for mirrors</title>
  70. <para>If no priority is given for a mirror via the metadata key <literal>priority</literal>,
  71. the order in which mirrors are contacted is random. If a certain set of mirrors
  72. should be tried first before any of another set is tried, a priority can be explicitly
  73. set. The mirrors with the lowest number are tried first. Mirrors which have no explicit
  74. priority set default to the highest possible number and are therefore tried last. The
  75. choice between mirrors with the same priority is again random.</para>
  76. </refsect2>
  77. <refsect2><title>Allowed transports in a mirrorlist</title>
  78. <para>The availability and choice of transports in a mirrorlist is limited by how the APT
  79. client is accessing the mirrorlist. If a local transport like <literal>file</literal>
  80. or <literal>copy</literal> is used, the mirrorlist can also include local sources, while a
  81. mirrorlist accessed via <literal>http</literal> can not. Additionally, a mirrorlist can
  82. not contain a mirrorlist or other wrapping transports (like <package>apt-transport-tor</package>).
  83. See the documentation of these transports on how to use them with the mirror method.</para>
  84. <para>Note that apt versions before 1.6 do not support any other transport than <literal>http</literal>.</para>
  85. </refsect2>
  86. </refsect1>
  87. <refsect1><title>Examples</title>
  88. <refsect2><title>Basic example</title>
  89. <para>A basic mirrorlist example supported by all apt versions with a mirror method
  90. (>= 0.7.24) in which the client will pick any of the three mirrors:</para>
  91. <literallayout>
  95. </literallayout>
  96. <para>Assuming a file with this content is stored as <filename>/etc/apt/mirrorlist.txt</filename>
  97. on your machine it can be used like this in &sources-list; (since apt 1.6):</para>
  98. <literallayout>
  99. deb mirror+file:/etc/apt/mirrorlist.txt &debian-stable-codename; main
  100. </literallayout>
  101. <para>All versions of the mirror method support a mirrorlist accessible via HTTP, so assuming
  102. it is available at <literal></literal> the sources.list entry
  103. from above could instead be written as:</para>
  104. <literallayout>
  105. deb mirror:// &debian-stable-codename; main
  106. </literallayout>
  107. <para>Note that since apt 1.6 the use of <literal>mirror+http</literal> should
  108. be preferred over <literal>mirror</literal> for uniformity. The functionality is the same.</para>
  109. </refsect2>
  110. <refsect2><title>Example with metadata-enhanced mirror selection</title>
  111. <para>As explained in the format definition apt versions before 1.6 do not support this and
  112. will fail parsing the mirrorlist. The example mirrorlist is intentionally complicated to show some
  113. aspects of the selection. The following setup is assumed: The first mirror is a local mirror
  114. accessible via the file method, but potentially incomplete. The second mirror has a great
  115. connection, but is a partial mirror insofar as it only contains files related
  116. to the architectures <literal>amd64</literal> and <literal>all</literal>. The remaining mirrors
  117. are average mirrors which should be contacted only if the earlier ones didn't work.
  118. </para>
  119. <literallayout>
  120. file:/srv/local/debian/mirror/ priority:1 type:index
  121. priority:2 arch:amd64 arch:all type:deb
  122. type:deb
  123. type:deb
  125. </literallayout>
  126. <para>In this setup with this mirrorlist the first mirror will be used to download all
  127. index files assuming the mirrorlist itself is accessed via a local transport like
  128. <literal>file</literal>. If it isn't, if the mirror is otherwise inaccessible or if it does not
  129. contain the requested file another mirror will be used to acquire the file, chosen
  130. depending on the type of the file: An index file will be served by the last
  131. mirror in the list, while a package of architecture <literal>amd64</literal> is served by
  132. the second and those of e.g. architecture <literal>i386</literal> by one of the last three.</para>
  133. </refsect2>
  134. </refsect1>
  135. &manbugs;
  136. </refentry>