First, some vocabulary:
Apt-Cacher-Ng can be configured by command line arguments or in its configuration file. Some extra configuration files can be included and automatically used, see next chapters for details.
The main configuration files are located in one single directory. Three types files are recognized (by suffix) and interpreted by the following schema.
Site: <hostname>
Archive-http: /base.directory/
(Optional fields are also used in remap descriptions, Alias, Aliases, X-Archive-http:).
For details about repository mapping, see sample config files shipped with the package. Basic syntax is one single line containing:
Remap-<repository_name>: /basepath/ file:list.txt ;
backendhost/dir file:where.txt
<repository_name> therein is an arbitrary name chosen by the administrator used to identify the repository in the local cache. It must be clearly different than any possible hostname and must not begin with an underscore (for internal reasons). Examples: project_foo_mirrors or ubuntu_stuff.
NOTE: unlike with some other APT proxy, repository_name does NOT represent any mandatory URL prefix that you need to put into every sources.list. It's only relevant for the internal processing.
The second part of the directive (between : and ; or end of line) consists of path prefixes that needs to be matched against the incoming URL to activate this rule. No wildcards are allowed, the path prefix needs to end with the last directory in the path. When a rewrite rule for a directory is specified here, all files accessed below this directory are stored in the local repository under a location relative to the rewrite path. Therefore special care about identical path level is required when trying to canalize access to multiple download locations into the same cache repository. To avoid cluttering of the configuration file with many URLs, it's possible to specify them in a separate file, for details see Notes below.
Also note that the hostname of the requested URLs is moved to the first path component, therefore it's required to include it in the path prefix spec when remapping access to certain machines. However, no real hostname must be specified when a list of backend servers is configured (see below). This method (similar to techniques used by some other APT proxies) allows to create a shortcut for the users so they don't need to specify (select) a certain Debian mirror.
Examples: /some-actively-used-old-server-name/debian or ftp.ubuntu.com/ubuntu/ or /debian/.
The last part of the Remap-... directive, appended after a semicolon, describes locations to download from. This part is optional if the first part contains only real locations and mandatory if shortcuts are used there.
The format is basically the same as in the first part. The subdirectory name and depth must match the URLs specified there exactly. For example, when the rewrite rule specifies "http://ftp.debian.org/debian" and some local mirror offers the data from that URL in "http://192.168.0.17/pub/mirrors/ftp.debian.org/debian" then the rewrite rule might be:
Remap-Something: http://ftp.debian.org/debian
; http://192.168.0.17/pub/mirrors/ftp.debian.org/debian
in one single line.
Notes:
If no repository is specified, the local storage space is derived from the request URL. If no backend is specified (with or without repositories specification) then the site in the request URL is used to download from, otherwise one of the backends after calculating the new real URL relatively to the backend description.
Use of predefined repositories is recommended. Large remapping lists (for many popular Debian mirrors) are supported quite efficiently; assigning them all into the same repository increases the probability of sharing the data between users that try to use different mirrors. The backends list can be customized to ensure that few locally best reachable mirrors are used to download from.
Some things are discouraged and should or must not be used in local configuration for backwards compatibility or other reasons: