Mirrorbits: a software CDN that redirects to the nearest mirror

What the redirector actually does

Mirrorbits is a geographical download redirector written in Go for distributing files efficiently across a set of mirrors. It offers a simple and economic way to create a Content Delivery Network layer using a pure software stack, and it is primarily designed for the distribution of large-scale open source projects with a lot of traffic.

The model is simple. You register your mirrors, each with the protocols a client can reach it on, and Mirrorbits sits in front. A client asks for a path, Mirrorbits decides which mirror should serve it, and answers either with a JSON document describing the mirrors or with an HTTP redirect. The client then fetches from the mirror directly, so the bandwidth goes from the mirror rather than from the redirector.

That is the whole trick, and it is why the readme leads with the performance figure rather than a feature list. It claims to be blazing fast and able to reach 8K QPS on a single laptop, and the reason is that serving a redirect is a cheap operation while serving a file is not.

The choice of what to redirect to is the interesting part. The decisions are made in realtime based on location, AS number and defined rules, and there is smart load-balancing over multiple mirrors in the same area to avoid hotspots, plus the ability to adjust the weight of each mirror. You can limit access to a country, region or ASN for any mirror, which is how a project keeps traffic inside a network it has a formal relationship with.

The secondary capability is that it can disable misbehaving mirrors without human intervention, which matters when a mirror silently starts serving corrupt or truncated files and you have no monitoring on it.

A production track record across a decade of projects

The readme answers the question of whether it is production ready with a single emphatic word, yes, and then backs it with a list.

It has served billions of files already, and the projects running it include Blender, since July 2026, and its mirror infrastructure wiki. CarbonROM runs it. The Chaos Computer Club uses it to distribute media. Endless OS uses it. Jellyfin has used it since April 2021. Jenkins has distributed Jenkins releases through it since February 2020. Kali Linux has distributed packages and images through it since December 2023. Kodi, previously XBMC, has used it since July 2015, which is the oldest entry on the list. LineageOS, previously CyanogenMod, since January 2017. MariaDB has distributed its deb and rpm packages for Linux distributions through it since December 2021. MSYS2 since June 2021. OSMC runs it. VideoLAN has distributed the VLC media player through it since April 2014, and the readme links a post announcing that the project moved to GitHub at that time.

A previous projects list names Parrot OS, Popcorn Time and SuperRepo as having used it.

That list is more informative than a benchmark would be, because each entry is a project with a real release cadence and a real audience, and several of them, VLC and Kodi especially, distribute large binaries to users on slow connections. A tool that redirects well matters most exactly there.

The caveat is in the same paragraph. Some things might change before the 1.0 release, and if you intend to deploy Mirrorbits in a production system it is advised to notify the author first so they can help you make any transition as seamless as possible.

That request is unusual and worth taking seriously, since the project is clearly a single-maintainer effort with a long history and a stable user base, and a major version bump would otherwise land on every deployment at once.

The prerequisites, and the GeoIP2 requirement

The dependency list is short and tells you what the tool needs to do its job.

Go 1.18 or later. Protobuf, protoc. Redis 3.2 or later with persistence enabled. And GeoIP2 databases from Maxmind, preferably updated regularly. Optionally, redis-sentinel for high availability support.

The GeoIP2 requirement deserves a note, because the readme issues a warning about it: GeoIP-legacy is not supported anymore, please use the new GeoIP2 mmdb databases. That is a hard break for anyone who set this up years ago, and the readme says so rather than leaving you to discover it when the daemon fails to start.

The reason the tool needs a GeoIP database at all is the location matching. Deciding which mirror to send a client to means knowing where the client is, and that is what the Maxmind city and country and ASN databases give you. The Dockerfile makes the operational side concrete: it installs geoipupdate, writes an account ID and a license key into /etc/GeoIP.conf, sets the edition IDs to GeoLite2-City, GeoLite2-Country and GeoLite2-ASN, creates the database directory and runs geoipupdate to fetch the databases at build time. The ASN edition matters because the AS number is one of the three inputs to the routing decision.

