Home / Alt manpages / apt-transport-mirror(1)

  • apt-transport-mirror(1)
  • User command
  • linux

Build a Resilient Mirror List with apt-transport-mirror

apt-transport-mirror lets APT pick from several repository mirrors and retry another one the moment a download fails. You will also see how to keep a partial mirror away from packages it does not carry, and how to check the configuration without installing or removing anything. Allow about fifteen minutes. Examples use APT 2.8.3, installed here as package version 2.8.3.

The route

Jump straight to the step you need, or tick off Done means at the end.

This is not a command you run by hand. APT invokes it when a source entry uses the mirror transport, so the real work happens in a mirror-list file and a sources-list entry.

1. Check the installed APT version

Start with a read-only check. No elevated privileges needed:

$ apt-cache policy apt
apt:
  Installed: 2.8.3
  Candidate: 2.8.3
  Version table:

Your version and repository lines will differ. The relevant line in the sand is APT 1.6: metadata-enhanced mirror lists, compressed mirror lists, and the mirror+file and mirror+http forms covered here all need that version or newer. Basic mirror transport support goes back to APT 0.7.24, but older clients are stricter about what they accept, so do not copy a metadata example onto an old machine without checking its installed manual first.

Checkpoint

If the installed version is below 1.6, use a plain list of HTTP mirrors and the older syntax in the compatibility notes below instead.

2. Create a plain mirror list

A mirror list is one URI per line. Blank lines and lines starting # are ignored. Every URI needs its own scheme, because that scheme is what selects the transport used for the real repository request.

# /etc/apt/mirrorlist.txt
https://mirror.example.net/debian/
https://deb.debian.org/debian/
https://security.debian.org/debian-security/

Swap the example hosts for mirrors that actually serve the same distribution and repository layout. Do not mix a Debian mirror in with an Ubuntu suite, and do not assume a host serving one suite also serves another. This file is configuration, so changing it can affect the very next package operation.

Writing under /etc/apt needs elevated privileges. Keep a backup before you replace an existing file:

$ sudo cp --preserve=all /etc/apt/mirrorlist.txt /etc/apt/mirrorlist.txt.bak
$ sudoedit /etc/apt/mirrorlist.txt

If the file does not exist yet, the backup command just fails safely. Create the new file with your normal editor, then check it back as the unprivileged user:

$ sed -n '1,20p' /etc/apt/mirrorlist.txt
https://mirror.example.net/debian/
https://deb.debian.org/debian/
https://security.debian.org/debian-security/

3. Point a sources entry at the list

For a local list on APT 1.6 or newer, add a source entry using mirror+file. The suite and component still describe the repository you actually want:

deb mirror+file:/etc/apt/mirrorlist.txt bookworm main

The usual source-file rules still apply. Put the entry in a dedicated file such as /etc/apt/sources.list.d/mirror.list, and keep a copy of the old source configuration before you disable it. Do not leave two entries fetching the same indexes unless you deliberately want both acquisition paths running.

For a mirror list served over HTTP, use the modern explicit form:

deb mirror+http://apt.example.org/mirror.lst bookworm main

The older mirror://apt.example.org/mirror.lst spelling does the same job for an HTTP mirror list. APT 1.6 and later prefer mirror+http because it makes the underlying transport visible at a glance.

Checkpoint

Before refreshing package metadata, check the source line names the intended suite and that the list URL or path is actually reachable by the transport named in the entry.

4. Add priorities and metadata only for real constraints

Without a priority metadata item, APT contacts mirrors in random order. Mirrors with the lowest numeric priority go first; mirrors without an explicit priority go last, and mirrors sharing the same priority are still picked randomly among themselves.

Metadata is appended to a mirror URI after a tab, with multiple items separated by spaces or tabs. This list, for example, gives a local mirror first choice for index files, uses a partial amd64 mirror for Debian packages, and leaves general-purpose mirrors as fallbacks:

file:/srv/local/debian/mirror/	priority:1 type:index
https://partial.example.org/debian/	priority:2 arch:amd64 arch:all type:deb
https://mirror.example.net/debian/	type:deb
https://deb.debian.org/debian/	type:deb

The supported filters are arch, codename, component, lang, suite and type. A mirror carrying type:deb is never picked for index files. A mirror carrying arch:amd64 or arch:all is never picked for an architecture outside that set. None of this actually verifies the mirror's contents; it only stops APT choosing a mirror for a request the metadata rules out.

Do not add metadata as decoration. A wrong architecture or type restriction can make a perfectly healthy mirror ineligible and force a slower fallback instead. Local mirrors accessed through file or copy are allowed, but a mirror list fetched over HTTP cannot include local sources, and a mirror list cannot wrap another mirror list or a wrapping transport such as apt-transport-tor.

5. Test the configuration with a controlled refresh

Refreshing package indexes contacts the configured mirrors and writes under APT's package lists directory, so it is a state-changing operation, even though it does not install any packages. It can replace index files and generate real network traffic, so run it when that is acceptable:

$ sudo apt-get update
Hit:1 ...
Reading package lists... Done

The exact mirror and progress lines vary, because selection is random within a priority group. A successful refresh shows APT could pull the required indexes through at least one eligible mirror; it does not prove every mirror is online or complete.

For a first rollout, keep the old source configuration available and change one thing at a time. If the refresh fails after your change, restore the previous source file or remove the new mirror entry, then run sudo apt-get update again. If you made a backup, restore it explicitly:

$ sudo cp --preserve=all /etc/apt/mirrorlist.txt.bak /etc/apt/mirrorlist.txt
$ sudo apt-get update

Restoring the list does not undo any package-list files already downloaded. For a genuinely clean retry, use APT's normal package-list maintenance procedures rather than deleting directories blindly.

Common traps

  • Mirror list will not parse. Check for a missing URI scheme, metadata used on a client older than 1.6, or a filename whose compression suffix does not match its actual contents; APT never detects compression from the file contents itself.
  • A mirror is never contacted. Check its priority and filters. A high explicit number makes it a late fallback. A type, arch, suite or component restriction may be correctly excluding it from the request.
  • All mirrors fail. The transport reports the acquisition error back to APT; it does not repair a broken repository or bypass signature verification for you.
  • Treating HTTP as safe. An HTTP mirror list and HTTP repository mirror carry all the usual risks of HTTP transport. HTTPS protects the connection when configured correctly, but repository authenticity still depends on APT's signed Release metadata and your trust configuration, not on the mirror list.

Done means

  • Version checked, and any 1.6-specific syntax used only on a compatible client.
  • Mirror list valid: one correctly schemed URI per mirror, with comments and blank lines used safely.
  • Sources entry correct, naming the intended suite and component with the right mirror transport.
  • Metadata justified: priorities and filters reflect real availability or content constraints, not guesses.
  • Refresh verified: a controlled sudo apt-get update succeeded, or the previous configuration was restored.
  • Backups kept until the new mirror path has actually been seen working.