Enhance downloads with advanced features

Description

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 a version available for Trac version 0.11 only.

Key features:

• 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 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 siuch as for file size, total file size, total number of files, see below for more options
• Wiki and Timeline integration

The admin interface looks as follows:

To take a look at the regular user interface, go to the download section on TracSecDl's homepage.

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://gitlab.com/goeb/tracsecdl.git

Installation

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/, the 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, for example the environment's plugins/ directory.

Enable the plugin by putting the following in your trac.ini file:

[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.

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 (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):

lighty_secret

If this is set, then the plugin will generate a URL suited for Lighttpd's mod_secdownload and redirect the browser to the generated URL.

regular_downloads

If this is enabled, then the plugin will generate a regular URL, ie without a mod_secdownload specific part, and redirect the browser to it.

trac_downloads

If this is enabled, then the plugin (or rather Trac) will send the file to the client by itself.

else

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.

Configuration

The plugin uses the following configuration options, the section in trac.ini is called [secdl]:

duplicate

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.

extensions

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.

lighty_prefix

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/'.

lighty_secret

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).

max_files

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.

max_size

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.

max_total

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.

no_extension

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.

order

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.

regular_downloads

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.

schemes

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'.

show_fields

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)

temp_dir

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.

title

Main navigation link title, and title of the downloads index page. Defaults to 'Downloads'.

trac_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.

upload_dir

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.

url

Path to the downloads page relative to the Trac environment root (one word, no slashes). Defaults to 'download'.

wiki_prefix

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:

[trac]
mainnav = wiki,secdl,timeline,roadmap,browser,tickets,newticket,search

Permissions

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)

Macros

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.

Author

Author: Stefan Göbel