Balancing the downloads between mirrors requires the use of a script.
A standard mechanism has been created that allows scripts to be easily created
which will not only comply with mirroring distribution policy but also take
advantage of more advanced features such as intelligent selection of a preferred mirror.
This mechanism is described below.
There are two basic options available:
-
The generic download script is quick to setup but is linked from
(rather than integrated with) the project documentation.
-
A project specific script which is integrated with a page created
in the normal way for the project and which uses the project's standard document look and feel.
This option takes more time to setup.
The starting point for a generic script is a download page. This is just a
page in the standard documentation which describes the releases. To use the
generic script, this page needs to be altered so that the actual download links
to the generic script in the appropriate fashion.
The generic script is called closer.cgi. The relative path of the distribution
(from the distribution root to the artifact) needs to be passed in as a parameter. So (for
example) if the artifact is foo-5.5.1.zip and is located in bar/foo
relative to /www/www.apache.org/dist then
http://www.apache.org/dyn/closer.cgi/bar/foo/foo-5.5.1.zip will display the mirrored
distribution for download.
Note there is some information which every project should include on the
download page. Please read best practices.
To create a project specific download page, two elements are needed:
-
a wrapper cgi script (for the standard python mirroring script)
-
a project page (containing information to be presented to the user
together with variables to be replaced by the script)
The script takes the path to
the project page as an input and passes this to the standard mirroring script. The standard
script then reads the page and uses information about the mirrors to substitute values for
the varibles. When linking to the project page (for example, from the rest of the project
documentation), it is important that these links are targeted at the script address (and not
the page address).
Conventionally, the wrapping script is called download.cgi. This should be created
in the same directory as the project page. This wrapper script just needs to set
up the correct directory and call the mirroring script. The following will do:
#!/bin/sh
# Wrapper script around mirrors.cgi script
# (we must change to that directory in order for python to pick up the
# python includes correctly)
cd /www/www.apache.org/dyn/mirrors
/www/www.apache.org/dyn/mirrors/mirrors.cgi $*
The release download page should be generated in the same way as the rest of the project
documentation. By convention, the name of the output should be download.html.
Note: the mirroring script guesses the download release page to be processed
by matching file names. There is no requirement to call the script download.cgi
and the download release page download.html but the name of the script must
correspond to the name of the download page. For example, release.cgi and
release.html will work but download.cgi and release.html
will not.
There are a number of elements that a
good project download page should contain.
The content used to generate that page can be viewed
here.
Downloads of artifacts linked to a mirror by an variable url. The correct mirroring base url
will be substituted for the [preferred] variable. The rest of the url should be
the path to the artifact relative to the base of the Apache distribution directory.
For example, for artifact foo-1.0.0.tar.gz contained in bar/foo
should use [preferred]/bar/foo/foo-1.0.0.tar.gz
Links to the checksum and signature for the artifact should be given next to the download link.
It is important that users check the sum and verify the signature so these links should be
close and clear. Note: these documents must not be mirrored.
For example, for artifact foo-1.0.0.tar.gz contained in bar/foo:
<a href="[preferred]/bar/foo/foo-1.0.0.tar.gz">zip</a>
<a href='http://www.apache.org/dist/bar/foo/foo-1.0.0.tar.gz.md5'>MD5</a>
<a href='http://www.apache.org/dist/bar/foo/foo-1.0.0.tar.gz.asc'>PGP</a>
Users should also be given information about the mirrors and the chance to choose a different
mirror (if they prefer). This is a little complex to describe so here is a typical script:
<p>[if-any logo]
<a href="[link]"><img align="right" src="[logo]" border="0" /></a>[end]
The currently selected mirror is <b>[preferred]</b>. If you encounter a
problem with this mirror, please select another mirror. If all
mirrors are failing, there are <i>backup</i> mirrors (at the end of
the mirrors list) that should be available.</p>
<form action="[location]" method="get" id="SelectMirror">
Other mirrors: <select name="Preferred">
[if-any http]
[for http]<option value="[http]">[http]</option>[end]
[end]
[if-any ftp]
[for ftp]<option value="[ftp]">[ftp]</option>[end]
[end]
[if-any backup]
[for backup]<option value="[backup]">[backup] (backup)</option>[end]
[end]
</select>
<input type="submit" value="Change" />
</form>
<p>You may also consult the <a href="http://www.apache.org/mirrors/">complete
list of mirrors</a>.</p>
More advice on creating a good project page is given below
Once the download page and the script have been uploaded to the project website (in the usual
manner), make the script executable. For example:
% chmod a+x download.cgi
All that remains is to wait for the main website to sync.