From e4ed47f10844cf7ad933f7a9b64583869592f139 Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Sat, 9 Dec 2017 12:32:32 +0100 Subject: add apt-transport-mirror manpage The mirror method is undocumented since 0.7.24, now with the reimplementation it is high time to get something written about it. --- debian/apt.install | 1 + doc/CMakeLists.txt | 1 + doc/apt-transport-mirror.1.xml | 150 +++++++++++++++++++++++++++++++++++++++++ doc/po4a.conf | 1 + 4 files changed, 153 insertions(+) create mode 100644 doc/apt-transport-mirror.1.xml diff --git a/debian/apt.install b/debian/apt.install index fc5a97133..705ea12d2 100644 --- a/debian/apt.install +++ b/debian/apt.install @@ -37,6 +37,7 @@ usr/share/man/*/apt-mark.* usr/share/man/*/apt-secure.* usr/share/man/*/apt-transport-http.* usr/share/man/*/apt-transport-https.* +usr/share/man/*/apt-transport-mirror.* usr/share/man/*/apt.* usr/share/man/*/apt_auth.* usr/share/man/*/apt_preferences.* diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index cb2fe892c..7cca4cf81 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -86,6 +86,7 @@ add_docbook(apt-man MANPAGE ALL apt-sortpkgs.1.xml apt-transport-http.1.xml apt-transport-https.1.xml + apt-transport-mirror.1.xml sources.list.5.xml DEPENDS ${ENTITIES} TRANSLATED_ENTITIES ${TRANSLATED_ENTITIES} diff --git a/doc/apt-transport-mirror.1.xml b/doc/apt-transport-mirror.1.xml new file mode 100644 index 000000000..72001fad5 --- /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 access via other transports like &apt-transport-http;. The basic functionality is +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 automatically +another possible mirror of the list is tried until either the file is retrieved or no mirror is +left in the list handling transparently server downtimes and similar problems. +The security implications of the transport are based 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 at least one line each specifying an URI for a mirror. +Empty lines and those starting with a hash key (#) are ignored. +An URI always starts with a URI scheme which defines the transport used for this +mirror. If the URI e.g. 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. +An URI can optionally be separated from metadata about the mirror by a tab. +Multiple datapoints in the provided metadata can itself be separated by spaces for tabs. +(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 usage 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 content performed. + + +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 via the metadata key priority for a +mirror 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 be written instead 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 proposefully complicated to show some +aspects of the selection. The following setup is assumed: The first mirror is local mirror +accessible via the file method, but potentially incomplete. The second mirror has a great +connection, but is a partial mirror in sofar 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, the mirror is otherwise inaccessible or does not +contain the requested file another mirror will be used to acquire the file, which one +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; + + diff --git a/doc/po4a.conf b/doc/po4a.conf index f1fe4cb0c..587215abc 100644 --- a/doc/po4a.conf +++ b/doc/po4a.conf @@ -29,6 +29,7 @@ [type: manpage] apt_auth.conf.5.xml $lang:$lang/apt_auth.conf.$lang.5.xml add_$lang:xml.add [type: manpage] apt-transport-http.1.xml $lang:$lang/apt-transport-http.$lang.1.xml add_$lang:xml.add [type: manpage] apt-transport-https.1.xml $lang:$lang/apt-transport-https.$lang.1.xml add_$lang:xml.add +[type: manpage] apt-transport-mirror.1.xml $lang:$lang/apt-transport-mirror.$lang.1.xml add_$lang:xml.add [type: docbook] guide.dbk $lang:$lang/guide.$lang.dbk # add_$lang::$lang/addendum/docbook_$lang.add -- cgit v1.2.3