From 851b6a097165af4d51c0db01b5e05256e5006896 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:00:48 +0200 Subject: Adding upstream version 2.6.1. Signed-off-by: Daniel Baumann --- doc/apt-transport-mirror.1.xml | 150 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 doc/apt-transport-mirror.1.xml (limited to 'doc/apt-transport-mirror.1.xml') 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 @@ + + %aptent; + %aptverbatiment; + %aptvendor; +]> + + + + + &apt-author.team; + &apt-email; + &apt-product; + + 2017-12-09T00:00:00Z + + + + apt-transport-mirror + 1 + APT + + + + + apt-transport-mirror + APT transport for more automated mirror selection + + +Description +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. +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. +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. + + +Options +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. + +Mirrorlist format +A mirrorlist contains one or more lines each specifying a URI for a mirror. +Empty lines and those starting with a hash character (#) 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 http:, the responsible transport +is &apt-transport-http; which might have specific requirements for the format of +the remaining part of the URI. +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.) +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. + + +Mirror selection by metadata +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 (arch), +codename of the release (codename), component of the repository +the file is in (component), language the file applies to (lang), +suite name of the release (suite) and type of the file (type). + + +Fallback order for mirrors +If no priority is given for a mirror via the metadata key priority, +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. + + +Allowed transports in a mirrorlist +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 file +or copy is used, the mirrorlist can also include local sources, while a +mirrorlist accessed via http can not. Additionally, a mirrorlist can +not contain a mirrorlist or other wrapping transports (like apt-transport-tor). +See the documentation of these transports on how to use them with the mirror method. +Note that apt versions before 1.6 do not support any other transport than http. + + + +Examples +Basic example +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: + +http://ftp.de.debian.org/debian/ +http://ftp.us.debian.org/debian/ +http://deb.debian.org/debian/ + +Assuming a file with this content is stored as /etc/apt/mirrorlist.txt +on your machine it can be used like this in &sources-list; (since apt 1.6): + +deb mirror+file:/etc/apt/mirrorlist.txt &debian-stable-codename; main + +All versions of the mirror method support a mirrorlist accessible via HTTP, so assuming +it is available at http://apt.example.org/mirror.lst the sources.list entry +from above could instead be written as: + +deb mirror://apt.example.org/mirror.lst &debian-stable-codename; main + +Note that since apt 1.6 the use of mirror+http should +be preferred over mirror for uniformity. The functionality is the same. + +Example with metadata-enhanced mirror selection +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 amd64 and all. The remaining mirrors +are average mirrors which should be contacted only if the earlier ones didn't work. + + +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/ + +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 +file. 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 amd64 is served by +the second and those of e.g. architecture i386 by one of the last three. + + + + + &manbugs; + + -- cgit v1.2.3