[[!meta title="HTTP mirror pool"]]

# Big picture

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

* We have dispatcher code, in JavaScript, that DAVE uses to dynamically modify the
  hostname, in the download link it gets from the ISO description file
  (IDF), so that each user is pointed to random mirror.
  - [public read-only mirror of the Git repository](https://git-tails.immerda.ch/mirror-pool-dispatcher/)
  - Vanilla JS (no frameworks)
  - The code is deployed live: <https://tails.boum.org/lib/js/mirror-dispatcher.js>
  - The library code has three consumers:
    * a Firefox extension (DAVE)
    * our website, for downloads we offer outside of the Installation
      Assistant, that are not supported by DAVE, such as images for
      release candidates; and in any case, for browsers that DAVE does
      not support
    * Tails Upgrader, that runs the library code with Node.js
  - Configuration for the JS is loaded from a JSON file hosted on our
    website.
    See [[the configuration section|mirrors#configuration]]
    for details.

* A DNS Round Robin pool that 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
  (`dl.amnesia.boum.org`). This fallback DNS pool is used:
  - by people who do not use JS, when downloading from our website;
  - for the [[wget download option|install/expert/usb]].

<a id="configuration"></a>

# 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
([[!tails_gitweb_repo mirror-pool desc="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
     `http://dl.amnesia.boum.org/tails`
   - in the new mirror pool design, this could be e.g.
     `http://42.dl.amnesia.boum.org/tails` (for mirrors who want to
     use the unique VirtualHost we provide them), or something they
     deal with themselves, e.g. `https://mirrors.kernel.org/tails`

 * 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](https://git-tails.immerda.ch/mirror-pool/tree/schema.json).

Here is
[an example configuration file](https://git-tails.immerda.ch/mirror-pool/tree/example-mirrors.json).
