Build a resilient APT mirror list with apt-transport-mirror

You will configure APT to choose from several repository mirrors and retry another mirror when a download fails. You will also see how to keep a partial mirror away from packages it does not contain, and how to check the configuration without installing or removing anything. Allow about fifteen minutes. The examples use APT 2.8.3, installed on this machine as package version 2.8.3.

apt-transport-mirror is not normally run as a standalone command. APT invokes it when a source entry uses the mirror transport. The work therefore happens in a mirror-list file and in a sources-list entry.

1. Check the installed APT version

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

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

Your version and repository lines will differ. The relevant boundary is APT 1.6. Metadata-enhanced mirror lists, compressed mirror lists and the mirror+file and mirror+http forms described here require that version or newer. Basic mirror transport support starts at APT 0.7.24. Older clients also have stricter transport support, so do not copy a metadata example to an old machine without checking its installed manual.

2. Create a plain mirror list

A mirror list contains one URI per line. Blank lines and lines beginning with # are ignored. Each URI must include its scheme because that scheme selects the transport used for the actual repository request.

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

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

Writing under /etc/apt needs elevated privileges. Keep a backup before replacing 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 already exist, the backup command will fail safely. Create the new file with your normal editor, then inspect it 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 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 retain a copy of the previous source configuration before disabling an old entry. Do not leave two entries that fetch the same indexes unless you deliberately want both acquisition paths.

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 has the same function for an HTTP mirror list. APT 1.6 and later prefer mirror+http because it makes the underlying transport visible.

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 are tried first. Mirrors without an explicit priority are placed last, and mirrors with the same priority are still chosen randomly.

Metadata is appended to a mirror URI after a tab. Separate multiple items with spaces or tabs. For example, this list 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 not selected for index files. A mirror carrying arch:amd64 or arch:all is not selected for an architecture outside that set. These filters do not verify the mirror contents; they only prevent APT from selecting a mirror for a request that the metadata excludes.

Do not add metadata as decoration. A wrong architecture or type restriction can make a healthy mirror ineligible and force a slower fallback. If the local mirror is accessed through file or copy, local mirror URIs are allowed. 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. It does not install packages, but it can replace index files and produce network traffic. 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 that APT could acquire the required indexes through at least one eligible mirror. It does not prove that every mirror is online or complete.

For a first rollout, keep the old source configuration available and make one controlled change at a time. If the refresh fails after the change, restore the previous source file or remove the new mirror entry, then run sudo apt-get update again. If you created 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 package-list files already downloaded. If you need a clean retry, use APT's normal package-list maintenance procedures rather than deleting directories blindly.

6. Diagnose the common traps

If APT reports that a mirror list cannot be parsed, check for a missing URI scheme, metadata on a client older than 1.6, or a filename whose compression suffix does not match its contents. Compressed mirror lists are supported from APT 1.6, but the filename must identify the algorithm. APT does not detect compression from the file contents.

If a mirror is never contacted, inspect its priority and filters. An explicit high number makes it a late fallback. A type, arch, suite or component restriction may correctly exclude it from the request. If all eligible mirrors fail, the transport eventually reports the acquisition error to APT; it does not repair a broken repository or bypass signature verification.

Security depends on every transport involved. An HTTP mirror list and HTTP repository mirror are exposed to the risks of HTTP transport. HTTPS protects the connection when correctly configured, but repository authenticity still depends on APT's signed Release metadata and your trust configuration. Treat a mirror list as routing input, not as a replacement for repository verification.