Clone wiki

TracSecDl / Home



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 Trac 0.11 available, though it may work for later versions).

The main features are:

  • multiple ways to send a requested file to the client:
    • Lighttpd with mod_secdownload
    • regular download handled by the server (bypassing Trac)
    • TracSecDl can handle the download itself
    • see Download Processing below for details
  • 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 the Configuration section below for more options)
  • Wiki and TimeLine integration

Bugs And Feature Requests

Existing bugs and feature requests for TracSecDl can be found at Bitbucket. If you have any issues, please create a new ticket.

Download And Source Code

Check the download section for available files (the latest source code should be available under the Branches tab), or browse the source. You can also clone the repository with Git, see the overview for details.


Trac 0.11 is required, other versions may work, but are currently not supported and not tested.


Basically, download the source code and extract it somewhere (or clone the repository), change to the extracted directory TracSecDl/0.11/ (the one containing the file) and run

python 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 (please do not disable individual parts of the plugin, this is not well tested):

tracsecdl.* = enabled

Check the TracPlugins installation guide, especially if you have trouble installing the plugin.

Download Processing

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 (i.e. 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 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 independent of the HTTP server in use, the lighty_prefix 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. Remote downloads are not restricted by this 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. Remote downloads are not restricted by this option.
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 (e.g. 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 URI 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:

Field Default New Row Comments
id not displayed
name yes file name, required to display the download link
url yes yes remote URL in case of remote downloads
description yes yes download description
size yes file size
time yes upload time
last_request yes time a download was last requested
count number of downloads
author user who created the download
ip yes remote address of the user who created the download
component assigned component
milestone assigned milestone
version assigned version
platform assigned platform
architecture assigned architecture
type assigned type
hidden not displayed
checksum_md5 yes yes MD5 checksum of the file
checksum_sha yes yes SHA512 checksum 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'.

Additional Options

To change the order of the main navigation bar items use the 'secdl' keyword, for example:

mainnav = wiki,secdl,timeline,roadmap,browser,tickets,newticket,search


The plugin defines three permissions:

Basic permission to access non-hidden downloads.
Access hidden downloads (includes SECDL_VIEW permission).
Access the admin interface to manage downloads (includes the other permissions).


On wiki pages, the following macros can be used:

to link to the download index page.
[download:index label]
same as above with a custom label.
link to an individual download, the label will be the file name.
[download: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:


The download section:



Copyright 2010-2011, 2014 Stefan Göbel - <tracsecdl —@— subtype —•— de>

TracSecDl is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

TracSecDl is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with TracSecDl. If not, see