1APT-TRANSPORT-MIRR(1)                 APT                APT-TRANSPORT-MIRR(1)
2
3
4

NAME

6       apt-transport-mirror - APT transport for more automated mirror
7       selection
8

DESCRIPTION

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
19       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
24       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

OPTIONS

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
34   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
43       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
49       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
53   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
64   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
73   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
82       Note that apt versions before 1.6 do not support any other transport
83       than http.
84

EXAMPLES

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
91           http://ftp.de.debian.org/debian/
92           http://ftp.us.debian.org/debian/
93           http://deb.debian.org/debian/
94
95       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
99           deb mirror+file:/etc/apt/mirrorlist.txt bookworm main
100
101       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
105           deb mirror://apt.example.org/mirror.lst bookworm main
106
107       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
110   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
121           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
127       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

BUGS

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

AUTHOR

141       APT team
142

NOTES

144        1. APT bug page
145           http://bugs.debian.org/src:apt
146
147
148
149APT 2.7.6                      09 December 2017          APT-TRANSPORT-MIRR(1)
Impressum