Redis is the other significant dependency, and it is not just a cache. The redis-sentinel support gives high availability for the database, and the clustering feature depends on all instances sharing the same Redis server, so that node discovery works automatically.

Building it and running the daemon and the CLI

You can take a prebuilt release or build it yourself, and the manual build is three commands:

$ git clone https://github.com/etix/mirrorbits.git
$ cd mirrorbits
$ sudo make install

The resulting executable lives in your /usr/local/bin directory, and you can override the location with PREFIX or DESTDIR:

sudo make install PREFIX=/usr

The Makefile shows the details that matter for an operator. The version and build identifiers are stamped into the binary at link time from git describe and the short commit hash, with the branch name included, and the templates path is baked in as well, so a package build can point the binary at the templates installed under a prefix. There are install and uninstall targets, and systemd service install and uninstall targets, with the service directory detected through pkg-config so the unit lands in the right place on the distribution you build for.

At runtime the binary is both the server and the command line tool. The daemon is started with:

mirrorbits daemon

And the CLI is invoked with:

mirrorbits help

Adding and enabling a mirror uses the same binary:

mirrorbits add -ftp="ftp://ftp.mirrors.example/myproject/" -http="http://ftp.mirrors.example/myproject/" mirrors.example

mirrorbits enable mirrors.example

A mirror is registered with the protocols clients should use for it, and then explicitly enabled, so registering and activating are separate steps.

There is also a seamless binary upgrade mode, which lets you replace the server executable at runtime without service disruption. Once the binary has been replaced on the filesystem, you issue the upgrade command in the CLI:

mirrorbits upgrade

For a service in front of a busy download site, that is a genuinely useful feature, because the alternative is coordinating a restart across the user base's request pattern.

The introspection queries, and the reverse proxy caveat

Two query arguments turn the redirector into something you can inspect, and both are documented with live examples.

By appending ?mirrorlist to any file served by Mirrorbits, you get realtime information about the given file, and the readme links a live example pointing at a VLC Windows installer. The ?mirrorstats argument gives realtime mirror statistics, with a live example at the root of the same host. For a project whose whole job is distributing binaries, being able to see which mirrors have a given file and how the mirrors are doing is the operational information you need, and exposing it through the same HTTP interface as the redirect is a small design decision that saves a separate monitoring surface.

The consideration section is where the sharp edges are, and the first one is about deployment. When configured in redirect mode, Mirrorbits can easily serve client requests directly, but it is usually recommended to set it behind a reverse proxy like nginx, and in that case you have to pass the IP address of the client within an X-Forwarded-For header:

proxy_set_header X-Forwarded-For $remote_addr;

That is not optional decoration. The whole routing decision depends on knowing where the client is, and behind a proxy without that header every request looks like it comes from the proxy's address, which would send all the traffic to one mirror.

The second consideration is about caching: it is advised to never cache requests intended for Mirrorbits, since each request is supposed to be unique, and caching the result might have unexpected consequences. The reason follows from the design. The redirect is computed per request from the client's location and the current state of the mirrors, so a cached answer is a stale answer, and a CDN in front of a CDN is the kind of arrangement that produces confusing behaviour rather than performance.

The feature list also mentions complete checksum and size control, support for partial repositories, realtime statistics per file, mirror and date, realtime reconfiguration, automatic fixing of timezone offsets for broken mirrors, If-Modified-Since support under RFC-7232, full IPv6 support, and Mirmon support for the mirror monitoring ecosystem.

Editorial conclusion

Adopt Mirrorbits if you distribute large files to a wide audience and want to hand each client a nearby mirror rather than pushing bandwidth yourself, and you have Redis and a GeoIP2 database to run. Do not adopt it if you have a handful of users, because it is built for high traffic mirrors, and be aware it is pre-1.0, so the readme asks you to notify the author before deploying in production. Before you commit, read the upgrade guide and the configuration sample, decide whether redirect mode or JSON mode fits your clients, and put it behind a reverse proxy that passes the client address correctly.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. videolabs/mirrorbits on GitHub