===================
Customizing mirrors
===================

.. contents::
   :local:
   :depth: 1


This section explains how you can customize your PyPI or
Anaconda repository mirror.

NOTE: This documentation is for versions of Repository 2.26
and newer. For versions between 2.30 and 2.26, see
:ref:`2.23 documentation <mirrors-anaconda-repository-2.23>`. For
documentation of older versions, please see
:ref:`2.20 documentation <mirrors-sync-configuration-2.2>`.

Before you start
=================

Repository comes with the command line tool ``anaconda-mirror`` to
mirror packages from Anaconda Cloud. An administrator can customize
which packages to mirror by creating a configuration file in
``$PREFIX/etc/anaconda-server/mirror/``, such as
``$PREFIX/etc/anaconda-server/mirror/my-mirror.yaml`` and specifying
that configuration file in the arguments to ``anaconda-mirror``::

  anaconda-mirror --config-file my-mirror

* platforms---valid options are: ``linux-64``, ``linux-32``,
  ``osx-64``, ``win-32`` and ``win-64``.

* package_list.

* python_versions---valid options are: ``2.6``, ``2.7``, ``3.3``,
  ``3.4``, ``3.5`` and ``3.6``.

* license_blacklist---valid options are: ``AGPL``, ``GPL2``, ``GPL3``,
  ``LGPL``, ``BSD``, ``MIT``, ``Apache``, ``PSF``, ``Public-Domain``
  and ``Proprietary and Other``.

* blacklist.

* whitelist.

* accounts---specifies the Cloud accounts that are mirrored. The
  default is the ``anaconda`` account.

* account_mapping---defines what account name the mirror is
  created with. The default is to use the same account name as on Cloud.

  EXAMPLE::

    account_mapping:
      anaconda: anaconda-mirror

* access---defines what permissions mirrored packages have on your
  Repository mirror. Valid options are: ``authenticated``, ``private``
  and ``public``.

* api_domain and api_token---These settings can be used if you
  want to mirror from a different Repository server, or if you
  want to mirror private packages from Cloud.


Mirroring a platform-specific list
==================================

By default, the anaconda-mirror tool mirrors all platforms. If you
know that you do not need all platforms, it saves time and disk space
if you edit the ``yaml`` file to specify the platform(s) you want to
mirror.

EXAMPLE::

  platforms:
    - linux-64
    - win-32


Mirroring a package-specific list
=================================

You may want to mirror only a small subset of Repository. Rather than
blacklisting a long list of packages you do not want to be mirrored, you
can instead simply enumerate the list of packages you do want to mirror.

EXAMPLE: This example mirrors only the three packages Accelerate,
PyQt and Zope. All other packages are ignored::

  package_list:
  - accelerate
  - pyqt
  - zope


Mirroring Python version-specific packages
==========================================

You may want to mirror only a subset of versions.

EXAMPLE: This example mirrors only Anaconda packages built for
Python 3.3::

  python_versions:
  - 3.3


Mirroring with a license blacklist
====================================

As of Repository 2.26.0, the Anaconda mirroring script supports license
blacklisting for the following license families:

* AGPL

* GPL2

* GPL3

* LGPL

* BSD

* MIT

* APACHE

* PSF

* PUBLICDOMAIN

* PROPRIETARY

* OTHER

* NONE

EXAMPLE: This example mirrors all the packages in the repository
except those that are GPL2-, GPL3- or BSD-licensed::

  license_blacklist:
    - GPL2
    - GPL3
    - BSD

NOTE: Older versions of Anaconda mirror support only license
blacklisting for GPL. If you are using an older version of
Repository, see the documentation for :ref:`customizing your
PyPI or Anaconda Repository mirror
<mirrors-sync-configuration-2.2>`.


Mirroring with a blacklist
============================

The ``blacklist`` allows access to all packages except those
explicitly listed.

EXAMPLE: This example mirrors the entire Repository except the
bzip2, tk and openssl packages::

  blacklist:
    - bzip2
    - tk
    - openssl


Mirroring with a whitelist
============================

The whitelist functions in combination with either the
license_blacklist or blacklist arguments, and re-adds packages
that were excluded by a previous argument.

EXAMPLE: This example mirrors the entire Repository except any
GPL2- or GPL3-licensed packages, but including readline, despite
the fact that it is GPL3-licensed::

  license_blacklist:
    - GPL2
    - GPL3
  whitelist:
    - readline


Combining multiple mirror configurations
========================================

You may find that combining two or more of the arguments above is the
simplest way to get the exact combination of packages that you want.

The platforms argument is evaluated before any other argument.

EXAMPLE: This example mirrors only linux-64 distributions of the
dnspython, shapely and gdal packages::

  platforms:
    - linux-64
  package_list:
    - dnspython
    - shapely
    - gdal

If the license_blacklist and blacklist arguments are combined,
the license_blacklist is evaluated first, and the blacklist is
a supplemental modifier.

EXAMPLE: In this example, the mirror configuration does not
mirror GPL2-licensed packages. It does not mirror the
GPL3-licensed package PyQt because it has been blacklisted. It
does mirror all other packages in Repository::

  license_blacklist:
    - GPL2
  blacklist:
    - pyqt

If the blacklist and whitelist arguments are both employed, the
blacklist is evaluated first, with the whitelist functioning
as a modifier.

EXAMPLE: This example mirrors all packages in the repository
except astropy and pygments. Despite being listed on the
blacklist, Accelerate is mirrored because it is listed on the
whitelist::

  blacklist:
   - accelerate
   - astropy
   - pygments
  whitelist:
   - accelerate
