Celebrating 20 years of community-led development "The Apache Way"
A release download page is the page that links the project's content to the mirrored artifact download. This document aims to describe the various options available to projects for download pages together with policy and best practices. (Background about the policy is in a separate document.) Release managers are the target audience.
Help to finish this document by contributing documentation patches ! If the information you seek isn't in this document, then please submit a patch once the infrastructure folks have answered your question.
Only release artifacts that have been approved by the relevant PMC may be linked from the download page.
Do not link to dist.apache.org
The download page must include a link to the source distribution. It may include links to binary distributions.
Links to the mirrored distribution artifacts must not reference the main Apache web site. They should use the standard mechanisms to distribute the load between the mirrors. See below for details.
All links to checksums, detached signatures and public keys must reference the main Apache web site and should use https:// (SSL). For example: https://www.apache.org/dist/httpd/KEYS
Old releases should be archived and may be linked from the download page.
All official pre-releases (e.g. milestones, alphas, betas) must removed in a timely fashion once the final or GA version has been released.
Your Apache Download Page...
...must have at least one link to the current release. This link must use the "closer" utility. For example: https://www.apache.org/dyn/closer.lua/PROJECT/VERSION/SOURCE-RELEASE
...must have a link to the checksum and hash for the current release. These links must use direct links to the Apache distribution server. For example: https://www.apache.org/dist/PROJECT/VERSION/HASH-OR-CHECKSUM
...must have a link to the keys file for your project. This link must use direct links to the Apache distribution server. For example: https://www.apache.org/dist/PROJECT/KEYS
...should have instructions on how to verify downloads. For this you can include a link to the Apache documentation on verification: http://www.apache.org/info/verification.html
...must not include a link to the top level "closer" utility (e.g. http://www.apache.org/dyn/closer.cgi/PROJECT) as the KEYS, sigs and hashes are missing, as are any verification instructions.
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
will display the mirrored distribution for download.
As an alternative, one can generate a direct download link using the following syntax:
See below for how to generate a customised page of direct links using a mirror.
Note there is some information which every project should include on the download page (e.g. KEYS, sigs, hashes). 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 around the standard mirrors.cgi script exec /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
Note: the mirroring script guesses the download release page to be
processed by matching file names. There is no requirement to call the
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
release.html will work but
release.html will not.
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
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
<a href="[preferred]/bar/foo/foo-1.0.0.tar.gz">zip</a> <a href='https://www.apache.org/dist/bar/foo/foo-1.0.0.tar.gz.md5'>MD5</a> <a href='https://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:
<a href="[link]"><img align="right" src="[logo]" border="0"
The currently selected mirror is <b>[preferred]</b>. If you
problem with this mirror, please select another mirror. If all
mirrors are failing, there are <i>backup</i> mirrors (at the
the mirrors list) that should be available.</p>
<form action="[location]" method="get" id="SelectMirror">
Other mirrors: <select name="Preferred">
[for http]<option value="[http]">[http]</option>[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
BEFORE the download script has been committed, make it executable.
The CMS will not honor propset changes post-initial-commit, so if you forget
this step please make the needed property changes on both the staging
and production svn trees. See CMS Reference for details.
Of course this caveat only applies to CMS sites; sites that use svnpubsub exclusively
will apply propset changes automatically as soon as they are committed.
All that remains is to wait for the main website to sync.
% svn propset svn:executable '*' download.cgi
% svn commit
Apache releases are downloaded from mirrors. It is therefore important that users understand that they should always check the hash sums and (if possible) also verify the OpenPGP compatible signature. The content of the release download page plays a critical role in this education process.
Please provide clear and easy links to the KEYS, sums and signatures from the download release page or include the information directly in the page itself. The HTTPD page is a good example.
Include a reminder text with links to more information for users. For example:
Note: when downloading from a mirror please check the md5sum and verify the OpenPGP compatible signature from the main Apache site. Links are provided above (next to the release download link). This KEYS file contains the public keys used for signing release. It is recommended that (when possible) a web of trust is used to confirm the identity of these keys. For more information, please see the Apache Release FAQ.
Users need to understand the origin of the artifacts, signatures and sums downloaded. Check that the stylesheets used do not obscure the linked url. It is best to use a simple, plain style for download links. Note that some of the maven style sheets may obscure some external links in some browsers (in particular MSIE).
If you are unable to wait 24 hours before announcing your release, then you
can pass a date and time to the download script to indicate that only
mirrors that have updated since that time should be selected. This works by
update=YYYYMMDDhhmm to the query string. For example, you can use
http://httpd.apache.org/download.cgi?update=200407051415 to request only
mirrors that have updated after 2:15pm on July 5, 2004 UTC.
use this option sparingly, since it can result in excessive load on
particular mirrors. It would be appropriate, for example, in an emailed
release announcement for an important security release, but should not
usually be used as a main website link.
Read these instructions thoroughly before configuring your project mirror. See also the excellent mirroring, PGP and MD5 resources by Henk. Review how other ASF projects do their mirrors.
If you need assistance in implementing URL redirection to direct downloaders to the mirrors, or if you need any other help in implementing this policy, please contact the email@example.com mailing list.