| Version 2 (modified by , 15 years ago) ( diff ) |
|---|
The Trac Configuration File
Table of Contents
Trac configuration is done by editing the trac.ini config file, located in <projectenv>/conf/trac.ini. Changes to the configuration are usually reflected immediately, though changes to the [components] or [logging] sections will require restarting the web server. You may also need to restart the web server after creating a global configuration file when none was previously present.
The trac.ini configuration file should be writable by the web server, as Trac currently relies on the possibility to trigger a complete environment reload to flush its caches.
Global Configuration
In versions prior to 0.11, the global configuration was by default located in $prefix/share/trac/conf/trac.ini or /etc/trac/trac.ini, depending on the distribution. If you're upgrading, you may want to specify that file to inherit from. Literally, when you're upgrading to 0.11, you have to add an [inherit] section to your project's trac.ini file. Additionally, you have to move your customized templates and common images from $prefix/share/trac/... to the new location.
Global options will be merged with the environment-specific options, where local options override global options. The options file is specified as follows:
[inherit] file = /path/to/global/trac.ini
Multiple files can be specified using a comma-separated list.
Note that you can also specify a global option file when creating a new project, by adding the option --inherit=/path/to/global/trac.ini to trac-admin's initenv command. If you do not do this but nevertheless intend to use a global option file with your new environment, you will have to go through the newly generated conf/trac.ini file and delete the entries that will otherwise override those set in the global file.
There are two more entries in the [inherit] section, templates_dir for sharing global templates and plugins_dir, for sharing plugins. Those entries can themselves be specified in the shared configuration file, and in fact, configuration files can even be chained if you specify another [inherit] file there.
Note that the templates found in the templates/ directory of the TracEnvironment have precedence over those found in [inherit] templates_dir. In turn, the latter have precedence over the installed templates, so be careful about what you put there, notably if you override a default template be sure to refresh your modifications when you upgrade to a new version of Trac (the preferred way to perform TracInterfaceCustomization being still to write a custom plugin doing an appropriate ITemplateStreamFilter transformation).
Reference for settings
This is a brief reference of available configuration options, and their default settings.
[attachment]
max_size | Maximum allowed file size (in bytes) for attachments. | 262144 |
max_zip_size |
Maximum allowed total size (in bytes) for an attachment list to be
downloadable as a | 2097152 |
render_unsafe_content | Whether attachments should be rendered in the browser, or only made downloadable. Pretty much any file may be interpreted as HTML by the browser, which allows a malicious user to attach a file containing cross-site scripting attacks. For public sites where anonymous users can create attachments it is recommended to leave this option disabled. | disabled |
[browser]
color_scale | Enable colorization of the age column. This uses the same color scale as the source code annotation: blue is older, red is newer. | enabled |
downloadable_paths | List of repository paths that can be downloaded. Leave this option empty if you want to disable all downloads, otherwise set it to a comma-separated list of authorized paths (those paths are glob patterns, i.e. "*" can be used as a wild card). In a multi-repository environment, the path must be qualified with the repository name if the path does not point to the default repository (e.g. /reponame/trunk). Note that a simple prefix matching is performed on the paths, so aliases won't get automatically resolved. | /trunk,/branches/*,/tags/* |
hide_properties | Comma-separated list of version control properties to hide from the repository browser. | svk:merge |
intermediate_color |
(r,g,b) color triple to use for the color corresponding
to the intermediate color, if two linear interpolations are used
for the color scale (see | (no default) |
intermediate_point |
If set to a value between 0 and 1 (exclusive), this will be the
point chosen to set the | (no default) |
newest_color |
(r,g,b) color triple to use for the color corresponding
to the newest color, for the color scale used in blame or
the browser age column if | (255, 136, 136) |
oldest_color |
(r,g,b) color triple to use for the color corresponding
to the oldest color, for the color scale used in blame or
the browser age column if | (136, 136, 255) |
oneliner_properties | Comma-separated list of version control properties to render as oneliner wiki content in the repository browser. | trac:summary |
render_unsafe_content | Whether raw files should be rendered in the browser, or only made downloadable. Pretty much any file may be interpreted as HTML by the browser, which allows a malicious user to create a file containing cross-site scripting attacks. For open repositories where anyone can check-in a file, it is recommended to leave this option disabled. | disabled |
wiki_properties | Comma-separated list of version control properties to render as wiki content in the repository browser. | trac:description |
[changeset]
max_diff_bytes | Maximum total size in bytes of the modified files (their old size plus their new size) for which the changeset view will attempt to show the diffs inlined. | 10000000 |
max_diff_files | Maximum number of modified files for which the changeset view will attempt to show the diffs inlined. | 0 |
wiki_format_messages | Whether wiki formatting should be applied to changeset messages. If this option is disabled, changeset messages will be rendered as pre-formatted text. | enabled |
[components]
Enable or disable components provided by Trac and plugins.
The component to enable/disable is specified by the option name.
The enabled state is determined by the option value: setting
the value to enabled or on will enable the component, any
other value (typically disabled or off) will disable the
component.
The option name is either the fully qualified name of the component or the module/package prefix of the component. The former enables/disables a specific component, while the latter enables/disables any component in the specified package/module.
Consider the following configuration snippet:
[components] trac.ticket.report.ReportModule = disabled acct_mgr.* = enabled
The first option tells Trac to disable the
report module.
The second option instructs Trac to enable all components in
the acct_mgr package. The trailing wildcard is required for
module/package matching.
To view the list of active components, go to the Plugins
section of About Trac (requires CONFIG_VIEW
permission).
See also: TracPlugins
[header_logo]
alt | Alternative text for the header logo. | (please configure the [header_logo] section in trac.ini) |
height | Height of the header logo image in pixels. | -1 |
link | URL to link to, from the header logo. | (no default) |
src | URL of the image to use as header logo. It can be absolute, server relative or relative.
If relative, it is relative to one of the | site/your_project_logo.png |
width | Width of the header logo image in pixels. | -1 |
[http-headers]
Headers to be added to the HTTP request. (since 1.2.3)
The header name must conform to ​RFC7230 and the following reserved names are not allowed: content-type, content-length, location, etag, pragma, cache-control, expires.
[inherit]
htdocs_dir | Path to the shared htdocs directory. Static resources in that directory are mapped to /chrome/shared under the environment URL, in addition to common and site locations. This can be useful in site.html for common interface customization of multiple Trac environments.
Non-absolute paths are relative to the Environment | (no default) |
plugins_dir | Path to the shared plugins directory.
Plugins in that directory are loaded in addition to those in
the directory of the environment
Non-absolute paths are relative to the Environment | (no default) |
templates_dir | Path to the shared templates directory.
Templates in that directory are loaded in addition to those in the
environments
Non-absolute paths are relative to the Environment | (no default) |
[intertrac]
This section configures