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:
- 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
setup.py file) and run
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 (please do not disable individual parts of the plugin, this is not well tested):
[components] tracsecdl.* = enabled
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 (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>will be the value of the
<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
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
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
- 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_extensionoption. Remote downloads are not restricted by this option.
- Must be set to the Lighttpd
secdownload-uri-prefixconfiguration 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
- The secret key to protect the downloads (Lighttpd
secdownload.secretconfiguration 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
0to 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
0to not restrict the file size. The default value is
524288(512 KiB). See also the
max_totalconfiguration 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
0to disable this feature (default). This applies to local files only.
- In addition to the allowed file extensions specified by the
extensionsoption, 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_fieldsfor 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_fieldslist, 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_secretis 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
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
yes file name, required to display the download link
yes yes remote URL in case of remote downloads
yes yes download description
yes file size
yes upload time
yes time a download was last requested
number of downloads
user who created the download
yes remote address of the user who created the download
yes yes MD5 checksum of the file
yes yes SHA512 checksum of the file
Temporary directory for uploaded files. If this is empty (default)
upload_dirwill 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
lighty_secretis not set and
regular_downloadsis 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
Comma separated list of prefixes used in the wiki to link to the downloads. The default value is
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:
- Basic permission to access non-hidden downloads.
- Access hidden downloads (includes
- 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.
- same as above with a custom label.
- link to an individual download, the label will be the file name.
- 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 http://www.gnu.org/licenses/.