1APT-TRANSPORT-MIRR(1) APT APT-TRANSPORT-MIRR(1)
2
6 apt-transport-mirror - APT transport for more automated mirror
7 selection
8
10 This APT transport isn't implementing a protocol to access local or
11 remote repositories on its own, but acquires a mirrorlist and redirects
12 all requests to the mirror(s) picked from this list, accessing them via
13 other transports like apt-transport-http(1). The basic functionality
14 has been available since apt 0.7.24, but was undocumented until apt 1.6
15 which contained a complete rework of the transport and its supported
16 features. Note that a transport is never called directly by a user but
17 used by APT tools based on user configuration.
18 If the acquisition of a file via a mirror fails, the method ensures
20 that another possible mirror from the list is automatically tried until
21 either the file is retrieved or no mirror is left in the list,
22 transparently handling server downtimes and similar problems.
23 The security implications of the transport depend on the security
25 considerations associated with the transport used to acquire the
26 mirrorlist and the transports involved in accessing the chosen
27 mirror(s) by the transport.
28
30 This transport has no configuration options at present. The mirror
31 selection is based entirely on the mirrors offered in the mirrorlist
32 and the files APT needs to acquire.
33 Mirrorlist format
35 A mirrorlist contains one or more lines each specifying a URI for a
36 mirror. Empty lines and those starting with a hash character (#) are
37 ignored. A URI always starts with a URI scheme which defines the
38 transport used for this mirror. If for example the URI starts with
39 http:, the responsible transport is apt-transport-http(1) which might
40 have specific requirements for the format of the remaining part of the
41 URI.
42 Metadata about a mirror can be given on the same line, separated from
44 the URI by a tab. Multiple items of metadata can themselves be
45 separated by either tabs or spaces. (This is an advanced feature only
46 available with apt >= 1.6. Earlier apt versions will fail to parse
47 mirrorlists using this feature.)
48 Since apt 1.6 the use of compressed mirrorlists is also supported. Note
50 that the filename of the mirrorlist must specify the compression
51 algorithm used; there is no auto-detection based on file contents.
52 Mirror selection by metadata
54 As specified in the format, a mirror can have additional metadata
55 attached to prevent a mirror from being selected for acquiring a file
56 not matching this metadata. This way the mirrorlist can e.g. contain
57 partial mirrors serving only certain architectures and APT will
58 automatically choose a different mirror for files requiring an unlisted
59 architecture. Supported are limits for the architecture (arch),
60 codename of the release (codename), component of the repository the
61 file is in (component), language the file applies to (lang), suite name
62 of the release (suite) and type of the file (type).
63 Fallback order for mirrors
65 If no priority is given for a mirror via the metadata key priority, the
66 order in which mirrors are contacted is random. If a certain set of
67 mirrors should be tried first before any of another set is tried, a
68 priority can be explicitly set. The mirrors with the lowest number are
69 tried first. Mirrors which have no explicit priority set default to the
70 highest possible number and are therefore tried last. The choice
71 between mirrors with the same priority is again random.
72 Allowed transports in a mirrorlist
74 The availability and choice of transports in a mirrorlist is limited by
75 how the APT client is accessing the mirrorlist. If a local transport
76 like file or copy is used, the mirrorlist can also include local
77 sources, while a mirrorlist accessed via http can not. Additionally, a
78 mirrorlist can not contain a mirrorlist or other wrapping transports
79 (like apt-transport-tor). See the documentation of these transports on
80 how to use them with the mirror method.
81 Note that apt versions before 1.6 do not support any other transport
83 than http.
84
86 Basic example
87 A basic mirrorlist example supported by all apt versions with a mirror
88 method (>= 0.7.24) in which the client will pick any of the three
89 mirrors:
90 http://ftp.de.debian.org/debian/
92 http://ftp.us.debian.org/debian/
93 http://deb.debian.org/debian/
94 Assuming a file with this content is stored as /etc/apt/mirrorlist.txt
96 on your machine it can be used like this in sources.list(5) (since apt
97 1.6):
98 deb mirror+file:/etc/apt/mirrorlist.txt bullseye main
100 All versions of the mirror method support a mirrorlist accessible via
102 HTTP, so assuming it is available at http://apt.example.org/mirror.lst
103 the sources.list entry from above could instead be written as:
104 deb mirror://apt.example.org/mirror.lst bullseye main
106 Note that since apt 1.6 the use of mirror+http should be preferred over
108 mirror for uniformity. The functionality is the same.
109 Example with metadata-enhanced mirror selection
111 As explained in the format definition apt versions before 1.6 do not
112 support this and will fail parsing the mirrorlist. The example
113 mirrorlist is intentionally complicated to show some aspects of the
114 selection. The following setup is assumed: The first mirror is a local
115 mirror accessible via the file method, but potentially incomplete. The
116 second mirror has a great connection, but is a partial mirror insofar
117 as it only contains files related to the architectures amd64 and all.
118 The remaining mirrors are average mirrors which should be contacted
119 only if the earlier ones didn't work.
120 file:/srv/local/debian/mirror/ priority:1 type:index
122 http://partial.example.org/mirror/ priority:2 arch:amd64 arch:all type:deb
123 http://ftp.us.debian.org/debian/ type:deb
124 http://ftp.de.debian.org/debian/ type:deb
125 https://deb.debian.org/debian/
126 In this setup with this mirrorlist the first mirror will be used to
128 download all index files assuming the mirrorlist itself is accessed via
129 a local transport like file. If it isn't, if the mirror is otherwise
130 inaccessible or if it does not contain the requested file another
131 mirror will be used to acquire the file, chosen depending on the type
132 of the file: An index file will be served by the last mirror in the
133 list, while a package of architecture amd64 is served by the second and
134 those of e.g. architecture i386 by one of the last three.
135
137 APT bug page[1]. If you wish to report a bug in APT, please see
138 /usr/share/doc/debian/bug-reporting.txt or the reportbug(1) command.
139
141 APT team
142
144 1. APT bug page
145 http://bugs.debian.org/src:apt
146APT 2.3.11 09 December 2017 APT-TRANSPORT-MIRR(1)