Changeset 37343


Ignore:
Timestamp:
Mar 12, 2016, 8:47:19 PM (4 years ago)
Author:
aafsvn
Message:

[titan] autoupdate wiki files

Location:
wiki/pages
Files:
54 edited

Legend:

Unmodified
Added
Removed
  • wiki/pages/CamelCase

    r26484 r37343  
    1 = !CamelCase =
    2 New words created by smashing together capitalized words.
     1= !CamelCase
     2New wiki links are automatically created when concatenating capitalized words, such that for example the word 'Camel' and the word 'Case' concatenated form a link to this CamelCase page.
    33
    4 CamelCase is the original wiki convention for creating hyperlinks, with the additional requirement that the capitals are followed by a lower-case letter; hence “AlabamA” and “ABc” will not be links.
     4!CamelCase is the original wiki convention for creating hyperlinks, with the additional requirement that the capitals are followed by a lower-case letter; hence “AlabamA” and “ABc” will not be links.
    55
    6 == Customizing the Wiki behavior ==
     6== Customizing the Wiki behavior
    77
    8 Some people dislike linking by CamelCase.  While Trac remains faithful to the original Wiki style, it provides a number of ways to accomodate users with different preferences:
    9  * There's an option (`ignore_missing_pages` in the [wiki:TracIni#wiki-section "[wiki]"] section of TracIni) to simply ignore links to missing pages when the link is written using the CamelCase style, instead of that word being replaced by a gray link followed by a question mark.[[BR]]
    10    That can be useful when CamelCase style is used to name code artifacts like class names and there's no corresponding page for them.
     8While Trac remains faithful to the original Wiki style, it provides a number of ways to accommodate users with different preferences:
     9 * To prevent the creation of a new link of a camel-cased word, prefix with '!': `!CamelCase`.
     10 * To ignore links to missing pages when the link is written using the CamelCase style, that word can instead be replaced by a gray link followed by a question mark. This is useful in cases when CamelCase style is used to name code artifacts like class names and there's no corresponding page for them. This option can be set in `ignore_missing_pages` in the [wiki:TracIni#wiki-section "[wiki]"] section of TracIni.
    1111 * There's an option (`split_page_names` in the  [wiki:TracIni#wiki-section "[wiki]"] section of TracIni) to automatically insert space characters between the words of a CamelCase link when rendering the link.
    1212 * Creation of explicit Wiki links is also easy, see WikiPageNames for details.
    13  * In addition, Wiki formatting can be disabled completely in some places (e.g. when rendering commit log messages). See `wiki_format_messages` in the [wiki:TracIni#changeset-section "[changeset]"] section of TracIni.
     13 * Wiki formatting can be disabled completely in some places, for example when rendering commit log messages. See `wiki_format_messages` in the [wiki:TracIni#changeset-section "[changeset]"] section of TracIni.
    1414
    1515See TracIni for more information on the available options.
    1616
    17 == More information on !CamelCase ==
     17== More information on !CamelCase
    1818
    1919 * http://c2.com/cgi/wiki?WikiCase
  • wiki/pages/InterMapTxt

    r26484 r37343  
    3939
    4040{{{
    41 PEP     http://www.python.org/peps/pep-$1.html                                       # Python Enhancement Proposal
     41PEP     http://www.python.org/dev/peps/pep-$1/    # Python Enhancement Proposal
     42PythonBug    http://bugs.python.org/issue$1       # Python Issue #$1
     43Python-issue http://bugs.python.org/issue$1       # Python Issue #$1
     44PythonWiki    https://wiki.python.org/moin/       # Python Wiki
     45
     46
    4247Trac-ML  http://thread.gmane.org/gmane.comp.version-control.subversion.trac.general/ # Message $1 in Trac Mailing List
    4348trac-dev http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/   # Message $1 in Trac Development Mailing List
    4449
     50apidoc http://www.edgewall.org/docs/trac-trunk/html/$1.html # $1 in the API documentation for Trac
     51apiref http://www.edgewall.org/docs/trac-trunk/epydoc/$1.html # $1 in the Epydoc API reference for Trac
     52
     53bitten   http://bitten.edgewall.org/intertrac/    # Bitten's Trac
     54
    4555Mercurial http://www.selenic.com/mercurial/wiki/index.cgi/ # the wiki for the Mercurial distributed SCM
    46 RFC       http://rfc.net/rfc$1.html # IETF's RFC $1
     56hg        http://www.selenic.com/hg/rev/$1?rev=$2          # Changeset $1 $2 in Mercurial repository
     57hg-issue  http://mercurial.selenic.com/bts/issue           # Issue $1 in Mercurial BTS
     58
     59RFC       http://tools.ietf.org/html/rfc$1          # IETF's RFC $1
     60ISO       http://en.wikipedia.org/wiki/ISO_         # ISO Standard $1 in Wikipedia
     61kb        http://support.microsoft.com/kb/$1/en-us/ # Article $1 in Microsoft's Knowledge Base
     62
     63pypi        http://pypi.python.org/pypi/   # $1 package in the Python Package Index
     64CheeseShop  http://pypi.python.org/pypi/           # $1 package in the Python Package Index
     65peak        http://peak.telecommunity.com/DevCenter/     # $1 in Python Enterprise Application Kit's Wiki
     66setuptools-issue http://bugs.python.org/setuptools/issue # issue$1 in legacy Setuptools tracker
     67pypa-setuptools-issue https://bitbucket.org/pypa/setuptools/issue/ # issue #$1 in BitBucket Setuptools tracker
     68
     69SQLite      http://www.sqlite.org/cvstrac/wiki?p=$1     # $1 page in the CvsTrac for SQLite
     70SQLiteTkt   http://www.sqlite.org/cvstrac/tktview?tn=$1 # Ticket $1 in the CvsTrac for SQLite
     71
     72mysql-bugs  http://bugs.mysql.com/bug.php?id=  # Bug #$1 in MySQL's bug database
     73mysql-issue http://bugs.mysql.com/bug.php?id=  # Bug #$1 in MySQL's bug database
     74
     75MODPYTHON          http://issues.apache.org/jira/browse/MODPYTHON- # Issue $1 in mod_python's JIRA instance
     76mod-python-issue   http://issues.apache.org/jira/browse/MODPYTHON- # Issue $1 in mod_python's JIRA instance
     77
     78SvnWiki     http://www.orcaware.com/svn/wiki/                        # Subversion Wiki
     79svnissue    http://subversion.tigris.org/issues/show_bug.cgi?id=     # Subversion issue #$1
     80svn-issue   http://subversion.tigris.org/issues/show_bug.cgi?id=     # Subversion issue #$1
     81svncset     http://svn.collab.net/viewvc/svn?view=revision&revision= # Subversion [$1]
     82
     83mod-wsgi    http://code.google.com/p/modwsgi/wiki/                 # mod_wsgi Wiki on Google Code
     84mod-wsgi-issue  http://code.google.com/p/modwsgi/issues/detail?id= # mod_wsgi Issue Tracker on Google Code
     85
     86chromium-issue  http://code.google.com/p/chromium/issues/detail?id=
     87
     88Django      http://code.djangoproject.com/intertrac/ # Django's Trac
     89AgileTrac   http://www.agile-trac.org/intertrac/     # Plugin adding Iterations to Trac
     90
     91CreoleWiki   http://wikicreole.org/wiki/
     92Creole1Wiki  http://wikicreole.org/wiki/
     93Creole2Wiki  http://wiki.wikicreole.org/
     94
     95MediaWiki    http://www.mediawiki.org/wiki/
     96
     97SO  http://stackoverflow.com/questions/ # Question $1 in StackOverflow
     98
     99Transifex https://www.transifex.com/projects/p/trac/
     100
     101kwquery      /query?group=status&keywords=~  # Custom query for tickets matching keyword $1
    47102
    48103#
     
    55110DebianBug        http://bugs.debian.org/
    56111DebianPackage    http://packages.debian.org/
     112DebianPTS        http://packages.qa.debian.org/
    57113Dictionary       http://www.dict.org/bin/Dict?Database=*&Form=Dict1&Strategy=*&Query=
    58114Google           http://www.google.com/search?q=
     115lmgtfy           http://lmgtfy.com/?q= # Well, just search for "$1", follow the link to see how to do it...
    59116GoogleGroups     http://groups.google.com/group/$1/msg/$2        # Message $2 in $1 Google Group
     117gdiscussion      https://groups.google.com/d/topic/$1/$2/discussion # Discussion $2 in $1 Google
     118gmessage         https://groups.google.com/d/msg/$1/$2 # Message $2 in $1 Google Group
     119gforum           https://groups.google.com/forum/#!forum/$1 # Forum $1 in Google Groups
    60120JargonFile       http://downlode.org/perl/jargon-redirect.cgi?term=
    61121MeatBall         http://www.usemod.com/cgi-bin/mb.pl?
    62122MetaWiki         http://sunir.org/apps/meta.pl?
    63123MetaWikiPedia    http://meta.wikipedia.org/wiki/
    64 MoinMoin         http://moinmoin.wikiwikiweb.de/
     124MoinMoin         http://moinmo.in/
     125TracHacks        http://trac-hacks.org/wiki/
     126OSM              http://www.openstreetmap.org/wiki/
    65127WhoIs            http://www.whois.sc/
    66128Why              http://clublet.com/c/c/why?
    67 c2Wiki             http://c2.com/cgi/wiki?
     129c2Wiki           http://c2.com/cgi/wiki?
    68130WikiPedia        http://en.wikipedia.org/wiki/
    69131}}}
     132
     133
     134----
     135See also: InterWiki, InterTrac
  • wiki/pages/InterTrac

    r26484 r37343  
    1 = InterTrac Links  =
     1= InterTrac Links
    22
    3 Trac supports a convenient way to refer to resources of other Trac servers, from within the Wiki markup, since version 0.10.
     3Trac supports a convenient way to refer to resources of other Trac servers, from within the Wiki markup. An !InterTrac link can be seen as a scoped TracLinks. It is used for referring to a Trac resource located in another Trac environment. A resource can be a wiki page, changeset, ticket or milestone.
    44
    5 == Definitions ==
    6 
    7 An InterTrac link can be seen as a scoped TracLinks.
    8 It is used for referring to a Trac resource
    9 (Wiki page, changeset, ticket, ...) located in another
    10 Trac environment.
    11 
    12 == List of Active InterTrac Prefixes ==
     5== List of Active InterTrac Prefixes
    136
    147[[InterTrac]]
    158
    16 == Link Syntax ==
     9== Link Syntax
    1710
    18 Simply use the name of the other Trac environment as a prefix,
    19 followed by a colon, ending with the resource located in the other environment.
     11Simply use the name of the other Trac environment as a prefix, followed by a colon, ending with the resource located in the other environment.
    2012
    2113{{{
     
    2517The other resource is specified using a regular TracLinks, of any flavor.
    2618
    27 That target environment name is either the real name of the
    28 environment, or an alias for it.
     19That target environment name is either the real name of the environment or an alias for it.
    2920The aliases are defined in `trac.ini` (see below).
    3021The prefix is case insensitive.
    3122
    32 If the InterTrac link is enclosed in square brackets (like `[th:WikiExtrasPlugin]`), the InterTrac prefix is removed in the displayed link, like a normal link resolver would be (i.e. the above would be displayed as `WikiExtrasPlugin`).
     23If the InterTrac link is enclosed in square brackets (like `[th:WikiExtrasPlugin]`), the InterTrac prefix is removed in the displayed link like a normal link resolver would be, ie the above would be displayed as `WikiExtrasPlugin`.
    3324
    34 For convenience, there's also some alternative short-hand form,
    35 where one can use an alias as an immediate prefix
    36 for the identifier of a ticket, changeset or report:
    37 (e.g. `#T234`, `[T1508]`, `[trac 1508]`, ...)
     25For convenience, there's also some alternative short-hand form, where one can use an alias as an immediate prefix for the identifier of a ticket, changeset or report, eg `#T234`, `[T1508]`, `[trac 1508]`.
    3826
    39 == Examples ==
     27== Examples
    4028
    4129It is necessary to setup a configuration for the InterTrac facility.
     
    4331
    4432Example configuration:
    45 {{{
    46 ...
     33{{{#!ini
    4734[intertrac]
    4835# -- Example of setting up an alias:
     
    5542
    5643The `.url` is mandatory and is used for locating the other Trac.
    57 This can be a relative URL in case that Trac environment is located
    58 on the same server.
     44This can be a relative URL in case that Trac environment is located on the same server.
    5945
    60 The `.title` information will be used for providing an useful tooltip
    61 when moving the cursor over an InterTrac links.
    62 
    63 Finally, the `.compat` option can be used to activate or disable
    64 a ''compatibility'' mode:
    65  * If the targeted Trac is running a version below [trac:milestone:0.10 0.10]
    66    ([trac:r3526 r3526] to be precise), then it doesn't know how to dispatch an InterTrac
    67    link, and it's up to the local Trac to prepare the correct link.
    68    Not all links will work that way, but the most common do.
    69    This is called the compatibility mode, and is `true` by default.
    70  * If you know that the remote Trac knows how to dispatch InterTrac links,
    71    you can explicitly disable this compatibility mode and then ''any''
    72    TracLinks can become an InterTrac link.
     46The `.title` information will be used for providing an useful tooltip when moving the cursor over an InterTrac links.
    7347
    7448Now, given the above configuration, one could create the following links:
     
    8458   * `trac:changeset:1912` trac:changeset:1912
    8559   * `[T1912]` [T1912]
    86  * to the log range [3300:3330]: '''(Note: the following ones need `trac.compat=false`)'''
     60 * to the log range [3300:3330]:
    8761   * `trac:log:@3300:3330` trac:log:@3300:3330 
    88    * `[trac 3300:3330]` [trac 3300:3330] 
    89  * finally, to link to the start page of a remote trac, simply use its prefix followed by ':', inside an explicit link. Example: `[th: Trac Hacks]` (''since 0.11; note that the ''remote'' Trac has to run 0.11 for this to work'')
     62   * `[trac 3300:3330]` [trac 3300:3330]
     63   * finally, to link to the start page of a remote trac, simply use its prefix followed by ':', inside an explicit link. Example: `[th: Trac Hacks]` (note that the ''remote'' Trac has to run Trac >= 0.11 for this to work'')
    9064
    91 The generic form `intertrac_prefix:module:id` is translated
    92 to the corresponding URL `<remote>/module/id`, shorthand links
    93 are specific to some modules (e.g. !#T234 is processed by the
    94 ticket module) and for the rest (`intertrac_prefix:something`),
    95 we rely on the TracSearch#quickjump facility of the remote Trac.
     65The generic form `intertrac_prefix:module:id` is translated to the corresponding URL `<remote>/module/id`, shorthand links are specific to some modules (e.g. !#T234 is processed by the ticket module) and for the rest (`intertrac_prefix:something`), we rely on the TracSearch#quickjump facility of the remote Trac.
    9666
    9767----
  • wiki/pages/InterWiki

    r26484 r37343  
    1 = Support for InterWiki links =
     1= Support for InterWiki links
    22
    3 ''(since [trac:milestone:0.10 0.10])''
     3== Definition
    44
    5 == Definition ==
     5An InterWiki link can be used for referring to a Wiki page located in another Wiki system, and by extension, to any object located in any other Web application, provided a simple URL mapping can be done.
    66
    7 An InterWiki link can be used for referring to a Wiki page
    8 located in another Wiki system, and by extension, to any object
    9 located in any other Web application, provided a simple URL
    10 mapping can be done.
     7At the extreme, InterWiki prefixes can even be used to simply introduce links to new protocols, such as `tsvn:` used by [trac:TortoiseSvn TortoiseSvn].
    118
    12 At the extreme, InterWiki prefixes can even be used to simply introduce
    13 links to new protocols, such as `tsvn:` used by [trac:TortoiseSvn TortoiseSvn].
    14 
    15 == Link Syntax ==
     9== Link Syntax
    1610
    1711{{{
     
    1913}}}
    2014
    21 The link is composed by the targeted Wiki (or system) name,
    22 followed by a colon (e.g. `MeatBall:`),
    23 followed by a page specification in the target.
     15The link is composed by the targeted Wiki (or system) name, followed by a colon, eg `MeatBall:`, followed by a page specification in the target.
    2416Note that, as for InterTrac prefixes, '''InterWiki prefixes are case insensitive'''.
    2517
    2618The target Wiki URL is looked up in the `[interwiki]` section of TracIni or in the InterMapTxt wiki page, modeled after MeatBall:InterMapTxt. If a prefix is defined in both the `[interwiki]` section and InterMapTxt, the `[interwiki]` section takes precedence.
    2719
    28 In addition to traditional InterWiki links, where the target
    29 is simply ''appended'' to the URL,
    30 Trac supports parametric InterWiki URLs:
    31 identifiers `$1`, `$2`, ... in the URL
    32 will be replaced by corresponding arguments.
    33 The argument list is formed by splitting the page identifier
    34 using the ":" separator.
     20In addition to traditional InterWiki links, where the target is simply ''appended'' to the URL, Trac supports parametric InterWiki URLs:
     21identifiers `$1`, `$2`, ... in the URL will be replaced by corresponding arguments.
     22The argument list is formed by splitting the page identifier using the ":" separator.
    3523
    36 === [interwiki] ===
     24=== [interwiki]
     25
    3726Every option in the `[interwiki]` section in TracIni defines one InterWiki prefix. The option name defines the prefix. The option value defines the URL, optionally followed by a description separated from the URL by whitespace. Parametric URLs are supported as well.
    3827
     
    4534}}}
    4635
    47 == Examples ==
     36== Examples
    4837
    4938If the following is an excerpt of the InterMapTxt page:
     
    7362
    7463Then,
    75  * `MoinMoin:InterWikiMap` should be rendered as MoinMoin:InterWikiMap
    76    and the ''title'' for that link would be "!InterWikiMap in !MoinMoin"
    77  * `Trac-ML:4346` should be rendered as Trac-ML:4346
    78    and the ''title'' for that link would be "Message 4346 in Trac Mailing List"
     64 * `MoinMoin:InterWikiMap` should be rendered as MoinMoin:InterWikiMap and the ''title'' for that link would be "!InterWikiMap in !MoinMoin"
     65 * `Trac-ML:4346` should be rendered as Trac-ML:4346 and the ''title'' for that link would be "Message 4346 in Trac Mailing List"
    7966
    8067----
  • wiki/pages/PageTemplates

    r26484 r37343  
    1 = Wiki Page Templates =
    2 
    3   ''(since [http://trac.edgewall.org/milestone/0.11 0.11])''
     1= Wiki Page Templates
    42
    53The default content for a new wiki page can be chosen from a list of page templates.
    64
    75That list is generated from all the wiki pages having a name starting with ''PageTemplates/''.
    8 The initial content of a new page will simply be the content of the chosen template page, or a blank page if the special ''(blank page)'' entry is selected. When there are no wiki pages with the ''PageTemplates/'' prefix, the initial content will always be the blank page and the list selector will not be shown (i.e. this matches the behavior we had up to now).
     6The initial content of a new page will simply be the content of the chosen template page, or a blank page if the special ''(blank page)'' entry is selected. When there are no wiki pages with the ''PageTemplates/'' prefix, the initial content will always be the blank page and the list selector will not be shown, ie this matches the behavior we had up to now.
    97
    108To create a new template, simply create a new page having a name starting with ''PageTemplates/''.
    119
    12 (Hint: one could even create a ''!PageTemplates/Template'' for facilitating the creation of new templates!)
     10Hint: one could even create a ''!PageTemplates/Template'' for facilitating the creation of new templates!
    1311
    14 After the first template has been created, a drop-down selection box will automatically appear on any new wiki pages that are created.  By default it is located on the right side of the 'Create this page' button. The default selection will be ''blank page'', or ''!DefaultPage'' if ''!PageTemplates/DefaultPage'' exists.
     12After the first template has been created, a drop-down selection box will automatically appear on any new wiki pages that are created. By default it is located on the right side of the 'Create this page' button. The default selection will be ''blank page'', or ''!DefaultPage'' if ''!PageTemplates/DefaultPage'' exists.
    1513
    1614Available templates:
    1715[[TitleIndex(PageTemplates/)]]
     16
    1817----
    1918See also: TracWiki
  • wiki/pages/TracAccessibility

    r26484 r37343  
    11= Accessibility Support in Trac =
    22
    3 Not every user has a graphic environment with a mouse or other pointing device. Some users rely on keyboard, alternative keyboard or voice input to navigate links, activate form controls, etc. In Trac, we work to assure users may interact with devices other than a pointing device.
     3Not every user has a graphic environment with a mouse or other pointing device. Some users rely on keyboard, alternative keyboard or voice input to navigate links, activate form controls, etc. In a Trac session, users can use devices other than a pointing device by enabling keyboard shortcuts through the [/prefs/keybindings Keyboard Shortcuts] preferences panel.
    44
    5 The keyboard shortcuts must be enabled for a session through the [/prefs/keybindings Keyboard Shortcuts] preferences panel.
    6 
    7 Trac supports accessibility keys for the most common operations.
    8  - on Linux platforms, press any of the keys listed below in combination with the `<Alt>` key
    9  - on a Mac, use the `<ctrl>` key instead
    10  - on Windows, you need to hit `<Shift> + <Alt> + <Key>`. This works for most browsers (Firefox, Chrome, Safari and Internet Explorer)
     5Trac supports accessibility keys for the most common operations. The access keys differ by browser and the following work for several browsers, but see [http://en.wikipedia.org/wiki/Access_key#Access_in_different_browsers access in different browsers] for more details.
     6 - on Linux platforms, press any of the keys listed below in combination with the `<Alt>` key
     7 - on a Mac, use the `<Ctrl>` + `<Opt>` key instead
     8 - on Windows, you need to hit `<Shift> + <Alt> + <Key>`. This works for the most common browsers, such as Firefox, Chrome, Safari and Internet Explorer
    119
    1210== Global Access Keys ==
    1311
    1412 * `1` - WikiStart
    15  * `2` - [wiki:TracTimeline Timeline]
    16  * `3` - [wiki:TracRoadmap Roadmap]
    17  * `4` - [wiki:TracSearch Search]
    18  * `6` - [wiki:TracGuide Trac Guide / Documentation]
    19  * `7` - [wiki:TracTickets New Ticket]
     13 * `2` - [TracTimeline Timeline]
     14 * `3` - [TracRoadmap Roadmap]
     15 * `4` - [TracSearch Search]
     16 * `6` - [TracGuide Trac Guide / Documentation]
     17 * `7` - [TracTickets New Ticket]
    2018 * `9` - [/about About Trac]
    21  * `0` - This page
    22  * `e` - Edit this page
     19 * `e` - Edit (wiki or report)
     20 * `r` - Preview (wiki or ticket)
    2321 * `f` - Search
    2422
  • wiki/pages/TracAdmin

    r26484 r37343  
    1 = TracAdmin =
     1= TracAdmin
     2
     3[[PageOutline(2-5, Contents, floated)]]
    24[[TracGuideToc]]
    35
    46Trac is distributed with a powerful command-line configuration tool. This tool can be used  to configure and customize your Trac-installation to better fit your needs.
    57
    6 Some of those operations can also be performed via the ''Admin'' web interface, an updated version of the [trac:WebAdmin] plugin now integrated within Trac (since version 0.11).
     8Some of those operations can also be performed via the web administration module.
    79
    8 == Usage ==
     10== Usage
    911
    1012For nearly every `trac-admin` command, you'll need to specify the path to the TracEnvironment that you want to administer as the first argument, for example:
     
    3335[[TracAdminHelp(initenv)]]
    3436
    35 It supports an extra `--inherit` option, which can be used to specify a global configuration file which can be used share settings between several environments. You can also inherit from a shared configuration afterwards, by setting the `[inherit] file` option in the `conf/trac.ini` file in your newly created environment, but the advantage of specifying the inherited configuration file at environment creation time is that only the options ''not'' already specified in the global configuration file will be written in the created environment's `conf/trac.ini` file.
     37It supports an extra `--inherit` option, which can be used to specify a global configuration file which can be used to share settings between several environments. You can also inherit from a shared configuration afterwards, by setting the `[inherit] file` option in the `conf/trac.ini` file in your newly created environment, but the advantage of specifying the inherited configuration file at environment creation time is that only the options ''not'' already specified in the global configuration file will be written in the created environment's `conf/trac.ini` file.
    3638See TracIni#GlobalConfiguration.
    3739
    3840Note that in version 0.11 of Trac, `initenv` lost an extra last argument `<templatepath>`, which was used in previous versions to point to the `templates` folder. If you are using the one-liner '`trac-admin /path/to/trac/ initenv <projectname> <db> <repostype> <repospath>`' in the above and getting an error that reads ''''`Wrong number of arguments to initenv: 4`'''', then this is because you're using a `trac-admin` script from an '''older''' version of Trac.
    3941
    40 == Interactive Mode ==
     42== Interactive Mode
    4143
    4244When passing the environment path as the only argument, `trac-admin` starts in interactive mode.
     
    5658}}}
    5759
    58 == Full Command Reference ==
     60== Full Command Reference
    5961
    6062You'll find below the detailed help for all the commands available by default in `trac-admin`. Note that this may not match the list given by `trac-admin <yourenv> help`, as the commands  pertaining to components disabled in that environment won't be available and conversely some plugins activated in the environment can add their own commands.
  • wiki/pages/TracBackup

    r26484 r37343  
    1 = Trac Backup =
     1= Trac Backup
     2
    23[[TracGuideToc]]
    34
    4 Since Trac uses a database backend, some extra care is required to safely create a backup of a [wiki:TracEnvironment project environment]. Luckily, [wiki:TracAdmin trac-admin] has a command to make backups easier: `hotcopy`.
     5Backups are simply a copied snapshot of the entire [wiki:TracEnvironment project environment] directory, including the database. Backups can be created using the `hotcopy` command in [wiki:TracAdmin trac-admin].
    56
    6   ''Note: Trac uses the `hotcopy` nomenclature to match that of [http://subversion.tigris.org/ Subversion], to make it easier to remember when managing both Trac and Subversion servers.''
     7'''Note''': Trac uses the `hotcopy` nomenclature to match that of [http://subversion.tigris.org/ Subversion], to make it easier to remember when managing both Trac and Subversion servers.
    78
    8 == Creating a Backup ==
     9== Creating a Backup
    910
    10 To create a backup of a live TracEnvironment, simply run:
    11 {{{
    12 
    13   $ trac-admin /path/to/projenv hotcopy /path/to/backupdir
    14 
     11To create a backup of a live TracEnvironment simply run:
     12{{{#!sh
     13$ trac-admin /path/to/projenv hotcopy /path/to/backupdir
    1514}}}
    1615
    17 [wiki:TracAdmin trac-admin] will lock the database while copying.''
     16[wiki:TracAdmin trac-admin] will lock the database while copying.
    1817
    1918The resulting backup directory is safe to handle using standard file-based backup tools like `tar` or `dump`/`restore`.
    2019
    21 Please, note, that hotcopy command does not overwrite target directory and when such exists, hotcopy ends with error: `Command failed: [Errno 17] File exists:` This is discussed in [trac:ticket:3198 #3198].
     20Please note, the `hotcopy` command will not overwrite a target directory and when such exists, the operation ends with an error: `Command failed: [Errno 17] File exists:` This is discussed in [trac:ticket:3198 #3198].
    2221
    23 === Restoring a Backup ===
     22=== Restoring a Backup
    2423
    25 Backups are simply a copied snapshot of the entire [wiki:TracEnvironment project environment] directory, including the SQLite database.
     24To restore an environment from a backup, stop the process running Trac, ie the Web server or [wiki:TracStandalone tracd], restore the contents of your backup (path/to/backupdir) to your [wiki:TracEnvironment project environment] directory and restart the service.
    2625
    27 To restore an environment from a backup, stop the process running Trac (i.e. the Web server or [wiki:TracStandalone tracd]), restore the contents of your backup (path/to/backupdir) to your [wiki:TracEnvironment project environment] directory and restart the service.
     26To restore a PostgreSQL database backup, use the command:
     27{{{#!sh
     28psql -U <user> -d <database> -f postgresql.dump
     29}}}
     30The `<database>` option is the same as the [TracEnvironment#DatabaseConnectionStrings database connection string] in the `[trac]` `database` option of //trac.ini//.
    2831
    2932----
  • wiki/pages/TracBatchModify

    r26484 r37343  
    22[[TracGuideToc]]
    33
    4 From [wiki:TracQuery custom query] results Trac provides support for modifying a batch of tickets in one request.
     4Trac supports modifying a batch of tickets in one request from [TracQuery custom query] results .
    55
    6 To perform a batch modification select the tickets you wish to modify and set the new field values using the section underneath the query results.
     6To perform a batch modification, select the tickets you wish to modify and set the new field values using the section underneath the query results.
    77
    88== List fields
    99
    10 The `Keywords` and `Cc` fields are treated as lists, where list items can be added and/or removed in addition of replacing the entire list value. All list field controls accept multiple items (i.e. multiple keywords or cc addresses).
     10The `Keywords` and `Cc` fields are treated as lists, where list items can be added and/or removed in addition of replacing the entire list value. All list field controls accept multiple items, such as multiple keywords or cc addresses.
     11
     12== Excluded fields
     13
     14Multi-line text fields are not supported, because no valid use-case has been presented for syncing them across several tickets. That restriction applies to the `Description` field as well as to any [TracTicketsCustomFields#AvailableFieldTypesandOptions custom field] of type 'textarea'. However, future versions of Trac could support in conjunction with more suitable actions like 'prepend', 'append' or 'search & replace' ([http://trac-hacks.org/ticket/2415 th:#2415]).
  • wiki/pages/TracBrowser

    r26484 r37343  
    1 = The Trac Repository Browser =
     1= The Trac Repository Browser
     2
    23[[TracGuideToc]]
    34
    4 The Trac repository browser can be used to browse specific revisions of directories
    5 and files stored in the repositories associated with the Trac environment.
     5The Trac repository browser can be used to browse specific revisions of directories and files stored in the repositories associated with the Trac environment.
    66
    7 ''(since 0.12)'':
    8 At the top-level of the repository browser is the '''Repository Index''',
    9 listing all the configured repositories.
    10 Each repository has a name which is used as a path prefix in a
    11 "virtual" file hierarchy encompassing all the available repositories.
    12 One of the repositories can be configured with an empty name; this is the default repository.  When such a default repository is present, its top-level files and directories
    13 are also listed, in a '''Default Repository''' section placed before the
    14 repository index. If the default repository is the only repository associated
    15 with the Trac environment the '''Repository Index''' will be omitted ^[#note-multirepos (1)]^.
     7At the top-level of the repository browser is the '''Repository Index''', listing all the configured repositories.
     8Each repository has a name which is used as a path prefix in a "virtual" file hierarchy encompassing all the available repositories.
     9One of the repositories can be configured with an empty name; this is the default repository. When such a default repository is present, its top-level files and directories are also listed, in a '''Default Repository''' section placed before the repository index. If the default repository is the only repository associated with the Trac environment, then the '''Repository Index''' will be omitted. This means that after upgrading a single-repository Trac of version 0.11 (or earlier) to a multi-repository Trac (0.12), the repository browser will look and feel the same, that single repository becoming automatically the "default" repository.
    1610
    17 Directory entries are displayed in a list with sortable columns. The list
    18 entries can be sorted by ''Name'', ''Size'', ''Age'' or ''Author'' by clicking on the column
    19 headers. The sort order can be reversed by clicking on a given column
    20 header again.
     11Directory entries are displayed in a list with sortable columns. The list entries can be sorted by ''Name'', ''Size'', ''Age'' or ''Author'' by clicking on the column headers. The sort order can be reversed by clicking on a given column header again.
    2112
    22 The browser can be used to navigate through the directory structure
    23 by clicking on the directory names.
     13The browser can be used to navigate through the directory structure by clicking on the directory names.
    2414Clicking on a file name will show the contents of the file.
    25 Clicking on the revision number of a file or directory will take
    26 you to the TracRevisionLog for that file.
    27 Note that there's also a ''Revision Log'' navigation link that will do the
    28 same for the path currently being examined.
    29 Clicking on the ''diff'' icon after revision number will display the changes made
    30 to the files modified in that revision.
     15Clicking on the revision number of a file or directory will take you to the TracRevisionLog for that file.
     16Note that there's also a ''Revision Log'' navigation link that will do the same for the path currently being examined.
     17Clicking on the ''diff'' icon after revision number will display the changes made to the files modified in that revision.
    3118Clicking on the ''Age'' of the file - will take you to that changeset in the timeline.
    3219
    33 It's also possible to browse directories or files as they were in history,
    34 at any given repository revision. The default behavior is to display the
    35 latest revision but another revision number can easily be selected using
    36 the ''View revision'' input field at the top of the page.
     20It's also possible to browse directories or files as they were in history, at any given repository revision. The default behavior is to display the latest revision but another revision number can easily be selected using the ''View revision'' input field at the top of the page.
    3721
    38 The color bar next to the ''Age'' column gives a visual indication of the age
    39 of the last change to a file or directory, following the convention that
    40 '''[[span(style=color:#88f,blue)]]''' is oldest and '''[[span(style=color:#f88,red)]]'''
    41 is newest, but this can be [TracIni#browser-section configured].
     22The color bar next to the ''Age'' column gives a visual indication of the age of the last change to a file or directory, following the convention that '''[[span(style=color:#88f,blue)]]''' is oldest and '''[[span(style=color:#f88,red)]]''' is newest, but this can be [TracIni#browser-section configured].
    4223
    43 At the top of the browser page, there's a ''Visit'' drop-down menu which you can use
    44 to select some interesting places in the repository, for example branches or tags.
     24At the top of the browser page, there's a ''Visit'' drop-down menu which you can use to select some interesting places in the repository, for example branches or tags.
    4525This is sometimes referred to as the ''browser quickjump'' facility.
    4626The precise meaning and content of this menu depends on your repository backend.
    47 For Subversion, this list contains by default the top-level trunk directory
    48 and sub-directories of the top-level branches and tags directories
    49 (`/trunk`, `/branches/*`, and `/tags/*`).  This can be [TracIni#svn-section configured]
    50 for more advanced cases.
     27For Subversion, this list contains by default the top-level trunk directory and sub-directories of the top-level branches and tags directories (`/trunk`, `/branches/*`, and `/tags/*`). This can be [TracIni#svn-section configured] for more advanced cases.
    5128
    52 If you're using a Javascript enabled browser, you'll be able to expand and
    53 collapse directories in-place by clicking on the arrow head at the right side of a
    54 directory. Alternatively, the [trac:TracKeys keyboard] can also be used for this:
    55  - use `'j'` and `'k'` to select the next or previous entry, starting with the first
    56  - `'o'` (open) to toggle between expanded and collapsed state of the selected
     29If you're using a Javascript enabled browser, you'll be able to expand and collapse directories in-place by clicking on the arrow head at the right side of a directory. Alternatively, the [trac:TracKeys keyboard] can also be used for this:
     30 - use `j` and `k` to select the next or previous entry, starting with the first
     31 - `o` ('''o'''pen) to toggle between expanded and collapsed state of the selected
    5732   directory or for visiting the selected file
    58  - `'v'` (view, visit) and `'<Enter>'`, same as above
    59  - `'r'` can be used to force the reload of an already expanded directory
    60  - `'A'` can be used to directly visit a file in annotate (blame) mode
    61  - `'L'` to view the log for the selected entry
    62 If no row has been selected using `'j'` or `'k'` these keys will operate on the entry under the mouse.
    63 
    64 {{{#!comment
    65 MMM: I guess that some keys are upper case and some lower to avoid conflicts with browser defined keys.
    66 I find for example in Firefox and IE on windows that 'a' works as well as 'A' but 'l' does not work for 'L'.
    67  cboos: 'l' is reserved for Vim like behavior, see #7867
    68 }}}
     33 - `v` ('''v'''iew, '''v'''isit) and `<Enter>`, same as above
     34 - `r` can be used to force the '''r'''eload of an already expanded directory
     35 - `a` can be used to directly visit a file in '''a'''nnotate (blame) mode
     36 - `l` to view the '''l'''og for the selected entry
     37If no row has been selected using `j` or `k` these keys will operate on the entry under the mouse.
    6938
    7039For the Subversion backend, some advanced additional features are available:
    71  - The `svn:needs-lock` property will be displayed
    72  - Support for the `svn:mergeinfo` property showing the merged and eligible information
    73  - Support for browsing the `svn:externals` property
    74    (which can be [TracIni#svn:externals-section configured])
    75  - The `svn:mime-type` property is used to select the syntax highlighter for rendering
    76    the file. For example, setting `svn:mime-type` to `text/html` will ensure the file is
    77    highlighted as HTML, regardless of the file extension. It also allows selecting the character
    78    encoding used in the file content. For example, if the file content is encoded in UTF-8,
    79    set `svn:mime-type` to `text/html;charset=utf-8`. The `charset=` specification overrides the
    80    default encoding defined in the `default_charset` option of the `[trac]` section
    81    of [TracIni#trac-section trac.ini].
     40 - The `svn:needs-lock` property will be displayed.
     41 - Support for the `svn:mergeinfo` property showing the merged and eligible information.
     42 - Support for browsing the `svn:externals` property, which can be [TracIni#svn:externals-section configured].
     43 - The `svn:mime-type` property is used to select the syntax highlighter for rendering the file. For example, setting `svn:mime-type` to `text/html` will ensure the file is highlighted as HTML, regardless of the file extension. It also allows selecting the character encoding used in the file content. For example, if the file content is encoded in UTF-8, set `svn:mime-type` to `text/html;charset=utf-8`. The `charset=` specification overrides the default encoding defined in the `default_charset` option of the `[trac]` section of [TracIni#trac-section trac.ini].
    8244{{{#!comment
    8345MMM: I found this section a bit hard to understand. I changed the first item as I understood that well.
     
    8648}}}
    8749
    88 
    8950----
    90 {{{#!div style="font-size:85%"
    91 [=#note-multirepos (1)] This means that after upgrading a single-repository Trac of version
    92 0.11 (or below) to a multi-repository Trac (0.12), the repository browser will look and feel
    93 the same, that single repository becoming automatically the "default" repository.
    94 }}}
    95 
    9651See also: TracGuide, TracChangeset, TracFineGrainedPermissions
  • wiki/pages/TracCgi

    r26484 r37343  
    1 = Installing Trac as CGI =
     1= Installing Trac as CGI
     2[[TracGuideToc]]
     3[[PageOutline]]
    24
    3 {{{
    4 #!div class=important
    5   ''Please note that using Trac via CGI is the slowest deployment method available. It is slower than [TracModPython mod_python], [TracFastCgi FastCGI] and even [trac:TracOnWindowsIisAjp IIS/AJP] on Windows.''
     5{{{#!div class=important
     6 ''Please note that using Trac via CGI is the slowest deployment method available. It is slower than [TracModPython mod_python], [TracFastCgi FastCGI] and even [trac:TracOnWindowsIisAjp IIS/AJP] on Windows.''
    67}}}
    78
    8 CGI script is the entrypoint that web-server calls when a web-request to an application is made. To generate the `trac.cgi` script run:
    9 {{{
    10 trac-admin /path/to/env deploy /path/to/www/trac
    11 }}}
    12 `trac.cgi` will be in the `cgi-bin` folder inside the given path. ''Make sure it is executable by your web server''. This command also copies `static resource` files to a `htdocs` directory of a given destination.
     9CGI script is the entrypoint that web-server calls when a web-request to an application is made. The `trac.cgi` script can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths, see TracInstall#cgi-bin. Make sure the script is executable by your web server.
    1310
    14 == Apache web-server configuration ==
     11== Apache web-server configuration
    1512
    1613In [http://httpd.apache.org/ Apache] there are two ways to run Trac as CGI:
    1714
    1815 1. Use a `ScriptAlias` directive that maps an URL to the `trac.cgi` script (recommended)
    19  2. Copy the `trac.cgi` file into the directory for CGI executables used by your web server (commonly named `cgi-bin`). You can also create a symbolic link, but in that case make sure that the `FollowSymLinks` option is enabled for the `cgi-bin` directory.
     16 1. Copy the `trac.cgi` file into the directory for CGI executables used by your web server (commonly named `cgi-bin`). You can also create a symbolic link, but in that case make sure that the `FollowSymLinks` option is enabled for the `cgi-bin` directory.
    2017
    2118To make Trac available at `http://yourhost.example.org/trac` add `ScriptAlias` directive to Apache configuration file, changing `trac.cgi` path to match your installation:
    22 {{{
     19{{{#!apache
    2320ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.cgi
    2421}}}
     
    2724
    2825If you're using Trac with a single project you need to set its location using the `TRAC_ENV` environment variable:
    29 {{{
     26{{{#!apache
    3027<Location "/trac">
    3128  SetEnv TRAC_ENV "/path/to/projectenv"
     
    3431
    3532Or to use multiple projects you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` variable:
    36 {{{
     33{{{#!apache
    3734<Location "/trac">
    3835  SetEnv TRAC_ENV_PARENT_DIR "/path/to/project/parent/dir"
     
    4239 ''Note that the `SetEnv` directive requires enabled `mod_env` module. It is also possible to set TRAC_ENV in trac.cgi. Just add the following code between "try:" and "from trac.web ...":''
    4340
    44 {{{
     41{{{#!python
    4542    import os
    4643    os.environ['TRAC_ENV'] = "/path/to/projectenv"
     
    4946 '' Or for TRAC_ENV_PARENT_DIR: ''
    5047
    51 {{{
     48{{{#!python
    5249    import os
    5350    os.environ['TRAC_ENV_PARENT_DIR'] = "/path/to/project/parent/dir"
    5451}}}
    5552
    56 If you are using the [http://httpd.apache.org/docs/suexec.html Apache suEXEC] feature please see [http://trac.edgewall.org/wiki/ApacheSuexec].
     53If you are using the [http://httpd.apache.org/docs/suexec.html Apache suEXEC] feature please see [trac:ApacheSuexec].
    5754
    5855On some systems, you ''may'' need to edit the shebang line in the `trac.cgi` file to point to your real Python installation path. On a Windows system you may need to configure Windows to know how to execute a .cgi file (Explorer -> Tools -> Folder Options -> File Types -> CGI).
    5956
    60 === Using WSGI ===
     57=== Using WSGI
    6158
    6259You can run a [http://henry.precheur.org/python/how_to_serve_cgi WSGI handler] [http://pythonweb.org/projects/webmodules/doc/0.5.3/html_multipage/lib/example-webserver-web-wsgi-simple-cgi.html under CGI].  You can [wiki:TracModWSGI#Thetrac.wsgiscript write your own application function], or use the deployed trac.wsgi's application.
    6360
    64 == Mapping Static Resources ==
     61== Mapping Static Resources
    6562
    6663See TracInstall#MappingStaticResources.
    6764
    68 == Adding Authentication ==
     65== Adding Authentication
    6966
    7067See TracInstall#ConfiguringAuthentication.
  • wiki/pages/TracChangeset

    r26484 r37343  
    22[[TracGuideToc]]
    33
    4 Trac has a built-in functionality for visualizing “diffs” - changes to files.
     4Trac has a built-in functionality for visualizing “diffs”, or changes to files.
    55
    6 There are different kinds of ''change sets''.
    7 Some can correspond to revisions made in the repositories,
    8 others can aggregate changes made in several revisions,
    9 but in the end, any kind of differences can be shown.
     6There are different kinds of ''change sets''.  Some correspond to revisions made in the repositories, others aggregate changes made in several revisions. Ultimately, any kind of difference can be shown.
    107
    11 The changeset view consists of two parts, the ''header''
    12 and the ''diff views''.
     8The changeset view consists of two parts, the ''header'' and the ''diff views''.
    139
    1410== Changeset Header ==
     
    2319 * Files — A list of files affected by this changeset
    2420
    25 If more than one revision is involved in the set of changes being
    26 displayed, the ''Timestamp'', ''Author'' and ''Message'' fields
    27 won't be shown.
     21If more than one revision is involved in the set of changes being displayed, the ''Timestamp'', ''Author'' and ''Message'' fields will not be shown.
    2822
    29 In front of each listed file, you'll find  a colored rectangle. The color
    30 indicates how the file is affected by the changeset.
     23A colored rectangle indicates how the file is affected by the changeset:
    3124 
    3225 [[span(style=background:#bfb;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Green: Added \\
     
    3932== Diff Views ==
    4033
    41 Below the header is the main part of the changeset, the diff view. Each file is shown in a separate section, each of which will contain only the regions of the file that are affected by the changeset. There are two different styles of displaying the diffs: ''inline'' or ''side-by-side'' (you can switch between those styles using the preferences form):
     34Below the header is the main part of the changeset, the diff view. Each file is shown in a separate section, each of which contains only the regions of the file that are affected by the changeset. There are two different styles to display the diffs: ''inline'' or ''side-by-side''. You can switch between the styles using the preferences form:
    4235
    43  * The ''inline'' style shows the changed regions of a file underneath each other. A region removed from the file will be colored red, an added region will be colored green. If a region was modified, the old version is displayed above the new version. Line numbers on the left side indicate the exact position of the change in both the old and the new version of the file.
    44  * The ''side-by-side'' style shows the old version on the left and the new version on the right (this will typically require more screen width than the inline style.) Added and removed regions will be colored in the same way as with the inline style (green and red, respectively), but modified regions will have a yellow background.
     36 * The ''inline'' style shows the changed regions of a file underneath each other. A region removed from the file will be colored red, an added region will be colored green. If a region was modified, the old version is displayed above the new version. Line numbers indicate the exact position of the change in both the old and the new version of the file.
     37 * The ''side-by-side'' style shows the old version on the left and the new version on the right and this will typically require more screen width than the inline style. Added and removed regions will be colored in the same way as with the inline style (green and red), and modified regions will have a yellow background.
    4538
    4639In addition, various advanced options are available in the preferences form for adjusting the display of the diffs:
    47  * You can set how many lines are displayed before and after every change
    48    (if the value ''all'' is used, then the full file will be shown)
    49  * You can toggle whether blank lines, case changes and white space changes are ignored, thereby letting you find the functional changes more quickly
    50 
     40 * You can set how many lines are displayed before and after every change; if the value ''all'' is used, then the full file will be shown.
     41 * You can toggle whether blank lines, case changes and white space changes are ignored, thereby letting you find the functional changes more quickly.
    5142
    5243== The Different Ways to Get a Diff ==
     
    5445=== Examining a Changeset ===
    5546
    56 When viewing a repository check-in, such as when following a
    57 changeset [wiki:TracLinks link] or a changeset event in the
    58 [wiki:TracTimeline timeline], Trac will display the exact changes
    59 made by the check-in.
     47When viewing a repository check-in, such as when following a changeset [wiki:TracLinks link] or a changeset event in the [wiki:TracTimeline timeline], Trac will display the exact changes made by the check-in.
    6048
    61 There will be also navigation links to the ''Previous Changeset''
    62 to and ''Next Changeset''.
     49There will be also navigation links to the ''Previous Changeset'' to and ''Next Changeset''.
    6350
    6451=== Examining Differences Between Revisions ===
    6552
    66 Often you'll want to look at changes made on a file
    67 or on a directory spanning multiple revisions. The easiest way
    68 to get there is from the TracRevisionLog, where you can select
    69 the ''old'' and the ''new'' revisions of the file or directory, and
    70 then click the ''View changes'' button.
     53Often you want to look at changes made on a file or on a directory spanning multiple revisions. The easiest way to get there is from the TracRevisionLog, where you can select the ''old'' and the ''new'' revisions of the file or directory, and then click the ''View changes'' button.
    7154
    7255=== Examining Differences Between Branches ===
    7356
    74 One of the core features of version control systems is the possibility
    75 to work simultaneously on different ''Lines of Developments'', commonly
    76 called “branches”. Trac enables you to examine the exact differences
    77 between such branches.
     57One of the core features of version control systems is the possibility to work simultaneously on different ''Lines of Developments'', commonly called “branches”. Trac enables you to examine the exact differences between such branches.
    7858
    79 Using the '''View changes ...''' button in the TracBrowser allows you to enter
    80 ''From:'' and ''To:'' path/revision pairs. The resulting set of differences consist
    81 of the changes that should be applied to the ''From:'' content in order
    82 to get to the ''To:'' content.
     59Using the '''View changes ...''' button in the TracBrowser allows you to enter ''From:'' and ''To:'' path/revision pairs. The resulting set of differences consist of the changes that should be applied to the ''From:'' content to get to the ''To:'' content.
    8360
    84 For convenience, it is possible to invert the roles of the ''old'' and the ''new''
    85 path/revision pairs by clicking the ''Reverse Diff'' link on the changeset page.
     61For convenience, it is possible to invert the roles of the ''old'' and the ''new'' path/revision pairs by clicking the ''Reverse Diff'' link on the changeset page.
    8662
    8763=== Checking the Last Change ===
    8864
    89 The last possibility for examining changes is to use the ''Last Change''
    90 link provided by the TracBrowser.
     65Another way to examine changes is to use the ''Last Change'' link provided by the TracBrowser.
    9166
    92 This link will take you to the last change that was made on that path.
    93 From there, you can use the ''Previous Change'' and ''Next Change'' links
    94 to traverse the change history of the file or directory.
     67This link will take you to the last change that was made on that path. From there, you can use the ''Previous Change'' and ''Next Change'' links to traverse the change history of the file or directory.
    9568
    9669----
  • wiki/pages/TracEnvironment

    r26484 r37343  
    1 = The Trac Environment =
     1= The Trac Environment
    22
    3 Trac uses a directory structure and a database for storing project data. The directory is referred to as the “environment”.
     3[[TracGuideToc]]
     4[[PageOutline(2-5)]]
    45
    5 == Creating an Environment ==
     6Trac uses a directory structure and a database for storing project data. The directory is referred to as the environment.
    67
    7 A new Trac environment is created using  [TracAdmin#initenv trac-admin's initenv]:
    8 {{{
     8== Creating an Environment
     9
     10A new Trac environment is created using [TracAdmin#initenv trac-admin's initenv]:
     11{{{#!sh
    912$ trac-admin /path/to/myproject initenv
    1013}}}
    1114
    12 `trac-admin` will ask you for the name of the project and the
    13 database connection string (explained below).
     15`trac-admin` will ask you for the name of the project and the database connection string, see below.
    1416
    15 === Some Useful Tips
    16  - The user under which the web server runs will require file system write permission to
    17  the environment directory and all the files inside. Please remember to set
    18  the appropriate permissions. The same applies to the source code repository,
    19  although the user under which Trac runs will only require write access to a Subversion repository created with the BDB file system; for other repository types, check the corresponding plugin's documentation.
     17=== Useful Tips
     18
     19 - Place your environment's directory on a filesystem which supports sub-second timestamps, as Trac monitors the timestamp of its configuration files and changes happening on a filesystem with too coarse-grained timestamp resolution may go undetected in Trac < 1.0.2. This is also true for the location of authentication files when using TracStandalone.
     20
     21 - The user under which the web server runs will require file system write permission to the environment directory and all the files inside. Please remember to set the appropriate permissions. The same applies to the source code repository, although the user under which Trac runs will only require write access to a Subversion repository created with the BDB file system; for other repository types, check the corresponding plugin's documentation.
    2022 
    21  - `initenv`, when using an svn repository, does not imply that trac-admin will perform `svnadmin create` for the specified repository path. You need to perform the `svnadmin create` prior to `trac-admin initenv` if you're creating a new svn repository altogether with a new trac environment, otherwise you will see a message "Warning: couldn't index the repository" when initializing the environment.
     23 - `initenv`, when using an svn repository, does not imply that trac-admin will perform `svnadmin create` for the specified repository path. You need to perform the `svnadmin create` prior to `trac-admin initenv` if you're creating a new svn repository altogether with a new Trac environment; otherwise you will see a message "Warning: couldn't index the repository" when initializing the environment.
    2224
    23  - Non-ascii environment paths are not supported
     25 - Non-ascii environment paths are not supported.
    2426 
    25  - Also, it seems that project names with spaces can be problematic for authentication (see [trac:#7163]).
     27 - Also, it seems that project names with spaces can be problematic for authentication, see [trac:#7163].
    2628
    2729 - TracPlugins located in a [TracIni#inherit-section shared plugins folder] that is defined in an [TracIni#GlobalConfiguration inherited configuration] are currently not loaded during creation, and hence, if they need to create extra tables for example, you'll need to [TracUpgrade#UpgradetheTracEnvironment upgrade the environment] before being able to use it.
    2830
    29 == Database Connection Strings ==
     31{{{#!div style="border: 1pt dotted; margin: 1em"
     32**Caveat:** don't confuse the //Trac environment directory// with the //source code repository directory//.
    3033
    31 Since version 0.9, Trac supports both [http://sqlite.org/ SQLite] and
    32 [http://www.postgresql.org/ PostgreSQL] database backends.  Preliminary
    33 support for [http://mysql.com/ MySQL] was added in 0.10.  The default is
    34 to use SQLite, which is probably sufficient for most projects. The database
    35 file is then stored in the environment directory, and can easily be
    36 [wiki:TracBackup backed up] together with the rest of the environment.
     34This is a common beginners' mistake.
     35It happens that the structure for a Trac environment is loosely modeled after the Subversion repository directory structure, but those are two disjoint entities and they are not and //must not// be located at the same place.
     36}}}
    3737
    38 === SQLite Connection String ===
     38== Database Connection Strings
     39
     40Trac supports [http://sqlite.org/ SQLite], [http://www.postgresql.org/ PostgreSQL] and [http://mysql.com/ MySQL] database backends. The default is SQLite, which is probably sufficient for most projects. The database file is then stored in the environment directory, and can easily be [wiki:TracBackup backed up] together with the rest of the environment.
     41
     42Note that if the username or password of the connection string (if applicable) contains the `:`, `/` or `@` characters, they need to be URL encoded.
     43
     44=== SQLite Connection String
     45
    3946The connection string for an SQLite database is:
    4047{{{
     
    4350where `db/trac.db` is the path to the database file within the Trac environment.
    4451
    45 === PostgreSQL Connection String ===
    46 If you want to use PostgreSQL or MySQL instead, you'll have to use a
    47 different connection string. For example, to connect to a PostgreSQL
    48 database on the same machine called `trac`, that allows access to the
    49 user `johndoe` with the password `letmein`, use:
     52=== PostgreSQL Connection String
     53
     54If you want to use PostgreSQL instead, you'll have to use a different connection string. For example, to connect to a PostgreSQL database on the same machine called `trac` for user `johndoe` with the password `letmein` use:
    5055{{{
    5156postgres://johndoe:letmein@localhost/trac
    5257}}}
    53 ''Note that due to the way the above string is parsed, the "/" and "@" characters cannot be part of the password.''
    5458
    55 If PostgreSQL is running on a non-standard port (for example 9342), use:
     59If PostgreSQL is running on a non-standard port, for example 9342, use:
    5660{{{
    5761postgres://johndoe:letmein@localhost:9342/trac
    5862}}}
    5963
    60 On UNIX, you might want to select a UNIX socket for the transport,
    61 either the default socket as defined by the PGHOST environment variable:
     64On UNIX, you might want to select a UNIX socket for the transport, either the default socket as defined by the PGHOST environment variable:
    6265{{{
    6366postgres://user:password@/database
    6467}}}
     68
    6569or a specific one:
    6670{{{
     
    6872}}}
    6973
    70 Note that with PostgreSQL you will have to create the database before running
    71 `trac-admin initenv`.
     74Note that with PostgreSQL you will have to create the database before running `trac-admin initenv`.
    7275
    7376See the [http://www.postgresql.org/docs/ PostgreSQL documentation] for detailed instructions on how to administer [http://postgresql.org PostgreSQL].
    74 Generally, the following is sufficient to create a database user named `tracuser`, and a database named `trac`.
    75 {{{
    76 createuser -U postgres -E -P tracuser
    77 createdb -U postgres -O tracuser -E UTF8 trac
    78 }}}
    79 When running `createuser` you will be prompted for the password for the user 'tracuser'. This new user will not be a superuser, will not be allowed to create other databases and will not be allowed to create other roles. These privileges are not needed to run a trac instance. If no password is desired for the user, simply remove the `-P` and `-E` options from the `createuser` command.  Also note that the database should be created as UTF8. LATIN1 encoding causes errors trac's use of unicode in trac.  SQL_ASCII also seems to work.
    80 
    81 Under some default configurations (debian) one will have run the `createuser` and `createdb` scripts as the `postgres` user.  For example:
    82 {{{
    83 sudo su - postgres -c 'createuser -U postgres -S -D -R -E -P tracuser'
    84 sudo su - postgres -c 'createdb -U postgres -O tracuser -E UTF8 trac'
     77Generally, the following is sufficient to create a database user named `tracuser` and a database named `trac`:
     78{{{#!sh
     79$ createuser -U postgres -E -P tracuser
     80$ createdb -U postgres -O tracuser -E UTF8 trac
    8581}}}
    8682
    87 Trac uses the `public` schema by default but you can specify a different schema in the connection string:
     83When running `createuser` you will be prompted for the password for the user 'tracuser'. This new user will not be a superuser, will not be allowed to create other databases and will not be allowed to create other roles. These privileges are not needed to run a Trac instance. If no password is desired for the user, simply remove the `-P` and `-E` options from the `createuser` command. Also note that the database should be created as UTF8. LATIN1 encoding causes errors, because of Trac's use of unicode. SQL_ASCII also seems to work.
     84
     85Under some default configurations (Debian) one will have run the `createuser` and `createdb` scripts as the `postgres` user:
     86{{{#!sh
     87$ sudo su - postgres -c 'createuser -U postgres -S -D -R -E -P tracuser'
     88$ sudo su - postgres -c 'createdb -U postgres -O tracuser -E UTF8 trac'
     89}}}
     90
     91Trac uses the `public` schema by default, but you can specify a different schema in the connection string:
    8892{{{
    8993postgres://user:pass@server/database?schema=yourschemaname
    9094}}}
    9195
    92 === MySQL Connection String ===
     96=== MySQL Connection String
    9397
    94 If you want to use MySQL instead, you'll have to use a
    95 different connection string. For example, to connect to a MySQL
    96 database on the same machine called `trac`, that allows access to the
    97 user `johndoe` with the password `letmein`, the mysql connection string is:
     98The format of the MySQL connection string is similar to those for PostgreSQL, with the `postgres` scheme being replaced by `mysql`. For example, to connect to a MySQL database on the same machine called `trac` for user `johndoe` with password `letmein`:
    9899{{{
    99100mysql://johndoe:letmein@localhost:3306/trac
    100101}}}
    101102
    102 == Source Code Repository ==
     103== Source Code Repository
    103104
    104 Since version 0.12, a single Trac environment can be connected to more than one repository. There are many different ways to connect repositories to an environment, see TracRepositoryAdmin. This page also details the various attributes that can be set for a repository (like `type`, `url`, `description`).
     105A single environment can be connected to more than one repository. However, by default Trac is not connected to any source code repository, and the ''Browse Source'' toolbar item will not be displayed.
    105106
    106 In Trac 0.12 `trac-admin` no longer asks questions related to repositories. Therefore, by default Trac is not connected to any source code repository, and the ''Browse Source'' toolbar item will not be displayed.
    107 You can also explicitly disable the `trac.versioncontrol.*` components (which are otherwise still loaded)
    108 {{{
    109 [components]
    110 trac.versioncontrol.* = disabled
    111 }}}
     107There are many different ways to connect repositories to an environment, see TracRepositoryAdmin. A single repository can be specified when the environment is created by passing the optional arguments `repository_type` and `repository_dir` to the `initenv` command.
    112108
    113 For some version control systems, it is possible to specify not only the path to the repository,
    114 but also a ''scope'' within the repository. Trac will then only show information
    115 related to the files and changesets below that scope. The Subversion backend for
    116 Trac supports this; for other types, check the corresponding plugin's documentation.
    117 
    118 Example of a configuration for a Subversion repository used as the default repository:
    119 {{{
    120 [trac]
    121 repository_type = svn
    122 repository_dir = /path/to/your/repository
    123 }}}
    124 
    125 The configuration for a scoped Subversion repository would be:
    126 {{{
    127 [trac]
    128 repository_type = svn
    129 repository_dir = /path/to/your/repository/scope/within/repos
    130 }}}
    131 
    132 == Directory Structure ==
     109== Directory Structure
    133110
    134111An environment directory will usually consist of the following files and directories:
    135112
    136113 * `README` - Brief description of the environment.
    137  * `VERSION` - Contains the environment version identifier.
    138  * `attachments` - Attachments to wiki pages and tickets are stored here.
     114 * `VERSION` - Environment version identifier.
     115 * `files`
     116  * `attachments` - Attachments to wiki pages and tickets.
    139117 * `conf`
    140    * `trac.ini` - Main configuration file. See TracIni.
     118  * `trac.ini` - Main configuration file. See TracIni.
    141119 * `db`
    142    * `trac.db` - The SQLite database (if you're using SQLite).
    143  * `htdocs` - directory containing web resources, which can be referenced in Genshi templates using `/htdocs/site/...` URLs. ''(since 0.11)''
    144  * `log` - default directory for log files, if logging is turned on and a relative path is given.
    145  * `plugins` - Environment-specific [wiki:TracPlugins plugins] (Python eggs or single file plugins, since [trac:milestone:0.10 0.10])
    146  * `templates` - Custom Genshi environment-specific templates. ''(since 0.11)''
    147    * `site.html` - method to customize header, footer, and style, described in TracInterfaceCustomization#SiteAppearance
    148 
    149 === Caveat: don't confuse a ''Trac environment directory'' with the ''source code repository directory'' #Caveat
    150 
    151 This is a common beginners' mistake.
    152 It happens that the structure for a Trac environment is loosely modelled after the Subversion repository directory
    153 structure, but those are two disjoint entities and they are not and ''must not'' be located at the same place.
     120  * `trac.db` - The SQLite database, if you are using SQLite.
     121 * `htdocs` - Directory containing web resources, which can be referenced in Genshi templates using `/chrome/site/...` URLs.
     122 * `log` - Default directory for log files, if `file` logging is enabled and a relative path is given.
     123 * `plugins` - Environment-specific [wiki:TracPlugins plugins].
     124 * `templates` - Custom Genshi environment-specific templates.
     125  * `site.html` - Method to customize header, footer, and style, described in TracInterfaceCustomization#SiteAppearance.
    154126
    155127----
  • wiki/pages/TracFastCgi

    r26484 r37343  
    1 [[PageOutline]]
    2 
    3 = Trac with FastCGI =
     1= Trac with FastCGI
     2
     3[[TracGuideToc]]
     4[[PageOutline(2-5, Contents, floated)]]
    45
    56[http://www.fastcgi.com/ FastCGI] interface allows Trac to remain resident much like with [wiki:TracModPython mod_python] or [wiki:TracModWSGI mod_wsgi]. It is faster than external CGI interfaces which must start a new process for each request.  Additionally, it is supported by much wider variety of web servers.
    67
    7 Note that unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], i.e. run with different permissions than web server running with (`mod_wsgi` supports the `WSGIDaemonProcess` with user / group parameters to achieve the same effect).
     8Note that unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], ie run with different permissions than the web server runs with. `mod_wsgi` supports the `WSGIDaemonProcess` with user / group parameters to achieve the same effect.
    89
    910'''Note for Windows:''' Trac's FastCGI does not run under Windows, as Windows does not implement `Socket.fromfd`, which is used by `_fcgi.py`. If you want to connect to IIS, you may want to try [trac:TracOnWindowsIisAjp AJP]/[trac:TracOnWindowsIisAjp ISAPI].
    1011
    11 [[PageOutline(2-3,Overview,inline)]]
    12 
    13 
    14 == Simple Apache configuration ==
     12== Simple Apache configuration
    1513
    1614There are two FastCGI modules commonly available for Apache: `mod_fastcgi` and
     
    1917The following sections focus on the FCGI specific setup, see also [wiki:TracModWSGI#ConfiguringAuthentication] for configuring the authentication in Apache.
    2018
    21 Regardless of which cgi module is used, be sure the web server has executable permissions on the cgi-bin folder. While FastCGI will throw specific permissions errors, mod_fcgid will throw an ambiguous error if this has not been done. (Connection reset by peer: mod_fcgid: error reading data from FastCGI server)
    22 
    23 === Set up with `mod_fastcgi` ===
     19Regardless of which cgi module is used, be sure the web server has executable permissions on the cgi-bin folder. While FastCGI will throw specific permissions errors, mod_fcgid will throw an ambiguous error if this has not been done. Connection reset by peer: mod_fcgid: error reading data from FastCGI server.
     20
     21=== Set up with `mod_fastcgi`
     22
    2423`mod_fastcgi` uses `FastCgiIpcDir` and `FastCgiConfig` directives that should be added to an appropriate Apache configuration file:
    2524{{{
     
    4847}}}
    4948
    50 === Set up with `mod_fcgid` ===
    51 Configure `ScriptAlias` (see TracCgi for details), but call `trac.fcgi`
    52 instead of `trac.cgi`. Note that slash at the end - it is important.
     49=== Set up with `mod_fcgid`
     50
     51Configure `ScriptAlias` (see TracCgi for details), but call `trac.fcgi` instead of `trac.cgi`:
    5352{{{
    5453ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.fcgi/
    5554}}}
    56 
    57 To set up Trac environment for `mod_fcgid` it is necessary to use
    58 `DefaultInitEnv` directive. It cannot be used in `Directory` or
    59 `Location` context, so if you need to support multiple projects, try
    60 alternative environment setup below.
     55Note the slash at the end.
     56
     57To set up Trac environment for `mod_fcgid` it is necessary to use `DefaultInitEnv` directive. It cannot be used in `Directory` or `Location` context, so if you need to support multiple projects, try alternative environment setup below.
    6158
    6259{{{
     
    6461}}}
    6562
    66 === alternative environment setup ===
    67 A better method to specify path to Trac environment is to embed the path
    68 into `trac.fcgi` script itself. That doesn't require configuration of server
    69 environment variables, works for both FastCgi modules
    70 (and for [http://www.lighttpd.net/ lighttpd] and CGI as well):
     63=== alternative environment setup
     64
     65A better method to specify path to the Trac environment is to embed the path into `trac.fcgi` script itself. That doesn't require configuration of the server environment variables, works for both [trac:FastCgi] modules as well as for [http://www.lighttpd.net/ lighttpd] and CGI:
    7166{{{
    7267import os
    7368os.environ['TRAC_ENV'] = "/path/to/projectenv"
    7469}}}
    75 or
     70or:
    7671{{{
    7772import os
     
    7974}}}
    8075
    81 With this method different projects can be supported by using different
    82 `.fcgi` scripts with different `ScriptAliases`.
     76With this method different projects can be supported by using different `.fcgi` scripts with different `ScriptAliases`.
    8377
    8478See [https://coderanger.net/~coderanger/httpd/fcgi_example.conf this fcgid example config] which uses a !ScriptAlias directive with trac.fcgi with a trailing / like this:
     
    8781}}}
    8882
    89 == Simple Cherokee Configuration ==
     83== Simple Cherokee Configuration
    9084
    9185The configuration on Cherokee's side is quite simple. You will only need to know that you can spawn Trac as an SCGI process.
    9286You can either start it manually, or better yet, automatically by letting Cherokee spawn the server whenever it is down.
    93 First set up an information source in cherokee-admin with a local interpreter.
     87First set up an information source in cherokee-admin with a local interpreter:
    9488
    9589{{{
     
    113107}}}
    114108
    115 
    116 == Simple Lighttpd Configuration ==
    117 
    118 The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.lighttpd.net/ lighttpd].
    119 
    120 lighttpd is a secure, fast, compliant and very flexible web-server that has been optimized for high-performance
    121 environments.  It has a very low memory footprint compared to other web servers and takes care of CPU load.
    122 
    123 For using `trac.fcgi`(prior to 0.11) / fcgi_frontend.py (0.11) with lighttpd add the following to your lighttpd.conf:
     109== Simple Lighttpd Configuration
     110
     111The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.lighttpd.net/ Lighttpd].
     112
     113Lighttpd is a secure, fast, compliant and very flexible web-server that has been optimized for high-performance environments. It has a very low memory footprint compared to other web servers and takes care of CPU load.
     114
     115For using `trac.fcgi`(prior to 0.11) / fcgi_frontend.py (0.11) with Lighttpd add the following to your lighttpd.conf:
    124116{{{
    125117#var.fcgi_binary="/usr/bin/python /path/to/fcgi_frontend.py" # 0.11 if installed with easy_setup, it is inside the egg directory
     
    138130}}}
    139131
    140 Note that you will need to add a new entry to `fastcgi.server` for each separate Trac instance that you wish to run. Alternatively, you may use the `TRAC_ENV_PARENT_DIR` variable instead of `TRAC_ENV` as described above,
    141 and you may set one of the two in `trac.fcgi` instead of in `lighttpd.conf`
    142 using `bin-environment` (as in the section above on Apache configuration).
    143 
    144 Note that lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example (see [trac:#2418]). This is fixed in lighttpd 1.5, and under lighttpd 1.4.23 or later the workaround is to add `"fix-root-scriptname" => "enable"` as a parameter of fastcgi.server.
     132Note that you will need to add a new entry to `fastcgi.server` for each separate Trac instance that you wish to run. Alternatively, you may use the `TRAC_ENV_PARENT_DIR` variable instead of `TRAC_ENV` as described above, and you may set one of the two in `trac.fcgi` instead of in `lighttpd.conf` using `bin-environment`, as in the section above on Apache configuration.
     133
     134Note that Lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example (see [trac:#2418]). This is fixed in Lighttpd 1.5, and under Lighttpd 1.4.23 or later the workaround is to add `"fix-root-scriptname" => "enable"` as a parameter of fastcgi.server.
    145135
    146136For using two projects with lighttpd add the following to your `lighttpd.conf`:
     
    166156                )
    167157}}}
    168 Note that field values are different.  If you prefer setting the environment
    169 variables in the `.fcgi` scripts, then copy/rename `trac.fcgi`, e.g., to
    170 `first.fcgi` and `second.fcgi`, and reference them in the above settings.
    171 Note that the above will result in different processes in any event, even
    172 if both are running from the same `trac.fcgi` script.
     158
     159Note that field values are different. If you prefer setting the environment variables in the `.fcgi` scripts, then copy/rename `trac.fcgi`, eg to `first.fcgi` and `second.fcgi`, and reference them in the above settings.
     160Note that the above will result in different processes in any event, even if both are running from the same `trac.fcgi` script.
    173161
    174162{{{
     
    213201               )
    214202
    215 
    216 }}}
    217 Note that lighttpd (I use version 1.4.3) stopped if password file doesn't exist.
    218 
    219 Note that lighttpd doesn't support 'valid-user' in versions prior to 1.3.16.
    220 
    221 Conditional configuration is also useful for mapping static resources, i.e. serving out images and CSS directly instead of through FastCGI:
     203}}}
     204Note that Lighttpd (v1.4.3) stops if the password file doesn't exist.
     205
     206Note that Lighttpd doesn't support 'valid-user' in versions prior to 1.3.16.
     207
     208Conditional configuration is also useful for mapping static resources, ie serving out images and CSS directly instead of through FastCGI:
    222209{{{
    223210# Aliasing functionality is needed
     
    243230}
    244231}}}
     232
    245233The technique can be easily adapted for use with multiple projects by creating aliases for each of them, and wrapping the fastcgi.server declarations inside conditional configuration blocks.
    246234Also there is another way to handle multiple projects and it's to use TRAC_ENV_PARENT_DIR instead of TRAC_ENV and use global auth, let's see an example:
     
    274262}}}
    275263
    276 Changing date/time format also supported by lighttpd over environment variable LC_TIME
     264Changing date/time format also supported by lighttpd over environment variable LC_TIME:
    277265{{{
    278266fastcgi.server = ("/trac" =>
     
    293281]
    294282
    295 Relaunch lighttpd, and browse to `http://yourhost.example.org/trac` to access Trac.
    296 
    297 Note about running lighttpd with reduced permissions:
    298 
    299 If nothing else helps and trac.fcgi doesn't start with lighttpd settings `server.username = "www-data"`, `server.groupname = "www-data"`, then in the `bin-environment` section set `PYTHON_EGG_CACHE` to the home directory of `www-data` or some other directory accessible to this account for writing.
    300 
    301 
    302 == Simple !LiteSpeed Configuration ==
     283Relaunch Lighttpd and browse to `http://yourhost.example.org/trac` to access Trac.
     284
     285Note about running Lighttpd with reduced permissions: If nothing else helps and trac.fcgi doesn't start with Lighttpd settings `server.username = "www-data"`, `server.groupname = "www-data"`, then in the `bin-environment` section set `PYTHON_EGG_CACHE` to the home directory of `www-data` or some other directory accessible to this account for writing.
     286
     287== Simple !LiteSpeed Configuration
    303288
    304289The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.litespeedtech.com/ LiteSpeed].
     
    306291!LiteSpeed web server is an event-driven asynchronous Apache replacement designed from the ground-up to be secure, scalable, and operate with minimal resources. !LiteSpeed can operate directly from an Apache config file and is targeted for business-critical environments.
    307292
    308  1. Please make sure you have first have a working install of a Trac project. Test install with “tracd” first.
    309 
    310  2. Create a Virtual Host for this setup. From now on we will refer to this vhost as !TracVhost. For this tutorial we will be assuming that your trac project will be accessible via:
    311 
     293 1. Please make sure you have a working install of a Trac project. Test install with "tracd" first.
     294
     295 2. Create a Virtual Host for this setup. From now on we will refer to this vhost as !TracVhost. For this tutorial we will be assuming that your Trac project will be accessible via:
    312296{{{
    313297http://yourdomain.com/trac/
    314298}}}
    315299
    316  3. Go “!TracVhost → External Apps” tab and create a new “External Application”.
    317 
     300 3. Go "!TracVhost → External Apps" tab and create a new "External Application".
    318301{{{
    319302Name: MyTracFCGI       
     
    332315}}}
    333316
    334  4. Optional. If you need to use htpasswd based authentication. Go to “!TracVhost → Security” tab and create a new security “Realm”.
     317 4. Optional: If you need to use htpasswd based authentication. Go to "!TracVhost → Security" tab and create a new security Realm.
    335318
    336319{{{
     
    342325If you don’t have a htpasswd file or don’t know how to create the entries within one, go to http://sherylcanter.com/encrypt.php, to generate the user:password combos.
    343326
    344  5. Go to “!PythonVhost → Contexts” and create a new “FCGI Context”.
     327 5. Go to "!PythonVhost → Contexts" and create a new FCGI Context.
    345328
    346329{{{
     
    365348}}}
    366349
    367 
    368 == Simple Nginx Configuration ==
     350== Simple Nginx Configuration
    369351
    370352Nginx is able to communicate with FastCGI processes, but can not spawn them. So you need to start FastCGI server for Trac separately.
    371353
    372354 1. Nginx configuration with basic authentication handled by Nginx - confirmed to work on 0.6.32
    373 {{{
     355 {{{
    374356    server {
    375357        listen       10.9.8.7:443;
     
    386368        ssl_prefer_server_ciphers   on;
    387369
    388         # (Or ``^/some/prefix/(.*)``.
    389         if ($uri ~ ^/(.*)) {
    390              set $path_info /$1;
     370        # it makes sense to serve static resources through Nginx (or ``~ [/some/prefix]/chrome/(.*)``)
     371        location ~ /chrome/(.*) {
     372             alias /home/trac/instance/static/htdocs/$1;
    391373        }
    392374
    393         # it makes sense to serve static resources through Nginx
    394         location /chrome/ {
    395              alias /home/trac/instance/static/htdocs/;
    396         }
    397 
    398         # You can copy this whole location to ``location [/some/prefix]/login``
     375        # You can copy this whole location to ``location [/some/prefix](/login)``
    399376        # and remove the auth entries below if you want Trac to enforce
    400377        # authorization where appropriate instead of needing to authenticate
    401378        # for accessing the whole site.
    402         # (Or ``location /some/prefix``.)
    403         location / {
     379        # (Or ``~ location /some/prefix(/.*)``.)
     380        location ~ (/.*) {
    404381            auth_basic            "trac realm";
    405382            auth_basic_user_file /home/trac/htpasswd;
     
    415392            # (Or ``fastcgi_param  SCRIPT_NAME  /some/prefix``.)
    416393            fastcgi_param  SCRIPT_NAME        "";
    417             fastcgi_param  PATH_INFO          $path_info;
     394            fastcgi_param  PATH_INFO          $1;
    418395
    419396            ## WSGI NEEDED VARIABLES - trac warns about them
     
    438415    }
    439416}}}
    440 
    441  2. Modified trac.fcgi:
    442 
    443 {{{
     417 1. Modified trac.fcgi:
     418 {{{
    444419#!/usr/bin/env python
    445420import os
     
    472447
    473448}}}
    474 
    475  3. reload nginx and launch trac.fcgi like that:
    476 
    477 {{{
     449 1. reload nginx and launch trac.fcgi like that:
     450 {{{#!sh
    478451trac@trac.example ~ $ ./trac-standalone-fcgi.py
    479452}}}
    480453
    481454The above assumes that:
    482  * There is a user named 'trac' for running trac instances and keeping trac environments in its home directory.
     455 * There is a user named 'trac' for running trac instances and keeping trac environments in its home directory
    483456 * `/home/trac/instance` contains a trac environment
    484457 * `/home/trac/htpasswd` contains authentication information
     
    488461
    489462Unfortunately nginx does not support variable expansion in fastcgi_pass directive.
    490 Thus it is not possible to serve multiple trac instances from one server block.
    491 
    492 If you worry enough about security, run trac instances under separate users.
    493 
    494 Another way to run trac as a FCGI external application is offered in ticket #T6224
     463Thus it is not possible to serve multiple Trac instances from one server block.
     464
     465If you worry enough about security, run Trac instances under separate users.
     466
     467Another way to run Trac as a FCGI external application is offered in ticket #T6224
    495468
    496469----
  • wiki/pages/TracFineGrainedPermissions

    r26484 r37343  
     1= Fine grained permissions =
    12[[PageOutline(2-5, Contents, floated)]]
    2 = Fine grained permissions =
    3 
    4 Before Trac 0.11, it was only possible to define fine-grained permissions checks on the repository browser sub-system.
    5 
    6 Since 0.11, there's a general mechanism in place that allows custom **permission policy plugins** to grant or deny any action on any kind of Trac resources, even at the level of specific versions of such resources.
    7 
    8 Note that for Trac 0.12, `authz_policy` has been integrated as an optional module (in `tracopt.perm.authz_policy.*`), so it's installed by default and can simply be activated via the //Plugins// panel in the Trac administration module.
    9 
     3[[TracGuideToc]]
     4
     5There is a general mechanism in place that allows custom **permission policy plugins** to grant or deny any action on any kind of Trac resource, even at the level of specific versions of such resources.
     6
     7That mechanism is `authz_policy`, which is an optional module in `tracopt.perm.authz_policy.*`, so it is installed by default. It can be activated via the //Plugins// panel in the Trac administration module.
    108
    119== Permission Policies ==
    1210
    13 A great diversity of permission policies can be implemented, and Trac comes with a few examples.
     11A great diversity of permission policies can be implemented and Trac comes with a few examples.
    1412
    1513Which policies are currently active is determined by a configuration setting in TracIni:
    16 e.g.
    17 {{{
    18 [trac]
    19 permission_policies = AuthzSourcePolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
    20 }}}
    21 This lists the [#AuthzSourcePolicy] described below as the first policy, followed by the !DefaultPermissionPolicy which checks for the traditional coarse grained style permissions described in TracPermissions, and the !LegacyAttachmentPolicy which knows how to use the coarse grained permissions for checking the permissions available on attachments.
    22 
    23 Among the possible optional choices, there is [#AuthzPolicy], a very generic permission policy, based on an Authz-style system. See
    24 [trac:source:branches/0.12-stable/tracopt/perm/authz_policy.py authz_policy.py] for details.
     14
     15{{{#!ini
     16[trac]
     17permission_policies = ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
     18}}}
     19This lists the [#ReadonlyWikiPolicy] which controls readonly access to wiki pages, followed by the !DefaultPermissionPolicy which checks for the traditional coarse grained style permissions described in TracPermissions, and the !LegacyAttachmentPolicy which knows how to use the coarse grained permissions for checking the permissions available on attachments.
     20
     21Among the optional choices, there is [#AuthzPolicy], a very generic permission policy, based on an Authz-style system. See
     22[trac:source:branches/1.0-stable/tracopt/perm/authz_policy.py authz_policy.py] for details.
    2523
    2624Another popular permission policy [#AuthzSourcePolicy], re-implements the pre-0.12 support for checking fine-grained permissions limited to Subversion repositories in terms of the new system.
    2725
    28 See also [trac:source:branches/0.12-stable/sample-plugins/permissions sample-plugins/permissions] for more examples.
    29 
     26See also [trac:source:branches/1.0-stable/sample-plugins/permissions sample-plugins/permissions] for more examples.
    3027
    3128=== !AuthzPolicy ===
    3229==== Configuration ====
    33 * Install [http://www.voidspace.org.uk/python/configobj.html ConfigObj] (still needed for 0.12).
    34 * Copy authz_policy.py into your plugins directory (only for Trac 0.11).
    3530* Put a [http://swapoff.org/files/authzpolicy.conf authzpolicy.conf] file somewhere, preferably on a secured location on the server, not readable for others than the webuser. If the  file contains non-ASCII characters, the UTF-8 encoding should be used.
    3631* Update your `trac.ini`:
    37   1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section
    38 {{{
     32  1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section:
     33{{{#!ini
    3934[trac]
    4035...
    41 permission_policies = AuthzPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
    42 }}}
    43   1. add a new `[authz_policy]` section
    44 {{{
     36permission_policies = AuthzPolicy, ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
     37}}}
     38  1. add a new `[authz_policy]` section:
     39{{{#!ini
    4540[authz_policy]
    4641authz_file = /some/trac/env/conf/authzpolicy.conf
    4742}}}
    48   1. enable the plugin through [/admin/general/plugin WebAdmin] or by editing the `[components]` section
    49 {{{
     43  1. enable the plugin through [/admin/general/plugin WebAdmin] or by editing the `[components]` section:
     44{{{#!ini
    5045[components]
    51 ...
    52 # Trac 0.12
    5346tracopt.perm.authz_policy.* = enabled
    54 # for Trac 0.11 use this
    55 #authz_policy.* = enabled
    56 }}}
    57 
     47}}}
    5848
    5949==== Usage Notes ====
    60 Note that the order in which permission policies are specified is quite critical,
    61 as policies will be examined in the sequence provided.
     50
     51Note the order in which permission policies are specified: policies are implemented in the sequence provided and therefore may override earlier policy specifications.
    6252
    6353A policy will return either `True`, `False` or `None` for a given permission check. `True` is returned if the policy explicitly grants the permission. `False` is returned if the policy explicitly denies the permission. `None` is returned if the policy is unable to either grant or deny the permission.
    6454
    65 NOTE: Only if the return value is `None` will the ''next'' permission policy be consulted.
    66 If none of the policies explicitly grants the permission, the final result will be `False`
    67 (i.e. permission denied).
     55NOTE: Only if the return value is `None` will the ''next'' permission policy be consulted. If none of the policies explicitly grants the permission, the final result will be `False`, i.e. permission denied.
    6856
    6957The `authzpolicy.conf` file is a `.ini` style configuration file:
    70 {{{
     58{{{#!ini
    7159[wiki:PrivatePage@*]
    7260john = WIKI_VIEW, !WIKI_MODIFY
     
    7462* =
    7563}}}
    76 * Each section of the config is a glob pattern used to match against a Trac resource
    77   descriptor. These descriptors are in the form:
     64* Each section of the config is a glob pattern used to match against a Trac resource descriptor. These descriptors are in the form:
    7865{{{
    7966<realm>:<id>@<version>[/<realm>:<id>@<version> ...]
    8067}}}
    81   Resources are ordered left to right, from parent to child. If any
    82   component is inapplicable, `*` is substituted. If the version pattern is
    83   not specified explicitely, all versions (`@*`) is added implicitly
    84 
    85   Example: Match the WikiStart page
    86 {{{
     68
     69Resources are ordered left to right, from parent to child. If any component is inapplicable, `*` is substituted. If the version pattern is not specified explicitly, all versions (`@*`) is added implicitly. Example: Match the WikiStart page:
     70{{{#!ini
    8771[wiki:*]
    8872[wiki:WikiStart*]
     
    9175}}}
    9276
    93   Example: Match the attachment `wiki:WikiStart@117/attachment/FOO.JPG@*`
    94   on WikiStart
    95 {{{
     77Example: Match the attachment `wiki:WikiStart@117/attachment:FOO.JPG@*` on WikiStart:
     78{{{#!ini
    9679[wiki:*]
    9780[wiki:WikiStart*]
    9881[wiki:WikiStart@*]
    99 [wiki:WikiStart@*/attachment/*]
    100 [wiki:WikiStart@117/attachment/FOO.JPG]
    101 }}}
    102 
    103 * Sections are checked against the current Trac resource descriptor '''IN ORDER''' of
    104   appearance in the configuration file. '''ORDER IS CRITICAL'''.
    105 
    106 * Once a section matches, the current username is matched against the keys
    107   (usernames) of the section, '''IN ORDER'''.
     82[wiki:WikiStart@*/attachment:*]
     83[wiki:WikiStart@117/attachment:FOO.JPG]
     84}}}
     85
     86* Sections are checked against the current Trac resource descriptor '''IN ORDER''' of appearance in the configuration file. '''ORDER IS CRITICAL'''.
     87
     88* Once a section matches, the current username is matched against the keys (usernames) of the section, '''IN ORDER'''.
    10889  * If a key (username) is prefixed with a `@`, it is treated as a group.
    109   * If a value (permission) is prefixed with a `!`, the permission is
    110     denied rather than granted.
    111 
    112   The username will match any of 'anonymous', 'authenticated', <username> or '*', using normal Trac permission rules. || '''Note:''' Other groups which are created by user (e.g. by 'adding subjects to groups' on web interface page //Admin / Permissions//) cannot be used. See [trac:ticket:5648 #5648] for details about this missing feature ||
     90  * If a value (permission) is prefixed with a `!`, the permission is denied rather than granted.
     91
     92The username will match any of 'anonymous', 'authenticated', <username> or '*', using normal Trac permission rules. || '''Note:''' Other groups which are created by user (e.g. by 'adding subjects to groups' on web interface page //Admin / Permissions//) cannot be used. See [trac:ticket:5648 #5648] for details about this missing feature. ||
    11393
    11494For example, if the `authz_file` contains:
    115 {{{
     95{{{#!ini
    11696[wiki:WikiStart@*]
    11797* = WIKI_VIEW
     
    129109
    130110Then:
    131   * All versions of WikiStart will be viewable by everybody (including anonymous)
     111  * All versions of WikiStart will be viewable by everybody, including anonymous
    132112  * !PrivatePage will be viewable only by john
    133113  * other pages will be viewable only by john and jack
    134114
    135115Groups:
    136 {{{
     116{{{#!ini
    137117[groups]
    138118admins = john, jack
     
    155135
    156136Some repository examples (Browse Source specific):
    157 {{{
     137{{{#!ini
    158138# A single repository:
    159139[repository:test_repo@*]
    160140john = BROWSER_VIEW, FILE_VIEW
    161141# John has BROWSER_VIEW and FILE_VIEW for the entire test_repo
     142
     143# The default repository (requires Trac 1.0.2 or later):
     144[repository:@*]
     145john = BROWSER_VIEW, FILE_VIEW
     146# John has BROWSER_VIEW and FILE_VIEW for the entire default repository
    162147
    163148# All repositories:
    164149[repository:*@*]
    165150jack = BROWSER_VIEW, FILE_VIEW
    166 # John has BROWSER_VIEW and FILE_VIEW for all repositories
    167 }}}
    168 
    169 Very fine grain repository access:
    170 {{{
     151# Jack has BROWSER_VIEW and FILE_VIEW for all repositories
     152}}}
     153
     154Very granular repository access:
     155{{{#!ini
    171156# John has BROWSER_VIEW and FILE_VIEW access to trunk/src/some/location/ only
    172157[repository:test_repo@*/source:trunk/src/some/location/*@*]
    173158john = BROWSER_VIEW, FILE_VIEW
    174159
    175 
    176160# John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of all files at trunk/src/some/location only
    177161[repository:test_repo@*/source:trunk/src/some/location/*@1]
    178162john = BROWSER_VIEW, FILE_VIEW
    179163
    180 
    181164# John has BROWSER_VIEW and FILE_VIEW access to all revisions of 'somefile' at trunk/src/some/location only
    182165[repository:test_repo@*/source:trunk/src/some/location/somefile@*]
    183166john = BROWSER_VIEW, FILE_VIEW
    184167
    185 
    186168# John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of 'somefile' at trunk/src/some/location only
    187169[repository:test_repo@*/source:trunk/src/some/location/somefile@1]
     
    191173Note: In order for Timeline to work/visible for John, we must add CHANGESET_VIEW to the above permission list.
    192174
    193 
    194175==== Missing Features ====
    195 Although possible with the !DefaultPermissionPolicy handling (see Admin panel), fine-grained permissions still miss those grouping features (see [trac:ticket:9573 #9573], [trac:ticket:5648 #5648]). Patches are partially available, see forgotten authz_policy.2.patch  part of [trac:ticket:6680 #6680]).
     176Although possible with the !DefaultPermissionPolicy handling (see Admin panel), fine-grained permissions still miss those grouping features (see [trac:ticket:9573 #9573], [trac:ticket:5648 #5648]). Patches are partially available, see authz_policy.2.patch, part of [trac:ticket:6680 #6680].
    196177
    197178You cannot do the following:
    198 {{{
     179{{{#!ini
    199180[groups]
    200181team1 = a, b, c
     
    204185}}}
    205186
    206 Permission groups are not supported either. You cannot do the following:
    207 {{{
     187Permission groups are not supported either, so you cannot do the following:
     188{{{#!ini
    208189[groups]
    209190permission_level_1 = WIKI_VIEW, TICKET_VIEW
     
    217198=== !AuthzSourcePolicy  (mod_authz_svn-like permission policy) === #AuthzSourcePolicy
    218199
    219 At the time of this writing, the old fine grained permissions system from Trac 0.11 and before used for restricting access to the repository has  been converted to a permission policy component, but from the user point of view, this makes little if no difference.
    220 
    221 That kind of fine-grained permission control needs a definition file, which is the one used by Subversion's mod_authz_svn.
    222 More information about this file format and about its usage in Subversion is available in the  [http://svnbook.red-bean.com/en/1.5/svn.serverconfig.pathbasedauthz.html Path-Based Authorization] section in the Server Configuration chapter of the svn book.
     200At the time of this writing, the old granular permissions system from Trac 0.11 and before used for restricting access to the repository has been converted to a permission policy component. But from the user's point of view, this makes little if any difference.
     201
     202That kind of granular permission control needs a definition file, which is the one used by Subversion's mod_authz_svn.
     203More information about this file format and about its usage in Subversion is available in the [http://svnbook.red-bean.com/en/1.5/svn.serverconfig.pathbasedauthz.html Path-Based Authorization] section in the Server Configuration chapter of the svn book.
    223204
    224205Example:
    225 {{{
     206{{{#!ini
    226207[/]
    227208* = r
     
    241222==== Trac Configuration ====
    242223
    243 To activate fine grained permissions you __must__ specify the {{{authz_file}}} option in the {{{[trac]}}} section of trac.ini. If this option is set to null or not specified the permissions will not be used.
    244 
    245 {{{
    246 [trac]
     224To activate granular permissions you __must__ specify the {{{authz_file}}} option in the `[svn]` section of trac.ini. If this option is set to null or not specified, the permissions will not be used.
     225
     226{{{#!ini
     227[svn]
    247228authz_file = /path/to/svnaccessfile
    248229}}}
    249230
    250 If you want to support the use of the `[`''modulename''`:/`''some''`/`''path''`]` syntax within the `authz_file`, add 
    251 
    252 {{{
     231If you want to support the use of the `[`''modulename''`:/`''some''`/`''path''`]` syntax within the `authz_file`, add:
     232
     233{{{#!ini
    253234authz_module_name = modulename
    254235}}}
    255236
    256 where ''modulename'' refers to the same repository indicated by the `repository_dir` entry in the `[trac]` section. As an example, if the `repository_dir` entry in the `[trac]` section is {{{/srv/active/svn/blahblah}}}, that would yield the following:
    257 
    258 {{{
    259 [trac]
     237where ''modulename'' refers to the same repository indicated by the `<name>.dir` entry in the `[repositories]` section. As an example, if the `somemodule.dir` entry in the `[repositories]` section is `/srv/active/svn/somemodule`, that would yield the following:
     238
     239{{{ #!ini
     240[svn]
    260241authz_file = /path/to/svnaccessfile
    261 authz_module_name = blahblah
     242authz_module_name = somemodule
    262243...
    263 repository_dir = /srv/active/svn/blahblah
    264 }}}
    265 
    266 where the svn access file, {{{/path/to/svnaccessfile}}}, contains entries such as {{{[blahblah:/some/path]}}}.
     244[repositories]
     245somemodule.dir = /srv/active/svn/somemodule
     246}}}
     247
     248where the svn access file, {{{/path/to/svnaccessfile}}}, contains entries such as {{{[somemodule:/some/path]}}}.
    267249
    268250'''Note:''' Usernames inside the Authz file __must__ be the same as those used inside trac.
     
    270252As of version 0.12, make sure you have ''!AuthzSourcePolicy'' included in the permission_policies list in trac.ini, otherwise the authz permissions file will be ignored.
    271253
    272 {{{ 
    273 [trac]
    274 permission_policies = AuthzSourcePolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
     254{{{#!ini
     255[trac]
     256permission_policies = AuthzSourcePolicy, ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
    275257}}}
    276258
     
    278260
    279261The same access file is typically applied to the corresponding Subversion repository using an Apache directive like this:
    280 {{{
     262{{{#!apache
    281263<Location /repos>
    282264  DAV svn
     
    288270}}}
    289271
    290 For information about how to restrict access to entire projects in a multiple project environment see [trac:wiki:TracMultipleProjectsSVNAccess]
     272For information about how to restrict access to entire projects in a multiple project environment see [trac:wiki:TracMultipleProjectsSVNAccess].
     273
     274=== ReadonlyWikiPolicy
     275
     276Since 1.1.2, the read-only attribute of wiki pages is enabled and enforced when `ReadonlyWikiPolicy` is in the list of active permission policies. The default for new Trac installations in 1.1.2 and later is:
     277{{{
     278[trac]
     279permission_policies = ReadonlyWikiPolicy,
     280 DefaultPermissionPolicy,
     281 LegacyAttachmentPolicy
     282}}}
     283
     284When upgrading from earlier versions of Trac, `ReadonlyWikiPolicy` will be appended to the list of `permission_policies` when upgrading the environment, provided that `permission_policies` has the default value. If any non-default `permission_polices` are active, `ReadonlyWikiPolicy` **will need to be manually added** to the list. A message will be echoed to the console when upgrading the environment, indicating if any action needs to be taken.
     285
     286**!ReadonlyWikiPolicy must be listed //before// !DefaultPermissionPolicy**. The latter returns `True` to allow modify, delete or rename actions when the user has the respective `WIKI_*` permission, without consideration for the read-only attribute.
     287
     288The `ReadonlyWikiPolicy` returns `False` to deny modify, delete and rename actions on wiki pages when the page has the read-only attribute set and the user does not have `WIKI_ADMIN`, regardless of `WIKI_MODIFY`, `WIKI_DELETE` and `WIKI_RENAME` permissions. It returns `None` for all other cases.
     289
     290When active, the [#AuthzPolicy] should therefore come before `ReadonlyWikiPolicy`, allowing it to grant or deny the actions on individual resources, which is the usual ordering for `AuthzPolicy` in the `permission_policies` list.
     291{{{
     292[trac]
     293permission_policies = AuthzPolicy,
     294 ReadonlyWikiPolicy,
     295 DefaultPermissionPolicy,
     296 LegacyAttachmentPolicy
     297}}}
     298
     299The placement of [#AuthzSourcePolicy] relative to `ReadonlyWikiPolicy` does not matter since they don't perform checks on the same realms.
     300
     301For all other permission policies, the user will need to decide the proper ordering. Generally, if the permission policy should be capable of overriding the check performed by `ReadonlyWikiPolicy`, it should come before `ReadonlyWikiPolicy` in the list. If the `ReadonlyWikiPolicy` should override the check performed by another permission policy, as is the case for `DefaultPermissionPolicy`, then `ReadonlyWikiPolicy` should come first.
    291302
    292303== Debugging permissions
    293304In trac.ini set:
    294 {{{
     305{{{#!ini
    295306[logging]
    296307log_file = trac.log
     
    299310}}}
    300311
    301 And watch:
    302 {{{
     312Display the trac.log to understand what checks are being performed:
     313{{{#!sh
    303314tail -n 0 -f log/trac.log | egrep '\[perm\]|\[authz_policy\]'
    304315}}}
    305316
    306 to understand what checks are being performed. See the sourced documentation of the plugin for more info.
    307 
     317See the sourced documentation of the plugin for more info.
    308318
    309319----
  • wiki/pages/TracGuide

    r26484 r37343  
    6161 * TracSupport — How to get more information
    6262
    63 If you are looking for a good place to ask a question about Trac, look no further than the [http://trac.edgewall.org/wiki/MailingList MailingList]. It provides a friendly environment to discuss openly among Trac users and developers.
     63If you are looking for a good place to ask a question about Trac, look no further than the [trac:MailingList MailingList]. It provides a friendly environment to discuss openly among Trac users and developers.
  • wiki/pages/TracImport

    r26484 r37343  
    22[[PageOutline]]
    33
    4 By means of migrating from other issue-tracking systems, perform some external actions over tickets or simply synchronize different data bases, there are some available tools, plug-ins or scripts which lets you import or up-date tickets into Trac.
    5 
    6 Below, follows a collection of some of those.
     4To migrate issue tickets from other issue-tracking systems or perform housekeeping actions on tickets or simply synchronize different databases, there are some tools, plug-ins and scripts available, which let you import or update tickets into Trac.
    75
    86== !TicketImportPlugin ==
    97
    10  [http://trac-hacks.org/wiki/TicketImportPlugin TicketImportPlugin] :: mainly, but not only, this plug-in lets you import or up-date into Trac a series of tickets from a '''CSV file''' or (if the [http://pypi.python.org/pypi/xlrd xlrd library] is installed) from an '''Excel file'''.
     8[http://trac-hacks.org/wiki/TicketImportPlugin TicketImportPlugin]: this plug-in lets you import or update into Trac a series of tickets from a '''CSV file''' or (if the [http://pypi.python.org/pypi/xlrd xlrd library] is installed) from an '''Excel spreadsheet'''.
    119
    1210== !ExportImportXlsPlugin ==
    1311
    14  [http://trac-hacks.org/wiki/ExportImportXlsPlugin ExportImportXlsPlugin] :: this plug-in add an admin panel for export and import tickets via '''XLS file'''.
    15   * It depends on the python packages xlwt/rxld.
     12[http://trac-hacks.org/wiki/ExportImportXlsPlugin ExportImportXlsPlugin]: this plug-in adds an admin panel for exporting and importing tickets via '''XLS file'''. Requires the python packages xlwt/rxld.
    1613
    1714== Bugzilla ==
    1815
    19  [http://trac-hacks.org/wiki/BugzillaIssueTrackingPlugin BugzillaIssueTrackingPlugin] :: integrates Bugzilla into Trac keeping TracLinks
    20 
    21 Ticket data can be imported from Bugzilla using the [http://trac.edgewall.org/browser/trunk/contrib/bugzilla2trac.py bugzilla2trac.py] script, available in the contrib/ directory of the Trac distribution.
     16[http://trac-hacks.org/wiki/BugzillaIssueTrackingPlugin BugzillaIssueTrackingPlugin]: integrates Bugzilla issue data into Trac keeping TracLinks. Ticket data can be imported from Bugzilla using the [trac:browser:trunk/contrib/bugzilla2trac.py bugzilla2trac.py] script, available in the contrib/ directory of the Trac distribution.
    2217
    2318{{{
     
    4035
    4136Currently, the following data is imported from Bugzilla:
    42 
    4337  * bugs
    4438  * bug activity (field changes)
     
    4741
    4842The script provides a number of features to ease the conversion, such as:
    49 
    50   * PRODUCT_KEYWORDS:  Trac doesn't have the concept of products, so the script provides the ability to attach a ticket keyword instead.
    51 
    52   * IGNORE_COMMENTS:  Don't import Bugzilla comments that match a certain regexp.
    53 
    54   * STATUS_KEYWORDS:  Attach ticket keywords for the Bugzilla statuses not available in Trac.  By default, the 'VERIFIED' and 'RELEASED' Bugzilla statuses are translated into Trac keywords.
     43  * PRODUCT_KEYWORDS: Trac has no concept of products, so the script provides the ability to attach a ticket keyword instead.
     44  * IGNORE_COMMENTS: Don't import Bugzilla comments that match a certain regexp.
     45  * STATUS_KEYWORDS: Attach ticket keywords for the Bugzilla statuses not available in Trac. By default, the 'VERIFIED' and 'RELEASED' Bugzilla statuses are translated into Trac keywords.
    5546
    5647For more details on the available options, see the configuration section at the top of the script.
    5748
     49=== Known Issues ===
     50{{{
     51#!comment
     52                   Don't merge this section in the default page
     53}}}
     54[[TicketQuery(keywords=~bugzilla,status=!closed)]]
     55
     56The adequate milestone for valid bugzilla2trac issue is usually ''Not applicable'', which means that fixes to the contributed script are not planned for a particular Trac release, but can happen anytime.
     57
    5858== Jira ==
    5959
    60  [http://trac-hacks.org/wiki/JiraToTracIntegration JiraToTracIntegration] :: provides tools to import Atlassian Jira backup files into Trac. The plug-in consists of a Python 3.1 commandline tool that:
    61    - Parses the Jira backup XML file
    62    - Sends the imported Jira data and attachments to Trac using the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin]
    63    - Generates a htpasswd file containing the imported Jira users and their SHA-512 base64 encoded passwords
     60[http://trac-hacks.org/wiki/JiraToTracIntegration JiraToTracIntegration]: provides tools to import Atlassian Jira backup files into Trac. The plug-in consists of a Python 3.1 commandline tool that:
     61  - Parses the Jira backup XML file.
     62  - Sends the imported Jira data and attachments to Trac using the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin].
     63  - Generates a htpasswd file containing the imported Jira users and their SHA-512 base64 encoded passwords.
    6464
    6565== Mantis ==
    6666
    67  [http://trac-hacks.org/wiki/MantisImportScript MantisImportScript] :: script to import from Mantis into Trac the following data:
     67[http://trac-hacks.org/wiki/MantisImportScript MantisImportScript]: script to import the following data from Mantis into Trac:
    6868  * bugs
    6969  * bug comments
     
    7373== !PlanetForge ==
    7474
    75  [http://trac-hacks.org/wiki/PlanetForgeImportExportPlugin PlanetForgeImportExportPlugin] :: this plugin exports Trac data (wiki, tickets, compoments, permissions, repositories, etc.) using the open format designed by the COCLICO project. It extends the webadmin panel and the 'trac admin ...' command. Still has no 'import' feature.
     75[http://trac-hacks.org/wiki/PlanetForgeImportExportPlugin PlanetForgeImportExportPlugin]: this plugin exports Trac data (wiki, tickets, compoments, permissions, repositories, etc.) using the open format designed by the COCLICO project. It extends the webadmin panel and the 'trac admin ...' command. Has no 'import' feature.
    7676
    7777== Scarab ==
    7878
    79  [http://trac-hacks.org/wiki/ScarabToTracScript ScarabToTracScript] :: script that migrates Scarab issues to Trac tickets
    80     * Requires [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin]
     79[http://trac-hacks.org/wiki/ScarabToTracScript ScarabToTracScript]: script that migrates Scarab issues to Trac tickets. Requires [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin]
    8180
    8281== Sourceforge ==
    8382
    84  [http://trac-hacks.org/wiki/SfnToTracScript SfnToTracScript] :: importer of !SourceForge's new backup file (originated from #Trac3521)
    85 
    86 Also, ticket data can be imported from Sourceforge using the [http://trac.edgewall.org/browser/trunk/contrib/sourceforge2trac.py sourceforge2trac.py] script, available in the contrib/ directory of the Trac distribution.
     83[http://trac-hacks.org/wiki/SfnToTracScript SfnToTracScript]: importer of !SourceForge's new backup file (originated from #Trac3521).
     84Also, ticket data can be imported from Sourceforge using the [trac:browser:trunk/contrib/sourceforge2trac.py sourceforge2trac.py] script, available in the contrib/ directory of the Trac distribution.
    8785
    8886== Other ==
    8987
    90 Since trac uses a SQL database to store the data, you can import from other systems by examining the database tables. Just go into [http://www.sqlite.org/sqlite.html sqlite] command line to look at the tables and import into them from your application.
     88Since Trac uses a SQL database to store the data, you can also custom-import from other systems by examining the database tables. Just go into [http://www.sqlite.org/sqlite.html sqlite] command line to look at the tables and import them from your application.
    9189
    9290=== Comma delimited file - CSV ===
    93 See [http://trac.edgewall.org/attachment/wiki/TracSynchronize/csv2trac.2.py csv2trac.2.py] for details.  This approach is particularly useful if one needs to enter a large number of tickets by hand. (note that the ticket type type field, (task etc...) is also needed for this script to work with more recent Trac releases)
    94 Comments on script: The script has an error on line 168, ('Ticket' needs to be 'ticket'). Also, the listed values for severity and priority are swapped.
     91See [trac:attachment:csv2trac.2.py:wiki:TracSynchronize csv2trac.2.py] for details. This approach is particularly useful if you need to enter a large number of tickets by hand. Note that the ticket type type field, (task etc...) is also needed for this script to work with more recent Trac releases.
     92Comments on script: The script has an error on line 168: 'Ticket' needs to be 'ticket'. Also, the listed values for severity and priority are swapped.
    9593
    9694----
  • wiki/pages/TracIni

    r26484 r37343  
    1 = The Trac Configuration File =
    2 
    3  ''[Note To Editors] Please discuss documentation changes in the [#Discussion] section. Even better, send us [TracDev/SubmittingPatches documentation patches] against the ''code'' (i.e. where the configuration entries are documented), either on Trac-dev or on new tickets. ''
     1= The Trac Configuration File
    42
    53[[TracGuideToc]]
    64[[PageOutline]]
    75
    8 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.
     6Trac is configured by editing the **`trac.ini`** file, located in the `<projectenv>/conf` directory. The `trac.ini` configuration file and its parent directory should be writable by the web server.
    97
    10 The `trac.ini` configuration file and its parent directory should be writable by the web server, as Trac currently relies on the possibility to trigger a complete environment reload to flush its caches.
     8Trac monitors the timestamp of the file to trigger a complete environment reload and flush its caches when the timestamp changes. Most changes to the configuration will be 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 [#GlobalConfiguration global configuration] file when none was previously present.
    119
    12 == Global Configuration ==
     10== Global Configuration
    1311
    14 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.
    15 
    16 Global options will be merged with the environment-specific options, where local options override global options. The options file is specified as follows:
    17 {{{
     12Configuration can be shared among environments using one or more global configuration files. Options in the global configuration will be merged with the environment-specific options, with local options overriding global options. The global configuration file is specified as follows:
     13{{{#!ini
    1814[inherit]
    1915file = /path/to/global/trac.ini
     
    2521There are two more entries in the [[#inherit-section| [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.
    2622
    27 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).
     23Note 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, refresh your modifications when you upgrade to a new version of Trac. The preferred way to perform TracInterfaceCustomization is still to write a custom plugin doing an appropriate `ITemplateStreamFilter` transformation.
    2824
    2925== Reference for settings
     
    3127This is a brief reference of available configuration options, and their default settings.
    3228
     29Documentation improvements should be discussed on the [trac:MailingList#Trac-dev trac-dev mailing list] or described in a [trac:NewTicket ticket]. Even better, [trac:TracDev/SubmittingPatches submit a patch] against the docstrings in the code.
     30{{{ #!comment
     31Please don't waste your time by editing the HTML code below, changes won't be picked up. Instead, follow the above guidance for suggesting documentation improvements.
     32}}}
    3333[[TracIni]]
    3434
  • wiki/pages/TracInstall

    r26484 r37343  
    1 = Trac Installation Guide for 1.0 =
     1= Trac Installation Guide for 1.1
    22[[TracGuideToc]]
    33
    44Trac is written in the Python programming language and needs a database, [http://sqlite.org/ SQLite], [http://www.postgresql.org/ PostgreSQL], or [http://mysql.com/ MySQL]. For HTML rendering, Trac uses the [http://genshi.edgewall.org Genshi] templating system.
    55
    6 Since version 0.12, Trac can also be localized, and there's probably a translation available for your language. If you want to be able to use the Trac interface in other languages, then make sure you have installed the optional package [#OtherPythonPackages Babel]. Pay attention to the extra steps for localization support in the [#InstallingTrac Installing Trac] section below. Lacking Babel, you will only get the default english version, as usual.
    7 
    8 If you're interested in contributing new translations for other languages or enhance the existing translations, then please have a look at [[trac:TracL10N]].
    9 
    10 What follows are generic instructions for installing and setting up Trac and its requirements. While you may find instructions for installing Trac on specific systems at [trac:TracInstallPlatforms TracInstallPlatforms] on the main Trac site, please be sure to '''first read through these general instructions''' to get a good understanding of the tasks involved.
     6Trac can also be localized, and there is probably a translation available in your language. If you want to use the Trac interface in other languages, then make sure you have installed the optional package [#OtherPythonPackages Babel]. Pay attention to the extra steps for localization support in the [#InstallingTrac Installing Trac] section below. Lacking Babel, you will only get the default English version.
     7
     8If you're interested in contributing new translations for other languages or enhancing the existing translations, then please have a look at [trac:wiki:TracL10N TracL10N].
     9
     10What follows are generic instructions for installing and setting up Trac. While you may find instructions for installing Trac on specific systems at [trac:TracInstallPlatforms TracInstallPlatforms], please '''first read through these general instructions''' to get a good understanding of the tasks involved.
    1111
    1212[[PageOutline(2-3,Installation Steps,inline)]]
    1313
    14 == Dependencies ==
     14== Dependencies
    1515=== Mandatory Dependencies
    1616To install Trac, the following software packages must be installed:
    1717
    18  * [http://www.python.org/ Python], version >= 2.5 and < 3.0
    19    (note that we dropped the support for Python 2.4 in this release)
    20  * [http://peak.telecommunity.com/DevCenter/setuptools setuptools], version >= 0.6, or better yet, [http://pypi.python.org/pypi/distribute distribute]
    21  * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6 (unreleased version 0.7dev should work as well)
    22 
    23 You also need a database system and the corresponding python bindings.
    24 The database can be either SQLite, PostgreSQL or MySQL.
     18 * [http://www.python.org/ Python], version >= 2.6 and < 3.0
     19   (note that we dropped the support for Python 2.5 in this release)
     20 * [http://pypi.python.org/pypi/setuptools setuptools], version >= 0.6
     21 * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6
     22
     23You also need a database system and the corresponding python bindings. The database can be either SQLite, PostgreSQL or MySQL.
    2524
    2625==== For the SQLite database #ForSQLite
    2726
    28 As you must be using Python 2.5, 2.6 or 2.7, you already have the SQLite database bindings bundled with the standard distribution of Python (the `sqlite3` module).
    29 
    30 However, if you'd like, you can download the latest and greatest version of [[trac:Pysqlite]] from
    31 [http://code.google.com/p/pysqlite/downloads/list google code], where you'll find the Windows
    32 installers or the `tar.gz` archive for building from source:
    33 {{{
    34 $ tar xvfz <version>.tar.gz
    35 $ cd <version>
    36 $ python setup.py build_static install
    37 }}}
    38  
    39 This will download the latest SQLite code and build the bindings.
    40 
    41 SQLite 2.x is no longer supported.
    42 
    43 A known bug PySqlite versions 2.5.2-4 prohibits upgrade of trac databases
    44 from 0.11.x to 0.12. Please use versions 2.5.5 and newer or 2.5.1 and
    45 older. See #9434 for more detail.
    46 
    47 See additional information in [trac:PySqlite PySqlite].
     27As you must be using Python 2.6 or 2.7, you already have the SQLite database bindings bundled with the standard distribution of Python (the `sqlite3` module).
     28
     29Optionally, you may install a newer version of [pypi:pysqlite pysqlite] than the one provided by the Python distribution. See [trac:PySqlite#ThePysqlite2bindings PySqlite] for details.
    4830
    4931==== For the PostgreSQL database #ForPostgreSQL
     
    5133You need to install the database and its Python bindings:
    5234 * [http://www.postgresql.org/ PostgreSQL], version 8.0 or later
    53  * [http://pypi.python.org/pypi/psycopg2 psycopg2]
     35 * [http://pypi.python.org/pypi/psycopg2 psycopg2], version 2.0 or later
    5436
    5537See [trac:DatabaseBackend#Postgresql DatabaseBackend] for details.
    5638
    57 
    5839==== For the MySQL database #ForMySQL
    5940
    60 Trac can now work quite well with MySQL, provided you follow the guidelines.
     41Trac works well with MySQL, provided you follow the guidelines:
    6142
    6243 * [http://mysql.com/ MySQL], version 5.0 or later
    6344 * [http://sf.net/projects/mysql-python MySQLdb], version 1.2.2 or later
    6445
    65 It is '''very''' important to read carefully the [trac:MySqlDb] page before creating the database.
     46Given the caveats and known issues surrounding MySQL, read carefully the [trac:MySqlDb] page before creating the database.
    6647
    6748=== Optional Dependencies
    6849
    69 ==== Version Control System ====
    70 
    71 ===== Subversion =====
    72  * [http://subversion.apache.org/ Subversion], 1.5.x or 1.6.x and the '''''corresponding''''' Python bindings. Older versions starting from 1.0, like 1.2.4, 1.3.2 or 1.4.2, etc. should still work. For troubleshooting information, check the [trac:TracSubversion#Troubleshooting TracSubversion] page.
    73 
    74 There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. (Good luck finding precompiled SWIG bindings for any Windows package at that listing. TracSubversion points you to [http://alagazam.net Algazam], which works for me under Python 2.6.)
    75 
    76 Note that Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], neither does it work yet with the newer `ctype`-style bindings.
    77 
    78 
    79 '''Please note:''' if using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported].
    80 
    81 
    82 ===== Others =====
    83 
    84 Support for other version control systems is provided via third-parties. See [trac:PluginList] and [trac:VersionControlSystem].
    85 
    86 ==== Web Server ====
    87 A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server ] section below.
    88 
    89 Alternatively you configure Trac to run in any of the following environments.
     50==== Subversion
     51
     52[http://subversion.apache.org/ Subversion], 1.6.x or later and the '''''corresponding''''' Python bindings.
     53
     54There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. (Good luck finding precompiled SWIG bindings for any Windows package at that listing. [trac:TracSubversion] points you to [http://alagazam.net Alagazam], which works for me under Python 2.6.)
     55
     56For troubleshooting information, see the [trac:TracSubversion#Troubleshooting TracSubversion] page.
     57
     58{{{#!div style="border: 1pt dotted; margin: 1em"
     59**Note:**
     60* Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], nor does it work yet with the newer `ctype`-style bindings.
     61* If using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported].
     62}}}
     63
     64==== Git
     65
     66[http://git-scm.com/ Git] 1.5.6 or later is supported. More information is available on the [trac:TracGit] page.
     67
     68==== Other Version Control Systems
     69
     70Support for other version control systems is provided via third-party plugins. See [trac:PluginList#VersionControlSystems] and [trac:VersionControlSystem].
     71
     72==== Web Server
     73A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server] section below.
     74
     75Alternatively you can configure Trac to run in any of the following environments:
    9076 * [http://httpd.apache.org/ Apache] with
    91    - [http://code.google.com/p/modwsgi/ mod_wsgi], see [wiki:TracModWSGI] and
    92      http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac
    93    - [http://modpython.org/ mod_python 3.3.1], deprecated: see TracModPython)
     77   - [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi], see [wiki:TracModWSGI] and
     78     [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac ModWSGI IntegrationWithTrac].
     79   - [http://modpython.org/ mod_python 3.5.0], see TracModPython
    9480 * a [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi)
    9581 * an [http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web
    9682   server (see [trac:TracOnWindowsIisAjp TracOnWindowsIisAjp])
     83 * Microsoft IIS with FastCGI and a FastCGI-to-WSGI gateway (see [trac:CookBook/Installation/TracOnWindowsIisWfastcgi IIS with FastCGI])
    9784 * a CGI-capable web server (see TracCgi), '''but usage of Trac as a cgi script
    9885   is highly discouraged''', better use one of the previous options.
    9986   
    10087
    101 ==== Other Python Packages ====
    102 
    103  * [http://babel.edgewall.org Babel], version >= 0.9.5,
    104    needed for localization support (unreleased version 1.0dev should work as well)
     88==== Other Python Packages
     89
     90 * [http://babel.edgewall.org Babel], version 0.9.6 or >= 1.3,
     91   needed for localization support
    10592 * [http://docutils.sourceforge.net/ docutils], version >= 0.3.9
    10693   for WikiRestructuredText.
    107  * [http://pygments.pocoo.org Pygments] for
    108    [wiki:TracSyntaxColoring syntax highlighting].
    109    [http://silvercity.sourceforge.net/ SilverCity] and/or
    110    [http://gnu.org/software/enscript/enscript.html Enscript] may still be used
    111    but are deprecated and you really should be using Pygments.
     94 * [http://pygments.org Pygments] for
     95   [TracSyntaxColoring syntax highlighting].
    11296 * [http://pytz.sf.net pytz] to get a complete list of time zones,
    11397   otherwise Trac will fall back on a shorter list from
    11498   an internal time zone implementation.
    11599
    116 '''Attention''': The various available versions of these dependencies are not necessarily interchangable, so please pay attention to the version numbers above. If you are having trouble getting Trac to work please double-check all the dependencies before asking for help on the [trac:MailingList] or [trac:IrcChannel].
    117 
    118 Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there ''probably concern older versions of Trac than the one you're installing'' (there are even some pages that are still talking about Trac 0.8!).
    119 
    120 
    121 == Installing Trac ==
     100{{{#!div style="border: 1pt dotted; margin: 1em"
     101**Attention**: The available versions of these dependencies are not necessarily interchangeable, so please pay attention to the version numbers. If you are having trouble getting Trac to work, please double-check all the dependencies before asking for help on the [trac:MailingList] or [trac:IrcChannel].
     102}}}
     103
     104Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there ''probably concern older versions of Trac than the one you're installing''.
     105
     106== Installing Trac
     107
     108The [TracAdmin trac-admin] command-line tool, used to create and maintain [TracEnvironment project environments], as well as the [TracStandalone tracd] standalone server are installed along with Trac. There are several methods for installing Trac.
     109
    122110=== Using `easy_install`
    123 One way to install Trac is using [http://pypi.python.org/pypi/setuptools setuptools].
    124 With setuptools you can install Trac from the subversion repository;
     111Trac can be installed from PyPI or the Subversion repository using [http://pypi.python.org/pypi/setuptools setuptools].
    125112
    126113A few examples:
    127114
    128  - install Trac 1.0:
    129    {{{
     115 - Install Trac 1.0:
     116   {{{#!sh
    130117   easy_install Trac==1.0
    131118   }}}
    132    (NOT YET ENABLED)
    133  - install latest development version 1.0dev:
    134    {{{
     119 - Install latest development version:
     120   {{{#!sh
    135121   easy_install Trac==dev
    136122   }}}
     
    138124   either use a released version or install from source
    139125
     126More information can be found on the [trac:setuptools] page.
     127
     128{{{#!div style="border: 1pt dotted; margin: 1em"
     129**Setuptools Warning:** If the version of your setuptools is in the range 5.4 through 5.6, the environment variable `PKG_RESOURCES_CACHE_ZIP_MANIFESTS` must be set in order to avoid significant performance degradation. More information may be found in the sections on [#RunningtheStandaloneServer Running The Standalone Server] and [#RunningTraconaWebServer Running Trac on a Web Server].
     130}}}
     131
    140132=== Using `pip`
    141133'pip' is an easy_install replacement that is very useful to quickly install python packages.
    142 To get a trac installation up and running in less than 5 minutes:
     134To get a Trac installation up and running in less than 5 minutes:
    143135
    144136Assuming you want to have your entire pip installation in `/opt/user/trac`
    145137
    146138 -
    147 {{{
    148 pip -E /opt/user/trac install trac psycopg2
     139 {{{#!sh
     140pip install trac psycopg2
    149141}}}
    150142or
    151143 -
    152 {{{
    153 pip -E /opt/user/trac install trac mysql-python
    154 }}}
    155 
    156 Make sure your OS specific headers are available for pip to automatically build PostgreSQL (libpq-dev) or MySQL (libmysqlclient-dev) bindings.
    157 
    158 pip will automatically resolve all dependencies (like Genshi, pygments, etc.) and download the latest packages on pypi.python.org and create a self contained installation in `/opt/user/trac`.
     144 {{{#!sh
     145pip install trac mysql-python
     146}}}
     147
     148Make sure your OS specific headers are available for pip to automatically build PostgreSQL (`libpq-dev`) or MySQL (`libmysqlclient-dev`) bindings.
     149
     150pip will automatically resolve all dependencies (like Genshi, pygments, etc.), download the latest packages from pypi.python.org and create a self contained installation in `/opt/user/trac`.
    159151
    160152All commands (`tracd`, `trac-admin`) are available in `/opt/user/trac/bin`. This can also be leveraged for `mod_python` (using `PythonHandler` directive) and `mod_wsgi` (using `WSGIDaemonProcess` directive)
    161153
    162 Additionally, you can install several trac plugins (listed [http://pypi.python.org/pypi?:action=search&term=trac&submit=search here]) through pip.
    163 
    164 
     154Additionally, you can install several Trac plugins (listed [https://pypi.python.org/pypi?:action=browse&show=all&c=516 here]) through pip.
    165155
    166156=== From source
    167 Of course, using the python-typical setup at the top of the source directory also works.
    168 
    169 You can obtain the source for a .tar.gz or .zip file corresponding to a release (e.g. Trac-1.0.tar.gz), or you can get the source directly from the repository (see Trac:SubversionRepository for details).
    170 
    171 {{{
     157Using the python-typical setup at the top of the source directory also works. You can obtain the source for a .tar.gz or .zip file corresponding to a release (e.g. `Trac-1.0.tar.gz`) from the [trac:TracDownload] page, or you can get the source directly from the repository. See [trac:TracRepositories#OfficialSubversionrepository TracRepositories] for details.
     158
     159{{{#!sh
    172160$ python ./setup.py install
    173161}}}
    174162
    175 ''You'll need root permissions or equivalent for this step.''
    176 
    177 This will byte-compile the python source code and install it as an .egg file or folder in the `site-packages` directory
    178 of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as htdocs and templates.
    179 
    180 The script will also install the [wiki:TracAdmin trac-admin] command-line tool, used to create and maintain [wiki:TracEnvironment project environments], as well as the [wiki:TracStandalone tracd] standalone server.
    181 
    182 If you install from source and want to make Trac available in other languages, make sure  Babel is installed. Only then, perform the `install` (or simply redo the `install` once again afterwards if you realize Babel was not yet installed):
    183 {{{
     163''You will need root permissions or equivalent for this step.''
     164
     165This will byte-compile the Python source code and install it as an .egg file or folder in the `site-packages` directory
     166of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as `htdocs` and `templates`.
     167
     168If you install from source and want to make Trac available in other languages, make sure Babel is installed. Only then, perform the `install` (or simply redo the `install` once again afterwards if you realize Babel was not yet installed):
     169{{{#!sh
    184170$ python ./setup.py install
    185171}}}
    186 Alternatively, you can do a `bdist_egg` and copy the .egg from dist/ to the place of your choice, or you can create a Windows installer (`bdist_wininst`).
    187 
    188 === Advanced Options ===
     172Alternatively, you can run `bdist_egg` and copy the .egg from `dist/` to the place of your choice, or you can create a Windows installer (`bdist_wininst`).
     173
     174=== Using installer
     175
     176On Windows, Trac can be installed using the exe installers available on the [trac:TracDownload] page. Installers are available for the 32-bit and 64-bit versions of Python. Make sure to use the installer that matches the architecture of your Python installation.
     177
     178=== Using package manager
     179
     180Trac may be available in your platform's package repository. Note however, that the version provided by your package manager may not be the latest release.
     181
     182=== Advanced `easy_install` Options
    189183
    190184To install Trac to a custom location, or find out about other advanced installation options, run:
    191 {{{
     185{{{#!sh
    192186easy_install --help
    193187}}}
    194188
    195 Also see [http://docs.python.org/inst/inst.html Installing Python Modules] for detailed information.
     189Also see [http://docs.python.org/2/install/index.html Installing Python Modules] for detailed information.
    196190
    197191Specifically, you might be interested in:
    198 {{{
     192{{{#!sh
    199193easy_install --prefix=/path/to/installdir
    200194}}}
    201 or, if installing Trac to a Mac OS X system:
    202 {{{
    203 easy_install --prefix=/usr/local --install-dir=/Library/Python/2.5/site-packages
    204 }}}
    205 Note: If installing on Mac OS X 10.6 running {{{ easy_install http://svn.edgewall.org/repos/trac/trunk }}} will install into {{{ /usr/local }}} and {{{ /Library/Python/2.6/site-packages }}} by default
    206 
    207 The above will place your `tracd` and `trac-admin` commands into `/usr/local/bin` and will install the Trac libraries and dependencies into `/Library/Python/2.5/site-packages`, which is Apple's preferred location for third-party Python application installations.
    208 
    209 
    210 == Creating a Project Environment ==
    211 
    212 A [TracEnvironment Trac environment] is the backend storage where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is basically a directory that contains a human-readable [TracIni configuration file], and various other files and directories.
    213 
    214 A new environment is created using [wiki:TracAdmin trac-admin]:
    215 {{{
     195or, if installing Trac on a Mac OS X system:
     196{{{#!sh
     197easy_install --prefix=/usr/local --install-dir=/Library/Python/2.6/site-packages
     198}}}
     199
     200{{{#!div style="border: 1pt dotted; margin: 1em"
     201**Mac OS X Note:** On Mac OS X 10.6,  running `easy_install trac` will install into `/usr/local` and `/Library/Python/2.6/site-packages` by default.
     202
     203The `tracd` and `trac-admin` commands will be placed in `/usr/local/bin` and will install the Trac libraries and dependencies into `/Library/Python/2.6/site-packages`, which is Apple's preferred location for third-party Python application installations.
     204}}}
     205
     206== Creating a Project Environment
     207
     208A [TracEnvironment Trac environment] is the backend where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is a directory that contains a human-readable [TracIni configuration file], and other files and directories.
     209
     210A new environment is created using [TracAdmin trac-admin]:
     211{{{#!sh
    216212$ trac-admin /path/to/myproject initenv
    217213}}}
    218214
    219 [TracAdmin trac-admin] will prompt you for the information it needs to create the environment, such as the name of the project and the [TracEnvironment#DatabaseConnectionStrings database connection string]. If you're not sure what to specify for one of these options, just press `<Enter>` to use the default value.
    220 
    221 Using the default database connection string in particular will always work as long as you have SQLite installed.
    222 For the other [DatabaseBackend database backends] you should plan ahead and already have a database ready to use at this point.
    223 
    224 Since 0.12, Trac doesn't ask for a [TracEnvironment#SourceCodeRepository source code repository] anymore when creating an environment. Repositories can be [TracRepositoryAdmin added] afterward, or the version control support can be disabled completely if you don't need it.
    225 
    226 Also note that the values you specify here can be changed later by directly editing the [TracIni conf/trac.ini] configuration file.
     215[TracAdmin trac-admin] will prompt you for the information it needs to create the environment: the name of the project and the [TracEnvironment#DatabaseConnectionStrings database connection string]. If you're not sure what to specify for any of these options, just press `<Enter>` to use the default value.
     216
     217Using the default database connection string will always work as long as you have SQLite installed. For the other [trac:DatabaseBackend database backends] you should plan ahead and already have a database ready to use at this point.
     218
     219Also note that the values you specify here can be changed later using TracAdmin or directly editing the [TracIni conf/trac.ini] configuration file.
     220
     221{{{#!div style="border: 1pt dotted; margin: 1em"
     222**Filesystem Warning:** When selecting the location of your environment, make sure that the filesystem on which the environment directory resides supports sub-second timestamps (i.e. **not** `ext2` or `ext3` on Linux, or HFS+ on OSX), as the modification time of the `conf/trac.ini` file will be monitored to decide whether an environment restart is needed or not. A too coarse-grained timestamp resolution may result in inconsistencies in Trac < 1.0.2. The best advice is to opt for a platform with sub-second timestamp resolution, regardless of the Trac version.
     223}}}
    227224
    228225Finally, make sure the user account under which the web front-end runs will have '''write permissions''' to the environment directory and all the files inside. This will be the case if you run `trac-admin ... initenv` as this user. If not, you should set the correct user afterwards. For example on Linux, with the web server running as user `apache` and group `apache`, enter:
    229 {{{
    230 # chown -R apache.apache /path/to/myproject
    231 }}}
     226{{{#!sh
     227$ chown -R apache:apache /path/to/myproject
     228}}}
     229
     230The actual username and groupname of the apache server may not be exactly `apache`, and are specified in the Apache configuration file by the directives `User` and `Group` (if Apache `httpd` is what you use).
    232231
    233232{{{#!div class=important
     
    235234}}}
    236235
    237 
    238236== Deploying Trac
    239237
    240 === Running the Standalone Server ===
    241 
    242 After having created a Trac environment, you can easily try the web interface by running the standalone server [wiki:TracStandalone tracd]:
    243 {{{
     238=== Running the Standalone Server
     239
     240After having created a Trac environment, you can easily try the web interface by running the standalone server [TracStandalone tracd]:
     241{{{#!sh
    244242$ tracd --port 8000 /path/to/myproject
    245243}}}
    246244
    247245Then, fire up a browser and visit `http://localhost:8000/`. You should get a simple listing of all environments that `tracd` knows about. Follow the link to the environment you just created, and you should see Trac in action. If you only plan on managing a single project with Trac you can have the standalone server skip the environment list by starting it like this:
    248 {{{
     246{{{#!sh
    249247$ tracd -s --port 8000 /path/to/myproject
    250248}}}
    251249
    252 === Running Trac on a Web Server ===
     250{{{#!div style="border: 1pt dotted; margin: 1em"
     251**Setuptools Warning:** If the version of your setuptools is in the range 5.4 through 5.6, the environment variable `PKG_RESOURCES_CACHE_ZIP_MANIFESTS` must be set in order to avoid significant performance degradation. The environment variable can be set system-wide, or for just the user that runs the `tracd` process. There are several ways to accomplish this in addition to what is discussed here, and depending on the distribution of your OS.
     252
     253To be effective system-wide a shell script with the `export` statement may be added to `/etc/profile.d`. To be effective for a user session the `export` statement may be added to `~/.profile`.
     254{{{#!sh
     255export PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1
     256}}}
     257
     258Alternatively, the variable can be set in the shell before executing `tracd`:
     259{{{#!sh
     260$ PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 tracd --port 8000 /path/to/myproject
     261}}}
     262}}}
     263
     264=== Running Trac on a Web Server
    253265
    254266Trac provides various options for connecting to a "real" web server:
    255  - [wiki:TracFastCgi FastCGI]
     267 - [TracFastCgi FastCGI]
    256268 - [wiki:TracModWSGI mod_wsgi]
    257  - //[wiki:TracModPython mod_python] (no longer recommended, as mod_python is not actively maintained anymore)//
    258  - //[wiki:TracCgi CGI] (should not be used, as the performance is far from optimal)//
     269 - [TracModPython mod_python]
     270 - //[TracCgi CGI] (should not be used, as the performance is far from optimal)//
    259271
    260272Trac also supports [trac:TracOnWindowsIisAjp AJP] which may be your choice if you want to connect to IIS. Other deployment scenarios are possible: [trac:TracNginxRecipe nginx], [http://projects.unbit.it/uwsgi/wiki/Example#Traconapacheinasub-uri uwsgi], [trac:TracOnWindowsIisIsapi Isapi-wsgi] etc.
    261273
    262 ==== Generating the Trac cgi-bin directory ==== #cgi-bin
    263 
    264 In order for Trac to function properly with FastCGI you need to have a `trac.fcgi` file and for mod_wsgi a `trac.wsgi` file. These are Python scripts which load the appropriate Python code. They can be generated using the `deploy` option of [wiki:TracAdmin trac-admin].
    265 
    266 There is, however, a bit of a chicken-and-egg problem. The [wiki:TracAdmin trac-admin] command requires an existing environment to function, but complains if the deploy directory already exists. This is a problem, because environments are often stored in a subdirectory of the deploy. The solution is to do something like this:
    267 {{{
     274==== Generating the Trac cgi-bin directory #cgi-bin
     275
     276In order for Trac to function properly with FastCGI you need to have a `trac.fcgi` file and for mod_wsgi a `trac.wsgi` file. These are Python scripts which load the appropriate Python code. They can be generated using the `deploy` option of [TracAdmin trac-admin].
     277
     278There is, however, a bit of a chicken-and-egg problem. The [TracAdmin trac-admin] command requires an existing environment to function, but complains if the deploy directory already exists. This is a problem, because environments are often stored in a subdirectory of the deploy. The solution is to do something like this:
     279{{{#!sh
    268280mkdir -p /usr/share/trac/projects/my-project
    269281trac-admin /usr/share/trac/projects/my-project initenv
     
    271283mv /tmp/deploy/* /usr/share/trac
    272284}}}
    273 
    274 
    275 ==== Mapping Static Resources ====
     285Don't forget to check that the web server has the execution right on scripts in the `/usr/share/trac/cgi-bin` directory.
     286
     287==== Mapping Static Resources
    276288
    277289Out of the box, Trac will pass static resources such as style sheets or images through itself. For anything but a tracd only based deployment, this is far from optimal as the web server could be set up to directly serve those static resources (for CGI setup, this is '''highly undesirable''' and will cause abysmal performance).
     
    281293There are two primary URL paths for static resources - `/chrome/common` and `/chrome/site`. Plugins can add their own resources, usually accessible by `/chrome/<plugin>` path, so its important to override only known paths and not try to make universal `/chrome` alias for everything.
    282294
    283 Note that in order to get those static resources on the filesystem, you need first to extract the relevant resources from Trac using the [TracAdmin trac-admin]` <environment> deploy` command:
     295Note that in order to get those static resources on the filesystem, you need first to extract the relevant resources from Trac using the TracAdmin `deploy` command:
    284296[[TracAdminHelp(deploy)]]
    285297
     
    289301 - `<plugins>/` - one directory for each resource directory managed by the plugins enabled for this environment
    290302
    291 ===== Example: Apache and `ScriptAlias` ===== #ScriptAlias-example
     303===== Example: Apache and `ScriptAlias` #ScriptAlias-example
    292304
    293305Assuming the deployment has been done this way:
    294 {{{
    295 $ trac-admin /var/trac/env deploy /path/to/trac/htdocs/common
     306{{{#!sh
     307$ trac-admin /var/trac/env deploy /path/to/shared/trac
    296308}}}
    297309
    298310Add the following snippet to Apache configuration ''before'' the `ScriptAlias` or `WSGIScriptAlias` (which map all the other requests to the Trac application), changing paths to match your deployment:
    299 {{{
     311{{{#!apache
    300312Alias /trac/chrome/common /path/to/trac/htdocs/common
    301313Alias /trac/chrome/site /path/to/trac/htdocs/site
     
    308320
    309321If using mod_python, you might want to add this too (otherwise, the alias will be ignored):
    310 {{{
     322{{{#!apache
    311323<Location "/trac/chrome/common/">
    312324  SetHandler None
     
    314326}}}
    315327
    316 Note that we mapped `/trac` part of the URL to the `trac.*cgi` script, and the path `/trac/chrome/common` is the path you have to append to that location to intercept requests to the static resources.
     328Note that we mapped the `/trac` part of the URL to the `trac.*cgi` script, and the path `/trac/chrome/common` is the path you have to append to that location to intercept requests to the static resources.
    317329
    318330Similarly, if you have static resources in a project's `htdocs` directory (which is referenced by `/trac/chrome/site` URL in themes), you can configure Apache to serve those resources (again, put this ''before'' the `ScriptAlias` or `WSGIScriptAlias` for the .*cgi scripts, and adjust names and locations to match your installation):
    319 {{{
     331{{{#!apache
    320332Alias /trac/chrome/site /path/to/projectenv/htdocs
    321333
     
    326338}}}
    327339
    328 Alternatively to aliasing `/trac/chrome/common`, you can tell Trac to generate direct links for those static resources (and only those), using the [[wiki:TracIni#trac-section| [trac] htdocs_location]] configuration setting:
    329 {{{
     340Alternatively to aliasing `/trac/chrome/common`, you can tell Trac to generate direct links for those static resources (and only those), using the [[TracIni#trac-section| [trac] htdocs_location]] configuration setting:
     341{{{#!ini
    330342[trac]
    331343htdocs_location = http://static.example.org/trac-common/
     
    334346
    335347Of course, you still need to make the Trac `htdocs/common` directory available through the web server at the specified URL, for example by copying (or linking) the directory into the document root of the web server:
    336 {{{
     348{{{#!sh
    337349$ ln -s /path/to/trac/htdocs/common /var/www/static.example.org/trac-common
    338350}}}
    339351
    340 
    341 ==== Setting up the Plugin Cache ====
    342 
    343 Some Python plugins need to be extracted to a cache directory. By default the cache resides in the home directory of the current user. When running Trac on a Web Server as a dedicated user (which is highly recommended) who has no home directory, this might prevent the plugins from starting. To override the cache location you can set the PYTHON_EGG_CACHE environment variable. Refer to your server documentation for detailed instructions on how to set environment variables.
    344 
    345 == Configuring Authentication ==
    346 
    347 Trac uses HTTP authentication. You'll need to configure your webserver to request authentication when the `.../login` URL is hit (the virtual path of the "login" button). Trac will automatically pick the REMOTE_USER variable up after you provide your credentials. Therefore, all user management goes through your web server configuration. Please consult the documentation of your web server for more info.
     352==== Setting up the Plugin Cache
     353
     354Some Python plugins need to be extracted to a cache directory. By default the cache resides in the home directory of the current user. When running Trac on a Web Server as a dedicated user (which is highly recommended) who has no home directory, this might prevent the plugins from starting. To override the cache location you can set the `PYTHON_EGG_CACHE` environment variable. Refer to your server documentation for detailed instructions on how to set environment variables.
     355
     356== Configuring Authentication
     357
     358Trac uses HTTP authentication. You'll need to configure your webserver to request authentication when the `.../login` URL is hit (the virtual path of the "login" button). Trac will automatically pick the `REMOTE_USER` variable up after you provide your credentials. Therefore, all user management goes through your web server configuration. Please consult the documentation of your web server for more info.
    348359
    349360The process of adding, removing, and configuring user accounts for authentication depends on the specific way you run Trac.
     
    351362Please refer to one of the following sections:
    352363 * TracStandalone#UsingAuthentication if you use the standalone server, `tracd`.
    353  * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: `mod_wsgi` of course, but the same instructions applies also for `mod_python`, `mod_fcgi` or `mod_fastcgi`.
     364 * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: `mod_wsgi`, `mod_python`, `mod_fcgi` or `mod_fastcgi`.
    354365 * TracFastCgi if you're using another web server with FCGI support (Cherokee, Lighttpd, !LiteSpeed, nginx)
     366
     367[trac:TracAuthenticationIntroduction] also contains some useful information for beginners.
    355368
    356369== Granting admin rights to the admin user
    357370Grant admin rights to user admin:
    358 {{{
     371{{{#!sh
    359372$ trac-admin /path/to/myproject permission add admin TRAC_ADMIN
    360373}}}
    361 This user will have an "Admin" entry menu that will allow you to admin your trac project.
    362 
    363 == Finishing the install
    364 
    365 === Automatic reference to the SVN changesets in Trac tickets ===
    366 
    367 You can configure SVN to automatically add a reference to the changeset into the ticket comments, whenever changes are committed to the repository. The description of the commit needs to contain one of the following formulas:
    368  * '''`Refs #123`''' - to reference this changeset in `#123` ticket
    369  * '''`Fixes #123`''' - to reference this changeset and close `#123` ticket with the default status ''fixed''
    370 
    371 This functionality requires a post-commit hook to be installed as described in [wiki:TracRepositoryAdmin#ExplicitSync TracRepositoryAdmin], and enabling the optional commit updater components by adding the following line to the `[components]` section of your [wiki:TracIni#components-section trac.ini], or enabling the components in the "Plugins" admin panel.
    372 {{{
    373 tracopt.ticket.commit_updater.* = enabled
    374 }}}
    375 For more information, see the documentation of the `CommitTicketUpdater` component in the "Plugins" admin panel.
    376 
    377 === Using Trac ===
     374
     375This user will have an //Admin// navigation item that directs to pages for administering your Trac project.
     376
     377== Configuring Trac
     378
     379TracRepositoryAdmin provides information on configuring version control repositories for your project.
     380
     381== Using Trac
    378382
    379383Once you have your Trac site up and running, you should be able to create tickets, view the timeline, browse your version control repository if configured, etc.
    380384
    381 Keep in mind that //anonymous// (not logged in) users can by default access only a few of the features, in particular they will have a read-only access to the resources. You will need to configure authentication and grant additional [wiki:TracPermissions permissions] to authenticated users to see the full set of features.
     385Keep in mind that //anonymous// (not logged in) users can by default access only a few of the features, in particular they will have a read-only access to the resources. You will need to configure authentication and grant additional [TracPermissions permissions] to authenticated users to see the full set of features.
    382386
    383387'' Enjoy! ''
  • wiki/pages/TracInterfaceCustomization

    r26484 r37343  
    1 = Customizing the Trac Interface =
     1= Customizing the Trac Interface
    22[[TracGuideToc]]
    33[[PageOutline]]
    44
    5 == Introduction ==
    6 This page is meant to give users suggestions on how they can customize the look of Trac.  Topics on this page cover editing the HTML templates and CSS files, but not the program code itself.  The topics are intended to show users how they can modify the look of Trac to meet their specific needs. Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page.
     5== Introduction
     6This page gives suggestions on how to customize the look of Trac. Topics include editing the HTML templates and CSS files, but not the program code itself. The topics show users how they can modify the look of Trac to meet their specific needs. Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page.
    77
    8 == Project Logo and Icon ==
    9 The easiest parts of the Trac interface to customize are the logo and the site icon.  Both of these can be configured with settings in [wiki:TracIni trac.ini].
     8== Project Logo and Icon
     9The easiest parts of the Trac interface to customize are the logo and the site icon. Both of these can be configured with settings in [wiki:TracIni trac.ini].
    1010
    11 The logo or icon image should be put in a folder named "htdocs" in your project's environment folder.  (''Note: in projects created with a Trac version prior to 0.9 you will need to create this folder'')
     11The logo or icon image should be put in a folder named "htdocs" in your project's environment folder. ''Note: in projects created with a Trac version prior to 0.9 you will need to create this folder''.
    1212
    13  ''Note: you can actually put the logo and icon anywhere on your server (as long as it's accessible through the web server), and use their absolute or server-relative URLs in the configuration.''
     13 '''Note''': you can actually put the logo and icon anywhere on your server (as long as it's accessible through the web server), and use their absolute or server-relative URLs in the configuration.
    1414
    1515Now configure the appropriate section of your [wiki:TracIni trac.ini]:
    1616
    17 === Logo ===
    18 Change the `src` setting to `site/` followed by the name of your image file.  The `width` and `height` settings should be modified to match your image's dimensions (the Trac chrome handler uses "`site/`" for files within the project directory `htdocs`, and "`common/`" for the common `htdocs` directory belonging to a Trac installation). Note that 'site/' is not a placeholder for your project name, it is the actual prefix that should be used (literally). For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'.
     17=== Logo
     18Change the `src` setting to `site/` followed by the name of your image file. The `width` and `height` settings should be modified to match your image's dimensions. The Trac chrome handler uses "`site/`" for files within the project directory `htdocs`, and "`common/`" for the common `htdocs` directory belonging to a Trac installation. Note that 'site/' is not a placeholder for your project name, it is the literal prefix that should be used. For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'.
    1919
    20 {{{
     20{{{#!ini
    2121[header_logo]
    2222src = site/my_logo.gif
     
    2626}}}
    2727
    28 === Icon ===
    29 Icons should be a 32x32 image in `.gif` or `.ico` format.  Change the `icon` setting to `site/` followed by the name of your icon file.  Icons will typically be displayed by your web browser next to the site's URL and in the `Bookmarks` menu.
     28=== Icon
     29Icons are small images displayed by your web browser next to the site's URL and in the `Bookmarks` menu. Icons should be a 32x32 image in `.gif` or `.ico` format. Change the `icon` setting to `site/` followed by the name of your icon file:
    3030
    31 {{{
     31{{{#!ini
    3232[project]
    3333icon = site/my_icon.ico
    3434}}}
    3535
    36 Note though that this icon is ignored by Internet Explorer, which only accepts a file named ``favicon.ico`` at the root of the host. To make the project icon work in both IE and other browsers, you can store the icon in the document root of the host, and reference it from ``trac.ini`` as follows:
     36== Custom Navigation Entries
     37The new [mainnav] and [metanav] can now be used to customize the text and link used for the navigation items, or even to disable them, but not for adding new ones.
    3738
    38 {{{
    39 [project]
    40 icon = /favicon.ico
    41 }}}
    42 
    43 Should your browser have issues with your favicon showing up in the address bar, you may put a "?" (less the quotation marks) after your favicon file extension.
    44 
    45 {{{
    46 [project]
    47 icon = /favicon.ico?
    48 }}}
    49 
    50 == Custom Navigation Entries ==
    51 The new [mainnav] and [metanav] can now be used to customize the text and link used for the navigation items, or even to disable them (but not for adding new ones).
    52 
    53 In the following example, we rename the link to the Wiki start "Home", and hide the "!Help/Guide". We also make the "View Tickets" entry link to a specific report .
    54 {{{
     39In the following example, we rename the link to the Wiki start "Home", and hide the "!Help/Guide". We also make the "View Tickets" entry link to a specific report:
     40{{{#!ini
    5541[mainnav]
    5642wiki.label = Home
     
    6551== Site Appearance == #SiteAppearance
    6652
    67 Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Documentation is yet to be written, in the meantime the following tip should work.
     53Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Say you want to add a link to a custom stylesheet, and then your own header and footer. Save the following content as `site.html` inside your projects `templates/` directory (each Trac project can have their own `site.html`), eg `/path/to/env/templates/site.html`:
    6854
    69 Say you want to add a link to a custom stylesheet, and then your own
    70 header and footer. Save the following content as `site.html` inside your projects `templates/` directory (each Trac project can have their own `site.html`), e.g. {{{/path/to/env/templates/site.html}}}:
    71 
    72 {{{
    73 #!xml
     55{{{#!xml
    7456<html xmlns="http://www.w3.org/1999/xhtml"
    7557      xmlns:py="http://genshi.edgewall.org/"
     
    7961  <head py:match="head" py:attrs="select('@*')">
    8062    ${select('*|comment()|text()')}
    81     <link rel="stylesheet" type="text/css"
    82           href="${href.chrome('site/style.css')}" />
     63    <link rel="stylesheet" href="${href.chrome('site/style.css')}" />
    8364  </head>
    8465
     
    9980}}}
    10081
    101 Those who are familiar with XSLT may notice that Genshi templates bear some similarities. However, there are some Trac specific features - for example `${href.chrome('site/style.css')}` attribute references a CSS file placed into environment's `htdocs/` directory. In a similar fashion `${chrome.htdocs_location}` is used to specify the common `htdocs/` directory belonging to a Trac installation. That latter location can however be overriden using the [[TracIni#trac-config|[trac] htdocs_location]] configuration setting.
     82Notice that XSLT bears some similarities with Genshi templates. However, there are some Trac specific features, for example the `${href.chrome('site/style.css')}` attribute references `style.css` in the environment's `htdocs/` directory. In a similar fashion `${chrome.htdocs_location}` is used to specify the common `htdocs/` directory belonging to a Trac installation. That latter location can however be overriden using the [[TracIni#trac-section|[trac] htdocs_location]] configuration setting.
    10283
    103 `site.html` is one file to contain all your modifications. It usually works using the `py:match` directive (element or attribute), and it allows you to modify the page as it renders - the matches hook onto specific sections depending on what it tries to find
    104 and modify them.
     84`site.html` is one file to contain all your modifications. It usually works using the `py:match` directive (element or attribute), and it allows you to modify the page as it renders. The matches hook onto specific sections depending on what it tries to find and modify them.
    10585See [http://groups.google.com/group/trac-users/browse_thread/thread/70487fb2c406c937/ this thread] for a detailed explanation of the above example `site.html`.
    10686A `site.html` can contain any number of such `py:match` sections for whatever you need to modify. This is all Genshi, so the [http://genshi.edgewall.org/wiki/Documentation/xml-templates.html docs on the exact syntax] can be found there.
    107 
    10887
    10988Example snippet of adding introduction text to the new ticket form (but not shown during preview):
     
    124103Example snippets for `style.css` can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss].
    125104
    126 If the environment is upgraded from 0.10 and a `site_newticket.cs` file already exists, it can actually be loaded by using a workaround - providing it contains no ClearSilver processing. In addition, as only one element can be imported, the content needs some sort of wrapper such as a `<div>` block or other similar parent container. The XInclude namespace must be specified to allow includes, but that can be moved to document root along with the others:
    127 {{{
    128 #!xml
    129 <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')"
    130         xmlns:xi="http://www.w3.org/2001/XInclude">
    131   <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)">
    132     <xi:include href="site_newticket.cs"><xi:fallback /></xi:include>
    133   </py:if>
    134   ${select('*')}
    135 </form>
    136 }}}
    137 
    138 Also note that the `site.html` (despite its name) can be put in a common templates directory - see the [[TracIni#inherit-section|[inherit] templates_dir]] option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global `site.html` file can be made to include any existing header, footer and newticket snippets.
     105Note that the `site.html`, despite its name, can be put in a shared templates directory, see the [[TracIni#inherit-section|[inherit] templates_dir]] option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global `site.html` file can be made to include any existing header, footer and newticket snippets.
    139106
    140107== Project List == #ProjectList
     
    142109You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects. 
    143110
    144 The following is the basic template used by Trac to display a list of links to the projects.  For projects that could not be loaded it displays an error message. You can use this as a starting point for your own index template.
     111The following is the basic template used by Trac to display a list of links to the projects. For projects that could not be loaded, it displays an error message. You can use this as a starting point for your own index template:
    145112
    146 {{{
    147 #!text/html
     113{{{#!text/html
    148114<!DOCTYPE html
    149115    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     
    173139
    174140For [wiki:TracModWSGI mod_wsgi]:
    175 {{{
     141{{{#!python
    176142os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template.html'
    177143}}}
    178144
    179145For [wiki:TracFastCgi FastCGI]:
    180 {{{
     146{{{#!apache
    181147FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \
    182148              -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template
     
    184150
    185151For [wiki:TracModPython mod_python]:
    186 {{{
     152{{{#!apache
    187153PythonOption TracEnvParentDir /parent/dir/of/projects
    188154PythonOption TracEnvIndexTemplate /path/to/template
     
    190156
    191157For [wiki:TracCgi CGI]:
    192 {{{
     158{{{#!apache
    193159SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template
    194160}}}
     
    196162For [wiki:TracStandalone], you'll need to set up the `TRAC_ENV_INDEX_TEMPLATE` environment variable in the shell used to launch tracd:
    197163 - Unix
    198    {{{
    199 #!sh
     164   {{{#!sh
    200165$ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template
    201166   }}}
    202167 - Windows
    203    {{{
    204 #!sh
     168   {{{#!sh
    205169$ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template
    206170   }}}
    207171
    208 == Project Templates ==
     172== Project Templates
    209173
    210 The appearance of each individual Trac environment (that is, instance of a project) can be customized independently of other projects, even those hosted by the same server. The recommended way is to use a `site.html` template (see [#SiteAppearance]) whenever possible. Using `site.html` means changes are made to the original templates as they are rendered, and you should not normally need to redo modifications whenever Trac is upgraded. If you do make a copy of `theme.html` or any other Trac template, you need to migrate your modifiations to the newer version - if not, new Trac features or bug fixes may not work as expected.
     174The appearance of each individual Trac environment, ie instance of a project, can be customized independently of other projects, even those hosted on the same server. The recommended way is to use a `site.html` template (see [#SiteAppearance]) whenever possible. Using `site.html` means changes are made to the original templates as they are rendered, and you should not normally need to redo modifications whenever Trac is upgraded. If you do make a copy of `theme.html` or any other Trac template, you need to migrate your modifiations to the newer version. If not, new Trac features or bug fixes may not work as expected.
    211175
    212 With that word of caution, any Trac template may be copied and customized. The default Trac templates are located inside the installed Trac egg (`/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, .../trac/ticket/templates, .../trac/wiki/templates, ++`). The [#ProjectList] template file is called `index.html`, while the template responsible for main layout is called `theme.html`. Page assets such as images and CSS style sheets are located in the egg's `trac/htdocs` directory.
     176With that word of caution, any Trac template may be copied and customized. The default Trac templates are located inside the installed Trac egg (`/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, .../trac/ticket/templates, .../trac/wiki/templates, ...`). The [#ProjectList] template file is called `index.html`, while the template responsible for main layout is called `theme.html`. Page assets such as images and CSS style sheets are located in the egg's `trac/htdocs` directory.
    213177
    214 However, do not edit templates or site resources inside the Trac egg - installing Trac again can completely delete your modifications. Instead use one of two alternatives:
     178However, do not edit templates or site resources inside the Trac egg. Reinstalling Trac overwrites your modifications. Instead use one of these alternatives:
    215179 * For a modification to one project only, copy the template to project `templates` directory.
    216  * For a modification shared by several projects, copy the template to a shared location and have each project point to this location using the `[inherit] templates_dir =` trac.ini option.
     180 * For a modification shared by several projects, copy the template to a shared location and have each project point to this location using the `[inherit] templates_dir` trac.ini option.
    217181
    218182Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg.
    219183
    220 Trac caches templates in memory by default to improve performance. To apply a template you need to restart the server.
     184Trac caches templates in memory by default to improve performance. To apply a template you need to restart the web server.
    221185
    222186----
  • wiki/pages/TracLinks

    r26484 r37343  
    2828 Milestones :: `milestone:1.0`
    2929 Attachment :: `attachment:example.tgz` (for current page attachment), `attachment:attachment.1073.diff:ticket:944` (absolute path)
    30  Changesets :: `r1`, `[1]`, `changeset:1` or (restricted) `[1/trunk]`, `changeset:1/trunk`
     30 Changesets :: `r1`, `[1]`, `changeset:1` or (restricted) `[1/trunk]`, `changeset:1/trunk`, `[1/repository]`
    3131 Revision log :: `r1:3`, `[1:3]` or `log:@1:3`, `log:trunk@1:3`, `[2:5/trunk]`
    3232 Diffs :: `diff:@1:3`, `diff:plugins/0.12/mercurial-plugin@9128:9953`,
     
    4343 Milestones :: milestone:1.0
    4444 Attachment :: attachment:example.tgz (for current page attachment), attachment:attachment.1073.diff:ticket:944 (absolute path)
    45  Changesets :: r1, [1], changeset:1 or (restricted) [1/trunk], changeset:1/trunk
     45 Changesets :: r1, [1], changeset:1 or (restricted) [1/trunk], changeset:1/trunk, [1/repository]
    4646 Revision log :: r1:3, [1:3] or log:@1:3, log:trunk@1:3, [2:5/trunk]
    4747 Diffs :: diff:@1:3, diff:plugins/0.12/mercurial-plugin@9128:9953,
     
    134134
    135135In order to link explicitly to a [=#toplevel toplevel] Wiki page,
    136 use the `wiki:/` prefix.
    137 Be careful **not** to use the `/` prefix alone, as this corresponds to the
    138 [#Server-relativelinks] syntax and with such a link you will lack the `/wiki/`
    139 part in the resulting URL.
    140 
    141 ''(Changed in 0.11)'' Note that in Trac 0.10, using e.g. `[../newticket]`  may have worked for linking to the `/newticket` top-level URL, but since 0.11, such a link will stay in the wiki namespace and therefore link to a sibling page.
    142 See [#Server-relativelinks] for the new syntax.
     136use the `wiki:/` prefix. Be careful **not** to use the `/` prefix alone, as this corresponds to the [#Server-relativelinks] syntax and with such a link you will lack the `/wiki/` part in the resulting URL. A link such as `[../newticket]` will stay in the wiki namespace and therefore link to a sibling page.
    143137
    144138=== Link anchors ===
     
    312306 - `ticket:1,150`
    313307
    314 ''(since Trac 0.11)''
    315 
    316308=== timeline: links ===
    317309
    318 Links to the timeline can be created by specifying a date in the ISO:8601 format. The date can be optionally followed by a time specification. The time is interpreted as being UTC time, but alternatively you can specify your local time, followed by your timezone if you don't want to compute the UTC time.
     310Links to the timeline can be created by specifying a date in the ISO:8601 format. The date can be optionally followed by a time specification. The time is interpreted as being UTC time, but if you don't want to compute the UTC time, you can specify a local time followed by your timezone offset relative to UTC.
    319311
    320312Examples:
     
    323315 - `timeline:2008-01-29T15:48Z`
    324316 - `timeline:2008-01-29T16:48+01`
    325 
    326 ''(since Trac 0.11)''
     317 - `timeline:2008-01-29T16:48+0100`
     318 - `timeline:2008-01-29T16:48+01:00`
    327319
    328320=== wiki: links ===
     
    339331 ''aliases:'' `browser:`, `repos:`
    340332
    341 The default behavior for a source:/some/path link is to open the browser in that directory directory
     333The default behavior for a `source:/some/path link` is to open the browser in that directory directory
    342334if the path points to a directory or to show the latest content of the file.
    343335
     
    351343
    352344Finally, one can also highlight an arbitrary set of lines:
    353  - `source:/some/file@123:10-20,100,103#L99` - highlight lines 10 to 20, and lines 100 and 103.
    354    ''(since 0.11)''
     345 - `source:/some/file@123:10-20,100,103#L99` - highlight lines 10 to 20, and lines 100 and 103, and target line 99
     346 - or without version number (the `@` is still needed): `source:/some/file@:10-20,100,103#L99`. Version can be omitted when the path is pointing to a source file that will no longer change (like `source:/tags/...`), otherwise it's better to specify which lines of //which version// of the file you're talking about
    355347
    356348Note that in presence of multiple repositories, the name of the repository is simply integrated in the path you specify for `source:` (e.g. `source:reponame/trunk/README`). ''(since 0.12)''
  • wiki/pages/TracLogging

    r26484 r37343  
    1 = Trac Logging =
     1= Trac Logging
    22[[TracGuideToc]]
    33
     
    66Logging is configured in the `[logging]` section in [wiki:TracIni#logging-section trac.ini].
    77
    8 == Supported Logging Methods ==
     8== Supported Logging Methods
    99
    1010The log method is set using the `log_type` option in [wiki:TracIni#logging-section trac.ini], which takes any of the following values:
     
    1616 '''eventlog''':: (Windows) Use the system's NT Event Log for Trac logging.
    1717
    18 == Log Levels ==
     18== Log Levels
    1919
    2020The verbosity level of logged messages can be set using the `log_level` option in [wiki:TracIni#logging-section trac.ini]. The log level defines the minimum level of urgency required for a message to be logged, and those levels are:
     
    2626 '''DEBUG''':: Trace messages, profiling, etc.
    2727
    28 Note that starting with Trac 0.11.5 you can in addition enable logging of SQL statements, at debug level. This is turned off by default, as it's very verbose (set `[trac] debug_sql = yes` in TracIni to activate).
     28Additionally, you can  enable logging of SQL statements at debug level. This is turned off by default, as it's very verbose. Set `[trac] debug_sql = yes` in TracIni to activate.
    2929
    30 == Log Format ==
     30== Log Format
    3131
    32 Starting with Trac 0.10.4 (see [trac:#2844 #2844]), it is possible to set the output format for log entries. This can be done through the `log_format` option in [wiki:TracIni#logging-section trac.ini]. The format is a string which can contain any of the [http://docs.python.org/library/logging.html#logrecord-attributes Python logging Formatter variables]. Additonally, the following Trac-specific variables can be used:
     32The output format for log entries can be specified through the `log_format` option in [wiki:TracIni#logging-section trac.ini]. The format is a string which can contain any of the [http://docs.python.org/library/logging.html#logrecord-attributes Python logging Formatter variables]. Additonally, the following Trac-specific variables can be used:
    3333 '''$(basename)s''':: The last path component of the current environment.
    3434 '''$(path)s''':: The absolute path for the current environment.
     
    3838
    3939The default format is:
    40 {{{
     40{{{#!ini
    4141log_format = Trac[$(module)s] $(levelname)s: $(message)s
    4242}}}
    4343
    4444In a multi-project environment where all logs are sent to the same place (e.g. `syslog`), it makes sense to add the project name. In this example we use `basename` since that can generally be used to identify a project:
    45 {{{
     45{{{#!ini
    4646log_format = Trac[$(basename)s:$(module)s] $(levelname)s: $(message)s
    4747}}}
  • wiki/pages/TracModPython

    r26484 r37343  
    1 = Trac and mod_python =
    21[[TracGuideToc]]
    32
     3= Trac and mod_python
     4
     5Mod_python is an [https://httpd.apache.org/ Apache] module that embeds the Python interpreter within the server, so that web-based applications in Python will run many times faster than traditional CGI and will have the ability to retain database connections.
    46Trac supports [http://www.modpython.org/ mod_python], which speeds up Trac's response times considerably, especially compared to [TracCgi CGI], and permits use of many Apache features not possible with [wiki:TracStandalone tracd]/mod_proxy.
    57
    6 {{{#!div class="important"
    7 ** A Word of Warning **
    8 
    9 As of 16^th^ June 2010, the mod_python project is officially dead.  If you are considering using mod_python for a new installation, '''please don't'''!  There are known issues which will not be fixed and there are now better alternatives.  Check out the main TracInstall pages for your target version for more information.
    10 }}}
    11 
    12 
    13 These instructions are for Apache 2; if you are still using Apache 1.3, you may have some luck with [trac:wiki:TracModPython2.7 TracModPython2.7], but you'll be totally on your own.
     8These instructions are for Apache 2. If you are using Apache 1.3, you may have some luck with [trac:wiki:TracModPython2.7 TracModPython2.7], but that is a deprecated setup.
    149
    1510[[PageOutline(2-3,Overview,inline)]]
     
    1813
    1914If you just installed mod_python, you may have to add a line to load the module in the Apache configuration:
    20 {{{
     15{{{#!apache
    2116LoadModule python_module modules/mod_python.so
    2217}}}
    2318
    24 ''Note: The exact path to the module depends on how the HTTPD installation is laid out.''
    25 
    26 On Debian using apt-get
    27 {{{
     19'''Note''': The exact path to the module depends on how the HTTPD installation is laid out.
     20
     21On Debian using apt-get:
     22{{{#!sh
    2823apt-get install libapache2-mod-python libapache2-mod-python-doc
    2924}}}
    30 (Still on Debian) after you have installed mod_python, you must enable the modules in apache2 (equivalent of the above Load Module directive):
    31 {{{
     25
     26Still on Debian, after you have installed mod_python, you must enable the modules in apache2, equivalent to the above Load Module directive:
     27{{{#!sh
    3228a2enmod python
    3329}}}
     30
    3431On Fedora use, using yum:
    35 {{{
     32{{{#!sh
    3633yum install mod_python
    3734}}}
    38 You can test your mod_python installation by adding the following to your httpd.conf.  You should remove this when you are done testing for security reasons. Note: mod_python.testhandler is only available in mod_python 3.2+.
    39 {{{
    40 #!xml
     35
     36You can test your mod_python installation by adding the following to your httpd.conf. You should remove this when you are done testing for security reasons. Note: mod_python.testhandler is only available in mod_python 3.2+.
     37{{{#!apache
    4138<Location /mpinfo>
    4239   SetHandler mod_python
     
    4946
    5047A simple setup of Trac on mod_python looks like this:
    51 {{{
    52 #!xml
     48{{{#!apache
    5349<Location /projects/myproject>
    5450   SetHandler mod_python
     
    6258}}}
    6359
    64 The option '''`TracUriRoot`''' may or may not be necessary in your setup. Try your configuration without it; if the URLs produced by Trac look wrong, if Trac does not seem to recognize URLs correctly, or you get an odd "No handler matched request to..." error, add the '''`TracUriRoot`''' option.  You will notice that the `Location` and '''`TracUriRoot`''' have the same path.
    65 
    66 The options available are
    67 {{{
    68     # For a single project
    69     PythonOption TracEnv /var/trac/myproject
    70 
    71     # For multiple projects
    72     PythonOption TracEnvParentDir /var/trac/myprojects
    73 
    74     # For the index of multiple projects
    75     PythonOption TracEnvIndexTemplate /srv/www/htdocs/trac/project_list_template.html
    76 
    77     # A space delimitted list, with a "," between key and value pairs.
    78     PythonOption TracTemplateVars key1,val1 key2,val2
    79 
    80     # Useful to get the date in the wanted order
    81     PythonOption TracLocale en_GB.UTF8
    82 
    83     # See description above       
    84     PythonOption TracUriRoot /projects/myproject
    85 }}}
    86 
    87 === Python Egg Cache ===
    88 
    89 Compressed python eggs like Genshi are normally extracted into a directory named `.python-eggs` in the users home directory. Since apache's home usually is not writable an alternate egg cache directory can be specified like this:
    90 {{{
     60The option '''`TracUriRoot`''' may or may not be necessary in your setup. Try your configuration without it; if the URLs produced by Trac look wrong, if Trac does not seem to recognize URLs correctly, or you get an odd "No handler matched request to..." error, add the '''`TracUriRoot`''' option. You will notice that the `Location` and '''`TracUriRoot`''' have the same path.
     61
     62The options available are:
     63{{{#!apache
     64# For a single project
     65PythonOption TracEnv /var/trac/myproject
     66
     67# For multiple projects
     68PythonOption TracEnvParentDir /var/trac/myprojects
     69
     70# For the index of multiple projects
     71PythonOption TracEnvIndexTemplate /srv/www/htdocs/trac/project_list_template.html
     72
     73# A space delimitted list, with a "," between key and value pairs.
     74PythonOption TracTemplateVars key1,val1 key2,val2
     75
     76# Useful to get the date in the wanted order
     77PythonOption TracLocale en_GB.UTF8
     78
     79# See description above       
     80PythonOption TracUriRoot /projects/myproject
     81}}}
     82
     83=== Python Egg Cache
     84
     85Compressed Python eggs like Genshi are normally extracted into a directory named `.python-eggs` in the users home directory. Since Apache's home usually is not writeable, an alternate egg cache directory can be specified like this:
     86{{{#!apache
    9187PythonOption PYTHON_EGG_CACHE /var/trac/myprojects/egg-cache
    9288}}}
    9389
    94 or you can uncompress the Genshi egg to resolve problems extracting from it.
    95 
    96 === Configuring Authentication ===
     90Or you can uncompress the Genshi egg to resolve problems extracting from it.
     91
     92=== Configuring Authentication
    9793
    9894See corresponding section in the [wiki:TracModWSGI#ConfiguringAuthentication] page.
    9995
    100 
    10196== Advanced Configuration
    10297
    103 === Setting the Python Egg Cache ===
    104 
    105 If the Egg Cache isn't writeable by your Web server, you'll either have to change the permissions, or point Python to a location where Apache can write. This can manifest itself as a ''500 internal server error'' and/or a complaint in the syslog.
    106 
    107 {{{
    108 #!xml
     98=== Setting the Python Egg Cache
     99
     100If the Egg Cache isn't writeable by your Web server, you'll either have to change the permissions, or point Python to a location where Apache can write. This can manifest itself as a `500 internal server error` and/or a complaint in the syslog.
     101
     102{{{#!apache
    109103<Location /projects/myproject>
    110104  ...
     
    114108}}}
    115109
    116 
    117 === Setting the !PythonPath ===
    118 
    119 If the Trac installation isn't installed in your Python path, you'll have to tell Apache where to find the Trac mod_python handler  using the `PythonPath` directive:
    120 {{{
    121 #!xml
     110=== Setting the !PythonPath
     111
     112If the Trac installation isn't installed in your Python path, you will have to tell Apache where to find the Trac mod_python handler  using the `PythonPath` directive:
     113{{{#!apache
    122114<Location /projects/myproject>
    123115  ...
     
    129121Be careful about using the !PythonPath directive, and ''not'' `SetEnv PYTHONPATH`, as the latter won't work.
    130122
    131 === Setting up multiple projects ===
     123=== Setting up multiple projects
    132124
    133125The Trac mod_python handler supports a configuration option similar to Subversion's `SvnParentPath`, called `TracEnvParentDir`:
    134 {{{
    135 #!xml
     126{{{#!apache
    136127<Location /projects>
    137128  SetHandler mod_python
     
    146137
    147138If you don't want to have the subdirectory listing as your projects home page you can use a
    148 {{{
    149 #!xml
     139{{{#!apache
    150140<LocationMatch "/.+/">
    151141}}}
     
    154144
    155145You can also use the same authentication realm for all of the projects using a `<LocationMatch>` directive:
    156 {{{
    157 #!xml
     146{{{#!apache
    158147<LocationMatch "/projects/[^/]+/login">
    159148  AuthType Basic
     
    164153}}}
    165154
    166 === Virtual Host Configuration ===
    167 
    168 Below is the sample configuration required to set up your trac as a virtual server (i.e. when you access it at the URLs like
    169 !http://trac.mycompany.com):
    170 
    171 {{{
    172 #!xml
    173 <VirtualHost * >
     155=== Virtual Host Configuration
     156
     157Below is the sample configuration required to set up your Trac as a virtual server, ie when you access it at the URLs like
     158`http://trac.mycompany.com`:
     159
     160{{{#!apache
     161<VirtualHost *>
    174162    DocumentRoot /var/www/myproject
    175163    ServerName trac.mycompany.com
     
    191179
    192180This does not seem to work in all cases. What you can do if it does not:
    193  * Try using `<LocationMatch>` instead of `<Location>`
    194  * <Location /> may, in your server setup, refer to the complete host instead of simple the root of the server. This means that everything (including the login directory referenced below) will be sent to python and authentication does not work (i.e. you get the infamous Authentication information missing error). If this applies to you, try using a sub-directory for trac instead of the root (i.e. /web/ and /web/login instead of / and /login).
     181 * Try using `<LocationMatch>` instead of `<Location>`.
     182 * `<Location />` may, in your server setup, refer to the complete host instead of simple the root of the server. This means that everything (including the login directory referenced below) will be sent to Python and authentication does not work, ie you get the infamous Authentication information missing error. If this is the case, try using a sub-directory for Trac instead of the root, ie /web/ and /web/login instead of / and /login.
    195183 * Depending on apache's `NameVirtualHost` configuration, you may need to use `<VirtualHost *:80>` instead of `<VirtualHost *>`.
    196184
    197 For a virtual host that supports multiple projects replace "`TracEnv`" /var/trac/myproject with "`TracEnvParentDir`" /var/trac/
    198 
    199 Note: !DocumentRoot should not point to your Trac project env. As Asmodai wrote on #trac: "suppose there's a webserver bug that allows disclosure of !DocumentRoot they could then leech the entire Trac environment".
    200 
    201 == Troubleshooting ==
    202 
    203 In general, if you get server error pages, you can either check the Apache error log, or enable the `PythonDebug` option:
    204 {{{
    205 #!xml
     185For a virtual host that supports multiple projects replace `TracEnv /var/trac/myproject` with `TracEnvParentDir /var/trac`.
     186
     187'''Note''': !DocumentRoot should not point to your Trac project env. As Asmodai wrote on #trac: "suppose there's a webserver bug that allows disclosure of !DocumentRoot they could then leech the entire Trac environment".
     188
     189== Troubleshooting
     190
     191If you get server error pages, you can either check the Apache error log, or enable the `PythonDebug` option:
     192{{{#!apache
    206193<Location /projects/myproject>
    207194  ...
     
    212199For multiple projects, try restarting the server as well.
    213200
    214 === Login Not Working ===
     201=== Login Not Working
     202
    215203If you've used `<Location />` directive, it will override any other directives, as well as `<Location /login>`.
    216204The workaround is to use negation expression as follows (for multi project setups):
    217 {{{
    218 #!xml
     205{{{#!apache
    219206#this one for other pages
    220207<Location ~ "/*(?!login)">
     
    223210   PythonOption TracEnvParentDir /projects
    224211   PythonOption TracUriRoot /
    225 
    226 </Location>
     212</Location>
     213
    227214#this one for login page
    228215<Location ~ "/[^/]+/login">
     
    247234
    248235This problem will most certainly hit you on Unix when using Python 2.4.
    249 In Python 2.4, some version of Expat (an XML parser library written in C) is used,
    250 and if Apache is using another version, this results in segmentation faults.
    251 As Trac 0.11 is using Genshi, which will indirectly use Expat, that problem
    252 can now hit you even if everything was working fine before with Trac 0.10.
    253 
    254 See Graham Dumpleton's detailed [http://www.dscpl.com.au/wiki/ModPython/Articles/ExpatCausingApacheCrash explanation and workarounds] for the issue.
    255 
    256 === Form submission problems ===
     236In Python 2.4, some version of [http://expat.sourceforge.net/ Expat] (an XML parser library written in C) is used and if Apache is using another version, this results in segmentation faults.
     237As Trac 0.11 is using Genshi, which will indirectly use Expat, that problem can now hit you even if everything was working fine before with Trac 0.10. This problem has not been reported for Python 2.5+, so best to upgrade.
     238
     239=== Form submission problems
    257240
    258241If you're experiencing problems submitting some of the forms in Trac (a common problem is that you get redirected to the start page after submission), check whether your {{{DocumentRoot}}} contains a folder or file with the same path that you mapped the mod_python handler to. For some reason, mod_python gets confused when it is mapped to a location that also matches a static resource.
    259242
    260 === Problem with virtual host configuration ===
    261 
    262 If the <Location /> directive is used, setting the `DocumentRoot` may result in a ''403 (Forbidden)'' error. Either remove the `DocumentRoot` directive, or make sure that accessing the directory it points is allowed (in a corresponding `<Directory>` block).
    263 
    264 Using <Location /> together with `SetHandler` resulted in having everything handled by mod_python, which leads to not being able download any CSS or images/icons. I used <Location /trac> `SetHandler None` </Location> to circumvent the problem, though I do not know if this is the most elegant solution.
    265 
    266 === Problem with zipped egg ===
    267 
    268 It's possible that your version of mod_python will not import modules from zipped eggs. If you encounter an `ImportError: No module named trac` in your Apache logs but you think everything is where it should be, this might be your problem. Look in your site-packages directory; if the Trac module appears as a ''file'' rather than a ''directory'', then this might be your problem. To rectify, try installing Trac using the `--always-unzip` option, like this:
    269 
    270 {{{
     243=== Problem with virtual host configuration
     244
     245If the <Location /> directive is used, setting the `DocumentRoot` may result in a ''403 (Forbidden)'' error. Either remove the `DocumentRoot` directive, or make sure that accessing the directory it points is allowed, in a corresponding `<Directory>` block.
     246
     247Using <Location /> together with `SetHandler` resulted in having everything handled by mod_python, which leads to not being able to download any CSS or images/icons. Use <Location /trac> `SetHandler None` </Location> to circumvent the problem, though this may not be the most elegant solution.
     248
     249=== Problem with zipped egg
     250
     251It's possible that your version of mod_python will not import modules from zipped eggs. If you encounter an `ImportError: No module named trac` in your Apache logs but you think everything is where it should be, this might be your problem. Look in your site-packages directory; if the Trac module appears as a ''file'' rather than a ''directory'', then this might be your problem. To rectify this, try installing Trac using the `--always-unzip` option:
     252
     253{{{#!sh
    271254easy_install --always-unzip Trac-0.12b1.zip
    272255}}}
    273256
    274 === Using .htaccess ===
     257=== Using .htaccess
    275258
    276259Although it may seem trivial to rewrite the above configuration as a directory in your document root with a `.htaccess` file, this does not work. Apache will append a "/" to any Trac URLs, which interferes with its correct operation.
    277260
    278 It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth. Stick to the provided instructions. :)
    279 
    280 A success story: For me it worked out-of-box, with following trivial config:
    281 {{{#!xml
     261It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth.
     262
     263This also works out-of-box, with following trivial config:
     264{{{#!apache
    282265SetHandler mod_python
    283266PythonInterpreter main_interpreter
     
    292275}}}
    293276
    294 The `TracUriRoot` is obviously the path you need to enter to the browser to get to the trac (e.g. domain.tld/projects/trac)
    295 
    296 === Additional .htaccess help ===
    297 
    298 If you are using the .htaccess method you may have additional problems if your trac directory is inheriting .htaccess directives from another. This may also help to add to your .htaccess file:
    299 
    300 {{{
     277The `TracUriRoot` is obviously the path you need to enter to the browser to get to Trac, eg `domain.tld/projects/trac`.
     278
     279=== Additional .htaccess help
     280
     281If you are using the .htaccess method you may have additional problems if your Trac directory is inheriting .htaccess directives from another. This may also help to add to your .htaccess file:
     282
     283{{{#!apache
    301284<IfModule mod_rewrite.c>
    302285  RewriteEngine Off
     
    305288
    306289=== Platform specific issues
    307 ==== Win32 Issues ====
    308 If you run trac with mod_python < 3.2 on Windows, uploading attachments will '''not''' work. This problem is resolved in mod_python 3.1.4 or later, so please upgrade mod_python to fix this.
    309 
    310 
    311 ==== OS X issues ====
    312 
    313 When using mod_python on OS X you will not be able to restart Apache using `apachectl restart`. This is apparently fixed in mod_python 3.2, but there's also a patch available for earlier versions [http://www.dscpl.com.au/projects/vampire/patches.html here].
    314 
    315 ==== SELinux issues ====
    316 
    317 If Trac reports something like: ''Cannot get shared lock on db.lock''
    318 The security context on the repository may need to be set:
    319 
    320 {{{
     290==== Win32 Issues
     291
     292If you run Trac with mod_python < 3.2 on Windows, uploading attachments will '''not''' work. This problem is resolved in mod_python 3.1.4 or later, so please upgrade mod_python to fix this.
     293
     294==== OS X issues
     295
     296When using mod_python on OS X you will not be able to restart Apache using `apachectl restart`. This is apparently fixed in mod_python 3.2, so please upgrade mod_python to fix this.
     297
     298==== SELinux issues
     299
     300If Trac reports something like: `Cannot get shared lock on db.lock`, then the security context on the repository may need to be set:
     301
     302{{{#!sh
    321303chcon -R -h -t httpd_sys_content_t PATH_TO_REPOSITORY
    322304}}}
    323305
    324 See also [http://subversion.tigris.org/faq.html#reposperms]
    325 
    326 ==== FreeBSD issues ====
    327 Pay attention to the version of the installed mod_python and sqlite packages. Ports have both the new and old ones, but earlier versions of pysqlite and mod_python won't integrate as the former requires threaded support in python, and the latter requires a threadless install.
    328 
    329 If you compiled and installed apache2, apache wouldn´t support threads (cause it doesn´t work very well on FreeBSD). You could force thread support when running ./configure for apache, using --enable-threads, but this isn´t recommendable.
    330 The best option [http://modpython.org/pipermail/mod_python/2006-September/021983.html seems to be] adding to /usr/local/apache2/bin/ennvars the line
    331 
    332 {{{
     306See also [http://subversion.apache.org/faq.html#reposperms How do I set repository permissions correctly?]
     307
     308==== FreeBSD issues
     309
     310The FreeBSD ports have both the new and old versions of mod_python and SQLite, but earlier versions of pysqlite and mod_python won't integrate:
     311 * pysqlite requires threaded support in Python
     312 * mod_python requires a threadless install.
     313
     314Apache2 does not automatically support threads on FreeBSD. You could force thread support when running `./configure` for Apache, using `--enable-threads`, but this isn´t recommended.
     315The best option [http://modpython.org/pipermail/mod_python/2006-September/021983.html seems to be] adding to /usr/local/apache2/bin/ennvars the line:
     316
     317{{{#!sh
    333318export LD_PRELOAD=/usr/lib/libc_r.so
    334319}}}
    335320
    336 
    337 ==== Fedora 7 Issues ====
    338 Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython but not for tracd
    339 
    340 
    341 === Subversion issues ===
    342 
    343 If you get the following Trac Error `Unsupported version control system "svn"` only under mod_python, though it works well on the command-line and even with TracStandalone, chances are that you forgot to add the path to the Python bindings with the [TracModPython#ConfiguringPythonPath PythonPath] directive. (The better way is to add a link to the bindings in the Python `site-packages` directory, or create a `.pth` file in that directory.)
    344 
    345 If this is not the case, it's possible that you're using Subversion libraries that are binary incompatible with the apache ones (an incompatibility of the `apr` libraries is usually the cause). In that case, you also won't be able to use the svn modules for Apache (`mod_dav_svn`).
    346 
    347 You also need a recent version of `mod_python` in order to avoid a runtime error ({{{argument number 2: a 'apr_pool_t *' is expected}}}) due to the default usage of multiple sub-interpreters. 3.2.8 ''should'' work, though it's probably better to use the workaround described in [trac:#3371 #3371], in order to force the use of the main interpreter:
    348 {{{
     321==== Fedora 7 Issues
     322
     323Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython, but not for tracd.
     324
     325=== Subversion issues
     326
     327If you get the following Trac error `Unsupported version control system "svn"` only under mod_python, though it works well on the command-line and even with TracStandalone, chances are that you forgot to add the path to the Python bindings with the [TracModPython#ConfiguringPythonPath PythonPath] directive. A better way is to add a link to the bindings in the Python `site-packages` directory, or create a `.pth` file in that directory.
     328
     329If this is not the case, it's possible that you are using Subversion libraries that are binary incompatible with the Apache ones and an incompatibility of the `apr` libraries is usually the cause. In that case, you also won't be able to use the svn modules for Apache (`mod_dav_svn`).
     330
     331You also need a recent version of `mod_python` in order to avoid a runtime error ({{{argument number 2: a 'apr_pool_t *' is expected}}}) due to the default usage of multiple sub-interpreters. Version 3.2.8 ''should'' work, though it's probably better to use the workaround described in [trac:#3371 #3371], in order to force the use of the main interpreter:
     332{{{#!apache
    349333PythonInterpreter main_interpreter
    350334}}}
    351 This is anyway the recommended workaround for other well-known issues seen when using the Python bindings for Subversion within mod_python ([trac:#2611 #2611], [trac:#3455 #3455]). See in particular Graham Dumpleton's comment in [trac:comment:9:ticket:3455 #3455] explaining the issue.
    352 
    353 === Page layout issues ===
    354 
    355 If the formatting of the Trac pages look weird chances are that the style sheets governing the page layout are not handled properly by the web server. Try adding the following lines to your apache configuration:
    356 {{{
    357 #!xml
     335
     336This is also the recommended workaround for other issues seen when using the Python bindings for Subversion within mod_python ([trac:#2611 #2611], [trac:#3455 #3455]). See in particular Graham Dumpleton's comment in [trac:comment:9:ticket:3455 #3455] explaining the issue.
     337
     338=== Page layout issues
     339
     340If the formatting of the Trac pages look weird, chances are that the style sheets governing the page layout are not handled properly by the web server. Try adding the following lines to your Apache configuration:
     341{{{#!apache
    358342Alias /myproject/css "/usr/share/trac/htdocs/css"
    359343<Location /myproject/css>
     
    362346}}}
    363347
    364 Note: For the above configuration to have any effect it must be put after the configuration of your project root location, i.e. {{{<Location /myproject />}}}.
    365 
    366 Also, setting `PythonOptimize On` seems to mess up the page headers and footers, in addition to hiding the documentation for macros and plugins (see #Trac8956). Considering how little effect the option has, it is probably a good idea to leave it `Off`.
    367 
    368 === HTTPS issues ===
    369 
    370 If you want to run Trac fully under https you might find that it tries to redirect to plain http. In this case just add the following line to your apache configuration:
    371 {{{
    372 #!xml
    373 <VirtualHost * >
     348'''Note''': For the above configuration to have any effect it must be put after the configuration of your project root location, ie {{{<Location /myproject />}}}.
     349
     350Also, setting `PythonOptimize On` seems to mess up the page headers and footers, in addition to hiding the documentation for macros and plugins (see #Trac8956). Considering how little effect the option has, leave it `Off`.
     351
     352=== HTTPS issues
     353
     354If you want to run Trac fully under https you might find that it tries to redirect to plain http. In this case just add the following line to your Apache configuration:
     355{{{#!apache
     356<VirtualHost *>
    374357    DocumentRoot /var/www/myproject
    375358    ServerName trac.mycompany.com
     
    379362}}}
    380363
    381 
    382 === Segmentation fault with php5-mhash or other php5 modules ===
    383 You may encounter segfaults (reported on debian etch) if php5-mhash module is installed. Try to remove it to see if this solves the problem. See debian bug report [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487]
    384 
    385 Some people also have troubles when using php5 compiled with its own 3rd party libraries instead of system libraries. Check here [http://www.djangoproject.com/documentation/modpython/#if-you-get-a-segmentation-fault]
     364=== Segmentation fault with php5-mhash or other php5 modules
     365
     366You may encounter segfaults (reported on Debian etch) if php5-mhash module is installed. Try to remove it to see if this solves the problem. See [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487 Debian bug report].
     367
     368Some people also have troubles when using PHP5 compiled with its own third party libraries instead of system libraries. Check [http://www.djangoproject.com/documentation/modpython/#if-you-get-a-segmentation-fault Django segmentation fault].
    386369
    387370----
    388 See also:  TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI],  [trac:TracNginxRecipe TracNginxRecipe]
     371See also: TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI], [trac:TracNginxRecipe]
  • wiki/pages/TracModWSGI

    r26484 r37343  
    1 = Trac and mod_wsgi =
    2 
    3 
    4 [http://code.google.com/p/modwsgi/ mod_wsgi] is an Apache module for running WSGI-compatible Python applications directly on top of the Apache webserver. The mod_wsgi adapter is written completely in C and provides very good performances.
     1= Trac and mod_wsgi
     2
     3[https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi] is an Apache module for running WSGI-compatible Python applications directly on top of the Apache webserver. The mod_wsgi adapter is written completely in C and provides very good performance.
    54
    65[[PageOutline(2-3,Overview,inline)]]
     
    87== The `trac.wsgi` script
    98
    10 Trac can be run on top of mod_wsgi with the help of the following application script, which is just a Python file, though usually saved with a `.wsgi` extension).
     9Trac can be run on top of mod_wsgi with the help of an application script, which is just a Python file saved with a `.wsgi` extension.
     10
     11A robust and generic version of this file can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths, see TracInstall#cgi-bin. The script should be sufficient for most installations and users not wanting more information can proceed to [#Mappingrequeststothescript configuring Apache].
     12
     13If you are using Trac with multiple projects, you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` in trac.wsgi:
     14{{{#!python
     15def application(environ, start_request):
     16    # Add this to config when you have multiple projects                                             
     17    environ.setdefault('trac.env_parent_dir', '/usr/share/trac/projects') 
     18    ..
     19}}}
    1120
    1221=== A very basic script
     
    2332}}}
    2433
    25 The `TRAC_ENV` variable should naturally be the directory for your Trac environment (if you have several Trac environments in a directory, you can also use `TRAC_ENV_PARENT_DIR` instead), while the `PYTHON_EGG_CACHE` should be a directory where Python can temporarily extract Python eggs.
     34The `TRAC_ENV` variable should naturally be the directory for your Trac environment, and the `PYTHON_EGG_CACHE` should be a directory where Python can temporarily extract Python eggs. If you have several Trac environments in a directory, you can also use `TRAC_ENV_PARENT_DIR` instead of `TRAC_ENV`.
     35
     36On Windows:
     37 - If run under the user's session, the Python Egg cache can be found in `%AppData%\Roaming`, for example:
     38{{{#!python
     39os.environ['PYTHON_EGG_CACHE'] = r'C:\Users\Administrator\AppData\Roaming\Python-Eggs'
     40}}}
     41 - If run under a Window service, you should create a directory for Python Egg cache:
     42{{{#!python
     43os.environ['PYTHON_EGG_CACHE'] = r'C:\Trac-Python-Eggs'
     44}}}
    2645
    2746=== A more elaborate script
    2847
    29 If you're using multiple `.wsgi` files (for example one per Trac environment) you must ''not'' use `os.environ['TRAC_ENV']` to set the path to the Trac environment. Using this method may lead to Trac delivering the content of another Trac environment, as the variable may be filled with the path of a previously viewed Trac environment.
     48If you are using multiple `.wsgi` files (for example one per Trac environment) you must ''not'' use `os.environ['TRAC_ENV']` to set the path to the Trac environment. Using this method may lead to Trac delivering the content of another Trac environment, as the variable may be filled with the path of a previously viewed Trac environment.
    3049
    3150To solve this problem, use the following `.wsgi` file instead:
     
    4362For clarity, you should give this file a `.wsgi` extension. You should probably put the file in its own directory, since you will expose it to Apache.
    4463
    45 If you have installed Trac and eggs in a path different from the standard one you should add that path by adding the following code at the top of the wsgi script:
     64If you have installed Trac and Python eggs in a path different from the standard one, you should add that path by adding the following code at the top of the wsgi script:
    4665
    4766{{{#!python
     
    5271Change it according to the path you installed the Trac libs at.
    5372
    54 === Recommended `trac.wsgi` script
    55 
    56 A somewhat robust and generic version of this file can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths (see TracInstall#cgi-bin).
    57 
    58 
    5973== Mapping requests to the script
    6074
    61 After you've done preparing your .wsgi script, add the following to your Apache configuration file (`httpd.conf` for example).
    62 
    63 {{{
     75After preparing your .wsgi script, add the following to your Apache configuration file, typically `httpd.conf`:
     76
     77{{{#!apache
    6478WSGIScriptAlias /trac /usr/local/trac/mysite/apache/mysite.wsgi
    6579
     
    7387Here, the script is in a subdirectory of the Trac environment.
    7488
    75 If you followed the directions [http://trac.edgewall.org/wiki/TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following:
    76 
    77 {{{
     89If you followed the directions [TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following:
     90
     91{{{#!apache
    7892WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi
    7993
     
    8599}}}
    86100
    87 In order to let Apache run the script, access to the directory in which the script resides is opened up to all of Apache. Additionally, the `WSGIApplicationGroup` directive ensures that Trac is always run in the first Python interpreter created by mod_wsgi; this is necessary because the Subversion Python bindings, which are used by Trac, don't always work in other sub-interpreters and may cause requests to hang or cause Apache to crash as a result. After adding this configuration, restart Apache, and then it should work.
     101In order to let Apache run the script, access to the directory in which the script resides is opened up to all of Apache. Additionally, the `WSGIApplicationGroup` directive ensures that Trac is always run in the first Python interpreter created by mod_wsgi. This is necessary because the Subversion Python bindings, which are used by Trac, don't always work in other sub-interpreters and may cause requests to hang or cause Apache to crash. After adding this configuration, restart Apache, and then it should work.
    88102
    89103To test the setup of Apache, mod_wsgi and Python itself (ie. without involving Trac and dependencies), this simple wsgi application can be used to make sure that requests gets served (use as only content in your `.wsgi` script):
     
    97111For more information about using the mod_wsgi specific directives, see the [http://code.google.com/p/modwsgi/wiki/ mod_wsgi's wiki] and more specifically the [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac IntegrationWithTrac] page.
    98112
    99 
    100113== Configuring Authentication
    101114
    102 We describe in the the following sections different methods for setting up authentication.
    103 
    104 See also [http://httpd.apache.org/docs/2.2/howto/auth.html Authentication, Authorization and Access Control] in the Apache guide.
    105 
    106 === Using Basic Authentication ===
    107 
    108 The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program to create the password file:
    109 {{{
     115The following sections describe different methods for setting up authentication. See also [http://httpd.apache.org/docs/2.2/howto/auth.html Authentication, Authorization and Access Control] in the Apache guide.
     116
     117=== Using Basic Authentication
     118
     119The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program as follows:
     120{{{#!sh
    110121$ htpasswd -c /somewhere/trac.htpasswd admin
    111122New password: <type password>
     
    114125}}}
    115126
    116 After the first user, you dont need the "-c" option anymore:
    117 {{{
     127After the first user, you don't need the "-c" option anymore:
     128{{{#!sh
    118129$ htpasswd /somewhere/trac.htpasswd john
    119130New password: <type password>
     
    126137After you've created the users, you can set their permissions using TracPermissions.
    127138
    128 Now, you'll need to enable authentication against the password file in the Apache configuration:
    129 {{{
     139Now, you need to enable authentication against the password file in the Apache configuration:
     140{{{#!apache
    130141<Location "/trac/login">
    131142  AuthType Basic
     
    136147}}}
    137148
    138 If you're hosting multiple projects you can use the same password file for all of them:
    139 {{{
     149If you are hosting multiple projects, you can use the same password file for all of them:
     150{{{#!apache
    140151<LocationMatch "/trac/[^/]+/login">
    141152  AuthType Basic
     
    148159See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html mod_auth_basic] documentation.
    149160
    150 === Using Digest Authentication ===
     161=== Using Digest Authentication
    151162
    152163For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”.
    153164
    154 You'll have to create your `.htpasswd` file with the `htdigest` command instead of `htpasswd`, as follows:
    155 {{{
    156 # htdigest -c /somewhere/trac.htpasswd trac admin
     165You have to create your `.htpasswd` file with the `htdigest` command instead of `htpasswd`, as follows:
     166{{{#!sh
     167$ htdigest -c /somewhere/trac.htpasswd trac admin
    157168}}}
    158169
    159170The "trac" parameter above is the "realm", and will have to be reused in the Apache configuration in the !AuthName directive:
    160171
    161 {{{
     172{{{#!apache
    162173<Location "/trac/login">
    163 
    164     AuthType Digest
    165     AuthName "trac"
    166     AuthDigestDomain /trac
    167     AuthUserFile /somewhere/trac.htpasswd
    168     Require valid-user
     174  AuthType Digest
     175  AuthName "trac"
     176  AuthDigestDomain /trac
     177  AuthUserFile /somewhere/trac.htpasswd
     178  Require valid-user
    169179</Location>
    170180}}}
     
    172182For multiple environments, you can use the same `LocationMatch` as described with the previous method.
    173183
     184'''Note: `Location` cannot be used inside .htaccess files, but must instead live within the main httpd.conf file. If you are on a shared server, you therefore will not be able to provide this level of granularity. '''
     185
    174186Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system:
    175 {{{
    176     LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
    177 }}}
    178 
     187{{{#!apache
     188  LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
     189}}}
    179190
    180191See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_digest.html mod_auth_digest] documentation.
     
    182193=== Using LDAP Authentication
    183194
    184 Configuration for [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap] authentication in Apache is a bit tricky (httpd 2.2.x and OpenLDAP: slapd 2.3.19)
    185 
    186 1. You need to load the following modules in Apache httpd.conf
    187 {{{
    188 LoadModule ldap_module modules/mod_ldap.so
    189 LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
    190 }}}
    191 
    192 2. Your httpd.conf also needs to look something like:
    193 
    194 {{{
     195Configuration for [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap] authentication in Apache is more involved (httpd 2.2.x and OpenLDAP: slapd 2.3.19).
     196
     1971. You need to load the following modules in Apache httpd.conf:
     198{{{#!apache
     199  LoadModule ldap_module modules/mod_ldap.so
     200  LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
     201}}}
     2021. Your httpd.conf also needs to look something like:
     203{{{#!apache
    195204<Location /trac/>
    196205  # (if you're using it, mod_python specific settings go here)
     
    206215</Location>
    207216}}}
    208 
    209 
    210 3. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory:
    211 
    212 
    213 Use the following as your LDAP URL:
    214 {{{
    215     AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)"
    216 }}}
    217 
    218 You will also need to provide an account for Apache to use when checking
    219 credentials. As this password will be listed in plaintext in the
    220 config, you should be sure to use an account specifically for this task:
    221 {{{
    222     AuthLDAPBindDN ldap-auth-user@example.com
    223     AuthLDAPBindPassword "password"
    224 }}}
    225 
    226 The whole section looks like:
    227 {{{
     2171. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory. Use the following as your LDAP URL:
     218{{{#!apache
     219  AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)"
     220}}}
     221 You will also need to provide an account for Apache to use when checking credentials. As this password will be listed in plaintext in the config, you need to use an account specifically for this task:
     222{{{#!apache
     223  AuthLDAPBindDN ldap-auth-user@example.com
     224  AuthLDAPBindPassword "password"
     225}}}
     226 The whole section looks like:
     227{{{#!apache
    228228<Location /trac/>
    229229  # (if you're using it, mod_python specific settings go here)
     
    239239  authzldapauthoritative Off
    240240  # require valid-user
    241   require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
    242 </Location>
    243 }}}
    244 
    245 Note 1: This is the case where the LDAP search will get around the multiple OUs, conecting to Global Catalog Server portion of AD (Notice the port is 3268, not the normal LDAP 389). The GCS is basically a "flattened" tree which allows searching for a user without knowing to which OU they belong.
    246 
    247 Note 2: You can also require the user be a member of a certain LDAP group, instead of
    248 just having a valid login:
    249 {{{
    250     Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com
     241  Require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
     242</Location>
     243}}}
     244
     245Note 1: This is the case where the LDAP search will get around the multiple OUs, conecting to the Global Catalog Server portion of AD. Note the port is 3268, not the normal LDAP 389. The GCS is basically a "flattened" tree which allows searching for a user without knowing to which OU they belong.
     246
     247Note 2: You can also require the user be a member of a certain LDAP group, instead of just having a valid login:
     248{{{#!apache
     249  Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com
    251250}}}
    252251
    253252See also:
    254   - [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html mod_authnz_ldap], documentation for mod_authnz_ldap
    255    
     253 - [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html mod_authnz_ldap], documentation for mod_authnz_ldap.   
    256254 - [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap], documentation for mod_ldap, which provides connection pooling and a shared cache.
    257255 - [http://trac-hacks.org/wiki/LdapPlugin TracHacks:LdapPlugin] for storing TracPermissions in LDAP.
     
    259257=== Using SSPI Authentication
    260258
    261 If you are using Apache on Windows, you can use mod_auth_sspi to provide
    262 single-sign-on. Download the module from the !SourceForge [http://sourceforge.net/projects/mod-auth-sspi/ mod-auth-sspi project] and then add the
    263 following to your !VirtualHost:
    264 {{{
    265     <Location /trac/login>
    266         AuthType SSPI
    267         AuthName "Trac Login"
    268         SSPIAuth On
    269         SSPIAuthoritative On
    270         SSPIDomain MyLocalDomain
    271         SSPIOfferBasic On
    272         SSPIOmitDomain Off
    273         SSPIBasicPreferred On
    274         Require valid-user
    275     </Location>
    276 }}}
    277 
    278 Using the above, usernames in Trac will be of the form `DOMAIN\username`, so
    279 you may have to re-add permissions and such. If you do not want the domain to
    280 be part of the username, set `SSPIOmitDomain On` instead.
     259If you are using Apache on Windows, you can use mod_auth_sspi to provide single-sign-on. Download the module from the !SourceForge [http://sourceforge.net/projects/mod-auth-sspi/ mod-auth-sspi project] and then add the following to your !VirtualHost:
     260{{{#!apache
     261<Location /trac/login>
     262  AuthType SSPI
     263  AuthName "Trac Login"
     264  SSPIAuth On
     265  SSPIAuthoritative On
     266  SSPIDomain MyLocalDomain
     267  SSPIOfferBasic On
     268  SSPIOmitDomain Off
     269  SSPIBasicPreferred On
     270  Require valid-user
     271</Location>
     272}}}
     273
     274Using the above, usernames in Trac will be of the form `DOMAIN\username`, so you may have to re-add permissions and such. If you do not want the domain to be part of the username, set `SSPIOmitDomain On` instead.
    281275
    282276Some common problems with SSPI authentication: [trac:#1055], [trac:#1168] and [trac:#3338].
     
    291285
    292286Here is an example (from the !HttpAuthStore link) using acct_mgr-0.4 for hosting a single project:
    293 {{{
     287{{{#!ini
    294288[components]
    295289; be sure to enable the component
     
    302296}}}
    303297This will generally be matched with an Apache config like:
    304 {{{
     298{{{#!apache
    305299<Location /authFile>
    306300   …HTTP authentication configuration…
     
    308302</Location>
    309303}}}
    310 Note that '''authFile''' need not exist. See the !HttpAuthStore link above for examples where multiple Trac projects are hosted on a server.
     304Note that '''authFile''' need not exist (unless you are using Account Manager older than 0.4). See the !HttpAuthStore link above for examples where multiple Trac projects are hosted on a server.
    311305
    312306=== Example: Apache/mod_wsgi with Basic Authentication, Trac being at the root of a virtual host
    313307
    314 Per the mod_wsgi documentation linked to above, here is an example Apache configuration that a) serves the Trac instance from a virtualhost subdomain and b) uses Apache basic authentication for Trac authentication.
    315 
     308Per the mod_wsgi documentation linked to above, here is an example Apache configuration that:
     309 - serves the Trac instance from a virtualhost subdomain
     310 - uses Apache basic authentication for Trac authentication.
    316311
    317312If you want your Trac to be served from e.g. !http://trac.my-proj.my-site.org, then from the folder e.g. `/home/trac-for-my-proj`, if you used the command `trac-admin the-env initenv` to create a folder `the-env`, and you used `trac-admin the-env deploy the-deploy` to create a folder `the-deploy`, then first:
    318313
    319314Create the htpasswd file:
    320 {{{
     315{{{#!sh
    321316cd /home/trac-for-my-proj/the-env
    322317htpasswd -c htpasswd firstuser
     
    324319htpasswd htpasswd seconduser
    325320}}}
    326 (keep the file above your document root for security reasons)
    327 
    328 Create this file e.g. (ubuntu) `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` with the following contents:
    329 
    330 {{{
     321Keep the file above your document root for security reasons.
     322
     323Create this file e.g. (ubuntu) `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` with the following content:
     324
     325{{{#!apache
    331326<Directory /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi>
    332327  WSGIApplicationGroup %{GLOBAL}
     
    351346Note: for subdomains to work you would probably also need to alter `/etc/hosts` and add A-Records to your host's DNS.
    352347
    353 
    354348== Troubleshooting
    355349
    356350=== Use a recent version
    357351
    358 Please use either version 1.6, 2.4 or later of `mod_wsgi`. Versions prior to 2.4 in the 2.X branch have problems with some Apache configurations that use WSGI file wrapper extension. This extension is used in Trac to serve up attachments and static media files such as style sheets. If you are affected by this problem attachments will appear to be empty and formatting of HTML pages will appear not to work due to style sheet files not loading properly. Another frequent symptom is that binary attachment downloads are truncated. See mod_wsgi tickets [http://code.google.com/p/modwsgi/issues/detail?id=100 #100] and [http://code.google.com/p/modwsgi/issues/detail?id=132 #132].
     352Please use either version 1.6, 2.4 or later of `mod_wsgi`. Versions prior to 2.4 in the 2.X branch have problems with some Apache configurations that use WSGI file wrapper extension. This extension is used in Trac to serve up attachments and static media files such as style sheets. If you are affected by this problem, attachments will appear to be empty and formatting of HTML pages will appear not to work due to style sheet files not loading properly. Another frequent symptom is that binary attachment downloads are truncated. See mod_wsgi tickets [http://code.google.com/p/modwsgi/issues/detail?id=100 #100] and [http://code.google.com/p/modwsgi/issues/detail?id=132 #132].
    359353
    360354''Note: using mod_wsgi 2.5 and Python 2.6.1 gave an Internal Server Error on my system (Apache 2.2.11 and Trac 0.11.2.1). Upgrading to Python 2.6.2 (as suggested [http://www.mail-archive.com/modwsgi@googlegroups.com/msg01917.html here]) solved this for me[[BR]]-- Graham Shanks''
    361355
    362 If you plan to use `mod_wsgi` in embedded mode on Windows or with the MPM worker on Linux, then you'll even need version 0.3.4 or greater (see [trac:#10675] for details).
    363 
    364 === Getting Trac to work nicely with SSPI and 'Require Group' ===
    365 If like me you've set Trac up on Apache, Win32 and configured SSPI, but added a 'Require group' option to your apache configuration, then the SSPIOmitDomain option is probably not working.  If its not working your usernames in trac are probably looking like 'DOMAIN\user' rather than 'user'.
    366 
    367 This WSGI script 'fixes' things, hope it helps:
     356If you plan to use `mod_wsgi` in embedded mode on Windows or with the MPM worker on Linux, then you will need version 3.4 or greater. See [trac:#10675] for details.
     357
     358=== Getting Trac to work nicely with SSPI and 'Require Group'
     359
     360If you have set Trac up on Apache, Win32 and configured SSPI, but added a 'Require group' option to your apache configuration, then the SSPIOmitDomain option is probably not working. If it is not working, your usernames in Trac probably look like 'DOMAIN\user' rather than 'user'.
     361
     362This WSGI script 'fixes' that:
    368363{{{#!python
    369364import os
     
    379374}}}
    380375
    381 
    382 === Trac with PostgreSQL ===
    383 
    384 When using the mod_wsgi adapter with multiple Trac instances and PostgreSQL (or MySQL?) as a database back-end, the server ''may'' create a lot of open database connections and thus PostgreSQL processes.
    385 
    386 A somewhat brutal workaround is to disabled connection pooling in Trac. This is done by setting `poolable = False` in `trac.db.postgres_backend` on the `PostgreSQLConnection` class.
    387 
    388 But it's not necessary to edit the source of Trac, the following lines in `trac.wsgi` will also work:
    389 
    390 {{{
     376=== Trac with PostgreSQL
     377
     378When using the mod_wsgi adapter with multiple Trac instances and PostgreSQL (or MySQL?) as the database, the server ''may'' create a lot of open database connections and thus PostgreSQL processes.
     379
     380A somewhat brutal workaround is to disable connection pooling in Trac. This is done by setting `poolable = False` in `trac.db.postgres_backend` on the `PostgreSQLConnection` class.
     381
     382But it is not necessary to edit the source of Trac. The following lines in `trac.wsgi` will also work:
     383
     384{{{#!python
    391385import trac.db.postgres_backend
    392386trac.db.postgres_backend.PostgreSQLConnection.poolable = False
     
    395389or
    396390
    397 {{{
     391{{{#!python
    398392import trac.db.mysql_backend
    399393trac.db.mysql_backend.MySQLConnection.poolable = False
    400394}}}
    401395
    402 Now Trac drops the connection after serving a page and the connection count on the database will be kept minimal.
     396Now Trac drops the connection after serving a page and the connection count on the database will be kept low.
    403397
    404398//This is not a recommended approach though. See also the notes at the bottom of the [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac mod_wsgi's IntegrationWithTrac] wiki page.//
     
    408402For more troubleshooting tips, see also the [TracModPython#Troubleshooting mod_python troubleshooting] section, as most Apache-related issues are quite similar, plus discussion of potential [http://code.google.com/p/modwsgi/wiki/ApplicationIssues application issues] when using mod_wsgi. The wsgi page also has a [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac Integration With Trac] document.
    409403
    410 
    411404----
    412 See also:  TracGuide, TracInstall, [wiki:TracFastCgi FastCGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]
     405See also: TracGuide, TracInstall, [wiki:TracFastCgi FastCGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]
  • wiki/pages/TracNavigation

    r26484 r37343  
    1 = Trac Navigation =
     1= Trac Navigation
    22
    3 Starting with Trac 0.11, it is now possible to customize the main and meta navigation entries in some basic ways.
    4 
    5 The new `[mainnav]` and `[metanav]` configuration sections can now be used to customize the text and link used for the navigation items, or even to disable them.  The `mainnav` and `metanav` options in the `[trac]` configuration section can also be used to change the order.
     3The main and meta navigation entries can be customized in some basic ways. The `[mainnav]` and `[metanav]` configuration sections can be used to customize the navigation item text and link, change the ordering of the navigation items, or even disable them.
    64
    75=== `[mainnav]` #mainnav-bar
     
    119** [=#Example Example] **
    1210
    13 In the following example, we rename the link to the Wiki start "Home", and make the "View Tickets" entry link to a specific report.  The second example (below) also hides the "!Help/Guide" link.
    14 
    15 Relevant excerpt from the TracIni:
    16 {{{
     11In the following example we rename the link to WikiStart //Home//, and make the //View Tickets// entry link to a specific report.
     12{{{#!ini
    1713[mainnav]
    1814wiki.label = Home
     
    2117
    2218=== `[metanav]` #metanav-bar
    23 `[metanav]` corresponds to the '''meta navigation bar''', by default positioned above the main navigation bar and below the ''Search'' box. It contains the ''Log in'', ''Logout'', ''!Help/Guide'' etc. entries. This navigation bar is meant to access some global information about the Trac project and the current user.
     19`[metanav]` corresponds to the '''meta navigation bar''', by default positioned above the main navigation bar and below the ''Search'' box. It contains the ''Login'', ''Logout'', ''!Help/Guide'' etc. entries. This navigation bar is meant to access some global information about the Trac project and the current user.
    2420
    25 There is one special entry in the  `[metanav]` section: `logout.redirect` is the page the user sees after hitting the logout button.
     21There is one special entry in the  `[metanav]` section: `logout.redirect` is the page the user sees after hitting the logout button.  The ''!Help/Guide'' link is also hidden in the following example.
    2622[[comment(see also #Trac3808)]]
    2723
    2824** Example **
    2925
    30 {{{
     26{{{#!ini
    3127[metanav]
    3228help = disabled
     
    3531
    3632
    37 === Notes
    38 Possible URL formats (for `.href` or `.redirect`):
     33=== URL Formats
     34Possible URL formats for `.href` or `.redirect`:
    3935|| '''config''' || '''redirect to''' ||
    4036|| `wiki/Logout` || `/projects/env/wiki/Logout` ||
     
    4339
    4440
    45 === `[trac]` #nav-order
    46 The `mainnav` and `metanav` options in the `[trac]` configuration section control the order in which the navigation items are displayed (left to right).  This can be useful with plugins that add navigation items.
     41=== Ordering #nav-order
     42The `order` attribute specifies the order in which the navigation items are displayed. This can be particularly useful for plugins that add navigation items.
    4743
    48 ** Example **
     44Non-negative floating point values may be used for the `order` attribute. The navigation items will be arranged from left to right in increasing order. Navigation items without an `order` attribute are sorted alphabetically by name.
    4945
    50 In the following example, we change the order to prioritise the ticket related items further left.
     46The default values are:
     47{{{#!ini
     48[mainnav]
     49browser.order = 4
     50newticket.order = 6
     51roadmap.order = 3
     52search.order = 7
     53tickets.order = 5
     54timeline.order = 2
     55wiki.order = 1
    5156
    52 Relevant excerpt from the TracIni:
    53 {{{
    54 [trac]
    55 mainnav = wiki,tickets,newticket,timeline,roadmap,browser,search,admin
     57[metanav]
     58about.order = 5
     59help.order = 4
     60login.order = 1
     61logout.order = 2
     62prefs.order = 3
    5663}}}
    57 
    58 The default order and item names can be viewed in the [TracIni#trac-section trac section of TracIni].
    5964
    6065=== Context Navigation #ctxtnav-bar
    6166
    62 Note that it is still not possible to customize the '''contextual navigation bar''', i.e. the one usually placed below the main navigation bar.
    63 
     67Note that it is still not possible to customize the '''contextual navigation bar''', ie the one usually placed below the main navigation bar.
    6468
    6569----
  • wiki/pages/TracNotification

    r26484 r37343  
    1 = Email Notification of Ticket Changes =
     1= Email Notification of Ticket Changes
    22[[TracGuideToc]]
    33
     
    88Disabled by default, notification can be activated and configured in [wiki:TracIni trac.ini].
    99
    10 == Receiving Notification Mails ==
    11 When reporting a new ticket or adding a comment, enter a valid email address or your username in the ''reporter'', ''assigned to/owner'' or ''cc'' field. Trac will automatically send you an email when changes are made to the ticket (depending on how notification is configured).
    12 
    13 This is useful to keep up-to-date on an issue or enhancement request that interests you.
    14 
    15 === How to use your username to receive notification mails ===
    16 
    17 To receive notification mails, you can either enter a full email address or your username. To get notified with a simple username or login, you need to specify a valid email address in the ''Preferences'' page.
    18 
    19 Alternatively, a default domain name ('''`smtp_default_domain`''') can be set in the TracIni file (see [#ConfigurationOptions Configuration Options] below). In this case, the default domain will be appended to the username, which can be useful for an "Intranet" kind of installation.
     10== Receiving Notification Mails
     11When reporting a new ticket or adding a comment, enter a valid email address or your Trac username in the ''reporter'', ''assigned to/owner'' or ''cc'' field. Trac will automatically send you an email when changes are made to the ticket, depending on how notification is configured.
     12
     13=== How to use your username to receive notification mails
     14
     15To receive notification mails, you can either enter a full email address or your Trac username. To get notified with a simple username or login, you need to specify a valid email address in the ''Preferences'' page.
     16
     17Alternatively, a default domain name ('''`smtp_default_domain`''') can be set in the TracIni file, see [#ConfigurationOptions Configuration Options] below. In this case, the default domain will be appended to the username, which can be useful for an "Intranet" kind of installation.
    2018
    2119When using apache and mod_kerb for authentication against Kerberos / Active Directory, usernames take the form ('''`username@EXAMPLE.LOCAL`'''). To avoid this being interpreted as an email address, add the Kerberos domain to  ('''`ignore_domains`''').
    2220
    23 == Configuring SMTP Notification ==
     21=== Ticket attachment notifications
     22
     23Since 1.0.3 Trac will send notifications when a ticket attachment is added or deleted. Usually attachment notifications will be enabled in an environment by default. To disable the attachment notifications for an environment the `TicketAttachmentNotifier` component must be disabled:
     24{{{#!ini
     25[components]
     26trac.ticket.notification.TicketAttachmentNotifier = disabled
     27}}}
     28
     29== Configuring SMTP Notification
    2430
    2531'''Important:''' For TracNotification to work correctly, the `[trac] base_url` option must be set in [wiki:TracIni trac.ini].
    2632
    27 === Configuration Options ===
    28 These are the available options for the `[notification]` section in trac.ini.
    29 
    30  * '''`smtp_enabled`''': Enable email notification.
    31  * '''`smtp_from`''': Email address to use for ''Sender''-headers in notification emails.
    32  * '''`smtp_from_name`''': Sender name to use for ''Sender''-headers in notification emails.
    33  * '''`smtp_from_author`''': (''since 1.0'') Use the author of a change (the reporter of a new ticket, or the author of a comment) as the `From:` header value in notification e-mails (default: false). If the author hasn't set an e-mail address, `smtp_from` and `smtp_from_name` are used instead.
    34  * '''`smtp_replyto`''': Email address to use for ''Reply-To''-headers in notification emails.
    35  * '''`smtp_default_domain`''': (''since 0.10'') Append the specified domain to addresses that do not contain one. Fully qualified addresses are not modified. The default domain is appended to all username/login for which an email address cannot be found from the user settings.
    36  * '''`smtp_always_cc`''': List of email addresses to always send notifications to. ''Typically used to post ticket changes to a dedicated mailing list.''
    37  * '''`smtp_always_bcc`''': (''since 0.10'') List of email addresses to always send notifications to, but keeps addresses not visible from other recipients of the notification email
    38  * '''`smtp_subject_prefix`''': (''since 0.10.1'') Text that is inserted before the subject of the email. Set to "!__default!__" by default.
    39  * '''`always_notify_reporter`''':  Always send notifications to any address in the reporter field (default: false).
    40  * '''`always_notify_owner`''': (''since 0.9'') Always send notifications to the address in the owner field (default: false).
    41  * '''`always_notify_updater`''': (''since 0.10'') Always send a notification to the updater of a ticket (default: true).
    42  * '''`use_public_cc`''': (''since 0.10'') Addresses in To: (owner, reporter) and Cc: lists are visible by all recipients (default is ''Bcc:'' - hidden copy).
    43  * '''`use_short_addr`''': (''since 0.10'') Enable delivery of notifications to addresses that do not contain a domain (i.e. do not end with ''@<domain.com>'').This option is useful for intranets, where the SMTP server can handle local addresses and map the username/login to a local mailbox. See also `smtp_default_domain`. Do not use this option with a public SMTP server.
    44  * '''`ignore_domains`''': Comma-separated list of domains that should not be considered part of email addresses (for usernames with Kerberos domains).
    45  * '''`mime_encoding`''': (''since 0.10'') This option allows selecting the MIME encoding scheme. Supported values:
    46    * `none`: default value, uses 7bit encoding if the text is plain ASCII, or 8bit otherwise.
    47    * `base64`: works with any kind of content. May cause some issues with touchy anti-spam/anti-virus engines.
    48    * `qp` or `quoted-printable`: best for european languages (more compact than base64) if 8bit encoding cannot be used.
    49  * '''`ticket_subject_template`''': (''since 0.11'') A [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet used to get the notification subject.
    50  * '''`email_sender`''': (''since 0.12'') Name of the component implementing `IEmailSender`. This component is used by the notification system to send emails. Trac currently provides the following components:
    51    * `SmtpEmailSender`: connects to an SMTP server (default).
    52    * `SendmailEmailSender`: runs a `sendmail`-compatible executable.
    53 
    54 Either '''`smtp_from`''' or '''`smtp_replyto`''' (or both) ''must'' be set, otherwise Trac refuses to send notification mails.
    55 
    56 The following options are specific to email delivery through SMTP.
    57  * '''`smtp_server`''': SMTP server used for notification messages.
    58  * '''`smtp_port`''': (''since 0.9'') Port used to contact the SMTP server.
    59  * '''`smtp_user`''': (''since 0.9'') User name for authentication SMTP account.
    60  * '''`smtp_password`''': (''since 0.9'') Password for authentication SMTP account.
    61  * '''`use_tls`''': (''since 0.10'') Toggle to send notifications via a SMTP server using [http://en.wikipedia.org/wiki/Transport_Layer_Security TLS], such as GMail.
    62 
    63 The following option is specific to email delivery through a `sendmail`-compatible executable.
    64  * '''`sendmail_path`''': (''since 0.12'') Path to the sendmail executable. The sendmail program must accept the `-i` and `-f` options.
    65 
    66 === Example Configuration (SMTP) ===
    67 {{{
     33=== Configuration Options
     34These are the available options for the `[notification]` section in trac.ini:
     35
     36[[TracIni(notification)]]
     37
     38=== Example Configuration (SMTP)
     39{{{#!ini
    6840[notification]
    6941smtp_enabled = true
     
    7446}}}
    7547
    76 === Example Configuration (`sendmail`) ===
    77 {{{
     48=== Example Configuration (`sendmail`)
     49{{{#!ini
    7850[notification]
    7951smtp_enabled = true
     
    8557}}}
    8658
    87 === Customizing the e-mail subject ===
     59=== Subscriber Configuration
     60The default subscriptions are configured in the `[notification-subscriber]` section in trac.ini:
     61
     62[[TracIni(notification-subscriber)]]
     63
     64Each user can override these defaults in his ''Notifications'' preferences.
     65
     66For example to unsubscribe from notifications for one's own changes and comments, the rule "Never notify: I update a ticket" should be added above other subscription rules.
     67
     68=== Customizing the e-mail subject
    8869The e-mail subject can be customized with the `ticket_subject_template` option, which contains a [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet. The default value is:
    89 {{{
     70{{{#!genshi
    9071$prefix #$ticket.id: $summary
    9172}}}
     
    9576 * `prefix`: The prefix defined in `smtp_subject_prefix`.
    9677 * `summary`: The ticket summary, with the old value if the summary was edited.
    97  * `ticket`: The ticket model object (see [trac:source:/trunk/trac/ticket/model.py model.py]). Individual ticket fields can be addressed by appending the field name separated by a dot, e.g. `$ticket.milestone`.
    98 
    99 === Customizing the e-mail content ===
    100 
    101 The notification e-mail content is generated based on `ticket_notify_email.txt` in `trac/templates`. You can add your own version of this template by adding a `ticket_notify_email.txt` to the templates directory of your environment. The default looks like this:
    102 
    103 {{{
     78 * `ticket`: The ticket model object (see [trac:source:/trunk/trac/ticket/model.py model.py]). Individual ticket fields can be addressed by appending the field name separated by a dot, eg `$ticket.milestone`.
     79
     80=== Customizing the e-mail content
     81
     82The notification e-mail content is generated based on `ticket_notify_email.txt` in `trac/ticket/templates`. You can add your own version of this template by adding a `ticket_notify_email.txt` to the templates directory of your environment. The default looks like this:
     83
     84{{{#!genshi
    10485$ticket_body_hdr
    10586$ticket_props
     
    135116$project.descr
    136117}}}
    137 == Sample Email ==
     118
     119== Sample Email
    138120{{{
    139121#42: testing
     
    146128---------------------------+------------------------------------------------
    147129Changes:
    148   * component:  changset view => search system
     130  * component:  changeset view => search system
    149131  * priority:  low => highest
    150132  * owner:  jonas => anonymous
     
    161143}}}
    162144
    163 
    164 == Customizing e-mail content for MS Outlook ==
    165 
    166 Out-of-the-box, MS Outlook normally presents plain text e-mails with a variable-width font; the ticket properties table will most certainly look like a mess in MS Outlook. This can be fixed with some customization of the [#Customizingthee-mailcontent e-mail template].
     145== Customizing e-mail content for MS Outlook
     146
     147MS Outlook normally presents plain text e-mails with a variable-width font, and as a result the ticket properties table will most certainly look like a mess in MS Outlook. This can be fixed with some customization of the [#Customizingthee-mailcontent e-mail template].
    167148
    168149Replace the following second row in the template:
     
    171152}}}
    172153
    173 with this instead (''requires Python 2.6 or later''):
     154with this (requires Python 2.6 or later):
    174155{{{
    175156--------------------------------------------------------------------------
     
    185166}}}
    186167
    187 The table of ticket properties is replaced with a list of a selection of the properties. A tab character separates the name and value in such a way that most people should find this more pleasing than the default table, when using MS Outlook.
     168The table of ticket properties is replaced with a list of a selection of the properties. A tab character separates the name and value in such a way that most people should find this more pleasing than the default table when using MS Outlook.
    188169{{{#!div style="margin: 1em 1.75em; border:1px dotted"
    189170{{{#!html
     
    205186Changes:<br />
    206187<br />
    207 &nbsp;&nbsp;* component: &nbsp;changset view =&gt; search system<br />
     188&nbsp;&nbsp;* component: &nbsp;changeset view =&gt; search system<br />
    208189&nbsp;&nbsp;* priority: &nbsp;low =&gt; highest<br />
    209190&nbsp;&nbsp;* owner: &nbsp;jonas =&gt; anonymous<br />
     
    221202}}}
    222203
    223 **Important**: Only those ticket fields that are listed in `sel` are part of the HTML mail. If you have defined custom ticket fields which shall be part of the mail they have to be added to `sel`, example:
     204**Important**: Only those ticket fields that are listed in `sel` are part of the HTML mail. If you have defined custom ticket fields which are to be part of the mail, then they have to be added to `sel`. Example:
    224205{{{
    225206   sel = ['Reporter', ..., 'Keywords', 'Custom1', 'Custom2']
    226207}}}
    227208
    228 However, it's not as perfect as an automatically HTML-formatted e-mail would be, but presented ticket properties are at least readable by default in MS Outlook...
    229 
    230 
    231 == Using GMail as the SMTP relay host ==
    232 
    233 Use the following configuration snippet
    234 {{{
     209However, the solution is still a workaround to an automatically HTML-formatted e-mail.
     210
     211== Using GMail as the SMTP relay host
     212
     213Use the following configuration snippet:
     214{{{#!ini
    235215[notification]
    236216smtp_enabled = true
     
    243223}}}
    244224
    245 where ''user'' and ''password'' match an existing GMail account, ''i.e.'' the ones you use to log in on [http://gmail.com]
     225where ''user'' and ''password'' match an existing GMail account, ie the ones you use to log in on [http://gmail.com].
    246226
    247227Alternatively, you can use `smtp_port = 25`.[[br]]
    248 You should not use `smtp_port = 465`. It will not work and your ticket submission may deadlock. Port 465 is reserved for the SMTPS protocol, which is not supported by Trac. See [comment:ticket:7107:2 #7107] for details.
    249  
    250 == Filtering notifications for one's own changes ==
    251 In Gmail, use the filter:
    252 
    253 {{{
    254 from:(<smtp_from>) (("Reporter: <username>" -Changes) OR "Changes (by <username>)")
    255 }}}
    256 
    257 For Trac .10, use the filter:
    258 {{{
    259 from:(<smtp_from>) (("Reporter: <username>" -Changes -Comment) OR "Changes (by <username>)" OR "Comment (by <username>)")
    260 }}}
    261 
    262 to delete these notifications.
    263 
    264 In Thunderbird, there is no such solution if you use IMAP
    265 (see http://kb.mozillazine.org/Filters_(Thunderbird)#Filtering_the_message_body).
    266 
    267 The best you can do is to set "always_notify_updater" in conf/trac.ini to false.
    268 You will however still get an email if you comment a ticket that you own or have reported.
    269 
    270 You can also add this plugin:
    271 http://trac-hacks.org/wiki/NeverNotifyUpdaterPlugin
    272 
    273 == Troubleshooting ==
     228You should not use `smtp_port = 465`. Doing so may deadlock your ticket submission. Port 465 is reserved for the SMTPS protocol, which is not supported by Trac. See [trac:comment:2:ticket:7107 #7107] for details.
     229
     230== Troubleshooting
    274231
    275232If you cannot get the notification working, first make sure the log is activated and have a look at the log to find if an error message has been logged. See TracLogging for help about the log feature.
    276233
    277 Notification errors are not reported through the web interface, so the user who submit a change or a new ticket never gets notified about a notification failure. The Trac administrator needs to look at the log to find the error trace.
    278 
    279 === ''Permission denied'' error ===
     234Notification errors are not reported through the web interface, so the user who submits a change or a new ticket never gets notified about a notification failure. The Trac administrator needs to look at the log to find the error trace.
     235
     236=== ''Permission denied'' error
    280237
    281238Typical error message:
    282 {{{
     239{{{#!sh
    283240  ...
    284241  File ".../smtplib.py", line 303, in connect
     
    287244}}}
    288245
    289 This error usually comes from a security settings on the server: many Linux distributions do not let the web server (Apache, ...) to post email message to the local SMTP server.
     246This error usually comes from a security settings on the server: many Linux distributions do not allow the web server (Apache, ...) to post email messages to the local SMTP server.
    290247
    291248Many users get confused when their manual attempts to contact the SMTP server succeed:
    292 {{{
     249{{{#!sh
    293250telnet localhost 25
    294251}}}
    295 The trouble is that a regular user may connect to the SMTP server, but the web server cannot:
    296 {{{
     252This is because a regular user may connect to the SMTP server, but the web server cannot:
     253{{{#!sh
    297254sudo -u www-data telnet localhost 25
    298255}}}
    299256
    300 In such a case, you need to configure your server so that the web server is authorized to post to the SMTP server. The actual settings depend on your Linux distribution and current security policy. You may find help browsing the Trac [trac:MailingList MailingList] archive.
     257In such a case, you need to configure your server so that the web server is authorized to post to the SMTP server. The actual settings depend on your Linux distribution and current security policy. You may find help in the Trac [trac:MailingList MailingList] archive.
    301258
    302259Relevant ML threads:
     
    304261
    305262For SELinux in Fedora 10:
    306 {{{
     263{{{#!sh
    307264$ setsebool -P httpd_can_sendmail 1
    308265}}}
    309 === ''Suspected spam'' error ===
     266
     267=== ''Suspected spam'' error
    310268
    311269Some SMTP servers may reject the notification email sent by Trac.
    312270
    313 The default Trac configuration uses Base64 encoding to send emails to the recipients. The whole body of the email is encoded, which sometimes trigger ''false positive'' SPAM detection on sensitive email servers. In such an event, it is recommended to change the default encoding to "quoted-printable" using the `mime_encoding` option.
    314 
    315 Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, it is recommended to stick with the Base64 encoding.
    316 
    317 === ''501, 5.5.4 Invalid Address'' error ===
    318 
    319 On IIS 6.0 you could get a
    320 {{{
    321 Failure sending notification on change to ticket #1: SMTPHeloError: (501, '5.5.4 Invalid Address')
    322 }}}
    323 in the trac log. Have a look [http://support.microsoft.com/kb/291828 here] for instructions on resolving it.
    324 
     271The default Trac configuration uses Base64 encoding to send emails to the recipients. The whole body of the email is encoded, which sometimes trigger ''false positive'' spam detection on sensitive email servers. In such an event, change the default encoding to "quoted-printable" using the `mime_encoding` option.
     272
     273Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, stick with the Base64 encoding.
    325274
    326275----
    327 See also: TracTickets, TracIni, TracGuide
     276See also: TracTickets, TracIni, TracGuide, [trac:TracDev/NotificationApi]
  • wiki/pages/TracPermissions

    r26484 r37343  
    1 = Trac Permissions =
     1= Trac Permissions
    22[[TracGuideToc]]
    33
    44Trac uses a simple, case sensitive, permission system to control what users can and can't access.
    55
    6 Permission privileges are managed using the [TracAdmin trac-admin] tool or (new in version 0.11) the ''General / Permissions'' panel in the ''Admin'' tab of the web interface.
     6Permission privileges are managed using the [TracAdmin trac-admin] tool or the ''General / Permissions'' panel in the ''Admin'' tab of the web interface.
    77
    88In addition to the default permission policy described in this page, it is possible to activate additional permission policies by enabling plugins and listing them in the `[trac] permission_policies` configuration entry in the TracIni. See TracFineGrainedPermissions for more details.
     
    1111In addition to these privileges, users can be granted additional individual rights in effect when authenticated and logged into the system. All logged in users belong to the virtual group "authenticated", which inherits permissions from "anonymous".
    1212
    13 == Graphical Admin Tab ==
    14 ''This feature is new in version 0.11.''
    15 
    16 To access this tab, a user must have one of the following permissions: `TRAC_ADMIN`, `PERMISSION_ADMIN`, `PERMISSION_ADD`, `PERMISSION_REMOVE`. The permissions can granted using the `trac-admin` command (more on `trac-admin` below):
     13== Graphical Admin Tab
     14
     15To access this tab, a user must have one of the following permissions: `TRAC_ADMIN`, `PERMISSION_ADMIN`, `PERMISSION_GRANT`, `PERMISSION_REVOKE`. The permissions can be granted using the `trac-admin` command (more on `trac-admin` below):
    1716{{{
    1817  $ trac-admin /path/to/projenv permission add bob TRAC_ADMIN
     
    2726An easy way to quickly secure a new Trac install is to run the above command on the anonymous user, install the [http://trac-hacks.org/wiki/AccountManagerPlugin AccountManagerPlugin], create a new admin account graphically and then remove the TRAC_ADMIN permission from the anonymous user.
    2827
    29 == Available Privileges ==
     28From the graphical admin tab, users with `PERMISSION_GRANT` will only be allowed to grant permissions that they possess, and users with `PERMISSION_REVOKE` will only be allowed to revoke permissions that they possess. For example, a user cannot grant `MILESTONE_ADMIN` unless they have `PERMISSION_GRANT` and `MILESTONE_ADMIN`, and they cannot revoke `MILESTONE_ADMIN` unless they have `PERMISSION_REVOKE` and `MILESTONE_ADMIN`. `PERMISSION_ADMIN` just grants the user both `PERMISSION_GRANT` and `PERMISSION_REVOKE`, and users with `TRAC_ADMIN` can grant or revoke any permission.
     29
     30== Available Privileges
    3031
    3132To enable all privileges for a user, use the `TRAC_ADMIN` permission. Having `TRAC_ADMIN` is like being `root` on a *NIX system: it will allow you to perform any operation.
     
    3334Otherwise, individual privileges can be assigned to users for the various different functional areas of Trac ('''note that the privilege names are case-sensitive'''):
    3435
    35 === Repository Browser ===
     36=== Repository Browser
    3637
    3738|| `BROWSER_VIEW` || View directory listings in the [wiki:TracBrowser repository browser] ||
     
    4041|| `CHANGESET_VIEW` || View [wiki:TracChangeset repository check-ins] ||
    4142
    42 === Ticket System ===
     43=== Ticket System
    4344
    4445|| `TICKET_VIEW` || View existing [wiki:TracTickets tickets] and perform [wiki:TracQuery ticket queries] ||
     
    4950|| `TICKET_EDIT_CC` || Full modify cc field ||
    5051|| `TICKET_EDIT_DESCRIPTION` || Modify description field ||
    51 || `TICKET_EDIT_COMMENT` || Modify comments ||
     52|| `TICKET_EDIT_COMMENT` || Modify another user's comments. Any user can modify their own comments by default. ||
    5253|| `TICKET_BATCH_MODIFY` || [wiki:TracBatchModify Batch modify] tickets ||
    53 || `TICKET_ADMIN` || All `TICKET_*` permissions, plus the deletion of ticket attachments and modification of the reporter and description fields. It also allows managing ticket properties in the WebAdmin panel. ||
     54|| `TICKET_ADMIN` || All `TICKET_*` permissions, deletion of ticket attachments and modification of the reporter field, which grants ability to create a ticket on behalf of another user (it will appear that another user created the ticket). It also allows managing ticket properties through the web administration module. ||
    5455
    5556Attention: the "view tickets" button appears with the `REPORT_VIEW` permission.
    5657
    57 === Roadmap ===
     58=== Roadmap
    5859
    5960|| `MILESTONE_VIEW` || View milestones and assign tickets to milestones. ||
     
    6566|| `ROADMAP_ADMIN` || to be removed with [trac:#3022 #3022], replaced by MILESTONE_ADMIN ||
    6667
    67 === Reports ===
     68=== Reports
    6869
    6970|| `REPORT_VIEW` || View [wiki:TracReports reports], i.e. the "view tickets" link. ||
     
    7475|| `REPORT_ADMIN` || All `REPORT_*` permissions ||
    7576
    76 === Wiki System ===
     77=== Wiki System
    7778
    7879|| `WIKI_VIEW` || View existing [wiki:TracWiki wiki] pages ||
     
    8384|| `WIKI_ADMIN` || All `WIKI_*` permissions, plus the management of ''readonly'' pages. ||
    8485
    85 === Permissions ===
     86=== Permissions
    8687
    8788|| `PERMISSION_GRANT` || add/grant a permission ||
     
    8990|| `PERMISSION_ADMIN` || All `PERMISSION_*` permissions ||
    9091
    91 === Others ===
     92=== Others
    9293
    9394|| `TIMELINE_VIEW` || View the [wiki:TracTimeline timeline] page ||
     
    9697|| `EMAIL_VIEW` || Shows email addresses even if [wiki:TracIni#trac-section trac show_email_addresses] configuration option is false ||
    9798
    98 == Creating New Privileges ==
    99 
    100 To create custom permissions, for example to be used in a custom workflow, enable the optional [trac:ExtraPermissionsProvider tracopt.perm.config_perm_provider.ExtraPermissionsProvider] component in the "Plugins" admin panel, and add the desired permissions to the `[extra-permissions]` section in your [wiki:TracIni#extra-permissions-section trac.ini]. For more information, please refer to the documentation of the component in the admin panel.
    101 
    102 == Granting Privileges ==
     99== Creating New Privileges
     100
     101To create custom permissions, for example to be used in a custom workflow, enable the optional [trac:ExtraPermissionsProvider tracopt.perm.config_perm_provider.ExtraPermissionsProvider] component in the "Plugins" admin panel, and add the desired permissions to the `[extra-permissions]` section in your [wiki:TracIni#extra-permissions-section trac.ini]. For more information, please refer to the documentation  on the [wiki:TracIni#extra-permissions-section TracIni] page after enabling the component.
     102
     103== Granting Privileges
    103104
    104105You grant privileges to users using [wiki:TracAdmin trac-admin]. The current set of privileges can be listed with the following command:
     
    122123}}}
    123124
    124 == Permission Groups ==
     125== Permission Groups
    125126
    126127There are two built-in groups, "authenticated" and "anonymous".
     
    144145Group membership can be checked by doing a {{{permission list}}} with no further arguments; the resulting output will include group memberships. '''Use at least one lowercase character in group names, as all-uppercase names are reserved for permissions'''.
    145146
    146 == Adding a New Group and Permissions ==
     147== Adding a New Group and Permissions
    147148Permission groups can be created by assigning a user to a group you wish to create, then assign permissions to that group.
    148149
     
    154155}}}
    155156
    156 == Removing Permissions ==
     157== Removing Permissions
    157158
    158159Permissions can be removed using the 'remove' command. For example:
     
    175176}}}
    176177
    177 == Default Permissions ==
     178== Default Permissions
    178179
    179180By default on a new Trac installation, the `anonymous` user will have ''view'' access to everything in Trac, but will not be able to create or modify anything.
  • wiki/pages/TracPlugins

    r26484 r37343  
    1 = Trac plugins =
    2 [[TracGuideToc]]
    3 
    4 From version 0.9 onwards, Trac is extensible with [trac:PluginList plugins]. Plugin functionality is based on the [trac:TracDev/ComponentArchitecture component architecture], with peculiarities described in the [TracDev/PluginDevelopment plugin development] page.
    5 
    6 == Plugin discovery ==
    7 
    8 From the user's point of view, a plugin is either a standalone .py file or an .egg package. Trac looks for plugins in the global shared plugins directory (see [TracIni#GlobalConfiguration Global Configuration]) and in the `plugins` directory of the local TracEnvironment. Components defined in globally-installed plugins should be explicitly enabled in the [[TracIni#components-section| [components] ]] section of the trac.ini file.
    9 
    10 == Requirements for Trac eggs ==
    11 
    12 To use egg-based plugins in Trac, you need to have [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (version 0.6) installed.
     1[[PageOutline(2-5,Contents,pullout)]]
     2
     3= Trac plugins
     4
     5Trac is extensible with [trac:PluginList plugins]. Plugin functionality is based on the [trac:TracDev/ComponentArchitecture component architecture], with special cases described in the [trac:TracDev/PluginDevelopment plugin development] page.
     6
     7== Plugin discovery
     8
     9From the user's point of view, a plugin is either a standalone .py file or an .egg package. Trac looks for plugins in Python's `site-packages` directory, the [TracIni#GlobalConfiguration global shared] `plugins` directory and the [TracEnvironment project environment] `plugins` directory. Components defined in globally-installed plugins must be explicitly enabled in the [[TracIni#components-section| [components] ]] section of the `trac.ini` file. Components defined in the `plugins` directory of the project environment are enabled, unless explicitly disabled in the `[components]` section of the `trac.ini` file.
     10
     11== Requirements for Trac eggs
     12
     13To use egg-based plugins in Trac, you need to have [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (version >= 0.6) installed.
    1314
    1415To install `setuptools`, download the bootstrap module [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py] and execute it as follows:
    1516
    16 {{{
     17{{{#!sh
    1718$ python ez_setup.py
    1819}}}
    1920
    20 If the `ez_setup.py` script fails to install the setuptools release, you can download it from [http://www.python.org/pypi/setuptools PyPI] and install it manually.
     21If the `ez_setup.py` script fails to install the setuptools release, you can download it from [pypi:setuptools PyPI] and install it manually.
    2122
    2223Plugins can also consist of a single `.py` file dropped directly into either the project's or the shared `plugins` directory.
    2324
    24 == Installing a Trac plugin ==
    25 
    26 === For a single project ===
     25== Installing a Trac plugin
     26
     27=== For a single project
    2728
    2829Plugins are typically packaged as [http://peak.telecommunity.com/DevCenter/PythonEggs Python eggs]. That means they are .zip archives with the file extension `.egg`.
     
    3233 * Unpack the source. It should provide `setup.py`.
    3334 * Run:
    34 
    35 {{{
     35 {{{#!sh
    3636$ python setup.py bdist_egg
    3737}}}
    3838
    39 You should have a *.egg file. Examine the output of running python to find where this was created.
    40 
    41 Once you have the plugin archive, copy it into the `plugins` directory of the [wiki:TracEnvironment project environment]. Also, make sure that the web server has sufficient permissions to read the plugin egg. Then restart the web server. If you are running as a [wiki:TracStandalone "tracd" standalone server], restart tracd (kill and run again).
     39You should now have an *.egg file. Examine the output of running Python to find where this was created.
     40
     41Once you have the plugin archive, copy it into the `plugins` directory of the [wiki:TracEnvironment project environment]. Also, make sure that the web server has sufficient permissions to read the plugin egg. Then restart the web server. If you are running as a [wiki:TracStandalone "tracd" standalone server], restart tracd, ie kill the process and run again.
    4242
    4343To uninstall a plugin installed this way, remove the egg from the `plugins` directory and restart the web server.
    4444
    45 Note: the Python version that the egg is built with ''must'' match the Python version with which Trac is run. For example, if you're running Trac under Python 2.5, but have upgraded your standalone Python to 2.6, the eggs won't be recognized.
    46 
    47 Note also: in a multi-project setup, a pool of Python interpreter instances will be dynamically allocated to projects based on need; since plugins occupy a place in Python's module system, the first version of any given plugin to be loaded will be used for all projects. In other words, you cannot use different versions of a single plugin in two projects of a multi-project setup. It may be safer to install plugins for all projects (see below), and then enable them selectively on a project-by-project basis.
    48 
    49 === For all projects ===
    50 
    51 ==== With an .egg file ====
    52 
    53 Some plugins (such as [trac:SpamFilter SpamFilter]) are downloadable as an `.egg` file that can be installed with the `easy_install` program:
    54 {{{
    55 easy_install TracSpamFilter
    56 }}}
    57 
    58 If `easy_install` is not on your system, see the Requirements section above to install it. Windows users will need to add the `Scripts` directory of their Python installation (for example, `C:\Python24\Scripts`) to their `PATH` environment variable (see [http://peak.telecommunity.com/DevCenter/EasyInstall#windows-notes easy_install Windows notes] for more information).
    59 
    60 If Trac reports permission errors after installing a zipped egg, and you would rather not bother providing a egg cache directory writable by the web server, you can get around it by simply unzipping the egg. Just pass `--always-unzip` to `easy_install`:
    61 {{{
    62 easy_install --always-unzip TracSpamFilter-0.4.1_r10106-py2.6.egg
    63 }}}
    64 You should end up with a directory having the same name as the zipped egg (complete with `.egg` extension) and containing its uncompressed contents.
    65 
    66 Trac also searches for plugins installed in the shared plugins directory ''(since 0.10)''; see TracIni#GlobalConfiguration. This is a convenient way to share the installation of plugins across several, but not all, environments.
    67 
    68 ==== From source ====
     45'''Note''': the Python version that the egg is built with ''must'' match the Python version with which Trac is run. For example, if you are running Trac under Python 2.6, but have upgraded your standalone Python to 2.7, the eggs won't be recognized.
     46
     47'''Note''': in a multi-project setup, a pool of Python interpreter instances will be dynamically allocated to projects based on need; since plugins occupy a place in Python's module system, the first version of any given plugin to be loaded will be used for all projects. In other words, you cannot use different versions of a single plugin in two projects of a multi-project setup. It may be safer to install plugins for all projects (see below), and then enable them selectively on a project-by-project basis.
     48
     49=== For all projects
     50
     51==== With an .egg file
     52
     53Some plugins, such as [trac:SpamFilter SpamFilter], are downloadable as an `.egg` file that can be installed with `easy_install` or `pip`:
     54{{{#!sh
     55$ easy_install TracSpamFilter
     56$ pip install TracSpamFilter
     57}}}
     58
     59If `easy_install` is not on your system, see the Requirements section above to install it. Windows users will need to add the `Scripts` directory of their Python installation (for example, `C:\Python27\Scripts`) to their `PATH` environment variable, or use the full path to `easy_install` (for example, `C:\Python27\Scripts\easy_install.py`). See [http://peak.telecommunity.com/DevCenter/EasyInstall#windows-notes easy_install Windows notes] for more information.
     60
     61`pip` is included in Python 2.7.9. In earlier versions of Python it can be installed through the package manager of your OS (e.g. `apt-get install python-pip`) or using the [https://pip.pypa.io/en/latest/installing.html#install-pip get_pip.py].
     62
     63If Trac reports permission errors after installing a zipped egg, and you would rather not bother providing an egg cache directory writable by the web server, you can get around it by simply unzipping the egg. Just pass `--always-unzip` to `easy_install`:
     64{{{#!sh
     65$ easy_install --always-unzip TracSpamFilter-0.4.1_r10106-py2.6.egg
     66}}}
     67You should end up with a directory having the same name as the zipped egg, complete with `.egg` extension, and containing its uncompressed contents.
     68
     69Trac also searches for plugins installed in the shared plugins directory, see TracIni#GlobalConfiguration. This is a convenient way to share the installation of plugins across several, but not all, environments.
     70
     71==== From source
    6972
    7073`easy_install` makes installing from source a snap. Just give it the URL to either a Subversion repository or a tarball/zip of the source:
    71 {{{
    72 easy_install http://svn.edgewall.com/repos/trac/plugins/0.12/spam-filter-captcha
    73 }}}
    74 
    75 ==== Enabling the plugin ====
    76 
    77 Unlike plugins installed per-environment, you'll have to explicitly enable globally installed plugins via [wiki:TracIni trac.ini]. This also applies to plugins installed in the shared plugins directory, i.e. the path specified in the `[inherit] plugins_dir` configuration option.
    78 
    79 This is done in the `[components]` section of the configuration file. For example:
    80 {{{
     74{{{#!sh
     75$ easy_install http://svn.edgewall.com/repos/trac/plugins/0.12/spam-filter-captcha
     76}}}
     77
     78==== Enabling the plugin
     79
     80Unlike plugins installed per environment, you'll have to explicitly enable globally installed plugins via [wiki:TracIni trac.ini]. This also applies to plugins installed in the shared plugins directory, ie the path specified in the `[inherit] plugins_dir` configuration option.
     81
     82This is done in the `[components]` section of the configuration file `trac.ini`. For example:
     83{{{#!ini
    8184[components]
    8285tracspamfilter.* = enabled
    8386}}}
    8487
    85 The name of the option is the Python package of the plugin. This should be specified in the documentation of the plugin, but can also be easily discovered by looking at the source (look for a top-level directory that contains a file named `__init__.py`).
    86 
    87 Note: After installing the plugin, you must restart your web server.
    88 
    89 ==== Uninstalling ====
    90 
    91 `easy_install` or `python setup.py` does not have an uninstall feature. Hower, it is usually quite trivial to remove a globally-installed egg and reference:
     88The name of the option is the Python package of the plugin. This should be specified in the documentation of the plugin, but can also be easily discovered by looking at the source: look for a top-level directory that contains a file named `__init__.py`.
     89
     90After installing the plugin, you must restart your web server.
     91
     92==== Uninstalling
     93
     94Neither `easy_install` nor `python setup.py` have an uninstall feature. However, it is usually trivial to remove a globally installed egg and reference:
    9295
    9396 1. Do `easy_install -m [plugin name]` to remove references from `$PYTHONLIB/site-packages/easy-install.pth` when the plugin installed by setuptools.
    9497 1. Delete executables from `/usr/bin`, `/usr/local/bin`, or `C:\\Python*\Scripts`. To find what executables are involved, refer to the `[console-script]` section of `setup.py`.
    95  1. Delete the .egg file or folder from where it's installed (usually inside `$PYTHONLIB/site-packages/`).
     98 1. Delete the .egg file or folder from where it's installed, usually inside `$PYTHONLIB/site-packages/`.
    9699 1. Restart the web server.
    97100
    98 If you are uncertain about the location of the egg, here's a small tip to help locate an egg (or any package). Just replace `myplugin` with whatever namespace the plugin uses (as used when enabling the plugin):
    99 {{{
     101If you are uncertain about the location of the egg file, you can try to locate it by replacing `myplugin` with whatever namespace the plugin uses (as used when enabling the plugin):
     102{{{#!pycon
    100103>>> import myplugin
    101104>>> print myplugin.__file__
     
    103106}}}
    104107
    105 == Setting up the plugin cache ==
    106 
    107 Some plugins will need to be extracted by the Python eggs runtime (`pkg_resources`), so that their contents are actual files on the file system. The directory in which they are extracted defaults to `.python-eggs` in the home directory of the current user, which may or may not be a problem. You can, however, override the default location using the `PYTHON_EGG_CACHE` environment variable.
     108== Setting up the plugin cache
     109
     110Some plugins will need to be extracted by the Python egg's runtime (`pkg_resources`), so that their contents are actual files on the file system. The directory in which they are extracted defaults to `.python-eggs` in the home directory of the current user, which may or may not be a problem. You can, however, override the default location using the `PYTHON_EGG_CACHE` environment variable.
    108111
    109112To do this from the Apache configuration, use the `SetEnv` directive:
    110 {{{
     113{{{#!apache
    111114SetEnv PYTHON_EGG_CACHE /path/to/dir
    112115}}}
    113116
    114 This works whether you're using the [wiki:TracCgi CGI] or the [wiki:TracModPython mod_python] front-end. Put this directive next to where you set the path to the [wiki:TracEnvironment Trac environment], i.e. in the same `<Location>` block.
    115 
    116 For example (for CGI):
    117 {{{
     117This works whether you're using the [wiki:TracCgi CGI] or the [wiki:TracModPython mod_python] front-end. Put this directive next to where you set the path to the [wiki:TracEnvironment Trac environment], ie in the same `<Location>` block.
     118
     119For example for CGI:
     120{{{#!apache
    118121 <Location /trac>
    119122   SetEnv TRAC_ENV /path/to/projenv
     
    122125}}}
    123126
    124 Or (for mod_python):
    125 {{{
     127Or for mod_python:
     128{{{#!apache
    126129 <Location /trac>
    127130   SetHandler mod_python
     
    131134}}}
    132135
    133  ''Note: !SetEnv requires the `mod_env` module which needs to be activated for Apache. In this case the !SetEnv directive can also be used in the `mod_python` Location block.''
     136'''Note''': !SetEnv requires the `mod_env` module, which needs to be activated for Apache. In this case the !SetEnv directive can also be used in the `mod_python` Location block.
    134137
    135138For [wiki:TracFastCgi FastCGI], you'll need to `-initial-env` option, or whatever is provided by your web server for setting environment variables.
    136139
    137  ''Note: that if you already use -initial-env to set the project directory for either a single project or parent you will need to add an additional -initial-env directive to the !FastCgiConfig directive. I.e.
    138 
    139 {{{
     140'''Note''': if you already use -initial-env to set the project directory for either a single project or parent, you will need to add an additional -initial-env directive to the !FastCgiConfig directive:
     141
     142{{{#!apache
    140143FastCgiConfig -initial-env TRAC_ENV=/var/lib/trac -initial-env PYTHON_EGG_CACHE=/var/lib/trac/plugin-cache
    141144}}}
    142145
    143 === About hook scripts ===
    144 
    145 If you've set up some subversion hook scripts that call the Trac engine, such as the post-commit hook script provided in the `/contrib` directory, make sure you define the `PYTHON_EGG_CACHE` environment variable within these scripts as well.
    146 
    147 == Troubleshooting ==
    148 
    149 === Is setuptools properly installed? ===
    150 
    151 Try this from the command line:
    152 {{{
    153 $ python -c "import pkg_resources"
    154 }}}
    155 
    156 If you get '''no output''', setuptools '''is''' installed. Otherwise, you'll need to install it before plugins will work in Trac.
    157 
    158 === Did you get the correct version of the Python egg? ===
    159 
    160 Python eggs have the Python version encoded in their filename. For example, `MyPlugin-1.0-py2.5.egg` is an egg for Python 2.5, and will '''not''' be loaded if you're running a different Python version (such as 2.4 or 2.6).
    161 
    162 Also, verify that the egg file you downloaded is indeed a .zip archive. If you downloaded it from a Trac site, chances are you downloaded the HTML preview page instead.
    163 
    164 === Is the plugin enabled? ===
    165 
    166 If you install a plugin globally (i.e., ''not'' inside the `plugins` directory of the Trac project environment), you must explicitly enable it in [TracIni trac.ini]. Make sure that:
    167 
    168  * ...you actually added the necessary line(s) to the `[components]` section.
    169  * ...the package/module names are correct.
    170  * ...the value is "enabled", not "enable" or "Enable".
    171 
    172 === Check the permissions on the .egg file ===
    173 
    174 Trac must be able to read the .egg file.
    175 
    176 === Check the log files ===
    177 
    178 Enable [wiki:TracLogging logging] and set the log level to `DEBUG`, then watch the log file for messages about loading plugins.
    179 
    180 === Verify you have proper permissions ===
    181 
    182 Some plugins require you have special permissions in order to use them. [trac:WebAdmin WebAdmin], for example, requires the user to have TRAC_ADMIN permissions for it to show up on the navigation bar.
    183 
    184 === Is the wrong version of the plugin loading? ===
    185 
    186 If you put your plugins inside plugins directories, and certainly if you have more than one project, you need to make sure that the correct version of the plugin is loading. Here are some basic rules:
    187 
    188  * Only one version of the plugin can be loaded for each running Trac server (i.e., each Python process). The Python namespaces and module list will be shared, and it cannot handle duplicates. Whether a plugin is `enabled` or `disabled` makes no difference.
    189  * A globally-installed plugin (typically `setup.py install`) will override any version in the global or project plugins directories. A plugin from the global plugins directory will be located ''before'' any project plugins directory.
    190  * If your Trac server hosts more than one project (as with `TRAC_ENV_PARENT_DIR` setups), having two versions of a plugin in two different projects will give uncertain results. Only one of them will load, and the one loaded will be shared by both projects. Trac will load the first plugin found, usually from the project that receives the first request.
    191  * Having more than one version listed inside Python site-packages is fine (i.e., installed with `setup.py install`) -- setuptools will make sure you get the version installed most recently. However, don't store more than one version inside a global or project plugins directory -- neither version number nor installed date will matter at all. There is no way to determine which one will be located first when Trac searches the directory for plugins.
    192 
    193 === If all of the above failed ===
    194 
    195 Okay, so the logs don't mention plugins, the egg is readable, the Python version is correct, ''and'' the egg has been installed globally (and is enabled in trac.ini)... and it ''still'' doesn't work or give any error messages or any other indication as to why. Hop on the [trac:IrcChannel IrcChannel] and ask away!
    196 
    197 == Web-based plugin administration ==
    198 
    199 The WebAdmin plugin (part of the core since 0.11) offers limited support for plugin configuration through the web to users with `TRAC_ADMIN` permission:
     146=== About hook scripts
     147
     148If you have set up some Subversion hook scripts that call the Trac engine, such as the post-commit hook script provided in the `/contrib` directory, make sure you define the `PYTHON_EGG_CACHE` environment variable within these scripts as well.
     149
     150== Web-based plugin administration
     151
     152The [trac:WebAdmin] interface offers limited support for plugin configuration through the web to users with `TRAC_ADMIN` permission:
    200153
    201154* en/disabling installed plugins
    202155* installing plugins by uploading them as eggs
    203156
    204 You probably want to disable the second function for security reasons: in `trac.ini`, in the `[components]` section, add the line
    205 {{{
     157If you wish to disable the second function for security reasons, add the following to your `trac.ini` file:
     158{{{#!ini
     159[components]
    206160trac.admin.web_ui.PluginAdminPanel = disabled
    207161}}}
    208162This disables the whole panel, so the first function will no longer be available either.
     163
     164== Troubleshooting
     165
     166=== Is setuptools properly installed?
     167
     168Try this from the command line:
     169{{{#!sh
     170$ python -c "import pkg_resources"
     171}}}
     172
     173If you get '''no output''', setuptools '''is''' installed. Otherwise, you'll need to install it before plugins will work in Trac.
     174
     175=== Did you get the correct version of the Python egg?
     176
     177Python eggs have the Python version encoded in their filename. For example, `MyPlugin-1.0-py2.5.egg` is an egg for Python 2.5, and will '''not''' be loaded if you're running a different Python version (such as 2.4 or 2.6).
     178
     179Also, verify that the egg file you downloaded is indeed a .zip archive. If you downloaded it from a Trac site, chances are you downloaded the HTML preview page instead.
     180
     181=== Is the plugin enabled?
     182
     183If you install a plugin globally, ie ''not'' inside the `plugins` directory of the Trac project environment, you must explicitly enable it in [TracIni trac.ini]. Make sure that:
     184
     185 * you actually added the necessary line(s) to the `[components]` section.
     186 * the package/module names are correct and do not contain typos.
     187 * the value is "enabled", not "enable" or "Enable".
     188 * the section name is "components", not "component".
     189
     190=== Check the permissions on the .egg file
     191
     192Trac must be able to read the .egg file.
     193
     194=== Check the log files
     195
     196Enable [wiki:TracLogging logging] and set the log level to `DEBUG`, then watch the log file for messages about loading plugins.
     197
     198=== Verify you have the proper permissions
     199
     200Some plugins require you have special permissions in order to use them. [trac:WebAdmin WebAdmin], for example, requires the user to have `TRAC_ADMIN` permissions for it to show up on the navigation bar.
     201
     202=== Is the wrong version of the plugin loading?
     203
     204If you put your plugins inside plugins directories, and certainly if you have more than one project, you need to make sure that the correct version of the plugin is loading. Here are some basic rules:
     205
     206 * Only one version of the plugin can be loaded for each running Trac server, ie each Python process. The Python namespaces and module list will be shared, and it cannot handle duplicates. Whether a plugin is `enabled` or `disabled` makes no difference.
     207 * A globally installed plugin (typically `setup.py install`) will override any version in the global or project plugins directories. A plugin from the global plugins directory will be located ''before'' any project plugins directory.
     208 * If your Trac server hosts more than one project (as with `TRAC_ENV_PARENT_DIR` setups), having two versions of a plugin in two different projects will give unpredicatable results. Only one of them will load, and the one loaded will be shared by both projects. Trac will load the first plugin found, usually from the project that receives the first request.
     209 * Having more than one version listed inside Python site-packages is fine, ie installed with `setup.py install`, because setuptools will make sure you get the version installed most recently. However, don't store more than one version inside a global or project plugins directory: neither the version number nor the installed date will matter at all. There is no way to determine which one will be located first when Trac searches the directory for plugins.
     210
     211=== If all of the above failed
     212
     213Okay, so the logs don't mention plugins, the egg is readable, the Python version is correct, ''and'' the egg has been installed globally (and is enabled in trac.ini)... and it ''still'' doesn't work or give any error messages or any other indication as to why. Hop on the [trac:IrcChannel IrcChannel] and ask away!
    209214
    210215----
  • wiki/pages/TracQuery

    r26484 r37343  
    1 = Trac Ticket Queries =
     1= Trac Ticket Queries
    22[[TracGuideToc]]
    33
    4 In addition to [wiki:TracReports reports], Trac provides support for ''custom ticket queries'', used to display lists of tickets meeting a specified set of criteria.
     4In addition to [wiki:TracReports reports], Trac provides support for ''custom ticket queries'', which can be used to display tickets that meet specified criteria.
    55
    66To configure and execute a custom query, switch to the ''View Tickets'' module from the navigation bar, and select the ''Custom Query'' link.
    77
    8 == Filters ==
     8== Filters
    99
    10 When you first go to the query page the default filter will display tickets relevant to you:
    11  * If logged in then all open tickets it will display open tickets assigned to you.
    12  * If not logged in but you have specified a name or email address in the preferences then it will display all open tickets where your email (or name if email not defined) is in the CC list.
    13  * If not logged and no name/email defined in the preferences then all open issues are displayed.
     10When you first go to the query page, the default filter will display tickets relevant to you:
     11 * If logged in then all open tickets, it will display open tickets assigned to you.
     12 * If not logged in but you have specified a name or email address in the preferences, then it will display all open tickets where your email (or name if email not defined) is in the CC list.
     13 * If not logged in and no name/email is defined in the preferences, then all open issues are displayed.
    1414
    15 Current filters can be removed by clicking the button to the left with the minus sign on the label.  New filters are added from the pulldown lists at the bottom corners of the filters box ('And' conditions on the left, 'Or' conditions on the right).  Filters with either a text box or a pulldown menu of options can be added multiple times to perform an ''or'' of the criteria.
     15Current filters can be removed by clicking the button to the left with the minus sign on the label. New filters are added from the pulldown lists at the bottom corners of the filters box; 'And' conditions on the left, 'Or' conditions on the right.  Filters with either a text box or a pulldown menu of options can be added multiple times to perform an ''Or'' on the criteria.
    1616
    1717You can use the fields just below the filters box to group the results based on a field, or display the full description for each ticket.
    1818
    19 Once you've edited your filters click the ''Update'' button to refresh your results.
     19After you have edited your filters, click the ''Update'' button to refresh your results.
    2020
    21 == Navigating Tickets ==
    22 Clicking on one of the query results will take you to that ticket.  You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' links just below the main menu bar, or click the ''Back to Query'' link to return to the query page. 
     21== Navigating Tickets
    2322
    24 You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Query'' links after saving your results.  When you return to the query ''any tickets which were edited'' will be displayed with italicized text.  If one of the tickets was edited such that [[html(<span style="color: grey">it no longer matches the query criteria </span>)]] the text will also be greyed. Lastly, if '''a new ticket matching the query criteria has been created''', it will be shown in bold.
     23Clicking on one of the query results will take you to that ticket. You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' links just below the main menu bar, or click the ''Back to Query'' link to return to the query page. 
     24
     25You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Query'' links after saving your results. When you return to the query ''any tickets which were edited'' will be displayed with italicized text. If one of the tickets was edited such that [[html(<span style="color: grey">it no longer matches the query criteria </span>)]], the text will also be greyed. Lastly, if '''a new ticket matching the query criteria has been created''', it will be shown in bold.
    2526
    2627The query results can be refreshed and cleared of these status indicators by clicking the ''Update'' button again.
    2728
    28 == Saving Queries ==
     29== Saving Queries
    2930
    3031Trac allows you to save the query as a named query accessible from the reports module. To save a query ensure that you have ''Updated'' the view and then click the ''Save query'' button displayed beneath the results.
    3132You can also save references to queries in Wiki content, as described below.
    3233
    33 ''Note:'' one way to easily build queries like the ones below, you can build and test the queries in the Custom report module and when ready - click ''Save query''. This will build the query string for you. All you need to do is remove the extra line breaks.
     34'''Note:''' one way to easily build queries like the ones below, you can build and test the queries in the Custom report module and when ready - click ''Save query''. This will build the query string for you. All you need to do is remove the extra line breaks.
    3435
    35 ''Note:'' you must have the '''REPORT_CREATE''' permission in order to save queries to the list of default reports. The ''Save query'' button will only appear if you are logged in as a user that has been granted this permission. If your account does not have permission to create reports, you can still use the methods below to save a query.
     36'''Note:''' you must have the '''REPORT_CREATE''' permission in order to save queries to the list of default reports. The ''Save query'' button will only appear if you are logged in as a user that has been granted this permission. If your account does not have permission to create reports, you can still use the methods below to save a query.
    3637
     38=== Using TracLinks
    3739
    38 === Using TracLinks ===
    39 
    40 You may want to save some queries so that you can come back to them later.  You can do this by making a link to the query from any Wiki page.
     40You may want to save some queries so that you can come back to them later. You can do this by making a link to the query from any Wiki page.
    4141{{{
    4242[query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0]
     
    4646  [query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0]
    4747
    48 This uses a very simple query language to specify the criteria (see [wiki:TracQuery#QueryLanguage Query Language]).
     48This uses a very simple query language to specify the criteria, see [wiki:TracQuery#QueryLanguage Query Language].
    4949
    5050Alternatively, you can copy the query string of a query and paste that into the Wiki link, including the leading `?` character:
     
    5656  [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]
    5757
    58 === Using the `[[TicketQuery]]` Macro ===
     58=== Customizing the ''table'' format
    5959
    60 The [trac:TicketQuery TicketQuery] macro lets you display lists of tickets matching certain criteria anywhere you can use WikiFormatting.
    61 
    62 Example:
    63 {{{
    64 [[TicketQuery(version=0.6|0.7&resolution=duplicate)]]
    65 }}}
    66 
    67 This is displayed as:
    68   [[TicketQuery(version=0.6|0.7&resolution=duplicate)]]
    69 
    70 Just like the [wiki:TracQuery#UsingTracLinks query: wiki links], the parameter of this macro expects a query string formatted according to the rules of the simple [wiki:TracQuery#QueryLanguage ticket query language]. This also allows displaying the link and description of a single ticket:
    71 {{{
    72 [[TicketQuery(id=123)]]
    73 }}}
    74 
    75 This is displayed as:
    76   [[TicketQuery(id=123)]]
    77 
    78 A more compact representation without the ticket summaries is also available:
    79 {{{
    80 [[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]]
    81 }}}
    82 
    83 This is displayed as:
    84   [[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]]
    85 
    86 Finally, if you wish to receive only the number of defects that match the query, use the ``count`` parameter.
    87 
    88 {{{
    89 [[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]]
    90 }}}
    91 
    92 This is displayed as:
    93   [[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]]
    94 
    95 === Customizing the ''table'' format ===
    96 You can also customize the columns displayed in the table format (''format=table'') by using ''col=<field>'' - you can specify multiple fields and what order they are displayed by placing pipes (`|`) between the columns like below:
    97 
     60You can also customize the columns displayed in the table format (''format=table'') by using ''col=<field>''. You can specify multiple fields and what order they are displayed in by placing pipes (`|`) between the columns:
    9861{{{
    9962[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]]
     
    10366[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]]
    10467
    105 ==== Full rows ====
    106 In ''table'' format you can also have full rows by using ''rows=<field>'' like below:
     68==== Full rows
    10769
     70In ''table'' format you can also have full rows by using ''rows=<field>'':
    10871{{{
    10972[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]]
     
    11376[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]]
    11477
     78== Query Language
    11579
    116 === Query Language ===
    117 
    118 `query:` TracLinks and the `[[TicketQuery]]` macro both use a mini “query language” for specifying query filters. Basically, the filters are separated by ampersands (`&`). Each filter then consists of the ticket field name, an operator, and one or more values. More than one value are separated by a pipe (`|`), meaning that the filter matches any of the values. To include a literal `&` or `|` in a value, escape the character with a backslash (`\`).
     80`query:` TracLinks and the `[[TicketQuery]]` macro both use a mini “query language” for specifying query filters. Filters are separated by ampersands (`&`). Each filter consists of the ticket field name, an operator and one or more values. More than one value are separated by a pipe (`|`), meaning that the filter matches any of the values. To include a literal `&` or `|` in a value, escape the character with a backslash (`\`).
    11981
    12082The available operators are:
     
    13092|| '''`!$=`''' || the field content does not end with any of the values ||
    13193
    132 The date fields `created` and `modified` can be constrained by using the `=` operator and specifying a value containing two dates separated by two dots (`..`). Either end of the date range can be left empty, meaning that the corresponding end of the range is open. The date parser understands a few natural date specifications like "3 weeks ago", "last month" and "now", as well as Bugzilla-style date specifications like "1d", "2w", "3m" or "4y" for 1 day, 2 weeks, 3 months and 4 years, respectively. Spaces in date specifications can be left out to avoid having to quote the query string.
     94The date fields `created` and `modified` can be constrained by using the `=` operator and specifying a value containing two dates separated by two dots (`..`). Either end of the date range can be left empty, meaning that the corresponding end of the range is open. The date parser understands a few natural date specifications like "3 weeks ago", "last month" and "now", as well as Bugzilla-style date specifications like "1d", "2w", "3m" or "4y" for 1 day, 2 weeks, 3 months and 4 years, respectively. Spaces in date specifications can be omitted to avoid having to quote the query string.
    13395|| '''`created=2007-01-01..2008-01-01`''' || query tickets created in 2007 ||
    13496|| '''`created=lastmonth..thismonth`''' || query tickets created during the previous month ||
     
    13799
    138100----
    139 See also: TracTickets, TracReports, TracGuide
     101See also: TracTickets, TracReports, TracGuide, TicketQuery
  • wiki/pages/TracReports

    r26484 r37343  
    3030
    3131== Changing Report Numbering ==
    32 There may be instances where you need to change the ID of the report, perhaps to organize the reports better. At present this requires changes to the trac database. The ''report'' table has the following schema ''(since 0.10)'':
     32There may be instances where you need to change the ID of the report, perhaps to organize the reports better. At present this requires changes to the trac database. The ''report'' table has the following schema:
    3333 * id integer PRIMARY KEY
    3434 * author text
     
    4747Clicking on one of the report results will take you to that ticket. You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' links just below the main menu bar, or click the ''Back to Report'' link to return to the report page.
    4848
    49 You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Report'' links after saving your results, but when you return to the report, there will be no hint about what has changed, as would happen if you were navigating a list of tickets obtained from a query (see TracQuery#NavigatingTickets). ''(since 0.11)''
     49You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Report'' links after saving your results, but when you return to the report, there will be no hint about what has changed, as would happen if you were navigating a list of tickets obtained from a query (see TracQuery#NavigatingTickets).
    5050
    5151== Alternative Download Formats ==
     
    109109}}}
    110110
     111Dynamic variables can also be used in the report title and description (since 1.1.1).
    111112
    112113== Advanced Reports: Dynamic Variables ==
     
    136137}}}
    137138
    138 Dynamic variables can also be used in the report title and description (since 1.1.1).
    139139
    140140=== !Special/Constant Variables ===
     
    164164 * '''id''' — same as '''ticket''' above when '''realm''' is not set
    165165 * '''realm''' — together with '''id''', can be used to create links to other resources than tickets (e.g. a realm of ''wiki'' and an ''id'' to a page name will create a link to that wiki page)
     166   - for some kind of resources, it may be necessary to specify their ''parent'' resources (e.g. for ''changeset'', which ''repos'') and this can be achieved using the '''parent_realm''' and '''parent_id''' columns
    166167 * '''created, modified, date, time''' — Format cell as a date and/or time.
    167168 * '''description''' — Ticket description field, parsed through the wiki engine.
     
    245246=== Reporting on custom fields ===
    246247
    247 If you have added custom fields to your tickets (a feature since v0.8, see TracTicketsCustomFields), you can write a SQL query to cover them. You'll need to make a join on the ticket_custom table, but this isn't especially easy.
     248If you have added custom fields to your tickets (see TracTicketsCustomFields), you can write a SQL query to cover them. You'll need to make a join on the ticket_custom table, but this isn't especially easy.
    248249
    249250If you have tickets in the database ''before'' you declare the extra fields in trac.ini, there will be no associated data in the ticket_custom table. To get around this, use SQL's "LEFT OUTER JOIN" clauses. See [trac:TracIniReportCustomFieldSample TracIniReportCustomFieldSample] for some examples.
  • wiki/pages/TracRepositoryAdmin

    r26484 r37343  
    1 = Repository Administration =
     1= Repository Administration
    22[[PageOutline(2-3)]]
    33
    4 == Quick start == #QuickStart
    5 
    6  * Manage repositories in the "Repository" admin panel, with `trac-admin` or in the `[repositories]` section of [wiki:TracIni#repositories-section trac.ini].
     4== Quick start #QuickStart
     5
     6 * Enable the repository connector(s) for the version control system(s) that you will use.
     7 * Add repositories through the //Repositories// admin panel, with `trac-admin` or in the `[repositories]` section of [wiki:TracIni#repositories-section trac.ini].
    78 * Set up a call to `trac-admin $ENV changeset added $REPO $REV` in the post-commit hook of each repository. Additionally, add a call to `trac-admin $ENV changeset modified $REPO $REV` in the post-revprop-change hook of repositories allowing revision property changes.
    8  * Set the `[trac] repository_sync_per_request` option to an empty value to disable per-request syncing.
    9  * Make sure the user under which your Subversion hooks are run has write access to the Trac environment, or use a tool like `sudo` to temporarily elevate privileges.
    10 
    11 == Specifying repositories == #Repositories
    12 Starting with 0.12, Trac can handle more than one repository per environment. The pre-0.12 way of specifying the repository with the `repository_dir` and `repository_type` options in the `[trac]` section of [wiki:TracIni trac.ini] is still supported, but two new mechanisms allow including additional repositories into an environment.
    13 
    14 It is also possible to define aliases of repositories, that act as "pointers" to real repositories. This can be useful when renaming a repository, to avoid breaking all the links to the old name.
    15 
    16 A number of attributes can be associated with each repository, which define the repository's location, type, name and how it is displayed in the source browser. The following attributes are supported:
     9 * Make sure the user under which your hooks are run has write access to the Trac environment, or use a tool like `sudo` to temporarily elevate privileges.
     10
     11== Enabling the components
     12
     13Support for version control systems is provided by optional components distributed with Trac, which are disabled by default //(since 1.0)//. Subversion and Git must be explicitly enabled if you wish to use them.
     14
     15The version control systems can be enabled by adding the following to the `[components]` section of your [TracIni#components-section trac.ini], or enabling the components in the //Plugins// admin panel.
     16
     17{{{#!ini
     18tracopt.versioncontrol.svn.* = enabled
     19}}}
     20
     21{{{#!ini
     22tracopt.versioncontrol.git.* = enabled
     23}}}
     24
     25== Specifying repositories #Repositories
     26Trac supports multiple repositories per environment, and the repositories may be for different version control system types. Each repository must be defined in a repository configuration provider, the two supported by default are the [#ReposDatabase database store] and the [#ReposTracIni trac.ini configuration file]. A repository should not be defined in multiple configuration providers.
     27
     28It is possible to define aliases of repositories, that act as "pointers" to real repositories. This can be useful when renaming a repository, to avoid breaking links to the old name.
     29
     30A number of attributes can be associated with each repository. The attributes define the repository's location, type, name and how it is displayed in the source browser. The following attributes are supported:
    1731
    1832||='''Attribute''' =||='''Description''' =||
     
    2438||The `dir` attribute specifies the location of the repository in the filesystem. It corresponds to the value previously specified in the option `[trac] repository_dir`. The `alias` and `dir` attributes are mutually exclusive. ||
    2539||`hidden` ||When set to `true`, the repository is hidden from the repository index page in the source browser. Browsing the repository is still possible, and links referencing the repository remain valid. ||
     40||`sync_per_request`||When set to `true` the repository will be synced on every request. This is not recommended, instead a post-commit hook should be configured to provide [#ExplicitSync explicit synchronization] and `sync_per_request` should be set to `false`.||
    2641||`type` ||The `type` attribute sets the type of version control system used by the repository. Trac supports Subversion and Git out-of-the-box, and plugins add support for many other systems. If `type` is not specified, it defaults to the value of the `[trac] repository_type` option. ||
    2742||`url` ||The `url` attribute specifies the root URL to be used for checking out from the repository. When specified, a "Repository URL" link is added to the context navigation links in the source browser, that can be copied into the tool used for creating the working copy. ||
     
    2944A repository `name` and one of `alias` or `dir` attributes are mandatory. All others are optional.
    3045
     46For some version control systems, it is possible to specify not only the path to the repository in the `dir` attribute, but also a ''scope'' within the repository. Trac will then only show information related to the files and changesets below that scope. The Subversion backend for Trac supports this. For other types, check the corresponding plugin's documentation.
     47
    3148After adding a repository, the cache for that repository must be re-synchronized once with the `trac-admin $ENV repository resync` command.
    3249
     
    3552
    3653
    37 === In `trac.ini` === #ReposTracIni
     54=== In `trac.ini` #ReposTracIni
    3855Repositories and repository attributes can be specified in the `[repositories]` section of [wiki:TracIni#repositories-section trac.ini]. Every attribute consists of a key structured as `{name}.{attribute}` and the corresponding value separated with an equal sign (`=`). The name of the default repository is empty.
    3956
     
    4158
    4259The following example defines two Subversion repositories named `project` and `lib`, and an alias to `project` as the default repository. This is a typical use case where a Trac environment previously had a single repository (the `project` repository), and was converted to multiple repositories. The alias ensures that links predating the change continue to resolve to the `project` repository.
    43 {{{
    44 #!ini
     60{{{#!ini
    4561[repositories]
    4662project.dir = /var/repos/project
     
    5975Note that `name.alias = target` makes `name` an alias for the `target` repo, not the other way around.
    6076
    61 === In the database === #ReposDatabase
     77=== In the database #ReposDatabase
    6278Repositories can also be specified in the database, using either the "Repositories" admin panel under "Version Control", or the `trac-admin $ENV repository` commands.
    6379
     
    8096Note that the default repository has an empty name, so it will likely need to be quoted when running `trac-admin` from a shell. Alternatively, the name "`(default)`" can be used instead, for example when running `trac-admin` in interactive mode.
    8197
    82 
    83 == Repository synchronization == #Synchronization
     98== Repository caching
     99
     100The Subversion and Git repository connectors support caching, which improves the performance browsing the repository, viewing logs and viewing changesets. Cached repositories must be [#Synchronization synchronized]; either explicit or implicit synchronization can be used. When searching changesets, only cached repositories are searched.
     101
     102Subversion repositories are cached unless the type is `direct-svnfs`. Git repositories are cached when `[git]` [wiki:TracIni#git-section cached_repository] is `true`.
     103
     104== Repository synchronization #Synchronization
    84105Prior to 0.12, Trac synchronized its cache with the repository on every HTTP request. This approach is not very efficient and not practical anymore with multiple repositories. For this reason, explicit synchronization through post-commit hooks was added.
    85106
    86107There is also new functionality in the form of a repository listener extension point ''(IRepositoryChangeListener)'' that is triggered by the post-commit hook when a changeset is added or modified, and can be used by plugins to perform actions on commit.
    87108
    88 === Mercurial Repositories ===
     109=== Mercurial Repositories
    89110Please note that at the time of writing, no initial resynchronization or any hooks are necessary for Mercurial repositories - see [trac:#9485] for more information.
    90111
    91 === Explicit synchronization === #ExplicitSync
    92 This is the preferred method of repository synchronization. It requires setting the `[trac]  repository_sync_per_request` option in [wiki:TracIni#trac-section trac.ini] to an empty value, and adding a call to `trac-admin` in the post-commit hook of each repository. Additionally, if a repository allows changing revision metadata, a call to `trac-admin` must be added to the post-revprop-change hook as well.
     112=== Explicit synchronization #ExplicitSync
     113This is the preferred method of repository synchronization. It requires setting the `sync_per_request` attribute to `false`, and adding a call to `trac-admin` in the `post-commit` hook of each repository. Additionally, if a repository allows changing revision metadata, a call to `trac-admin` must be added to the `post-revprop-change` hook as well.
    93114
    94115 `changeset added <repos> <rev> [...]`::
     
    100121The `<repos>` argument can be either a repository name (use "`(default)`" for the default repository) or the path to the repository.
    101122
    102 Note that you may have to set the environment variable PYTHON_EGG_CACHE to the same value as was used for the web server configuration before calling trac-admin, if you changed it from its default location. See [wiki:TracPlugins Trac Plugins] for more information.
     123Note that you may have to set the environment variable `PYTHON_EGG_CACHE` to the same value as was used for the web server configuration before calling `trac-admin`, if you changed it from its default location. See [wiki:TracPlugins Trac Plugins] for more information.
     124
     125==== Subversion
    103126
    104127The following examples are complete post-commit and post-revprop-change scripts for Subversion. They should be edited for the specific environment, marked executable (where applicable) and placed in the `hooks` directory of each repository. On Unix (`post-commit`):
     
    108131/usr/bin/trac-admin /path/to/env changeset added "$1" "$2"
    109132}}}
    110 Note: Ubuntu doesn't seem to like /usr/bin/trac-admin, so just use:
    111 {{{#!sh
    112 #!/bin/sh
    113 export PYTHON_EGG_CACHE="/path/to/dir"
    114 trac-admin /path/to/env/ changeset added "$1" "$2"
    115 }}}
     133Note: Check with `whereis trac-admin`, whether `trac-admin` is really installed under `/usr/bin/` or maybe under `/usr/local/bin/` and adapt the path.
    116134On Windows (`post-commit.cmd`):
    117 {{{#!application/x-dos-batch
     135{{{#!bat
    118136@C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset added "%1" "%2"
    119137}}}
     
    126144}}}
    127145On Windows (`post-revprop-change.cmd`):
    128 {{{#!application/x-dos-batch
     146{{{#!bat
    129147@C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset modified "%1" "%2"
    130148}}}
     
    136154See the [http://svnbook.red-bean.com/en/1.5/svn.reposadmin.create.html#svn.reposadmin.create.hooks section about hooks] in the Subversion book for more information. Other repository types will require different hook setups.
    137155