= !TracSecDl = [[PageOutline(2)]] == Important == ---- '''This plugin is actually hosted at [http://code.ntworks.net/TracSecDl], please visit this page for up to date information.''' (The text below is basically a copy of the actual homepage, note however that I can only post five external links here, so you should visit the URL mentioned above for working links to the project's bug tracker etc.) ---- == Description == This plugin adds a download section to Trac. It was inspired by (and offers nearly all the features of) the [wiki:DownloadsPlugin DownloadsPlugin] (!TracSecDl currently lacks integration with the [wiki:TagsPlugin TagsPlugin] and [wiki:TracAdmin TracAdmin], and there is only a version for ''0.11'' available). The main features are: * multiple ways to send a requested file to the client: * [http://www.lighttpd.net/ Lighttpd] with [http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs:ModSecDownload mod_secdownload] * regular download handled by the server (bypassing Trac) * !TracSecDl can handle the download itself * see [#DownloadProcessing below] for details * inclusion of arbitrary remote URLs in the downloads list * hidden downloads, only visible to users with the appropriate [#Permissions permission] * automatic calculation of MD5 and SHA512 checksums for uploaded files * configurable limits for file size, total file size, total number of files... (see [#Configuration below] for more options) * [wiki:TracWiki Wiki] and [wiki:TracTimeline Timeline] integration == Bugs And Feature Requests == Existing bugs and feature requests for !TracSecDl can be found at [http://code.ntworks.net/TracSecDl/report its bug tracker]. If you have any issues, please create a [http://code.ntworks.net/TracSecDl/newticket new ticket]. == 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 git://code.ntworks.net/TracSecDl.git }}} == Dependencies == Trac 0.11 is required, other versions are currently not supported. == Installation == Basically, download the source, extract it somewhere, change to the extracted directory ''!TracSecDl/0.11/'' (that 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 [wiki:TracEnvironment environment's] ''plugins/'' directory). Enable the plugin by putting the following in your ''[wiki:TracIni trac.ini]'' (please do not disable individual parts of the plugin, this is not well tested): {{{ #!ini [components] tracsecdl.* = enabled }}} Check the [wiki:TracPlugins 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 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 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, 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, 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 {{{///}}}: * {{{}}} will be the value of the {{{lighty_prefix}}} configuration option * {{{}}} and {{{}}} are calculated automatically and will protect the download (see the mod_secdownload documentation] for details) * {{{}}} 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 {{{/}}}, both parts are exactly the same as described above (and, though it is server-independent, the {{{lighty_secret}}} option sets the {{{}}}). In both cases you have to make sure that requests to the {{{}}} 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 {{{}}} 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 sction 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 [wiki:TracEnvironment 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: {{{ #!ini [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 [#Screenshots admin interface] to manage downloads (includes the other permissions) == Macros == On wiki pages, the following macros can be used: * {{{[download:index]}}} to link to the download index page * {{{[download:index label]}}}, same as above with a custom label * {{{[download:id]}}} 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 configuration] option. == Screenshots == The admin interface: [[Image(admin.png)]] To take a look at the regular user interface go to the download section on !TracSecDl's homepage. == Author == '''Author:''' Stefan Göbel == License == Copyright © 2010 Stefan Göbel This program 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. This program 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 this program. If not, see .