Package: apt-cacher-ng Version: 0.3.3-1 Severity: wishlist Hi,
I found apt-cacher-ng's documentation very difficult to read (although I don't normally have problems understanding English text :). Especially the part about configuration and URL remapping is somewhat dense. Some examples and suggested rephrasings: > "Repository": the tree in the local cache designated for file storage. May > be identical with the hostname of a mirror, but does not need to. In the > last case, a backend definition must be provided. " Neither a tree nor a repository can be identical to a hostname, so the first sentence doesn't even make sense, strictly speaking. Maybe what you mean is the following: "Repository: the internal identifier of a local cache directory. If it doesn't match the hostname of an actual mirror, you need to provide a backend definition (see below)." Even so, 3.2 leads me to believe that in order for a backend definition to be unnecessary, it is not the repository name that has to match the hostname of a mirror but the base path. > "Backend": description of a remote side as URL or combination of host and > base directory, to look for the files stored under it. Backends are > defined as part of remapping scheme, see section 3.2. I suggest instead: "Backend: a text file consisting of a list of mirror URLs, one per line (a more complex RFC822-like format is also supported). Used for URL remapping; see section 3.2." It would be useful to point out what happens if the backend definition contains more than one backend. Are they tried in the order specified, falling back to the next one if the last one failed? Is the fastest backend chosen somehow? Maybe you use round-robin? Or choose randomly? Are several used in parallel? > "Volatile files": Volatile files provide information about others > contained on the particular side, i.e. Packages, Sources and Pdiff index > files. "apt-get update" fetches newer copies of them, for example. > Volatile files are always object to change. NOTE: The might be referred to > as "the index files" in program messages. The use of "side" instead of "site" is always confusing. I suggest the following rewording: "'Volatile' files: nothing to do with debian-volatile, sorry about the confusion. Any metadata pertaining to package files stored in a remote repository is classified as 'volatile'. This includes Packages, Sources, Release, Pdiff and similar files. Program messages sometimes refer to them as 'index files'." > "Package files": Those are all other files considered being a software > package supported by ACNG. Are not allowed to change on the remote after > the first download has begun, expect trouble otherwise. This is more or less OK, but I think the following would be clearer: "'Package files': files that contain software packages; .debs and the files that make up a Debian source package (.tar.gz, .diff, .dsc)." I can't rephrase the second sentence because I don't understand it. The first download of what, by whom, from where? > 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. I suggest: "Apt-cacher-ng takes its configuration from configuration files and from the command line." Also, I'd move this sentence into the next paragraph (make it the first sentnce of the first paragraph after the 3.1 heading). > The main configuration files are located in one single directory. Three > types files are recognized (by suffix) and interpreted by the following > schema. [...] I suggest: "By default, the /etc/apt-cacher-ng directory contains all config files, HTML page templates, the stylesheet and other text-based support files used by apt-cacher-ng. *.conf files are assumed to contain configuration directives in the form of "key: value" pairs. The package comes with a commented example configuration file. apt-cacher-ng reads all files matching *.conf in alphabetical order and merges the contents. Lists of remote package repositories (i.e. mirrors) can be specified in one of two formats: - simple text files with one URL per line (the URL should point to the base directory of the repository, e.g. "http://ftp.de.debian.org/debian/";) - in an RFC822-like format, with lines like 'Site: <hostname>' and 'Archive-http: /base/directory/of/repository/'. The meaning of the fields is explained in section XXXXX. Apt-cacher-ng autodetects the format of the list." > All must begin with http:// and end with a / (slash). As installed, the only line in backends_debian doesn't end with a slash (it just reads "http://ftp.hu.debian.org/debian";), so either this is wrong or the postinst is wrong. Section 3.2 is where it gets extremely hard to follow. I'll try to provide my own version here, but I'm not sure I understood the original correctly. I'll also pepper it with questions the original left unanswered (I'll put these in [brackets]). --- >8 --- "3.2 Repositories and URL remapping URL remapping has several uses. First, it allows your apt-cacher-ng based proxy to masquerade as a Debian or Ubuntu mirror; it can be made to appear to contain the same directory structure and files the client would find on a real mirror. Instead of referencing a real mirror, the client's sources.list file would contain a line like 'deb http://name.of.proxy.host/debian stable main'. Your backend definition in apt-cacher-ng's configuration determines which actual debian mirror will be used to fetch the files. This keeps the client configuration clean, simple and straightforward. Without URL remapping, the sources.list file on the client would have to read something like 'deb http://name.of.proxy.host/ftp.de.debian.org/debain stable main'. Note that, depending on the remapping configuration, it is possible that apt-cacher-ng will actually use a mirror other than ftp.de.debian.org even in this case (see below). [Is this right?] A second use is obscuring the real location of a repository from your clients. This allows you to change the real location easily, without having to modify the configuration of all clients; you just have to edit the backend configuration in one single place. You configure URL remapping with lines like the following: Remap-debian: http://ftp.de.debian.org/debian This is the simplest case. When a client asks for http://proxy.host/ftp.de.debian.org/debian/something, apt-cacher-ng fetches http://ftp.de.debian.org/debian/something. [Is this right?] Slightly more complex examples: Remap-ubuntu: /ubuntu ; http://us.archive.ubuntu.com/ubuntu Remap-medibuntu: /medibuntu ; http://packages.medibuntu.org These two examples specify trivial mappings. Whenever a client asks for http://proxy.host/ubuntu/foo, apt-cacher-ng will retreive http://us.archive.ubuntu.com/ubuntu/foo. When a client wants http://proxy.host/medibuntu/bar, apt-cacher-ng fetches http://packages.medibuntu.org/bar. This is still relatively simple. More complex remappings are also possible. A "Remap-" line contains three pieces of information: 1. A unique internal identifier for the remapping ruleset specified by the line; in the examples above, "ubuntu" and "medibuntu". These identifiers have no meaning; we could just as well have chosen "blarg" and "deedledum". Restrictions: the identifier must be valid as a filename; it mustn't begin with an underscore; and it mustn't contain whitespace. This is the part of the line between "Remap-" and the first colon (':'). 2. A list of pathnames to apply remapping to. These can be specified directly, separated by spaces, but apt-cacher-ng can also read them from files. Large lists of pathnames to remap are handled efficiently. You can use "file:filename" to read a list of pathnames from "filename". Filename can be absolute, or relative to the configuration directory. You can mix files and literal pathnames in the list. Pathnames mustn't contain wildcards, but "file:" specifications may. apt-cacher-ng can decompress .gz and .bz2 files. A leading "http://"; in pathnames is replaced by a single "/". This is the part of the line between the first colon and the first semicolon (';'). 3. A list of backend servers to fetch the files from, whenever clients request a file from a remapped path. Backend lists are specified the same way as path lists. Example: Remap-debrep: file:deb_mirror*.gz /debian ; file:backends_debian This causes apt-cacher-ng to read a list of debian mirrors from all files matching "deb_mirror*.gz" and construct a list of pathnames consisting of entries like /ftp.de.debian.org/debian /ftp.kfki.hu/linux/debian and so on. The last element of the list will be simply /debian. All these paths will be remapped to paths read from backends_debian, which can contain the base URL of a single Debian mirror, or several URLs, one per line. [What happens when there are several?] The same RFC822-like format deb_mirrors.gz is supplied in is also supported, so you could just make backends_debian a subset of deb_mirrors.gz. Client sources.list files could specify either of the following and still actually use the mirrors from backends_debian: - 'deb http://proxy.host/arbitrary.official.debian.mirror/basepath stable main' - 'deb http://proxy.host/debian stable main' [Would transparent proxying work? I.e. could you just redirect requests to port 80 of debian mirrors to the port of apt-cacher-ng?]" --- 8< --- What I think is missing from the documentation: - description of the fields in the RFC822 files; - explanation of how a backend to download from is chosen if more than one is specified; - an explanation of the unix socket thing; - an explanation of ForceManaged (based on 3.2 one is under the impression that only remapped paths are supported anyway). Please feel free to include whatever I wrote in the documentation verbatim if you like it. Best regards, Andras -- Andras Korn <korn at chardonnay.math.bme.hu> <http://chardonnay.math.bme.hu/~korn/> QOTD: A kormany ol, butit, es nyomorba dont! -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
