Your project's release download page links the project's content to the mirrors where people can download your latest release(s). This page describes how a release manager can put such a page together.
Material about Apache's policies on releases, mirrors, and download pages is here.
dist.apache.org.https:// (SSL). For example: https://downloads.apache.org/httpd/KEYS.Your Apache project's download page:
https://www.apache.org/dyn/closer.lua/PROJECT/VERSION/SOURCE-RELEASE.https://downloads.apache.org/PROJECT/VERSION/HASH-OR-CHECKSUM.https://downloads.apache.org/PROJECT/KEYS.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. You'll find below a standard mechanism to let you easily create scripts that comply with the ASF mirroring distribution policy and take advantage of more advanced features such as intelligent selection of a preferred mirror.
There are two basic options:
The starting point for a generic script is a download page in the standard documentation which describes the releases. To use the generic script, you need to alter the page so the actual download links to the generic script in the appropriate fashion.
The generic script is closer.cgi. Paaa in the relative path from the distribution root to the artifact as a parameter. So if the artifact is foo-5.5.1.zip and is located in bar/foo relative to downloads.apache.org, then http://www.apache.org/dyn/closer.cgi/bar/foo/foo-5.5.1.zip will display the mirrored distribution for downloading.
As an alternative, you can generate a direct download link using the following syntax:
http://www.apache.org/dyn/closer.cgi?filename=bar/foo/foo-5.5.1.zip&action=download
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, you need:
The script takes the path to the project page as an input and passes it to the standard mirroring script. The standard script reads the page and uses information about the mirrors to substitute values for the variables. When you link to the project page (for example, from the rest of the project documentation), it is important to target these links at the script address (and not the page address).
Conventionally, the wrapper script is called download.cgi. Create this in the same directory as the project page. This wrapper script sets up the correct directory and calls the mirroring script:
#!/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 resulting page is 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. See the content to generate that page here.
Downloads of artifacts are linked to a mirror by a 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
Provide links to the checksum and signature for the artifact 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='https://downloads.apache.org/bar/foo/foo-1.0.0.tar.gz.md5'>MD5</a>`
`<a href='https://downloads.apache.org/bar/foo/foo-1.0.0.tar.gz.asc'>PGP</a>`
Give users 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 below.
Before you commit the download script, 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 Apache CMS Reference for details. Of course this caveat only applies to CMS sites; sites that use pypubsub or svnpubsub exclusively will apply propset changes automatically as soon as they are committed. For example:
% svn propset svn:executable '*' download.cgi
% svn commit
All that remains is to wait for the main website to sync.
Users download Apache releases from mirrors. It is therefore important that they understand that they should always check the hash sums and (if possible) also verify the OpenPGP compatible signature of each download. 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. We recommend that you use a web of trust, if possible 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 they download. Check that the stylesheets your download site uses do not obscure the linked URLs. 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.
Normally you should wait 24 hours after uploading a release to https://downloads.apache.org/ before announcing it, in order to let mirrors catch up.
If you cannot wait, 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 adding 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.
Please 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 not appropriate as a main website link.
If you need assistance in implementing URL redirection to the mirrors, or if you need any other help in implementing this policy, please contact the users@infra.apache.org mailing list.
Copyright 2020, The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache® and the Apache feather logo are trademarks of The Apache Software Foundation...