Get Gentoo!
  1. Master Index
  2. General Concepts

Mirrors

Automatic Mirroring

Packages will automatically have their SRC_URI components mirrored onto Gentoo mirrors. When fetching, Portage checks Gentoo mirrors first before trying the original upstream location.

This is generally desired behaviour — upstream mirrors are prone to being rearranged, tidied out or having files modified.

Restricting Automatic Mirroring

Three RESTRICT keywords can be used to control the mirroring process.

The RESTRICT="mirror" setting should be used if we cannot legally mirror certain files; files will still be downloaded from the original locations.

The RESTRICT="primaryuri" setting causes Portage to try original locations first, and then fall back to mirrors if necessary — this is sometimes useful if approximate download counts are needed, or if upstream have a reliable mirror setup.

There is also RESTRICT="fetch", which prevents Portage from trying to fetch anything manually. The pkg_nofetch function will be called if any SRC_URI components cannot be found. This should only be used if a license requires it.

Replacing Automatically Mirrored Files

On rare occasions you may need to replace a file that is already mirrored. In this case proceed as follows:

  1. Put a copy of the new distfile on dev.gentoo.org into /space/distfiles-local
  2. commit the new manifest to the git tree
  3. wait
After a few hours a cron job on dev.gentoo.org will fetch the file and replace the version on the mirrors. The file will be automatically removed from /space/distfiles-local after approximately two weeks.

More general information about the internals of mirroring can be found on infrastructure's pages.

Suitable Download Hosts

If you have to host a source file (patch or tarball) yourself, as long as it is suitable to be distributed by Gentoo Foundation (by license and legality), you're suggested to use your developer's space at dev.gentoo.org. Since external overlays may depend on your patches/tarballs, using the dev space at dev.gentoo.org keeps the distfiles at a stable and reliable infrastructure. If you retire, other developers can take over your distfiles and place them into their own devspace.

Previous policy was to use mirror://gentoo directly, but this is now deprecated, as that wouldn't allow to have long-term availability and traceability of the source files, which might be a requirement of the license.

When you upload the file to dev.gentoo.org:~/public_html, you must ensure that it, and its parent directories, are world-readable.

Gentoo Mirrors

To manually upload a file to mirror://gentoo, scp it to dev.gentoo.org:/space/distfiles-local. The file should appear on the mirrors within four hours (note that this is less frequent than Git to RSYNC). If the upstream download location for a package uses a non-standard TCP port (anything other than 21, 80 or 443), you must manually mirror the files. Not doing so can cause all kinds of problems with strict firewalls.

Mirroring Process

Mirroring Process

Diagram showing the mirroring process.