Enhance downloads with advanced features
Notice: This plugin is hosted at the Bitbucket project page, so please visit that page for up to date information.
This plugin adds a download section to Trac. It was inspired by and offers nearly all the features of the DownloadsPlugin. TracSecDl currently lacks integration with the TagsPlugin and TracAdmin, and there is only a version for 0.11 available.
- multiple ways to send a requested file to the client:
- inclusion of arbitrary remote URLs in the downloads list
- hidden downloads, only visible to users with the appropriate permission
- automatic calculation of MD5 and SHA512 checksums for uploaded files
- configurable limits for file size, total file size, total number of files... (see below for more options)
- Wiki and Timeline integration
Bugs And Feature Requests
Existing bugs and feature requests for TracSecDl can be found at its bug tracker. If you have any issues, please create a new ticket there.
Download And Source Code
Visit the plugin's homepage and check the download section for available files. You can also clone the repository with git:
$ git clone https://bitbucket.org/goeb/tracsecdl.git
Trac 0.11 is required, other versions are currently not supported.
Basically, download the source, extract it somewhere, change to the extracted directory TracSecDl/0.11/ (that one containing the setup.py file) and run the following:
python setup.py bdist_egg
This will create an .egg file somewhere (probably in the dist/ folder). Place this file in a plugin directory where it can be found by Trac (eg. the environment's plugins/ directory).
Enable the plugin by putting the following in your trac.ini:
[components] tracsecdl.* = enabled
Please do not disable individual parts of the plugin, this is not well tested.
Check the TracPlugins installation guide, especially if you have trouble installing the plugin.
When a user requests a download, the plugin will first check if the user's permissions are sufficient to access the download. If the requested download is a remote one (ie. no file uploaded to the server but a remote URL specified instead) the plugin will simply send a 302 redirect to the remote URL. If it is a local download, the following three configuration options are checked (in that order):
- If this is set the plugin will generate a URL suited for Lighttpd's mod_secdownload and redirect the browser to the generated URL.
- If this is enabled, the plugin will generate a regular URL (ie. without a mod_secdownload specific part) and redirect the browser to it.
- If this is enabled, the plugin (or rather Trac) will send the file to the client by itself.
- If none of the above was set, an error page will be displayed.
In the first case the generated (relative) URL will look like <prefix>/<checksum>/<timestamp>/<file path>:
- <prefix> will be the value of the lighty_prefix configuration option
- <checksum> and <timestamp> are calculated automatically and will protect the download (see the mod_secdownload documentation] for details)
- <file path> will be set by the plugin, it is determined by the path of the environment, the uploaded file's name and its download ID
In the second case (regular_downloads) the URL will be <prefix>/<file path>, both parts are exactly the same as described above (and, though it is server-independent, the lighty_secret option sets the <prefix>).
In both cases you have to make sure that requests to the <prefix> path are handled by the server itself and not by Trac, it depends on the server how to do that, see the appropriate documentation. Also, make sure that the directory specified by the upload_dir option is mapped accordingly to the <prefix> location.
Important: The plugin checks the user's permissions when a download is requested, and then sends a redirect to the actual location (except for local files if trac_downloads is used). In case of remote downloads and regular downloads, everyone who knows this target URL can access the file (unless there are other mechanisms to protect it). In case of mod_secdownload the download URL will be valid for a short time only (this is configured in the server configuration).
The recommended setup is Lighttpd with mod_secdownload (hence the plugin's name), if you do not need to protect your downloads (if they are all public anyway) you can also use the regular download option. It is not recommended to use the trac_downloads option for FastCGI setups, since the number of FastCGI processes is usually limited and this will block one process for the time of the download.
The plugin uses the following configuration options, the section in trac.ini is called [secdl]:
- Specify what to do if a file is uploaded with an already existing file name. To deny the upload, set it to 'deny' (default), set it to 'allow' to allow two files with the same name. Note that this applies only to local downloads, remote downloads are not restricted.
- Comma separated list of allowed file extensions (without leading dot). Leave this empty to not restrict the file types. The default is 'zip,gz,bz2,rar'. See also the no_extension option.
- Must be set to the Lighttpd secdownload-uri-prefix configuration value if mod_secdownload is used. The final download URL will be constructed using this value as the first part after the root path, followed by the protected part of the URL. If regular downloads are enabled, the URL will be the same but without the protected part. Note that if you do not start the value for this option with a '/', an URL relative to the Trac environment root will be created. This is in most cases not what you want! The default value is '/download/'.
- The secret key to protect the downloads (Lighttpd secdownload.secret configuration value). The downloads using mod_secdownload are disabled if this is left empty (default).
- Maximum number of uploaded files. If this limit is reached, no more uploads are allowed. Set this to 0 to allow an unlimited number of uploads (default). Note that this applies to local files only.
- Maximum allowed file size for uploaded files in bytes. Note that a file has to be uploaded completely before this can be checked. Set max_size to 0 to not restrict the file size. The default value is 524288 (512 KiB). See also the max_total configuration option. Note that this applies to local files only.
- Maximum total size of uploaded files in bytes. If a new file upload would exceed this limit it will be denied. Note that a file has to be uploaded completely before this can be checked (unless the limit is already reached). Set this to 0 to disable this feature (default). This applies to local files only.
- In addition to the allowed file extensions specified by the extensions option, allow files with no extension to be uploaded if this option is set to True. The default value is False.
- Default order of the downloads table, specified as comma separated list of field names. See show_fields for a list of allowed field names. You may prepend a '!' to change the sort order of a given field (eg. use '!name' to sort by file name in a descending order). Note that the fields used here have to be included in the show_fields list, too. The default value is '!time', so latest downloads will be shown at the top of the table.
- Enable regular downloads not using mod_secdownload. Note that the webserver has to be configured to serve the files in upload_dir. This option will be ignored unless lighty_secret is empty. Regular downloads may be used on other servers than Lighttpd, too, but keep in mind that there are no further restrictions to access these files.
- Comma separated list of allowed schemes for the remote downloads. A remote download with another scheme can not be created. To not restrict the remote URLs leave this option empty. Note that URLs without a scheme are always denied. The default is 'http,https'.
Comma separated list of fields to show on the downloads index page. Note that some options are not displayed in a separate column but will force a new table row, and some options are not displayed at all (though they are valid). The order does not matter. Valid options are (bold ones are included in the default list, italic ones will be displayed in an additional row):
- 'id' (not displayed)
- 'name' (file name of the download, required to display the download link)
- 'url' (remote URL in case of remote downloads)
- 'description' (download description)
- 'size' (file size)
- 'time' (upload time)
- 'last_request' (time a download was last requested)
- 'count' (number of downloads)
- 'author' (user who created the download)
- 'ip' (remote address of the user who created the download)
- 'component', 'milestone', 'version' (assigned component etc.)
- 'platform', architecture', 'type' (assigned platform etc.)
- 'hidden' (not displayed in the user interface)
- 'checksum_md5', 'checksum_sha' (checksums of the file)
- Temporary directory for uploaded files. If this is empty (default) upload_dir will be used. Note that it is highly recommended to use a directory on the same physical partition as upload_dir. The directory must exist and the user running Trac must have write access to this directory.
- Main navigation link title, and title of the downloads index page. Defaults to 'Downloads'.
- If lighty_secret is not set and regular_downloads is disabled, too, this option can be enabled to allow downloads to be handled by Trac itself. This is disabled by default.
- Directory to store uploaded files. The directory must exist and the user running Trac must have write access to this directory. The user running Lighttpd (or any other webserver if regular downloads are used) must have read permissions. The default value is '/var/lib/trac/files'. Note that you can safely use the same upload directory for multiple environments, the uploaded files are automatically stored in subdirectories for each environment.
- Path to the downloads page relative to the Trac environment root (one word, no slashes). Defaults to 'download'.
- Comma separated list of prefixes used in the wiki to link to the downloads. The default value is 'download,secdownload'.
To change the order of the main navigation bar items use the 'secdl' keyword, for example:
[trac] mainnav = wiki,secdl,timeline,roadmap,browser,tickets,newticket,search
The plugin defines three permissions:
- SECDL_VIEW: basic permission to access non-hidden downloads
- SECDL_HIDDEN: access hidden downloads (includes SECDL_VIEW permission)
- SECDL_ADMIN: access the admin interface to manage downloads (includes the other permissions)
On wiki pages, the following macros can be used:
- [export:index] to link to the download index page
- [export:index label], same as above with a custom label
- [export:id] link to an individual download, the label will be the file name
- [export:id label], same as above with a custom label
The examples above assume that 'download' is included in the wiki_prefix configuration option.
The admin interface:
To take a look at the regular user interface go to the download section on TracSecDl's homepage.
Author: Stefan Göbel