Big picture

The Tails downloads are served using two different mirror pools, depending on the use case:

JSON pool

A dispatcher code in JavaScript dynamically modifies the hostname in the URL of our ISO image, so that each user is pointed to random mirror.

DNS pool

A DNS Round Robin pool points to a few (3-7) fast and reliable mirrors. It is the fallback for some use cases. So we still have a DNS dynamic update system, re-purposed from the one we already had ( This fallback DNS pool is used:

Mirror pool configuration

The client dispatcher code fetches the mirror pool configuration file from our website:

The configuration file is written in JSON, to avoid the need to use a third-party parser.

The configuration file is stored in a dedicated Git repository (public read-only mirror), that is added to our website with the ikiwiki underlay mechanism. Using a separate Git repository gives us finer-grained access control possibilities in the long run, e.g. we may want to let people who don't have commit access to Git maintain the mirrors pool. Note that we'll need to serve the configuration file from outside our website if we ever want to do so: an underlay can affect our website in ways that are probably (almost?) as bad as what one can do with Git access to the website itself.

The configuration file is essentially a list of mirrors, and for each of them we need a few values:

  • url_prefix: whatever needs to be pre-pended to the path to an ISO (e.g. /stable/tails-i386-2.0/tails-i386-2.0.iso) that is shared between all mirrors, to form a complete URL to that ISO; for example:

    • in the old mirror pool design, this would be
    • in the new mirror pool design, this could be e.g.
  • weight: the probability this mirror has to be picked by the dispatcher code, expressed as a non-negative integer; weight 0 means that the mirror is currently disabled, and will never be redirected to

  • email (optional): the email address of the mirror's operator

  • notes (optional): various additional notes that can be useful to the managers of the mirror pool

For a more formal, and probably more up-to-date definition of the data model, better see its JSON schema.