Changeset 40534 for wiki


Ignore:
Timestamp:
06/15/17 06:03:07 (6 years ago)
Author:
aafsvn
Message:

[titan] autoupdate wiki files

Location:
wiki/pages
Files:
19 edited

Legend:

Unmodified
Added
Removed

  • wiki/pages/TracInterfaceCustomization

    r40226 r40534  
    1 = Customizing the Trac Interface
    2 [[TracGuideToc]]
    3 [[PageOutline]]
    4 
    5 == Introduction
    6 This 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.
    7 
    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].
    10 
    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''.
    12 
    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.
    14 
    15 Now configure the appropriate section of your [wiki:TracIni trac.ini]:
    16 
    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 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'.
    19 
    20 {{{#!ini
    21 [header_logo]
    22 src = site/my_logo.gif
    23 alt = My Project
    24 width = 300
    25 height = 100
    26 }}}
    27 
    28 === Icon
    29 Icons 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:
    30 
    31 {{{#!ini
    32 [project]
    33 icon = site/my_icon.ico
    34 }}}
    35 
    36 == Custom Navigation Entries
    37 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.
    38 
    39 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:
    40 {{{#!ini
    41 [mainnav]
    42 wiki.label = Home
    43 tickets.href = /report/24
    44 
    45 [metanav]
    46 help = disabled
    47 }}}
    48 
    49 See also TracNavigation for a more detailed explanation of the mainnav and metanav terms.
    50 
    51 == Site Appearance == #SiteAppearance
    52 
    53 Trac 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`:
    54 
    55 {{{#!xml
    56 <html xmlns="http://www.w3.org/1999/xhtml"
    57       xmlns:py="http://genshi.edgewall.org/"
    58       py:strip="">
    59 
    60   <!--! Add site-specific style sheet -->
    61   <head py:match="head" py:attrs="select('@*')">
    62     ${select('*|comment()|text()')}
    63     <link rel="stylesheet" href="${href.chrome('site/style.css')}" />
    64   </head>
    65 
    66   <body py:match="body" py:attrs="select('@*')">
    67     <!--! Add site-specific header -->
    68     <div id="siteheader">
    69       <!--! Place your header content here... -->
    70     </div>
    71 
    72     ${select('*|text()')}
    73 
    74     <!--! Add site-specific footer -->
    75     <div id="sitefooter">
    76       <!--! Place your footer content here... -->
    77     </div>
    78   </body>
    79 </html>
    80 }}}
    81 
    82 Notice 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.
    83 
    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.
    85 See [http://groups.google.com/group/trac-users/browse_thread/thread/70487fb2c406c937/ this thread] for a detailed explanation of the above example `site.html`.
    86 A `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.
    87 
    88 Example snippet of adding introduction text to the new ticket form (but not shown during preview):
    89 
    90 {{{#!xml
    91 <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')">
    92   <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)">
    93     <p>Please make sure to search for existing tickets before reporting a new one!</p>
    94   </py:if>
    95   ${select('*')}
    96 </form>
    97 }}}
    98 
    99 This example illustrates a technique of using `req.environ['PATH_INFO']` to limit scope of changes to one view only. For instance, to make changes in `site.html` only for timeline and avoid modifying other sections - use  `req.environ['PATH_INFO'] == '/timeline'` condition in `<py:if>` test.
    100 
    101 More examples snippets for `site.html` can be found at [trac:wiki:CookBook/SiteHtml CookBook/SiteHtml].
    102 
    103 Example snippets for `style.css` can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss].
    104 
    105 Note 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.
    106 
    107 == Project List == #ProjectList
    108 
    109 You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects. 
    110 
    111 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:
    112 
    113 {{{#!text/html
    114 <!DOCTYPE html
    115     PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    116     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    117 <html xmlns="http://www.w3.org/1999/xhtml"
    118       xmlns:py="http://genshi.edgewall.org/"
    119       xmlns:xi="http://www.w3.org/2001/XInclude">
    120   <head>
    121     <title>Available Projects</title>
    122   </head>
    123   <body>
    124     <h1>Available Projects</h1>
    125     <ul>
    126       <li py:for="project in projects" py:choose="">
    127         <a py:when="project.href" href="$project.href"
    128            title="$project.description">$project.name</a>
    129         <py:otherwise>
    130           <small>$project.name: <em>Error</em> <br /> ($project.description)</small>
    131         </py:otherwise>
    132       </li>
    133     </ul>
    134   </body>
    135 </html>
    136 }}}
    137 
    138 Once you've created your custom template you will need to configure the webserver to tell Trac where the template is located (pls verify ... not yet changed to 0.11):
    139 
    140 For [wiki:TracModWSGI mod_wsgi]:
    141 {{{#!python
    142 os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template.html'
    143 }}}
    144 
    145 For [wiki:TracFastCgi FastCGI]:
    146 {{{#!apache
    147 FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \
    148               -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template
    149 }}}
    150 
    151 For [wiki:TracModPython mod_python]:
    152 {{{#!apache
    153 PythonOption TracEnvParentDir /parent/dir/of/projects
    154 PythonOption TracEnvIndexTemplate /path/to/template
    155 }}}
    156 
    157 For [wiki:TracCgi CGI]:
    158 {{{#!apache
    159 SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template
    160 }}}
    161 
    162 For [wiki:TracStandalone], you'll need to set up the `TRAC_ENV_INDEX_TEMPLATE` environment variable in the shell used to launch tracd:
    163  - Unix
    164    {{{#!sh
    165 $ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template
    166    }}}
    167  - Windows
    168    {{{#!sh
    169 $ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template
    170    }}}
    171 
    172 == Project Templates
    173 
    174 The 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.
    175 
    176 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.
    177 
    178 However, do not edit templates or site resources inside the Trac egg. Reinstalling Trac overwrites your modifications. Instead use one of these alternatives:
    179  * For a modification to one project only, copy the template to project `templates` directory.
    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.
    181 
    182 Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg.
    183 
    184 Trac caches templates in memory by default to improve performance. To apply a template you need to restart the web server.
    185 
    186 ----
    187 See also TracGuide, TracIni

  • wiki/pages/TracLanguages

    r40226 r40534  
    1 ||=Code=||=Name=||=English name=||=Language title=||
    2 ||Ar||العربية||Arabic||لغات أخرى||
    3 ||Ast||asturianu||Asturian||Otres llingües||
    4 ||Az||azərbaycanca||Azeri||Başqa dillərdə||
    5 ||Be||беларуская||Belarusian||Іншыя мовы||
    6 ||Bg||български||Bulgarian||Други езици||
    7 ||Bn||বাংলা||Bengali||অন্যান্য ভাষাসমূহ||
    8 ||Bs||bosanski||Bosnian||Drugim jezicima||
    9 ||Ca||català||Catalan||Altres llengües||
    10 ||Ca-Valencia||valencià||Valencian||Altres llengües||
    11 ||Cs||čeština||Czech||Další jazyky||
    12 ||Da||dansk||Danish||Andre sprog||
    13 ||de||Deutsch||German||Andere Sprachen||
    14 ||gr||Ελληνικά||Greek||Άλλες γλώσσες||
    15 ||en||English||(American) English||Languages||
    16 ||En_AU||Australian||Australian English||Languages||
    17 ||En_GB||British||British||Languages||
    18 ||Es||español||Spanish||Altres idiomas||
    19 ||Et||eesti||Estonian||Teistes keeltes||
    20 ||Eu||euskara||Basque||Beste hizkuntzak||
    21 ||Fa||فارسی||Persian||زبانهای دیگر||
    22 ||Fi||suomi||Finnish||Muilla kielillä||
    23 ||fr||français||French||Autres langues||
    24 ||Gl||galego||Galician||Outras linguas||
    25 ||He||עברית||Hebrew||שפות אחרות||
    26 ||Hi||हिन्दी||Hindi||अन्य भाषाओं||
    27 ||Hr||hrvatski||Croatian||Drugi jezici||
    28 ||Hu||magyar||Hungarian||Más nyelveken||
    29 ||Hy||Հայերեն||Armenian||այլ լեզուներ||
    30 ||Id||Bahasa Indonesia||Indonesian||Bahasa lain||
    31 ||Is||Íslenska||Icelandic||Á öðrum tungumálum||
    32 ||it||italiano||Italian||Altre lingue||
    33 ||Ja||日本語||Japanese||他の言語||
    34 ||Ka||ქართული||Georgian||სხვა ენებზე||
    35 ||Ko||한국어||Korean||다른 언어||
    36 ||Km||ភាសាខ្មែរ||Khmer||ភាសាផ្សេងទៀត||
    37 ||Lt||lietuvių||Lithuanian||Kitomis kalbomis||
    38 ||Lv||latviešu||Latvian||Pārējās valodas||
    39 ||Mk||македонски||Macedonian||Други јазици||
    40 ||Nb||norsk bokmål||Norwegian (Bokmal)||Andre språk||
    41 ||nl||Nederlands||Dutch||Andere talen||
    42 ||pl||polski||Polish||Inne języki||
    43 ||Pt||português||Portuguese||Outras línguas||
    44 ||Pt_BR||português brasileiro||Brazilian Portuguese||Outras línguas||
    45 ||Ro||Română||Romanian||Alte limbi||
    46 ||ru||русский||Russian||Другие языки||
    47 ||Sq||shqip||Albanian||Gjuhët e tjera||
    48 ||Sk||slovenčina||Slovak||Ďalšie jazyky||
    49 ||Sl||slovenščina||Slovenian||Drugi jeziki||
    50 ||Sr||српски||Serbian||Остали језици||
    51 ||Sv||svenska||Swedish||Andra språk||
    52 ||Th||ไทย||Thai||ภาษาอื่น ๆ||
    53 ||Tr||Türkçe||Turkish||Diğer diller||
    54 ||Uk||українська||Ukrainian||Інші мови||
    55 ||Uz||ўзбек тили||Uzbek||Boshqa tillarda||
    56 ||vn||Tiếng Việt||Vietnamese||Ngôn ngữ khác||
    57 ||Zh_CN||简体中文||Chinese (Simplified)||其他语言||
    58 ||Zh_TW||正體中文||Chinese (Traditional)||其他語言||

  • wiki/pages/TracLinks

    r40226 r40534  
    1 = Trac Links =
    2 [[TracGuideToc]]
    3 
    4 TracLinks are a fundamental feature of Trac, because they allow easy hyperlinking between the various entities in the system—such as tickets, reports, changesets, Wiki pages, milestones, and source files—from anywhere WikiFormatting is used.
    5 
    6 TracLinks are generally of the form '''type:id''' (where ''id'' represents the
    7 number, name or path of the item) though some frequently used kinds of items
    8 also have short-hand notations.
    9 
    10 == Where to use TracLinks ==
    11 You can use TracLinks in:
    12 
    13  * Source code (Subversion) commit messages
    14  * Wiki pages
    15  * Full descriptions for tickets, reports and milestones
    16 
    17 and any other text fields explicitly marked as supporting WikiFormatting.
    18 
    19 == Overview ==
    20 
    21 ||= Wiki Markup =||= Display =||
    22 {{{#!td
    23  Wiki pages :: `CamelCase` or `wiki:CamelCase`
    24  Parent page :: `[..]`
    25  Tickets :: `#1` or `ticket:1`
    26  Ticket comments :: `comment:1:ticket:2`
    27  Reports :: `{1}` or `report:1`
    28  Milestones :: `milestone:1.0`
    29  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`, `[1/repository]`
    31  Revision log :: `r1:3`, `[1:3]` or `log:@1:3`, `log:trunk@1:3`, `[2:5/trunk]`
    32  Diffs :: `diff:@1:3`, `diff:plugins/0.12/mercurial-plugin@9128:9953`,
    33           `diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default`
    34           or `diff:trunk/trac@3538//sandbox/vc-refactoring@3539`
    35  Files :: `source:trunk/COPYING`, `source:/trunk/COPYING@200` (at version 200), `source:/trunk/COPYING@200#L25` (at version 200, line 25)
    36 }}}
    37 {{{#!td
    38  Wiki pages :: CamelCase or wiki:CamelCase
    39  Parent page :: [..]
    40  Tickets :: #1 or ticket:1
    41  Ticket comments :: comment:1:ticket:2
    42  Reports :: {1} or report:1
    43  Milestones :: milestone:1.0
    44  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, [1/repository]
    46  Revision log :: r1:3, [1:3] or log:@1:3, log:trunk@1:3, [2:5/trunk]
    47  Diffs :: diff:@1:3, diff:plugins/0.12/mercurial-plugin@9128:9953,
    48           diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default
    49           or diff:trunk/trac@3538//sandbox/vc-refactoring@3539
    50  Files :: source:trunk/COPYING, source:/trunk/COPYING@200 (at version 200), source:/trunk/COPYING@200#L25 (at version 200, line 25)
    51 }}}
    52 
    53 '''Note:''' The wiki:CamelCase form is rarely used, but it can be convenient to refer to
    54 pages whose names do not follow WikiPageNames rules, i.e., single words,
    55 non-alphabetic characters, etc. See WikiPageNames for more about features specific
    56 to links to Wiki page names.
    57 
    58 
    59 {{{#!table class=""
    60 |||| Trac links using the full (non-shorthand) notation can also be given a custom link title like this: ||
    61 {{{#!td
    62 {{{
    63 [ticket:1 This is a link to ticket number one] or
    64 [[ticket:1|This is another link to ticket number one]].
    65 }}}
    66 }}}
    67 {{{#!td
    68 [ticket:1 This is a link to ticket number one] or
    69 [[ticket:1|This is another link to ticket number one]].
    70 }}}
    71 |--------------------------------------------------------------------------------------
    72 |||| If the title is omitted, only the id (the part after the colon) is displayed:  ||
    73 {{{#!td
    74 {{{
    75 [ticket:1] or [[ticket:2]]
    76 }}}
    77 }}}
    78 {{{#!td
    79 [ticket:1] or [[ticket:2]]
    80 }}}
    81 |--------------------------------------------------------------------------------------
    82 |||| `wiki` is the default if the namespace part of a full link is omitted:  ||
    83 {{{#!td
    84 {{{
    85 [SandBox the sandbox] or
    86 [[SandBox|the sandbox]]
    87 }}}
    88 }}}
    89 {{{#!td
    90 [SandBox the sandbox] or
    91 [[SandBox|the sandbox]]
    92 }}}
    93 |--------------------------------------------------------------------------------------
    94 |||| The short form ''realm:target'' can also be wrapped within a <...> pair, [[br]] which allow for arbitrary characters (i.e. anything but >)  ||
    95 {{{#!td
    96 {{{
    97 <wiki:Strange(page@!)>
    98 }}}
    99 }}}
    100 {{{#!td
    101 <wiki:Strange(page@!)>
    102 }}}
    103 }}}
    104 
    105 TracLinks are a very simple idea, but actually allow quite a complex network of information. In practice, it's very intuitive and simple to use, and we've found the "link trail" extremely helpful to better understand what's happening in a project or why a particular change was made.
    106 
    107 
    108 == Advanced use of TracLinks ==
    109 
    110 === Relative links ===
    111 
    112 To create a link to a [trac:SubWiki SubWiki]-page just use a '/':
    113 {{{
    114  WikiPage/SubWikiPage or ./SubWikiPage
    115 }}}
    116 
    117 To link from a [trac:SubWiki SubWiki] page to a parent, simply use a '..':
    118 {{{
    119   [..] or [[..]]
    120 }}}
    121   [..] or [[..]]
    122 
    123 To link from a [trac:SubWiki SubWiki] page to a [=#sibling sibling] page, use a '../':
    124 {{{
    125   [../Sibling see next sibling] or [[../Sibling|see next sibling]]
    126 }}}
    127   [../Sibling see next sibling] or [[../Sibling|see next sibling]]
    128 
    129 But in practice you often won't need to add the `../` prefix to link to a sibling page.
    130 For resolving the location of a wiki link, it's the target page closest in the hierarchy
    131 to the page where the link is written which will be selected. So for example, within
    132 a sub-hierarchy, a sibling page will be targeted in preference to a toplevel page.
    133 This makes it easy to copy or move pages to a sub-hierarchy by [[WikiNewPage#renaming|renaming]] without having to adapt the links.
    134 
    135 In order to link explicitly to a [=#toplevel toplevel] Wiki page,
    136 use 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.
    137 
    138 === Link anchors ===
    139 
    140 To create a link to a specific anchor in a page, use '#':
    141 {{{
    142  [#Linkanchors Link anchors] or [[#Linkanchors|Link anchors]]
    143 }}}
    144   [#Linkanchors Link anchors] or [[#Linkanchors|Link anchors]]
    145 
    146 Hint: when you move your mouse over the title of a section, a '¶' character will be displayed. This is a link to that specific section and you can use this to copy the `#...` part inside a relative link to an anchor.
    147 
    148 To create a link to the first or last occurrence of a term on a page, use a ''pseudo anchor'' starting with '#/' or '#?':
    149 {{{
    150  [#/Milestone first occurrence of Milestone] or
    151  [#?Milestone last occurrence of Milestone]
    152 }}}
    153  [#/Milestone first occurrence of Milestone] or
    154  [#?Milestone last occurrence of Milestone]
    155 This will also highlight all other matches on the linked page. By default only case sensitive matches are considered. To include case insensitive matches append '/i':
    156 {{{
    157  [#/Milestone/i first occurrence of Milestone or milestone] or
    158  [#?Milestone/i last occurrence of Milestone or milestone]
    159 }}}
    160  [#/Milestone/i first occurrence of Milestone or milestone] or
    161  [#?Milestone/i last occurrence of Milestone or milestone]
    162 
    163 ''(since Trac 1.0)''
    164 
    165 Such anchors can be very useful for linking to specific lines in a file in the source browser:
    166 {{{
    167  [trac:source:tags/trac-0.12/trac/wiki/api.py#L127 Line 127] or
    168  [trac:source:tags/trac-0.12/trac/ticket/roadmap.py#L47 Line 47]
    169 }}}
    170  [trac:source:tags/trac-0.12/trac/wiki/api.py#L127 Line 127] or
    171  [trac:source:tags/trac-0.12/trac/ticket/roadmap.py#L47 Line 47]
    172 (Hint: The line numbers displayed in the source browser are links to anchors on the respective lines.)
    173 
    174 Since such links become outdated when the file changes, it can be useful to link using a '#/' pseudo anchor instead:
    175 {{{
    176  [trac:source:trunk/trac/wiki/api.py#/IWikiSyntaxProvider IWikiSyntaxProvider] or
    177  [trac:source:trunk/trac/env.py#/ISystemInfoProvider ISystemInfoProvider]
    178 }}}
    179  [trac:source:trunk/trac/wiki/api.py#/IWikiSyntaxProvider IWikiSyntaxProvider] or
    180  [trac:source:trunk/trac/env.py#/ISystemInfoProvider ISystemInfoProvider]
    181 
    182 === InterWiki links ===
    183 
    184 Other prefixes can be defined freely and made to point to resources in other Web applications. The definition of those prefixes as well as the URLs of the corresponding Web applications is defined in a special Wiki page, the InterMapTxt page. Note that while this could be used to create links to other Trac environments, there's a more specialized way to register other Trac environments which offers greater flexibility.
    185 
    186 === InterTrac links ===
    187 
    188 This can be seen as a kind of InterWiki link specialized for targeting other Trac projects.
    189 
    190 Any type of Trac link can be written in one Trac environment and actually refer to resources in another Trac environment. All that is required is to prefix the Trac link with the name of the other Trac environment followed by a colon. The other Trac environment must be registered on the InterTrac page.
    191 
    192 A distinctive advantage of InterTrac links over InterWiki links is that the shorthand form of Trac links (e.g. `{}`, `r`, `#`) can also be used. For example if T was set as an alias for Trac, links to Trac tickets can be written #T234, links to Trac changesets can be written [trac 1508].
    193 See InterTrac for the complete details.
    194 
    195 === Server-relative links ===
    196 
    197 It is often useful to be able to link to objects in your project that
    198 have no built-in Trac linking mechanism, such as static resources, `newticket`,
    199 a shared `/register` page on the server, etc.
    200 
    201 To link to resources inside the project, use either an absolute path from the project root,
    202 or a relative link from the URL of the current page (''Changed in 0.11''):
    203 
    204 {{{
    205 [/newticket Create a new ticket] or [[//newticket|Create a new ticket]]
    206 [/ home] or [[/|home]]
    207 }}}
    208 
    209 Display: [/newticket Create a new ticket] or [[//newticket|Create a new ticket]]
    210 [/ home] or [[/|home]]
    211 
    212 To link to another location on the server (possibly outside the project but on the same host), use the `//` prefix (''Changed in 0.11''):
    213 
    214 {{{
    215 [//register Register Here] or [[//register|Register Here]]
    216 }}}
    217 
    218 Display: [//register Register Here] or [[//register|Register Here]]
    219 
    220 === Quoting space in TracLinks ===
    221 
    222 Immediately after a TracLinks prefix, targets containing space characters should
    223 be enclosed in a pair of quotes or double quotes.
    224 Examples:
    225  * !wiki:"The whitespace convention"
    226  * !attachment:'the file.txt' or
    227  * !attachment:"the file.txt"
    228  * !attachment:"the file.txt:ticket:123"
    229 
    230 Note that by using [trac:WikiCreole] style links, it's quite natural to write links containing spaces:
    231  * ![[The whitespace convention]]
    232  * ![[attachment:the file.txt]]
    233 
    234 === Escaping Links ===
    235 
    236 To prevent parsing of a !TracLink, you can escape it by preceding it with a '!' (exclamation mark).
    237 {{{
    238  !NoLinkHere.
    239  ![42] is not a link either.
    240 }}}
    241 
    242 Display:
    243  !NoLinkHere.
    244  ![42] is not a link either.
    245 
    246 
    247 === Parameterized Trac links ===
    248 
    249 Many Trac resources have more than one way to be rendered, depending on some extra parameters. For example, a Wiki page can accept a `version` or a `format` parameter, a report can make use of dynamic variables, etc.
    250 
    251 Trac links can support an arbitrary set of parameters, written in the same way as they would be for the corresponding URL. Some examples:
    252  - `wiki:WikiStart?format=txt`
    253  - `ticket:1?version=1`
    254  - `[/newticket?component=module1 create a ticket for module1]`
    255  - `[/newticket?summary=Add+short+description+here create a ticket with URL with spaces]`
    256 
    257 
    258 == TracLinks Reference ==
    259 The following sections describe the individual link types in detail, as well as notes on advanced usage of links.
    260 
    261 === attachment: links ===
    262 
    263 The link syntax for attachments is as follows:
    264  * !attachment:the_file.txt creates a link to the attachment the_file.txt of the current object
    265  * !attachment:the_file.txt:wiki:MyPage creates a link to the attachment the_file.txt of the !MyPage wiki page
    266  * !attachment:the_file.txt:ticket:753 creates a link to the attachment the_file.txt of the ticket 753
    267 
    268 Note that the older way, putting the filename at the end, is still supported: !attachment:ticket:753:the_file.txt.
    269 
    270 If you'd like to create a direct link to the content of the attached file instead of a link to the attachment page, simply use `raw-attachment:` instead of `attachment:`.
    271 
    272 This can be useful for pointing directly to an HTML document, for example. Note that for this use case, you'd have to allow the web browser to render the content by setting `[attachment] render_unsafe_content = yes` (see TracIni#attachment-section). Caveat: only do that in environments for which you're 100% confident you can trust the people who are able to attach files, as otherwise this would open up your site to [wikipedia:Cross-site_scripting cross-site scripting] attacks.
    273 
    274 See also [#export:links].
    275 
    276 === comment: links ===
    277 
    278 When you're inside a given ticket, you can simply write e.g. !comment:3 to link to the third change comment.
    279 It is possible to link to a comment of a specific ticket from anywhere using one of the following syntax:
    280  - `comment:3:ticket:123`
    281  - `ticket:123#comment:3` (note that you can't write `#123#!comment:3`!)
    282 It is also possible to link to the ticket's description using one of the following syntax:
    283  - `comment:description` (within the ticket)
    284  - `comment:description:ticket:123`
    285  - `ticket:123#comment:description`
    286 
    287 === htdocs: links ===
    288 
    289 Use `htdocs:path/to/file` to reference files in the `htdocs` directory of the Trac environment, the [TracEnvironment#DirectoryStructure web resource directory].
    290 
    291 === query: links ===
    292 
    293 See TracQuery#UsingTracLinks and [#ticket:links].
    294 
    295 === search: links ===
    296 
    297 See TracSearch#SearchLinks
    298 
    299 === ticket: links ===
    300  ''alias:'' `bug:`
    301 
    302 Besides the obvious `ticket:id` form, it is also possible to specify a list of tickets or even a range of tickets instead of the `id`. This generates a link to a custom query view containing this fixed set of tickets.
    303 
    304 Example:
    305  - `ticket:5000-6000`
    306  - `ticket:1,150`
    307 
    308 === timeline: links ===
    309 
    310 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 if you don't want to compute the UTC time, you can specify a local time followed by your timezone offset relative to UTC.
    311 
    312 Examples:
    313  - `timeline:2008-01-29`
    314  - `timeline:2008-01-29T15:48`
    315  - `timeline:2008-01-29T15:48Z`
    316  - `timeline:2008-01-29T16:48+01`
    317  - `timeline:2008-01-29T16:48+0100`
    318  - `timeline:2008-01-29T16:48+01:00`
    319 
    320 === wiki: links ===
    321 
    322 See WikiPageNames and [#QuotingspaceinTracLinks quoting space in TracLinks] above. It is possible to create a link to a specific page revision using the syntax WikiStart@1.
    323 
    324 === Version Control related links ===
    325 
    326 It should be noted that multiple repository support works by creating a kind of virtual namespace for versioned files in which the toplevel folders correspond to the repository names. Therefore, in presence of multiple repositories, a ''/path'' specification in the syntax of links detailed below should start with the name of the repository. If omitted, the default repository is used. In case a toplevel folder of the default repository has the same name as a repository, the latter "wins". One can always access such folder by fully qualifying it (the default repository can be an alias of a named repository, or conversely, it is always possible to create an alias for the default repository, ask your Trac administrator).
    327 
    328 For example, `source:/trunk/COPYING` targets the path `/trunk/COPYING` in the default repository, whereas `source:/projectA/trunk/COPYING` targets the path `/trunk/COPYING` in the repository named `projectA`. This can be the same file if `'projectA'` is an alias to the default repository or if `''` (the default repository) is an alias to `'projectA'`.
    329 
    330 ==== source: links ====
    331  ''aliases:'' `browser:`, `repos:`
    332 
    333 The default behavior for a `source:/some/path link` is to open the browser in that directory directory
    334 if the path points to a directory or to show the latest content of the file.
    335 
    336 It's also possible to link directly to a specific revision of a file like this:
    337  - `source:/some/file@123` - link to the file's revision 123
    338  - `source:/some/file@head` - link explicitly to the latest revision of the file
    339 
    340 If the revision is specified, one can even link to a specific line number:
    341  - `source:/some/file@123#L10`
    342  - `source:/tag/0.10@head#L10`
    343 
    344 Finally, one can also highlight an arbitrary set of lines:
    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
    347 
    348 Note 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)''
    349 
    350 ==== export: links ====
    351 
    352 To force the download of a file in the repository, as opposed to displaying it in the browser, use the `export` link.  Several forms are available:
    353  * `export:/some/file` - get the HEAD revision of the specified file
    354  * `export:123:/some/file` - get revision 123 of the specified file
    355  * `export:/some/file@123` - get revision 123 of the specified file
    356 
    357 This can be very useful for displaying XML or HTML documentation with correct stylesheets and images, in case that has been checked in into the repository. Note that for this use case, you'd have to allow the web browser to render the content by setting `[browser] render_unsafe_content = yes` (see TracIni#browser-section), otherwise Trac will force the files to be downloaded as attachments for security concerns.
    358 
    359 If the path is to a directory in the repository instead of a specific file, the source browser will be used to display the directory (identical to the result of `source:/some/dir`).
    360 
    361 ==== log: links ====
    362 
    363 The `log:` links are used to display revision ranges. In its simplest form, it can link to the latest revisions of the specified path, but it can also support displaying an arbitrary set of revisions.
    364  - `log:/` - the latest revisions starting at the root of the repository
    365  - `log:/trunk/tools` - the latest revisions in `trunk/tools`
    366  - `log:/trunk/tools@10000` - the revisions in `trunk/tools` starting from  revision 10000
    367  - `log:@20788,20791:20795` - list revision 20788 and the revisions from 20791 to 20795
    368  - `log:/trunk/tools@20788,20791:20795` - list revision 20788 and the revisions from 20791 to 20795 which affect the given path
    369 
    370 There are short forms for revision ranges as well:
    371  - `[20788,20791:20795]`
    372  - `[20788,20791:20795/trunk/tools]`
    373  - `r20791:20795` (but not `r20788,20791:20795` nor `r20791:20795/trunk`)
    374 
    375 Finally, note that in all of the above, a revision range can be written either as `x:y` or `x-y`.
    376 
    377 In the presence of multiple repositories, the name of the repository should be specified as the first part of the path, e.g. `log:repos/branches` or `[20-40/repos]`.
    378 
    379 ----
    380 See also: WikiFormatting, TracWiki, WikiPageNames, InterTrac, InterWiki
    381  

  • wiki/pages/TracLogging

    r40226 r40534  
    1 = Trac Logging
    2 [[TracGuideToc]]
    3 
    4 Trac supports logging of system messages using the standard [http://docs.python.org/library/logging.html logging module] that comes with Python.
    5 
    6 Logging is configured in the `[logging]` section in [wiki:TracIni#logging-section trac.ini].
    7 
    8 == Supported Logging Methods
    9 
    10 The log method is set using the `log_type` option in [wiki:TracIni#logging-section trac.ini], which takes any of the following values:
    11 
    12  '''none'':: Suppress all log messages.
    13  '''file''':: Log messages to a file, specified with the `log_file` option in [wiki:TracIni#logging-section trac.ini]. Relative paths in `log_file` are resolved relative to the `log` directory of the environment.
    14  '''stderr''':: Output all log entries to console ([wiki:TracStandalone tracd] only).
    15  '''syslog''':: (UNIX) Send all log messages to the local syslogd via named pipe `/dev/log`. By default, syslog will write them to the file /var/log/messages.
    16  '''eventlog''':: (Windows) Use the system's NT Event Log for Trac logging.
    17 
    18 == Log Levels
    19 
    20 The 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:
    21 
    22  '''CRITICAL''':: Log only the most critical (typically fatal) errors.
    23  '''ERROR''':: Log failures, bugs and errors.
    24  '''WARN''':: Log warnings, non-interrupting events.
    25  '''INFO''':: Diagnostic information, log information about all processing.
    26  '''DEBUG''':: Trace messages, profiling, etc.
    27 
    28 Additionally, 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.
    29 
    30 == Log Format
    31 
    32 The 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:
    33  '''$(basename)s''':: The last path component of the current environment.
    34  '''$(path)s''':: The absolute path for the current environment.
    35  '''$(project)s''':: The originating project's name.
    36 
    37 Note that variables are identified using a dollar sign (`$(...)s`) instead of percent sign (`%(...)s`).
    38 
    39 The default format is:
    40 {{{#!ini
    41 log_format = Trac[$(module)s] $(levelname)s: $(message)s
    42 }}}
    43 
    44 In 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 {{{#!ini
    46 log_format = Trac[$(basename)s:$(module)s] $(levelname)s: $(message)s
    47 }}}
    48 
    49 ----
    50 See also: TracIni, TracGuide, TracEnvironment

  • wiki/pages/TracModPython

    r40226 r40534  
    1 [[TracGuideToc]]
    2 
    3 = Trac and mod_python
    4 
    5 Mod_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.
    6 Trac 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.
    7 
    8 These 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.
    9 
    10 [[PageOutline(2-3,Overview,inline)]]
    11 
    12 == Simple configuration: single project == #Simpleconfiguration
    13 
    14 If you just installed mod_python, you may have to add a line to load the module in the Apache configuration:
    15 {{{#!apache
    16 LoadModule python_module modules/mod_python.so
    17 }}}
    18 
    19 '''Note''': The exact path to the module depends on how the HTTPD installation is laid out.
    20 
    21 On Debian using apt-get:
    22 {{{#!sh
    23 apt-get install libapache2-mod-python libapache2-mod-python-doc
    24 }}}
    25 
    26 Still on Debian, after you have installed mod_python, you must enable the modules in apache2, equivalent to the above Load Module directive:
    27 {{{#!sh
    28 a2enmod python
    29 }}}
    30 
    31 On Fedora use, using yum:
    32 {{{#!sh
    33 yum install mod_python
    34 }}}
    35 
    36 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+.
    37 {{{#!apache
    38 <Location /mpinfo>
    39    SetHandler mod_python
    40    PythonInterpreter main_interpreter
    41    PythonHandler mod_python.testhandler
    42    Order allow,deny
    43    Allow from all
    44 </Location>
    45 }}}
    46 
    47 A simple setup of Trac on mod_python looks like this:
    48 {{{#!apache
    49 <Location /projects/myproject>
    50    SetHandler mod_python
    51    PythonInterpreter main_interpreter
    52    PythonHandler trac.web.modpython_frontend
    53    PythonOption TracEnv /var/trac/myproject
    54    PythonOption TracUriRoot /projects/myproject
    55    Order allow,deny
    56    Allow from all
    57 </Location>
    58 }}}
    59 
    60 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.
    61 
    62 The options available are:
    63 {{{#!apache
    64 # For a single project
    65 PythonOption TracEnv /var/trac/myproject
    66 
    67 # For multiple projects
    68 PythonOption TracEnvParentDir /var/trac/myprojects
    69 
    70 # For the index of multiple projects
    71 PythonOption TracEnvIndexTemplate /srv/www/htdocs/trac/project_list_template.html
    72 
    73 # A space delimitted list, with a "," between key and value pairs.
    74 PythonOption TracTemplateVars key1,val1 key2,val2
    75 
    76 # Useful to get the date in the wanted order
    77 PythonOption TracLocale en_GB.UTF8
    78 
    79 # See description above       
    80 PythonOption TracUriRoot /projects/myproject
    81 }}}
    82 
    83 === Python Egg Cache
    84 
    85 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 writeable, an alternate egg cache directory can be specified like this:
    86 {{{#!apache
    87 PythonOption PYTHON_EGG_CACHE /var/trac/myprojects/egg-cache
    88 }}}
    89 
    90 Or you can uncompress the Genshi egg to resolve problems extracting from it.
    91 
    92 === Configuring Authentication
    93 
    94 See corresponding section in the [wiki:TracModWSGI#ConfiguringAuthentication] page.
    95 
    96 == Advanced Configuration
    97 
    98 === Setting the Python Egg Cache
    99 
    100 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.
    101 
    102 {{{#!apache
    103 <Location /projects/myproject>
    104   ...
    105   PythonOption PYTHON_EGG_CACHE /tmp
    106   ...
    107 </Location>
    108 }}}
    109 
    110 === Setting the !PythonPath
    111 
    112 If 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
    114 <Location /projects/myproject>
    115   ...
    116   PythonPath "sys.path + ['/path/to/trac']"
    117   ...
    118 </Location>
    119 }}}
    120 
    121 Be careful about using the !PythonPath directive, and ''not'' `SetEnv PYTHONPATH`, as the latter won't work.
    122 
    123 === Setting up multiple projects
    124 
    125 The Trac mod_python handler supports a configuration option similar to Subversion's `SvnParentPath`, called `TracEnvParentDir`:
    126 {{{#!apache
    127 <Location /projects>
    128   SetHandler mod_python
    129   PythonInterpreter main_interpreter
    130   PythonHandler trac.web.modpython_frontend
    131   PythonOption TracEnvParentDir /var/trac
    132   PythonOption TracUriRoot /projects
    133 </Location>
    134 }}}
    135 
    136 When you request the `/projects` URL, you will get a listing of all subdirectories of the directory you set as `TracEnvParentDir` that look like Trac environment directories. Selecting any project in the list will bring you to the corresponding Trac environment.
    137 
    138 If you don't want to have the subdirectory listing as your projects home page you can use a
    139 {{{#!apache
    140 <LocationMatch "/.+/">
    141 }}}
    142 
    143 This will instruct Apache to use mod_python for all locations different from root while having the possibility of placing a custom home page for root in your !DocumentRoot folder.
    144 
    145 You can also use the same authentication realm for all of the projects using a `<LocationMatch>` directive:
    146 {{{#!apache
    147 <LocationMatch "/projects/[^/]+/login">
    148   AuthType Basic
    149   AuthName "Trac"
    150   AuthUserFile /var/trac/.htpasswd
    151   Require valid-user
    152 </LocationMatch>
    153 }}}
    154 
    155 === Virtual Host Configuration
    156 
    157 Below 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 *>
    162     DocumentRoot /var/www/myproject
    163     ServerName trac.mycompany.com
    164     <Location />
    165         SetHandler mod_python
    166         PythonInterpreter main_interpreter
    167         PythonHandler trac.web.modpython_frontend
    168         PythonOption TracEnv /var/trac/myproject
    169         PythonOption TracUriRoot /
    170     </Location>
    171     <Location /login>
    172         AuthType Basic
    173         AuthName "MyCompany Trac Server"
    174         AuthUserFile /var/trac/myproject/.htpasswd
    175         Require valid-user
    176     </Location>
    177 </VirtualHost>
    178 }}}
    179 
    180 This does not seem to work in all cases. What you can do if it does not:
    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.
    183  * Depending on apache's `NameVirtualHost` configuration, you may need to use `<VirtualHost *:80>` instead of `<VirtualHost *>`.
    184 
    185 For 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 
    191 If you get server error pages, you can either check the Apache error log, or enable the `PythonDebug` option:
    192 {{{#!apache
    193 <Location /projects/myproject>
    194   ...
    195   PythonDebug on
    196 </Location>
    197 }}}
    198 
    199 For multiple projects, try restarting the server as well.
    200 
    201 === Login Not Working
    202 
    203 If you've used `<Location />` directive, it will override any other directives, as well as `<Location /login>`.
    204 The workaround is to use negation expression as follows (for multi project setups):
    205 {{{#!apache
    206 #this one for other pages
    207 <Location ~ "/*(?!login)">
    208    SetHandler mod_python
    209    PythonHandler trac.web.modpython_frontend
    210    PythonOption TracEnvParentDir /projects
    211    PythonOption TracUriRoot /
    212 </Location>
    213 
    214 #this one for login page
    215 <Location ~ "/[^/]+/login">
    216    SetHandler mod_python
    217    PythonHandler trac.web.modpython_frontend
    218    PythonOption TracEnvParentDir /projects
    219    PythonOption TracUriRoot /
    220 
    221    #remove these if you don't want to force SSL
    222    RewriteEngine On
    223    RewriteCond %{HTTPS} off
    224    RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
    225 
    226    AuthType Basic
    227    AuthName "Trac"
    228    AuthUserFile /projects/.htpasswd
    229    Require valid-user
    230 </Location>
    231 }}}
    232 
    233 === Expat-related segmentation faults === #expat
    234 
    235 This problem will most certainly hit you on Unix when using Python 2.4.
    236 In 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.
    237 As 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
    240 
    241 If 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.
    242 
    243 === Problem with virtual host configuration
    244 
    245 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.
    246 
    247 Using <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 
    251 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 this, try installing Trac using the `--always-unzip` option:
    252 
    253 {{{#!sh
    254 easy_install --always-unzip Trac-0.12b1.zip
    255 }}}
    256 
    257 === Using .htaccess
    258 
    259 Although 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.
    260 
    261 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.
    262 
    263 This also works out-of-box, with following trivial config:
    264 {{{#!apache
    265 SetHandler mod_python
    266 PythonInterpreter main_interpreter
    267 PythonHandler trac.web.modpython_frontend
    268 PythonOption TracEnv /system/path/to/this/directory
    269 PythonOption TracUriRoot /path/on/apache
    270 
    271 AuthType Basic
    272 AuthName "ProjectName"
    273 AuthUserFile /path/to/.htpasswd
    274 Require valid-user
    275 }}}
    276 
    277 The `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 
    281 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:
    282 
    283 {{{#!apache
    284 <IfModule mod_rewrite.c>
    285   RewriteEngine Off
    286 </IfModule>
    287 }}}
    288 
    289 === Platform specific issues
    290 ==== Win32 Issues
    291 
    292 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.
    293 
    294 ==== OS X issues
    295 
    296 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, so please upgrade mod_python to fix this.
    297 
    298 ==== SELinux issues
    299 
    300 If 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
    303 chcon -R -h -t httpd_sys_content_t PATH_TO_REPOSITORY
    304 }}}
    305 
    306 See also [http://subversion.apache.org/faq.html#reposperms How do I set repository permissions correctly?]
    307 
    308 ==== FreeBSD issues
    309 
    310 The 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 
    314 Apache2 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.
    315 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:
    316 
    317 {{{#!sh
    318 export LD_PRELOAD=/usr/lib/libc_r.so
    319 }}}
    320 
    321 ==== Fedora 7 Issues
    322 
    323 Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython, but not for tracd.
    324 
    325 === Subversion issues
    326 
    327 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. 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 
    329 If 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 
    331 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. 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
    333 PythonInterpreter main_interpreter
    334 }}}
    335 
    336 This 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 
    340 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:
    341 {{{#!apache
    342 Alias /myproject/css "/usr/share/trac/htdocs/css"
    343 <Location /myproject/css>
    344     SetHandler None
    345 </Location>
    346 }}}
    347 
    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 
    350 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, leave it `Off`.
    351 
    352 === HTTPS issues
    353 
    354 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:
    355 {{{#!apache
    356 <VirtualHost *>
    357     DocumentRoot /var/www/myproject
    358     ServerName trac.mycompany.com
    359     SetEnv HTTPS 1
    360     ....
    361 </VirtualHost>
    362 }}}
    363 
    364 === Segmentation fault with php5-mhash or other php5 modules
    365 
    366 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 [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487 Debian bug report].
    367 
    368 Some 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].
    369 
    370 ----
    371 See also: TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI], [trac:TracNginxRecipe]

  • wiki/pages/TracModWSGI

    r40226 r40534  
    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.
    4 
    5 [[PageOutline(2-3,Overview,inline)]]
    6 
    7 == The `trac.wsgi` script
    8 
    9 Trac 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 
    11 A 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 
    13 If 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
    15 def 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 }}}
    20 
    21 === A very basic script
    22 In its simplest form, the script could be:
    23 
    24 {{{#!python
    25 import os
    26 
    27 os.environ['TRAC_ENV'] = '/usr/local/trac/mysite'
    28 os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'
    29 
    30 import trac.web.main
    31 application = trac.web.main.dispatch_request
    32 }}}
    33 
    34 The `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 
    36 On Windows:
    37  - If run under the user's session, the Python Egg cache can be found in `%AppData%\Roaming`, for example:
    38 {{{#!python
    39 os.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
    43 os.environ['PYTHON_EGG_CACHE'] = r'C:\Trac-Python-Eggs'
    44 }}}
    45 
    46 === A more elaborate script
    47 
    48 If 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.
    49 
    50 To solve this problem, use the following `.wsgi` file instead:
    51 {{{#!python
    52 import os
    53 
    54 os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'
    55 
    56 import trac.web.main
    57 def application(environ, start_response):
    58   environ['trac.env_path'] = '/usr/local/trac/mysite'
    59   return trac.web.main.dispatch_request(environ, start_response)
    60 }}}
    61 
    62 For 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.
    63 
    64 If 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:
    65 
    66 {{{#!python
    67 import site
    68 site.addsitedir('/usr/local/trac/lib/python2.4/site-packages')
    69 }}}
    70 
    71 Change it according to the path you installed the Trac libs at.
    72 
    73 == Mapping requests to the script
    74 
    75 After preparing your .wsgi script, add the following to your Apache configuration file, typically `httpd.conf`:
    76 
    77 {{{#!apache
    78 WSGIScriptAlias /trac /usr/local/trac/mysite/apache/mysite.wsgi
    79 
    80 <Directory /usr/local/trac/mysite/apache>
    81     WSGIApplicationGroup %{GLOBAL}
    82     Order deny,allow
    83     Allow from all
    84 </Directory>
    85 }}}
    86 
    87 Here, the script is in a subdirectory of the Trac environment.
    88 
    89 If you followed the directions [TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following:
    90 
    91 {{{#!apache
    92 WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi
    93 
    94 <Directory /usr/share/trac/cgi-bin>
    95     WSGIApplicationGroup %{GLOBAL}
    96     Order deny,allow
    97     Allow from all
    98 </Directory>
    99 }}}
    100 
    101 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. After adding this configuration, restart Apache, and then it should work.
    102 
    103 To 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):
    104 
    105 {{{#!python
    106 def application(environ, start_response):
    107         start_response('200 OK',[('Content-type','text/html')])
    108         return ['<html><body>Hello World!</body></html>']
    109 }}}
    110 
    111 For 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.
    112 
    113 == Configuring Authentication
    114 
    115 The 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 
    119 The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program as follows:
    120 {{{#!sh
    121 $ htpasswd -c /somewhere/trac.htpasswd admin
    122 New password: <type password>
    123 Re-type new password: <type password again>
    124 Adding password for user admin
    125 }}}
    126 
    127 After the first user, you don't need the "-c" option anymore:
    128 {{{#!sh
    129 $ htpasswd /somewhere/trac.htpasswd john
    130 New password: <type password>
    131 Re-type new password: <type password again>
    132 Adding password for user john
    133 }}}
    134 
    135   ''See the man page for `htpasswd` for full documentation.''
    136 
    137 After you've created the users, you can set their permissions using TracPermissions.
    138 
    139 Now, you need to enable authentication against the password file in the Apache configuration:
    140 {{{#!apache
    141 <Location "/trac/login">
    142   AuthType Basic
    143   AuthName "Trac"
    144   AuthUserFile /somewhere/trac.htpasswd
    145   Require valid-user
    146 </Location>
    147 }}}
    148 
    149 If you are hosting multiple projects, you can use the same password file for all of them:
    150 {{{#!apache
    151 <LocationMatch "/trac/[^/]+/login">
    152   AuthType Basic
    153   AuthName "Trac"
    154   AuthUserFile /somewhere/trac.htpasswd
    155   Require valid-user
    156 </LocationMatch>
    157 }}}
    158 Note that neither a file nor a directory named 'login' needs to exist.[[BR]]
    159 See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html mod_auth_basic] documentation.
    160 
    161 === Using Digest Authentication
    162 
    163 For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”.
    164 
    165 You 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
    168 }}}
    169 
    170 The "trac" parameter above is the "realm", and will have to be reused in the Apache configuration in the !AuthName directive:
    171 
    172 {{{#!apache
    173 <Location "/trac/login">
    174   AuthType Digest
    175   AuthName "trac"
    176   AuthDigestDomain /trac
    177   AuthUserFile /somewhere/trac.htpasswd
    178   Require valid-user
    179 </Location>
    180 }}}
    181 
    182 For multiple environments, you can use the same `LocationMatch` as described with the previous method.
    183 
    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 
    186 Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system:
    187 {{{#!apache
    188   LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
    189 }}}
    190 
    191 See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_digest.html mod_auth_digest] documentation.
    192 
    193 === Using LDAP Authentication
    194 
    195 Configuration 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 
    197 1. 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 }}}
    202 1. Your httpd.conf also needs to look something like:
    203 {{{#!apache
    204 <Location /trac/>
    205   # (if you're using it, mod_python specific settings go here)
    206   Order deny,allow
    207   Deny from all
    208   Allow from 192.168.11.0/24
    209   AuthType Basic
    210   AuthName "Trac"
    211   AuthBasicProvider "ldap"
    212   AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=co,dc=ke?uid?sub?(objectClass=inetOrgPerson)"
    213   authzldapauthoritative Off
    214   Require valid-user
    215 </Location>
    216 }}}
    217 1. 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
    228 <Location /trac/>
    229   # (if you're using it, mod_python specific settings go here)
    230   Order deny,allow
    231   Deny from all
    232   Allow from 192.168.11.0/24
    233   AuthType Basic
    234   AuthName "Trac"
    235   AuthBasicProvider "ldap"
    236   AuthLDAPURL "ldap://adserver.company.com:3268/DC=company,DC=com?sAMAccountName?sub?(objectClass=user)"
    237   AuthLDAPBindDN       ldap-auth-user@company.com
    238   AuthLDAPBindPassword "the_password"
    239   authzldapauthoritative Off
    240   # 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 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 
    247 Note 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
    250 }}}
    251 
    252 See also:
    253  - [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html mod_authnz_ldap], documentation for mod_authnz_ldap.   
    254  - [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.
    255  - [http://trac-hacks.org/wiki/LdapPlugin TracHacks:LdapPlugin] for storing TracPermissions in LDAP.
    256 
    257 === Using SSPI Authentication
    258 
    259 If 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 
    274 Using 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.
    275 
    276 Some common problems with SSPI authentication: [trac:#1055], [trac:#1168] and [trac:#3338].
    277 
    278 See also [trac:TracOnWindows/Advanced].
    279 
    280 === Using Apache authentication with the Account Manager plugin's Login form ===
    281 
    282 To begin with, see the basic instructions for using the Account Manager plugin's [http://trac-hacks.org/wiki/AccountManagerPlugin/Modules#LoginModule Login module] and its [http://trac-hacks.org/wiki/AccountManagerPlugin/AuthStores#HttpAuthStore HttpAuthStore authentication module].
    283 
    284 '''Note:''' If is difficult to get !HttpAuthStore to work with WSGI when using any Account Manager version prior to acct_mgr-0.4. Upgrading is recommended.
    285 
    286 Here is an example (from the !HttpAuthStore link) using acct_mgr-0.4 for hosting a single project:
    287 {{{#!ini
    288 [components]
    289 ; be sure to enable the component
    290 acct_mgr.http.HttpAuthStore = enabled
    291 
    292 [account-manager]
    293 ; configure the plugin to use a page that is secured with http authentication
    294 authentication_url = /authFile
    295 password_store = HttpAuthStore
    296 }}}
    297 This will generally be matched with an Apache config like:
    298 {{{#!apache
    299 <Location /authFile>
    300    …HTTP authentication configuration…
    301    Require valid-user
    302 </Location>
    303 }}}
    304 Note 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.
    305 
    306 === Example: Apache/mod_wsgi with Basic Authentication, Trac being at the root of a virtual host
    307 
    308 Per 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.
    311 
    312 If 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:
    313 
    314 Create the htpasswd file:
    315 {{{#!sh
    316 cd /home/trac-for-my-proj/the-env
    317 htpasswd -c htpasswd firstuser
    318 ### and add more users to it as needed:
    319 htpasswd htpasswd seconduser
    320 }}}
    321 Keep the file above your document root for security reasons.
    322 
    323 Create this file e.g. (ubuntu) `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` with the following content:
    324 
    325 {{{#!apache
    326 <Directory /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi>
    327   WSGIApplicationGroup %{GLOBAL}
    328   Order deny,allow
    329   Allow from all
    330 </Directory>
    331 
    332 <VirtualHost *:80>
    333   ServerName trac.my-proj.my-site.org
    334   DocumentRoot /home/trac-for-my-proj/the-env/htdocs/
    335   WSGIScriptAlias / /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi
    336   <Location '/'>
    337     AuthType Basic
    338     AuthName "Trac"
    339     AuthUserFile /home/trac-for-my-proj/the-env/htpasswd
    340     Require valid-user
    341   </Location>
    342 </VirtualHost>
    343 
    344 }}}
    345 
    346 Note: for subdomains to work you would probably also need to alter `/etc/hosts` and add A-Records to your host's DNS.
    347 
    348 == Troubleshooting
    349 
    350 === Use a recent version
    351 
    352 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].
    353 
    354 ''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''
    355 
    356 If 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 
    360 If 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 
    362 This WSGI script 'fixes' that:
    363 {{{#!python
    364 import os
    365 import trac.web.main
    366 
    367 os.environ['TRAC_ENV'] = '/usr/local/trac/mysite'
    368 os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'
    369 
    370 def application(environ, start_response):
    371     if "\\" in environ['REMOTE_USER']:
    372         environ['REMOTE_USER'] = environ['REMOTE_USER'].split("\\", 1)[1]
    373     return trac.web.main.dispatch_request(environ, start_response)
    374 }}}
    375 
    376 === Trac with PostgreSQL
    377 
    378 When 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 
    380 A 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 
    382 But it is not necessary to edit the source of Trac. The following lines in `trac.wsgi` will also work:
    383 
    384 {{{#!python
    385 import trac.db.postgres_backend
    386 trac.db.postgres_backend.PostgreSQLConnection.poolable = False
    387 }}}
    388 
    389 or
    390 
    391 {{{#!python
    392 import trac.db.mysql_backend
    393 trac.db.mysql_backend.MySQLConnection.poolable = False
    394 }}}
    395 
    396 Now Trac drops the connection after serving a page and the connection count on the database will be kept low.
    397 
    398 //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.//
    399 
    400 === Other resources
    401 
    402 For 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.
    403 
    404 ----
    405 See also: TracGuide, TracInstall, [wiki:TracFastCgi FastCGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]

  • wiki/pages/TracNavigation

    r40226 r40534  
    1 = Trac Navigation
    2 
    3 The 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.
    4 
    5 === `[mainnav]` #mainnav-bar
    6 `[mainnav]` corresponds to the '''main navigation bar''', the one containing entries such as ''Wiki'', ''Timeline'', ''Roadmap'', ''Browse Source'' and so on. This navigation bar is meant to access the default page of the main modules enabled in Trac that are accessible for the current user.
    7 
    8 
    9 ** [=#Example Example] **
    10 
    11 In the following example we rename the link to WikiStart //Home//, and make the //View Tickets// entry link to a specific report.
    12 {{{#!ini
    13 [mainnav]
    14 wiki.label = Home
    15 tickets.href = /report/24
    16 }}}
    17 
    18 === `[metanav]` #metanav-bar
    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.
    20 
    21 There 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.
    22 [[comment(see also #Trac3808)]]
    23 
    24 ** Example **
    25 
    26 {{{#!ini
    27 [metanav]
    28 help = disabled
    29 logout.redirect = wiki/Logout
    30 }}}
    31 
    32 
    33 === URL Formats
    34 Possible URL formats for `.href` or `.redirect`:
    35 || '''config''' || '''redirect to''' ||
    36 || `wiki/Logout` || `/projects/env/wiki/Logout` ||
    37 || `http://hostname/` || `http://hostname/` ||
    38 || `/projects` || `/projects` ||
    39 
    40 
    41 === Ordering #nav-order
    42 The `order` attribute specifies the order in which the navigation items are displayed. This can be particularly useful for plugins that add navigation items.
    43 
    44 Non-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.
    45 
    46 The default values are:
    47 {{{#!ini
    48 [mainnav]
    49 browser.order = 4
    50 newticket.order = 6
    51 roadmap.order = 3
    52 search.order = 7
    53 tickets.order = 5
    54 timeline.order = 2
    55 wiki.order = 1
    56 
    57 [metanav]
    58 about.order = 5
    59 help.order = 4
    60 login.order = 1
    61 logout.order = 2
    62 prefs.order = 3
    63 }}}
    64 
    65 === Context Navigation #ctxtnav-bar
    66 
    67 Note that it is still not possible to customize the '''contextual navigation bar''', ie the one usually placed below the main navigation bar.
    68 
    69 ----
    70 See also: TracInterfaceCustomization, and the [http://trac-hacks.org/wiki/NavAddPlugin TracHacks:NavAddPlugin] or [http://trac-hacks.org/wiki/MenusPlugin TracHacks:MenusPlugin] (still needed for adding entries)

  • wiki/pages/TracNotification

    r40226 r40534  
    1 = Email Notification of Ticket Changes
    2 [[TracGuideToc]]
    3 
    4 Trac supports notification of ticket changes via email.
    5 
    6 Email notification is useful to keep users up-to-date on tickets/issues of interest, and also provides a convenient way to post all ticket changes to a dedicated mailing list. For example, this is how the [http://lists.edgewall.com/archive/trac-tickets/ Trac-tickets] mailing list is set up.
    7 
    8 Disabled by default, notification can be activated and configured in [wiki:TracIni trac.ini].
    9 
    10 == Receiving Notification Mails
    11 When 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 
    15 To 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 
    17 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.
    18 
    19 When 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`''').
    20 
    21 === Ticket attachment notifications
    22 
    23 Since 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]
    26 trac.ticket.notification.TicketAttachmentNotifier = disabled
    27 }}}
    28 
    29 == Configuring SMTP Notification
    30 
    31 '''Important:''' For TracNotification to work correctly, the `[trac] base_url` option must be set in [wiki:TracIni trac.ini].
    32 
    33 === Configuration Options
    34 These are the available options for the `[notification]` section in trac.ini:
    35 
    36 [[TracIni(notification)]]
    37 
    38 === Example Configuration (SMTP)
    39 {{{#!ini
    40 [notification]
    41 smtp_enabled = true
    42 smtp_server = mail.example.com
    43 smtp_from = notifier@example.com
    44 smtp_replyto = myproj@projects.example.com
    45 smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com
    46 }}}
    47 
    48 === Example Configuration (`sendmail`)
    49 {{{#!ini
    50 [notification]
    51 smtp_enabled = true
    52 email_sender = SendmailEmailSender
    53 sendmail_path = /usr/sbin/sendmail
    54 smtp_from = notifier@example.com
    55 smtp_replyto = myproj@projects.example.com
    56 smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com
    57 }}}
    58 
    59 === Subscriber Configuration
    60 The default subscriptions are configured in the `[notification-subscriber]` section in trac.ini:
    61 
    62 [[TracIni(notification-subscriber)]]
    63 
    64 Each user can override these defaults in his ''Notifications'' preferences.
    65 
    66 For 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
    69 The 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:
    70 {{{#!genshi
    71 $prefix #$ticket.id: $summary
    72 }}}
    73 The following variables are available in the template:
    74 
    75  * `env`: The project environment (see [trac:source:/trunk/trac/env.py env.py]).
    76  * `prefix`: The prefix defined in `smtp_subject_prefix`.
    77  * `summary`: The ticket summary, with the old value if the summary was edited.
    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 
    82 The 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
    85 $ticket_body_hdr
    86 $ticket_props
    87 {% choose ticket.new %}\
    88 {%   when True %}\
    89 $ticket.description
    90 {%   end %}\
    91 {%   otherwise %}\
    92 {%     if changes_body %}\
    93 ${_('Changes (by %(author)s):', author=change.author)}
    94 
    95 $changes_body
    96 {%     end %}\
    97 {%     if changes_descr %}\
    98 {%       if not changes_body and not change.comment and change.author %}\
    99 ${_('Description changed by %(author)s:', author=change.author)}
    100 {%       end %}\
    101 $changes_descr
    102 --
    103 {%     end %}\
    104 {%     if change.comment %}\
    105 
    106 ${changes_body and _('Comment:') or _('Comment (by %(author)s):', author=change.author)}
    107 
    108 $change.comment
    109 {%     end %}\
    110 {%   end %}\
    111 {% end %}\
    112 
    113 --
    114 ${_('Ticket URL: <%(link)s>', link=ticket.link)}
    115 $project.name <${project.url or abs_href()}>
    116 $project.descr
    117 }}}
    118 
    119 == Sample Email
    120 {{{
    121 #42: testing
    122 ---------------------------+------------------------------------------------
    123        Id:  42             |      Status:  assigned               
    124 Component:  report system  |    Modified:  Fri Apr  9 00:04:31 2004
    125  Severity:  major          |   Milestone:  0.9                     
    126  Priority:  lowest         |     Version:  0.6                     
    127     Owner:  anonymous      |    Reporter:  jonas@example.com               
    128 ---------------------------+------------------------------------------------
    129 Changes:
    130   * component:  changeset view => search system
    131   * priority:  low => highest
    132   * owner:  jonas => anonymous
    133   * cc:  daniel@example.com =>
    134          daniel@example.com, jonas@example.com
    135   * status:  new => assigned
    136 
    137 Comment:
    138 I'm interested too!
    139 
    140 --
    141 Ticket URL: <http://example.com/trac/ticket/42>
    142 My Project <http://myproj.example.com/>
    143 }}}
    144 
    145 == Customizing e-mail content for MS Outlook
    146 
    147 MS 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].
    148 
    149 Replace the following second row in the template:
    150 {{{
    151 $ticket_props
    152 }}}
    153 
    154 with this (requires Python 2.6 or later):
    155 {{{
    156 --------------------------------------------------------------------------
    157 {% with
    158    pv = [(a[0].strip(), a[1].strip()) for a in [b.split(':') for b in
    159          [c.strip() for c in
    160           ticket_props.replace('|', '\n').splitlines()[1:-1]] if ':' in b]];
    161    sel = ['Reporter', 'Owner', 'Type', 'Status', 'Priority', 'Milestone',
    162           'Component', 'Severity', 'Resolution', 'Keywords'] %}\
    163 ${'\n'.join('%s\t%s' % (format(p[0]+':', ' <12'), p[1]) for p in pv if p[0] in sel)}
    164 {% end %}\
    165 --------------------------------------------------------------------------
    166 }}}
    167 
    168 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.
    169 {{{#!div style="margin: 1em 1.75em; border:1px dotted"
    170 {{{#!html
    171 #42: testing<br />
    172 --------------------------------------------------------------------------<br />
    173 <table cellpadding=0>
    174 <tr><td>Reporter:</td><td>jonas@example.com</td></tr>
    175 <tr><td>Owner:</td><td>anonymous</td></tr>
    176 <tr><td>Type:</td><td>defect</td></tr>
    177 <tr><td>Status:</td><td>assigned</td></tr>
    178 <tr><td>Priority:</td><td>lowest</td></tr>
    179 <tr><td>Milestone:</td><td>0.9</td></tr>
    180 <tr><td>Component:</td><td>report system</td></tr>
    181 <tr><td>Severity:</td><td>major</td></tr>
    182 <tr><td>Resolution:</td><td> </td></tr>
    183 <tr><td>Keywords:</td><td> </td></tr>
    184 </table>
    185 --------------------------------------------------------------------------<br />
    186 Changes:<br />
    187 <br />
    188 &nbsp;&nbsp;* component: &nbsp;changeset view =&gt; search system<br />
    189 &nbsp;&nbsp;* priority: &nbsp;low =&gt; highest<br />
    190 &nbsp;&nbsp;* owner: &nbsp;jonas =&gt; anonymous<br />
    191 &nbsp;&nbsp;* cc: &nbsp;daniel@example.com =&gt;<br />
    192 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;daniel@example.com, jonas@example.com<br />
    193 &nbsp;&nbsp;* status: &nbsp;new =&gt; assigned<br />
    194 <br />
    195 Comment:<br />
    196 I'm interested too!<br />
    197 <br />
    198 --<br />
    199 Ticket URL: &lt;http://example.com/trac/ticket/42&gt;<br />
    200 My Project &lt;http://myproj.example.com/&gt;<br />
    201 }}}
    202 }}}
    203 
    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:
    205 {{{
    206    sel = ['Reporter', ..., 'Keywords', 'Custom1', 'Custom2']
    207 }}}
    208 
    209 However, the solution is still a workaround to an automatically HTML-formatted e-mail.
    210 
    211 == Using GMail as the SMTP relay host
    212 
    213 Use the following configuration snippet:
    214 {{{#!ini
    215 [notification]
    216 smtp_enabled = true
    217 use_tls = true
    218 mime_encoding = base64
    219 smtp_server = smtp.gmail.com
    220 smtp_port = 587
    221 smtp_user = user
    222 smtp_password = password
    223 }}}
    224 
    225 where ''user'' and ''password'' match an existing GMail account, ie the ones you use to log in on [http://gmail.com].
    226 
    227 Alternatively, you can use `smtp_port = 25`.[[br]]
    228 You 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
    231 
    232 If 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.
    233 
    234 Notification 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
    237 
    238 Typical error message:
    239 {{{#!sh
    240   ...
    241   File ".../smtplib.py", line 303, in connect
    242     raise socket.error, msg
    243   error: (13, 'Permission denied')
    244 }}}
    245 
    246 This 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.
    247 
    248 Many users get confused when their manual attempts to contact the SMTP server succeed:
    249 {{{#!sh
    250 telnet localhost 25
    251 }}}
    252 This is because a regular user may connect to the SMTP server, but the web server cannot:
    253 {{{#!sh
    254 sudo -u www-data telnet localhost 25
    255 }}}
    256 
    257 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 in the Trac [trac:MailingList MailingList] archive.
    258 
    259 Relevant ML threads:
    260  * SELinux: http://article.gmane.org/gmane.comp.version-control.subversion.trac.general/7518
    261 
    262 For SELinux in Fedora 10:
    263 {{{#!sh
    264 $ setsebool -P httpd_can_sendmail 1
    265 }}}
    266 
    267 === ''Suspected spam'' error
    268 
    269 Some SMTP servers may reject the notification email sent by Trac.
    270 
    271 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, change the default encoding to "quoted-printable" using the `mime_encoding` option.
    272 
    273 Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, stick with the Base64 encoding.
    274 
    275 ----
    276 See also: TracTickets, TracIni, TracGuide, [trac:TracDev/NotificationApi]

  • wiki/pages/TracPermissions

    r40226 r40534  
    1 = Trac Permissions
    2 [[TracGuideToc]]
    3 
    4 Trac uses a simple, case sensitive, permission system to control what users can and can't access.
    5 
    6 Permission privileges are managed using the [TracAdmin trac-admin] tool or the ''General / Permissions'' panel in the ''Admin'' tab of the web interface.
    7 
    8 In 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.
    9 
    10 Non-authenticated users accessing the system are assigned the name "anonymous". Assign permissions to the "anonymous" user to set privileges for anonymous/guest users. The parts of Trac that a user does not have the privileges for will not be displayed in the navigation.
    11 In 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".
    12 
    13 == Graphical Admin Tab
    14 
    15 To 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):
    16 {{{
    17   $ trac-admin /path/to/projenv permission add bob TRAC_ADMIN
    18 }}}
    19 
    20 Then, the user `bob` will be able to see the Admin tab, and can then access the permissions menu. This menu will allow you to perform all the following actions, but from the browser without requiring root access to the server (just the correct permissions for your user account). '''Use at least one lowercase character in user names, as all-uppercase names are reserved for permissions.'''
    21 
    22  1. [[Image(htdocs:../common/guide/admin.png)]]
    23  1. [[Image(htdocs:../common/guide/admin-permissions.png)]]
    24  1. [[Image(htdocs:../common/guide/admin-permissions-TICKET_ADMIN.png)]]
    25 
    26 An 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.
    27 
    28 From 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
    31 
    32 To 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.
    33 
    34 Otherwise, individual privileges can be assigned to users for the various different functional areas of Trac ('''note that the privilege names are case-sensitive'''):
    35 
    36 === Repository Browser
    37 
    38 || `BROWSER_VIEW` || View directory listings in the [wiki:TracBrowser repository browser] ||
    39 || `LOG_VIEW` || View revision logs of files and directories in the [wiki:TracBrowser repository browser] ||
    40 || `FILE_VIEW` || View files in the [wiki:TracBrowser repository browser] ||
    41 || `CHANGESET_VIEW` || View [wiki:TracChangeset repository check-ins] ||
    42 
    43 === Ticket System
    44 
    45 || `TICKET_VIEW` || View existing [wiki:TracTickets tickets] and perform [wiki:TracQuery ticket queries] ||
    46 || `TICKET_CREATE` || Create new [wiki:TracTickets tickets] ||
    47 || `TICKET_APPEND` || Add comments or attachments to [wiki:TracTickets tickets] ||
    48 || `TICKET_CHGPROP` || Modify [wiki:TracTickets ticket] properties (priority, assignment, keywords, etc.) with the following exceptions: edit description field, add/remove other users from cc field when logged in, and set email to pref ||
    49 || `TICKET_MODIFY` || Includes both `TICKET_APPEND` and `TICKET_CHGPROP`, and in addition allows resolving [wiki:TracTickets tickets]. Tickets can be assigned to users through a [TracTickets#Assign-toasDrop-DownList drop-down list] when the list of possible owners has been restricted. ||
    50 || `TICKET_EDIT_CC` || Full modify cc field ||
    51 || `TICKET_EDIT_DESCRIPTION` || Modify description field ||
    52 || `TICKET_EDIT_COMMENT` || Modify another user's comments. Any user can modify their own comments by default. ||
    53 || `TICKET_BATCH_MODIFY` || [wiki:TracBatchModify Batch modify] tickets ||
    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. ||
    55 
    56 Attention: the "view tickets" button appears with the `REPORT_VIEW` permission.
    57 
    58 === Roadmap
    59 
    60 || `MILESTONE_VIEW` || View milestones and assign tickets to milestones. ||
    61 || `MILESTONE_CREATE` || Create a new milestone ||
    62 || `MILESTONE_MODIFY` || Modify existing milestones ||
    63 || `MILESTONE_DELETE` || Delete milestones ||
    64 || `MILESTONE_ADMIN` || All `MILESTONE_*` permissions ||
    65 || `ROADMAP_VIEW` || View the [wiki:TracRoadmap roadmap] page, is not (yet) the same as MILESTONE_VIEW, see [trac:#4292 #4292] ||
    66 || `ROADMAP_ADMIN` || to be removed with [trac:#3022 #3022], replaced by MILESTONE_ADMIN ||
    67 
    68 === Reports
    69 
    70 || `REPORT_VIEW` || View [wiki:TracReports reports], i.e. the "view tickets" link. ||
    71 || `REPORT_SQL_VIEW` || View the underlying SQL query of a [wiki:TracReports report] ||
    72 || `REPORT_CREATE` || Create new [wiki:TracReports reports] ||
    73 || `REPORT_MODIFY` || Modify existing [wiki:TracReports reports] ||
    74 || `REPORT_DELETE` || Delete [wiki:TracReports reports] ||
    75 || `REPORT_ADMIN` || All `REPORT_*` permissions ||
    76 
    77 === Wiki System
    78 
    79 || `WIKI_VIEW` || View existing [wiki:TracWiki wiki] pages ||
    80 || `WIKI_CREATE` || Create new [wiki:TracWiki wiki] pages ||
    81 || `WIKI_MODIFY` || Change [wiki:TracWiki wiki] pages ||
    82 || `WIKI_RENAME` || Rename [wiki:TracWiki wiki] pages ||
    83 || `WIKI_DELETE` || Delete [wiki:TracWiki wiki] pages and attachments ||
    84 || `WIKI_ADMIN` || All `WIKI_*` permissions, plus the management of ''readonly'' pages. ||
    85 
    86 === Permissions
    87 
    88 || `PERMISSION_GRANT` || add/grant a permission ||
    89 || `PERMISSION_REVOKE` || remove/revoke a permission ||
    90 || `PERMISSION_ADMIN` || All `PERMISSION_*` permissions ||
    91 
    92 === Others
    93 
    94 || `TIMELINE_VIEW` || View the [wiki:TracTimeline timeline] page ||
    95 || `SEARCH_VIEW` || View and execute [wiki:TracSearch search] queries ||
    96 || `CONFIG_VIEW` || Enables additional pages on ''About Trac'' that show the current configuration or the list of installed plugins ||
    97 || `EMAIL_VIEW` || Shows email addresses even if [wiki:TracIni#trac-section trac show_email_addresses] configuration option is false ||
    98 
    99 == Creating New Privileges
    100 
    101 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  on the [wiki:TracIni#extra-permissions-section TracIni] page after enabling the component.
    102 
    103 == Granting Privileges
    104 
    105 You grant privileges to users using [wiki:TracAdmin trac-admin]. The current set of privileges can be listed with the following command:
    106 {{{
    107   $ trac-admin /path/to/projenv permission list
    108 }}}
    109 
    110 This command will allow the user ''bob'' to delete reports:
    111 {{{
    112   $ trac-admin /path/to/projenv permission add bob REPORT_DELETE
    113 }}}
    114 
    115 The `permission add` command also accepts multiple privilege names:
    116 {{{
    117   $ trac-admin /path/to/projenv permission add bob REPORT_DELETE WIKI_CREATE
    118 }}}
    119 
    120 Or add all privileges:
    121 {{{
    122   $ trac-admin /path/to/projenv permission add bob TRAC_ADMIN
    123 }}}
    124 
    125 == Permission Groups
    126 
    127 There are two built-in groups, "authenticated" and "anonymous".
    128 Any user who has not logged in is automatically in the "anonymous" group.
    129 Any user who has logged in is also in the "authenticated" group.
    130 The "authenticated" group inherits permissions from the "anonymous" group.
    131 For example, if the "anonymous" group has permission WIKI_MODIFY,
    132 it is not necessary to add the WIKI_MODIFY permission to the "authenticated" group as well.
    133 
    134 Custom groups may be defined that inherit permissions from the two built-in groups.
    135 
    136 Permissions can be grouped together to form roles such as ''developer'', ''admin'', etc.
    137 {{{
    138   $ trac-admin /path/to/projenv permission add developer WIKI_ADMIN
    139   $ trac-admin /path/to/projenv permission add developer REPORT_ADMIN
    140   $ trac-admin /path/to/projenv permission add developer TICKET_MODIFY
    141   $ trac-admin /path/to/projenv permission add bob developer
    142   $ trac-admin /path/to/projenv permission add john developer
    143 }}}
    144 
    145 Group 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'''.
    146 
    147 == Adding a New Group and Permissions
    148 Permission groups can be created by assigning a user to a group you wish to create, then assign permissions to that group.
    149 
    150 The following will add ''bob'' to the new group called ''beta_testers'' and then will assign WIKI_ADMIN permissions to that group. (Thus, ''bob'' will inherit the WIKI_ADMIN permission)
    151 {{{
    152    $ trac-admin /path/to/projenv permission add bob beta_testers
    153    $ trac-admin /path/to/projenv permission add beta_testers WIKI_ADMIN
    154 
    155 }}}
    156 
    157 == Removing Permissions
    158 
    159 Permissions can be removed using the 'remove' command. For example:
    160 
    161 This command will prevent the user ''bob'' from deleting reports:
    162 {{{
    163   $ trac-admin /path/to/projenv permission remove bob REPORT_DELETE
    164 }}}
    165 
    166 Just like `permission add`, this command accepts multiple privilege names.
    167 
    168 You can also remove all privileges for a specific user:
    169 {{{
    170   $ trac-admin /path/to/projenv permission remove bob '*'
    171 }}}
    172 
    173 Or one privilege for all users:
    174 {{{
    175   $ trac-admin /path/to/projenv permission remove '*' REPORT_ADMIN
    176 }}}
    177 
    178 == Default Permissions
    179 
    180 By 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.
    181 On the other hand, the `authenticated` users will have the permissions to ''create and modify tickets and wiki pages''.
    182 
    183 '''anonymous'''
    184 {{{
    185  BROWSER_VIEW
    186  CHANGESET_VIEW
    187  FILE_VIEW
    188  LOG_VIEW
    189  MILESTONE_VIEW
    190  REPORT_SQL_VIEW
    191  REPORT_VIEW
    192  ROADMAP_VIEW
    193  SEARCH_VIEW
    194  TICKET_VIEW
    195  TIMELINE_VIEW
    196  WIKI_VIEW
    197 }}}
    198 
    199 '''authenticated'''
    200 {{{
    201  TICKET_CREATE
    202  TICKET_MODIFY
    203  WIKI_CREATE
    204  WIKI_MODIFY 
    205 }}}
    206 ----
    207 See also: TracAdmin, TracGuide and TracFineGrainedPermissions

  • wiki/pages/TracPlugins

    r40226 r40534  
    1 [[PageOutline(2-5,Contents,pullout)]]
    2 
    3 = Trac plugins
    4 
    5 Trac 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 
    9 From 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 
    13 To use egg-based plugins in Trac, you need to have [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (version >= 0.6) installed.
    14 
    15 To install `setuptools`, download the bootstrap module [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py] and execute it as follows:
    16 
    17 {{{#!sh
    18 $ python ez_setup.py
    19 }}}
    20 
    21 If the `ez_setup.py` script fails to install the setuptools release, you can download it from [pypi:setuptools PyPI] and install it manually.
    22 
    23 Plugins can also consist of a single `.py` file dropped directly into either the project's or the shared `plugins` directory.
    24 
    25 == Installing a Trac plugin
    26 
    27 === For a single project
    28 
    29 Plugins are typically packaged as [http://peak.telecommunity.com/DevCenter/PythonEggs Python eggs]. That means they are .zip archives with the file extension `.egg`.
    30 
    31 If you have downloaded a source distribution of a plugin, and want to build the `.egg` file:
    32 
    33  * Unpack the source. It should provide `setup.py`.
    34  * Run:
    35  {{{#!sh
    36 $ python setup.py bdist_egg
    37 }}}
    38 
    39 You should now have an *.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, ie kill the process and run again.
    42 
    43 To uninstall a plugin installed this way, remove the egg from the `plugins` directory and restart the web server.
    44 
    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 
    53 Some 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 
    59 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:\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 
    63 If 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 }}}
    67 You should end up with a directory having the same name as the zipped egg, complete with `.egg` extension, and containing its uncompressed contents.
    68 
    69 Trac 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
    72 
    73 `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:
    74 {{{#!sh
    75 $ easy_install http://svn.edgewall.com/repos/trac/plugins/0.12/spam-filter-captcha
    76 }}}
    77 
    78 ==== Enabling the plugin
    79 
    80 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, ie the path specified in the `[inherit] plugins_dir` configuration option.
    81 
    82 This is done in the `[components]` section of the configuration file `trac.ini`. For example:
    83 {{{#!ini
    84 [components]
    85 tracspamfilter.* = enabled
    86 }}}
    87 
    88 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`.
    89 
    90 After installing the plugin, you must restart your web server.
    91 
    92 ==== Uninstalling
    93 
    94 Neither `easy_install` nor `python setup.py` have an uninstall feature. However, it is usually trivial to remove a globally installed egg and reference:
    95 
    96  1. Do `easy_install -m [plugin name]` to remove references from `$PYTHONLIB/site-packages/easy-install.pth` when the plugin installed by setuptools.
    97  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`.
    98  1. Delete the .egg file or folder from where it's installed, usually inside `$PYTHONLIB/site-packages/`.
    99  1. Restart the web server.
    100 
    101 If 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
    103 >>> import myplugin
    104 >>> print myplugin.__file__
    105 /opt/local/python24/lib/site-packages/myplugin-0.4.2-py2.4.egg/myplugin/__init__.pyc
    106 }}}
    107 
    108 == Setting up the plugin cache
    109 
    110 Some 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.
    111 
    112 To do this from the Apache configuration, use the `SetEnv` directive:
    113 {{{#!apache
    114 SetEnv PYTHON_EGG_CACHE /path/to/dir
    115 }}}
    116 
    117 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], ie in the same `<Location>` block.
    118 
    119 For example for CGI:
    120 {{{#!apache
    121  <Location /trac>
    122    SetEnv TRAC_ENV /path/to/projenv
    123    SetEnv PYTHON_EGG_CACHE /path/to/dir
    124  </Location>
    125 }}}
    126 
    127 Or for mod_python:
    128 {{{#!apache
    129  <Location /trac>
    130    SetHandler mod_python
    131    ...
    132    SetEnv PYTHON_EGG_CACHE /path/to/dir
    133  </Location>
    134 }}}
    135 
    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.
    137 
    138 For [wiki:TracFastCgi FastCGI], you'll need to `-initial-env` option, or whatever is provided by your web server for setting environment variables.
    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
    143 FastCgiConfig -initial-env TRAC_ENV=/var/lib/trac -initial-env PYTHON_EGG_CACHE=/var/lib/trac/plugin-cache
    144 }}}
    145 
    146 === About hook scripts
    147 
    148 If 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 
    152 The [trac:WebAdmin] interface offers limited support for plugin configuration through the web to users with `TRAC_ADMIN` permission:
    153 
    154 * en/disabling installed plugins
    155 * installing plugins by uploading them as eggs
    156 
    157 If you wish to disable the second function for security reasons, add the following to your `trac.ini` file:
    158 {{{#!ini
    159 [components]
    160 trac.admin.web_ui.PluginAdminPanel = disabled
    161 }}}
    162 This disables the whole panel, so the first function will no longer be available either.
    163 
    164 == Troubleshooting
    165 
    166 === Is setuptools properly installed?
    167 
    168 Try this from the command line:
    169 {{{#!sh
    170 $ python -c "import pkg_resources"
    171 }}}
    172 
    173 If 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 
    177 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).
    178 
    179 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.
    180 
    181 === Is the plugin enabled?
    182 
    183 If 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 
    192 Trac must be able to read the .egg file.
    193 
    194 === Check the log files
    195 
    196 Enable [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 
    200 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.
    201 
    202 === Is the wrong version of the plugin loading?
    203 
    204 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:
    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 
    213 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!
    214 
    215 ----
    216 See also TracGuide, [trac:PluginList plugin list], [trac:TracDev/ComponentArchitecture component architecture].

  • wiki/pages/TracQuery

    r40226 r40534  
    1 = Trac Ticket Queries
    2 [[TracGuideToc]]
    3 
    4 In addition to [wiki:TracReports reports], Trac provides support for ''custom ticket queries'', which can be used to display tickets that meet specified criteria.
    5 
    6 To configure and execute a custom query, switch to the ''View Tickets'' module from the navigation bar, and select the ''Custom Query'' link.
    7 
    8 == Filters
    9 
    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 in and no name/email is defined in the preferences, then all open issues are displayed.
    14 
    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'' on the criteria.
    16 
    17 You 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.
    18 
    19 After you have edited your filters, click the ''Update'' button to refresh your results.
    20 
    21 == Navigating Tickets
    22 
    23 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. 
    24 
    25 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.
    26 
    27 The query results can be refreshed and cleared of these status indicators by clicking the ''Update'' button again.
    28 
    29 == Saving Queries
    30 
    31 Trac 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.
    32 You can also save references to queries in Wiki content, as described below.
    33 
    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.
    35 
    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.
    37 
    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.
    41 {{{
    42 [query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0]
    43 }}}
    44 
    45 Which is displayed as:
    46   [query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0]
    47 
    48 This uses a very simple query language to specify the criteria, see [wiki:TracQuery#QueryLanguage Query Language].
    49 
    50 Alternatively, you can copy the query string of a query and paste that into the Wiki link, including the leading `?` character:
    51 {{{
    52 [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]
    53 }}}
    54 
    55 Which is displayed as:
    56   [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]
    57 
    58 === Customizing the ''table'' format
    59 
    60 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 in by placing pipes (`|`) between the columns:
    61 {{{
    62 [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]]
    63 }}}
    64 
    65 This is displayed as:
    66 [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]]
    67 
    68 ==== Full rows
    69 
    70 In ''table'' format you can also have full rows by using ''rows=<field>'':
    71 {{{
    72 [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]]
    73 }}}
    74 
    75 This is displayed as:
    76 [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]]
    77 
    78 == Query Language
    79 
    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 (`\`).
    81 
    82 The available operators are:
    83 || '''`=`''' || the field content exactly matches one of the values ||
    84 || '''`~=`''' || the field content contains one or more of the values ||
    85 || '''`^=`''' || the field content starts with one of the values ||
    86 || '''`$=`''' || the field content ends with one of the values ||
    87 
    88 All of these operators can also be negated:
    89 || '''`!=`''' || the field content matches none of the values ||
    90 || '''`!~=`''' || the field content does not contain any of the values ||
    91 || '''`!^=`''' || the field content does not start with any of the values ||
    92 || '''`!$=`''' || the field content does not end with any of the values ||
    93 
    94 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 omitted to avoid having to quote the query string.
    95 || '''`created=2007-01-01..2008-01-01`''' || query tickets created in 2007 ||
    96 || '''`created=lastmonth..thismonth`''' || query tickets created during the previous month ||
    97 || '''`modified=1weekago..`''' || query tickets that have been modified in the last week ||
    98 || '''`modified=..30daysago`''' || query tickets that have been inactive for the last 30 days ||
    99 
    100 ----
    101 See also: TracTickets, TracReports, TracGuide, TicketQuery

  • wiki/pages/TracReports

    r40226 r40534  
    1 = Trac Reports =
    2 [[TracGuideToc]]
    3 
    4 The Trac reports module provides a simple, yet powerful reporting facility
    5 to present information about tickets in the Trac database.
    6 
    7 Rather than have its own report definition format, TracReports relies on standard SQL
    8 `SELECT` statements for custom report definition.
    9 
    10   '''Note:''' ''The report module is being phased out in its current form because it seriously limits the ability of the Trac team to make adjustments to the underlying database schema. We believe that the [wiki:TracQuery query module] is a good replacement that provides more flexibility and better usability. While there are certain reports that cannot yet be handled by the query module, we intend to further enhance it so that at some point the reports module can be completely removed. This also means that there will be no major enhancements to the report module anymore.''
    11 
    12   ''You can already completely replace the reports module by the query module simply by disabling the former in [wiki:TracIni trac.ini]:''
    13   {{{
    14   [components]
    15   trac.ticket.report.* = disabled
    16   }}}
    17   ''This will make the query module the default handler for the “View Tickets” navigation item. We encourage you to try this configuration and report back what kind of features of reports you are missing, if any.''
    18 
    19 A report consists of these basic parts:
    20  * '''ID''' — Unique (sequential) identifier
    21  * '''Title''' — Descriptive title
    22  * '''Description''' — A brief description of the report, in WikiFormatting text.
    23  * '''Report Body''' — List of results from report query, formatted according to the methods described below.
    24  * '''Footer''' — Links to alternative download formats for this report.
    25 
    26 == Changing Sort Order ==
    27 Simple reports - ungrouped reports to be specific - can be changed to be sorted by any column simply by clicking the column header.
    28 
    29 If a column header is a hyperlink (red), click the column you would like to sort by. Clicking the same header again reverses the order.
    30 
    31 == 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:
    33  * id integer PRIMARY KEY
    34  * author text
    35  * title text
    36  * query text
    37  * description text
    38 Changing the ID changes the shown order and number in the ''Available Reports'' list and the report's perma-link. This is done by running something like:
    39 {{{
    40 update report set id=5 where id=3;
    41 }}}
    42 Keep in mind that the integrity has to be maintained (i.e., ID has to be unique, and you don't want to exceed the max, since that's managed by SQLite someplace).
    43 
    44 You may also need to update or remove the report number stored in the report or query.
    45 
    46 == Navigating Tickets ==
    47 Clicking 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.
    48 
    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).
    50 
    51 == Alternative Download Formats ==
    52 Aside from the default HTML view, reports can also be exported in a number of alternative formats.
    53 At the bottom of the report page, you will find a list of available data formats. Click the desired link to
    54 download the alternative report format.
    55 
    56 === Comma-delimited - CSV (Comma Separated Values) ===
    57 Export the report as plain text, each row on its own line, columns separated by a single comma (',').
    58 '''Note:''' The output is fully escaped so carriage returns, line feeds, and commas will be preserved in the output.
    59 
    60 === Tab-delimited ===
    61 Like above, but uses tabs (\t) instead of comma.
    62 
    63 === RSS - XML Content Syndication ===
    64 All reports support syndication using XML/RSS 2.0. To subscribe to an RSS feed, click the orange 'XML' icon at the bottom of the page. See TracRss for general information on RSS support in Trac.
    65 
    66 ----
    67 
    68 == Creating Custom Reports ==
    69 
    70 ''Creating a custom report requires a comfortable knowledge of SQL.''
    71 
    72 '''Note that you need to set up [TracPermissions#Reports permissions] in order to see the buttons for adding or editing reports.'''
    73 
    74 A report is basically a single named SQL query, executed and presented by
    75 Trac.  Reports can be viewed and created from a custom SQL expression directly
    76 in the web interface.
    77 
    78 Typically, a report consists of a SELECT-expression from the 'ticket' table,
    79 using the available columns and sorting the way you want it.
    80 
    81 == Ticket columns ==
    82 The ''ticket'' table has the following columns:
    83  * id
    84  * type
    85  * time
    86  * changetime
    87  * component
    88  * severity 
    89  * priority
    90  * owner
    91  * reporter
    92  * cc
    93  * version
    94  * milestone
    95  * status
    96  * resolution
    97  * summary
    98  * description
    99  * keywords
    100 
    101 See TracTickets for a detailed description of the column fields.
    102 
    103 Example: '''All active tickets, sorted by priority and time'''
    104 {{{
    105 SELECT id AS ticket, status, severity, priority, owner,
    106        time AS created, summary FROM ticket
    107   WHERE status IN ('new', 'assigned', 'reopened')
    108   ORDER BY priority, time
    109 }}}
    110 
    111 Dynamic variables can also be used in the report title and description (since 1.1.1).
    112 
    113 == Advanced Reports: Dynamic Variables ==
    114 For more flexible reports, Trac supports the use of ''dynamic variables'' in report SQL statements.
    115 In short, dynamic variables are ''special'' strings that are replaced by custom data before query execution.
    116 
    117 === Using Variables in a Query ===
    118 The syntax for dynamic variables is simple, any upper case word beginning with '$' is considered a variable.
    119 
    120 Example:
    121 {{{
    122 SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY
    123 }}}
    124 
    125 To assign a value to $PRIORITY when viewing the report, you must define it as an argument in the report URL, leaving out the leading '$'.
    126 
    127 Example:
    128 {{{
    129  http://trac.edgewall.org/reports/14?PRIORITY=high
    130 }}}
    131 
    132 To use multiple variables, separate them with an '&'.
    133 
    134 Example:
    135 {{{
    136  http://trac.edgewall.org/reports/14?PRIORITY=high&SEVERITY=critical
    137 }}}
    138 
    139 
    140 === !Special/Constant Variables ===
    141 There is one dynamic variable whose value is set automatically (the URL does not have to be changed) to allow practical reports.
    142 
    143  * $USER — Username of logged in user.
    144 
    145 Example (''List all tickets assigned to me''):
    146 {{{
    147 SELECT id AS ticket,summary FROM ticket WHERE owner=$USER
    148 }}}
    149 
    150 
    151 
    152 == Advanced Reports: Custom Formatting ==
    153 Trac is also capable of more advanced reports, including custom layouts,
    154 result grouping and user-defined CSS styles. To create such reports, we'll use
    155 specialized SQL statements to control the output of the Trac report engine.
    156 
    157 === Special Columns ===
    158 To format reports, TracReports looks for 'magic' column names in the query
    159 result. These 'magic' names are processed and affect the layout and style of the
    160 final report.
    161 
    162 === Automatically formatted columns ===
    163  * '''ticket''' — Ticket ID number. Becomes a hyperlink to that ticket.
    164  * '''id''' — same as '''ticket''' above when '''realm''' is not set
    165  * '''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
    167  * '''created, modified, date, time''' — Format cell as a date and/or time.
    168  * '''description''' — Ticket description field, parsed through the wiki engine.
    169 
    170 '''Example:'''
    171 {{{
    172 SELECT id AS ticket, created, status, summary FROM ticket
    173 }}}
    174 
    175 Those columns can also be defined but marked as hidden, see [#column-syntax below].
    176 
    177 See trac:wiki/CookBook/Configuration/Reports for some example of creating reports for realms other than ''ticket''.
    178 
    179 === Custom formatting columns ===
    180 Columns whose names begin and end with 2 underscores (Example: '''`__color__`''') are
    181 assumed to be ''formatting hints'', affecting the appearance of the row.
    182  
    183  * '''`__group__`''' — Group results based on values in this column. Each group will have its own header and table.
    184  * '''`__grouplink__`''' — Make the header of each group a link to the specified URL. The URL is taken from the first row of each group.
    185  * '''`__color__`''' — Should be a numeric value ranging from 1 to 5 to select a pre-defined row color. Typically used to color rows by issue priority.
    186 {{{
    187 #!html
    188 <div style="margin-left:7.5em">Defaults:
    189 <span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fdc; border-color: #e88; color: #a22">Color 1</span>
    190 <span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #ffb; border-color: #eea; color: #880">Color 2</span>
    191 <span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fbfbfb; border-color: #ddd; color: #444">Color 3</span>
    192 <span style="border: none; color: #333; background: transparent; font-size: 85%; background: #e7ffff; border-color: #cee; color: #099">Color 4</span>
    193 <span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #e7eeff; border-color: #cde; color: #469">Color 5</span>
    194 </div>
    195 }}}
    196  * '''`__style__`''' — A custom CSS style expression to use on the `<tr>` element of the current row.
    197  * '''`__class__`''' — Zero or more space-separated CSS class names to be set on the `<tr>` element of the current row. These classes are added to the class name derived from `__color__` and the odd / even indicator.
    198 
    199 '''Example:''' ''List active tickets, grouped by milestone, group header linked to milestone page, colored by priority''
    200 {{{
    201 SELECT p.value AS __color__,
    202      t.milestone AS __group__,
    203      '../milestone/' || t.milestone AS __grouplink__,
    204      (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__,
    205        t.id AS ticket, summary
    206   FROM ticket t,enum p
    207   WHERE t.status IN ('new', 'assigned', 'reopened')
    208     AND p.name=t.priority AND p.type='priority'
    209   ORDER BY t.milestone, p.value, t.severity, t.time
    210 }}}
    211 
    212 '''Note:''' A table join is used to match ''ticket'' priorities with their
    213 numeric representation from the ''enum'' table.
    214 
    215 === Changing layout of report rows === #column-syntax
    216 By default, all columns on each row are display on a single row in the HTML
    217 report, possibly formatted according to the descriptions above. However, it's
    218 also possible to create multi-line report entries.
    219 
    220  * '''`column_`''' — ''Break row after this''. By appending an underscore ('_') to the column name, the remaining columns will be continued on a second line.
    221 
    222  * '''`_column_`''' — ''Full row''. By adding an underscore ('_') both at the beginning and the end of a column name, the data will be shown on a separate row.
    223 
    224  * '''`_column`''' — ''Hide data''. Prepending an underscore ('_') to a column name instructs Trac to hide the contents from the HTML output. This is useful for information to be visible only if downloaded in other formats (like CSV or RSS/XML).
    225    This can be used to hide any kind of column, even important ones required for identifying the resource, e.g. `id as _id` will hide the '''Id''' column but the link to the ticket will be present.
    226 
    227 '''Example:''' ''List active tickets, grouped by milestone, colored by priority, with  description and multi-line layout''
    228 
    229 {{{
    230 SELECT p.value AS __color__,
    231        t.milestone AS __group__,
    232        (CASE owner
    233           WHEN 'daniel' THEN 'font-weight: bold; background: red;'
    234           ELSE '' END) AS __style__,
    235        t.id AS ticket, summary AS summary_,             -- ## Break line here
    236        component,version, severity, milestone, status, owner,
    237        time AS created, changetime AS modified,         -- ## Dates are formatted
    238        description AS _description_,                    -- ## Uses a full row
    239        changetime AS _changetime, reporter AS _reporter -- ## Hidden from HTML output
    240   FROM ticket t,enum p
    241   WHERE t.status IN ('new', 'assigned', 'reopened')
    242     AND p.name=t.priority AND p.type='priority'
    243   ORDER BY t.milestone, p.value, t.severity, t.time
    244 }}}
    245 
    246 === Reporting on custom fields ===
    247 
    248 If 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.
    249 
    250 If 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.
    251 
    252 === A note about SQL rewriting #rewriting
    253 
    254 Beyond the relatively trivial replacement of dynamic variables, the SQL query is also altered in order to support two features of the reports:
    255  1. [#sort-order changing the sort order]
    256  2. pagination support (limitation of the number of result rows displayed on each page)
    257 In order to support the first feature, the sort column is inserted in the `ORDER BY` clause in the first position or in the second position if a `__group__` column is specified (an `ORDER BY` clause is created if needed). In order to support pagination, a `LIMIT ... OFFSET ...` clause is appended.
    258 The query might be too complex for the automatic rewrite to work correctly, resulting in an erroneous query. In this case you still have the possibility to control exactly how the rewrite is done by manually inserting the following tokens:
    259  - `@SORT_COLUMN@`, the place where the name of the selected sort column will be inserted,
    260  - `@LIMIT_OFFSET@`, the place where the pagination support clause will be added
    261 Note that if you write them after an SQL comment, `--`, you'll effectively disable rewriting if this is what you want!
    262 
    263 Let's take an example, consider the following SQL query:
    264 {{{
    265 -- ## 4: Assigned, Active Tickets by Owner ## --
    266 
    267 --
    268 -- List assigned tickets, group by ticket owner, sorted by priority.
    269 --
    270 
    271 SELECT p.value AS __color__,
    272    owner AS __group__,
    273    id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
    274    changetime AS _changetime, description AS _description,
    275    reporter AS _reporter
    276   FROM ticket t,enum p
    277   WHERE status = 'assigned'
    278 AND p.name=t.priority AND p.type='priority'
    279   ORDER BY __group__, p.value, severity, time
    280 }}}
    281 
    282 The automatic rewrite will be the following (4 rows per page, page 2, sorted by `component`):
    283 {{{
    284 SELECT p.value AS __color__,
    285    owner AS __group__,
    286    id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
    287    changetime AS _changetime, description AS _description,
    288    reporter AS _reporter
    289   FROM ticket t,enum p
    290   WHERE status = 'assigned'
    291 AND p.name=t.priority AND p.type='priority'
    292   ORDER BY __group__ ASC, `component` ASC,  __group__, p.value, severity, time
    293  LIMIT 4 OFFSET 4
    294 }}}
    295 
    296 The equivalent SQL query with the rewrite tokens would have been:
    297 {{{
    298 SELECT p.value AS __color__,
    299    owner AS __group__,
    300    id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
    301    changetime AS _changetime, description AS _description,
    302    reporter AS _reporter
    303   FROM ticket t,enum p
    304   WHERE status = 'assigned'
    305 AND p.name=t.priority AND p.type='priority'
    306   ORDER BY __group__, @SORT_COLUMN@, p.value, severity, time
    307 @LIMIT_OFFSET@
    308 }}}
    309 
    310 If you want to always sort first by priority and only then by the user selected sort column, simply use the following `ORDER BY` clause:
    311 {{{
    312   ORDER BY __group__, p.value, @SORT_COLUMN@, severity, time
    313 }}}
    314 
    315 ----
    316 See also: TracTickets, TracQuery, TracGuide, [http://www.sqlite.org/lang_expr.html Query Language Understood by SQLite]

  • wiki/pages/TracRepositoryAdmin

    r40226 r40534  
    1 = Repository Administration
    2 [[PageOutline(2-3)]]
    3 
    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].
    8  * 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.
    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 
    13 Support 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 
    15 The 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
    18 tracopt.versioncontrol.svn.* = enabled
    19 }}}
    20 
    21 {{{#!ini
    22 tracopt.versioncontrol.git.* = enabled
    23 }}}
    24 
    25 == Specifying repositories #Repositories
    26 Trac 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 
    28 It 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 
    30 A 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:
    31 
    32 ||='''Attribute''' =||='''Description''' =||
    33 ||`alias` ||\
    34 ||A repository having an `alias` attribute is an alias to a real repository. All TracLinks referencing the alias resolve to the aliased repository. Note that multiple indirection is not supported, so an alias must always point to a real repository. The `alias` and `dir` attributes are mutually exclusive. ||
    35 ||`description` ||\
    36 ||The text specified in the `description` attribute is displayed below the top-level entry for the repository in the source browser. It supports WikiFormatting. ||
    37 ||`dir` ||\
    38 ||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. ||
    39 ||`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`.||
    41 ||`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. ||
    42 ||`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. ||
    43 
    44 A repository `name` and one of `alias` or `dir` attributes are mandatory. All others are optional.
    45 
    46 For 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 
    48 After adding a repository, the cache for that repository must be re-synchronized once with the `trac-admin $ENV repository resync` command.
    49 
    50  `repository resync <repos>`::
    51    Re-synchronize Trac with a repository.
    52 
    53 
    54 === In `trac.ini` #ReposTracIni
    55 Repositories 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.
    56 
    57 The main advantage of specifying repositories in `trac.ini` is that they can be inherited from a global configuration (see the [wiki:TracIni#GlobalConfiguration global configuration] section of TracIni). One drawback is that, due to limitations in the `ConfigParser` class used to parse `trac.ini`, the repository name is always all-lowercase.
    58 
    59 The 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.
    60 {{{#!ini
    61 [repositories]
    62 project.dir = /var/repos/project
    63 project.description = This is the ''main'' project repository.
    64 project.type = svn
    65 project.url = http://example.com/svn/project
    66 project.hidden = true
    67 
    68 lib.dir = /var/repos/lib
    69 lib.description = This is the secondary library code.
    70 lib.type = svn
    71 lib.url = http://example.com/svn/lib
    72 
    73 .alias = project
    74 }}}
    75 Note that `name.alias = target` makes `name` an alias for the `target` repo, not the other way around.
    76 
    77 === In the database #ReposDatabase
    78 Repositories can also be specified in the database, using either the "Repositories" admin panel under "Version Control", or the `trac-admin $ENV repository` commands.
    79 
    80 The admin panel shows the list of all repositories defined in the Trac environment. It allows adding repositories and aliases, editing repository attributes and removing repositories. Note that repositories defined in `trac.ini` are displayed but cannot be edited.
    81 
    82 The following [wiki:TracAdmin trac-admin] commands can be used to perform repository operations from the command line.
    83 
    84  `repository add <repos> <dir> [type]`::
    85    Add a repository `<repos>` located at `<dir>`, and optionally specify its type.
    86 
    87  `repository alias <name> <target>`::
    88    Create an alias `<name>` for the repository `<target>`.
    89 
    90  `repository remove <repos>`::
    91    Remove the repository `<repos>`.
    92 
    93  `repository set <repos> <key> <value>`::
    94    Set the attribute `<key>` to `<value>` for the repository `<repos>`.
    95 
    96 Note 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.
    97 
    98 == Repository caching
    99 
    100 The 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 
    102 Subversion 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
    105 Prior 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.
    106 
    107 There 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.
    108 
    109 === Mercurial Repositories
    110 Please note that at the time of writing, no initial resynchronization or any hooks are necessary for Mercurial repositories - see [trac:#9485] for more information.
    111 
    112 === Explicit synchronization #ExplicitSync
    113 This 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.
    114 
    115  `changeset added <repos> <rev> [...]`::
    116    Notify Trac that one or more changesets have been added to a repository.
    117 
    118  `changeset modified <repos> <rev> [...]`::
    119    Notify Trac that metadata on one or more changesets in a repository has been modified.
    120 
    121 The `<repos>` argument can be either a repository name (use "`(default)`" for the default repository) or the path to the repository.
    122 
    123 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.
    124 
    125 ==== Subversion
    126 
    127 The 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`):
    128 {{{#!sh
    129 #!/bin/sh
    130 export PYTHON_EGG_CACHE="/path/to/dir"
    131 /usr/bin/trac-admin /path/to/env changeset added "$1" "$2"
    132 }}}
    133 Note: Check with `whereis trac-admin`, whether `trac-admin` is really installed under `/usr/bin/` or maybe under `/usr/local/bin/` and adapt the path.
    134 On Windows (`post-commit.cmd`):
    135 {{{#!bat
    136 @C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset added "%1" "%2"
    137 }}}
    138 
    139 The post-revprop-change hook for Subversion is very similar. On Unix (`post-revprop-change`):
    140 {{{#!sh
    141 #!/bin/sh
    142 export PYTHON_EGG_CACHE="/path/to/dir"
    143 /usr/bin/trac-admin /path/to/env changeset modified "$1" "$2"
    144 }}}
    145 On Windows (`post-revprop-change.cmd`):
    146 {{{#!bat
    147 @C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset modified "%1" "%2"
    148 }}}
    149 
    150 The Unix variants above assume that the user running the Subversion commit has write access to the Trac environment, which is the case in the standard configuration where both the repository and Trac are served by the web server. If you access the repository through another means, for example `svn+ssh://`, you may have to run `trac-admin` with different privileges, for example by using `sudo`.
    151 
    152 Note that calling `trac-admin` in your Subversion hooks can slow down the commit and log editing operations on the client side. You might want to use the [trac:source:trunk/contrib/trac-svn-hook contrib/trac-svn-hook] script which starts `trac-admin` in an asynchronous way. The script also comes with a number of safety checks and usage advices which should make it easier to set up and test your hooks. There's no equivalent `trac-svn-hook.bat` for Windows yet, but the script can be run by Cygwin's bash.
    153 
    154 See 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.
    155 
    156 ==== Git
    157 
    158 Git hooks can be used in the same way for explicit syncing of Git repositories.  If your git repository is one that gets committed to directly on the machine that hosts trac, add the following to the `hooks/post-commit` file in your git repo (note: this will do nothing if you only update the repo by pushing to it):
    159 {{{#!sh
    160 #!/bin/sh
    161 REV=$(git rev-parse HEAD)
    162 trac-admin /path/to/env changeset added <repos> $REV
    163 }}}
    164 
    165 Alternately, if your repository is one that only gets pushed to, add the following to the `hooks/post-receive` file in the repo:
    166 {{{#!sh
    167 #!/bin/sh
    168 tracenv=/path/to/env     # change with your Trac environment's path
    169 repos=                   # change with your repository's name
    170 while read oldrev newrev refname; do
    171     if [ "$oldrev" = 0000000000000000000000000000000000000000 ]; then
    172         git rev-list --reverse "$newrev" --
    173     else
    174         git rev-list --reverse "$newrev" "^$oldrev" --
    175     fi | xargs trac-admin "$tracenv" changeset added "$repos"
    176 done
    177 }}}
    178 
    179 The `<repos>` argument can be either a repository name (use "`(default)`" for the default repository) or the path to the repository.
    180 
    181 ==== Mercurial
    182 
    183 For Mercurial, add the following entries to the `.hgrc` file of each repository accessed by Trac (if [trac:TracMercurial] is installed in a Trac `plugins` directory, download [trac:source:mercurial-plugin/tracext/hg/hooks.py hooks.py] and place it somewhere accessible):
    184 {{{#!ini
    185 [hooks]
    186 ; If mercurial-plugin is installed globally
    187 commit = python:tracext.hg.hooks.add_changesets
    188 changegroup = python:tracext.hg.hooks.add_changesets
    189 
    190 ; If mercurial-plugin is installed in a Trac plugins directory
    191 commit = python:/path/to/hooks.py:add_changesets
    192 changegroup = python:/path/to/hooks.py:add_changesets
    193 
    194 [trac]
    195 env = /path/to/env
    196 trac-admin = /path/to/trac-admin
    197 }}}
    198 
    199 === Per-request synchronization #PerRequestSync
    200 If the post-commit hooks are not available, the environment can be set up for per-request synchronization. In that case, the `sync_per_request` attribute for each repository in the database and in [wiki:TracIni#trac-section trac.ini] must be set to `false`.
    201 
    202 Note that in this case, the changeset listener extension point is not called, and therefore plugins using it will not work correctly.
    203 
    204 == Automatic changeset references in tickets
    205 
    206 You can automatically add a reference to the changeset as a ticket comment whenever changes are committed to the repository. The description of the commit needs to contain one of the following formulas:
    207  * '''`Refs #123`''' - to reference this changeset in `#123` ticket
    208  * '''`Fixes #123`''' - to reference this changeset and close `#123` ticket with the default status ''fixed''
    209 
    210 This functionality requires installing a post-commit hook as described in [#ExplicitSync], 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.
    211 {{{#!ini
    212 tracopt.ticket.commit_updater.* = enabled
    213 }}}
    214 For more information, see the documentation of the `CommitTicketUpdater` component in the //Plugins// admin panel and the [trac:CommitTicketUpdater] page.
    215 
    216 == Troubleshooting
    217 
    218 === My trac-post-commit-hook doesn't work anymore #trac-post-commit-hook
    219 
    220 You must now use the optional components from `tracopt.ticket.commit_updater.*`, which you can activate through the Plugins panel in the Administrative part of the web interface, or by directly modifying the [TracIni#components-section "[components]"] section in the trac.ini. Be sure to use [#ExplicitSync explicit synchronization] as explained above.

  • wiki/pages/TracRevisionLog

    r40226 r40534  
    1 = Viewing Revision Logs =
    2 [[TracGuideToc]]
    3 
    4 When you browse the repository, it is always possible to view the ''Revision Log'' that corresponds to the repository path. This displays a list of the most recent changesets in which the current path or any other path below it has been modified.
    5 
    6 == The Revision Log Form ==
    7 
    8 It is possible to set the revision at which the revision log should start, using the ''View log starting at'' field. An empty value or a value of ''head'' is interpreted as the newest changeset.
    9 
    10 It is also possible to specify the revision at which the log should stop, using the ''Back to'' field. By default it is empty,
    11 which means the revision log will show the latest 100 revisions.
    12 
    13 Also, there are three modes of operation of the revision log.
    14 
    15 By default, the revision log ''stops on copy'', which means that whenever an ''Add'', ''Copy'' or ''Rename'' operation is detected, no older revision will be shown. That's very convenient when working with branches, as one only sees the history corresponding to what has been done on the branch.
    16 
    17 It is also possible to indicate that one wants to see what happened before a ''Copy'' or ''Rename'' change, by selecting the
    18 ''Follow copies'' mode. This will cross all copies or renames changes.
    19 Each time the name of the path changes, there will be an additional indentation level. That way, the changes on the different paths are easily grouped together visually.
    20 
    21 It is even possible to go past an ''Add'' change, in order to see if there has been a ''Delete'' change on that path, before
    22 that ''Add''. This mode corresponds to the mode called ''Show only adds, moves and deletes''. This operation can be quite resource intensive and therefore take some time to be shown on screen.
    23 
    24 Finally, there's also a checkbox ''Show full log messages'', which controls whether the full content of the commit log message
    25 should be displayed for each change, or only a shortened version of it.
    26 
    27 == The Revision Log Information ==
    28 
    29 For each revision log entry, the following columns are displayed:
    30  1. The first column contains a pair of radio buttons and should be used
    31     for selecting the ''old'' and the ''new'' revisions that will be
    32     used for [wiki:TracRevisionLog#viewingtheactualchanges viewing the actual changes].
    33  1. A color code (similar to the one used for the
    34     [wiki:TracChangeset#ChangesetHeader changesets]) indicating kind of change.
    35     Clicking on this column refreshes the revision log so that it restarts
    36     with this change.
    37  1. The '''Revision''' number, displayed as `@xyz`.
    38     This is a link to the TracBrowser, using the displayed revision as the base line.
    39  Next to it, you can see a little "wheel" icon [[Image(htdocs:../common/changeset.png)]],  which is clickable and leads to the TracChangeset view for that revision.
    40  1. The '''Date''' at which the change was made.
    41     The date is displayed as the time elapsed from the date of the revision. The time
    42     elapsed is displayed as the number of hours, days, weeks, months, or years.
    43  1. The '''Author''' of the change.
    44  1. The '''Log Message''', which contains either the truncated or full commit
    45     log message, depending on the value of the ''Show full log messages''
    46     checkbox in the form above.
    47    
    48 
    49 == Inspecting Changes Between Revisions ==
    50 
    51 The ''View changes...'' buttons (placed above and below the list of changes, on the left side) will show the set of differences
    52 corresponding to the aggregated changes starting from the ''old'' revision (first radio-button) to the ''new'' revision (second
    53 radio-button), in the TracChangeset view.
    54 
    55 Note that the ''old'' revision doesn't need to be actually ''older'' than the ''new'' revision: it simply gives a base
    56 for the diff. It's therefore entirely possible to easily generate a ''reverse diff'', for reverting what has been done
    57 in the given range of revisions.
    58 
    59 Finally, if the two revisions are identical, the corresponding changeset will be shown. This has the same effect as clicking on the !ChangeSet number.
    60 
    61 == Alternative Formats ==
    62 
    63 === The !ChangeLog Text ===
    64 
    65 At the bottom of the page, there's a ''!ChangeLog'' link that will show the range of revisions as currently shown, but as a simple text, matching the usual conventions for !ChangeLog files.
    66 
    67 === RSS Support ===
    68 
    69 The revision log also provides a RSS feed to monitor the changes. To subscribe to a RSS feed for a file or directory, open its
    70 revision log in the browser and click the orange 'XML' icon at the bottom of the page. For more information on RSS support in Trac, see TracRss.
    71 
    72 ----
    73 See also: TracBrowser, TracChangeset, TracGuide

  • wiki/pages/TracRoadmap

    r40226 r40534  
    1 = The Trac Roadmap
    2 [[TracGuideToc]]
    3 
    4 The roadmap provides a view on the [wiki:TracTickets ticket system] that helps planning and managing the future development of a project.
    5 
    6 == The Roadmap View
    7 
    8 A roadmap is a list of future milestones. The roadmap can be filtered to show or hide ''completed milestones'' and ''milestones with no due date''. In the case that both ''show completed milestones'' and ''hide milestones with no due date'' are selected, ''completed'' milestones with no due date will be shown.
    9 
    10 == The Milestone View
    11 
    12 A milestone is a future timeframe in which tickets are expected to be solved. You can add a description to milestones (using WikiFormatting) describing main objectives, for example. In addition, tickets targeted for a milestone are aggregated, and the ratio between active and resolved tickets is displayed as a milestone progress bar. It is possible to further [trac:TracRoadmapCustomGroups customise the ticket grouping] and have multiple ticket statuses shown on the progress bar.
    13 
    14 It is possible to drill down into this simple statistic by viewing the individual milestone pages. By default, the active/resolved ratio will be grouped and displayed by component. You can also regroup the status by other criteria, such as ticket owner or severity. Ticket numbers are linked to [wiki:TracQuery custom queries] listing corresponding tickets.
    15 
    16 == Roadmap Administration
    17 
    18 With appropriate permissions it is possible to add, modify and remove milestones using either the web interface (roadmap and milestone pages), web administration interface or by using `trac-admin`.
    19 
    20 '''Note:''' Milestone descriptions can not currently be edited using 'trac-admin'.
    21 
    22 == iCalendar Support
    23 
    24 The Roadmap supports the [http://www.ietf.org/rfc/rfc2445.txt iCalendar] format to keep track of planned milestones and related tickets from your favorite calendar software. Many calendar applications support the iCalendar specification including
    25  * [http://www.apple.com/ical/ Apple iCal] for Mac OS X
    26  * the cross-platform [http://www.mozilla.org/projects/calendar/ Mozilla Calendar]
    27  * [http://chandlerproject.org Chandler]
    28  * [http://kontact.kde.org/korganizer/ Korganizer], the calendar application of the [http://www.kde.org/ KDE] project
    29  * [https://wiki.gnome.org/Apps/Evolution Evolution]
    30  * [http://office.microsoft.com/en-us/outlook/ Microsoft Outlook] can also read iCalendar files and appears as a new static calendar in Outlook
    31  * [https://www.google.com/calendar/ Google Calendar]
    32 
    33 To subscribe to the roadmap, copy the iCalendar link from the roadmap (found at the bottom of the page) and choose the "Subscribe to remote calendar" action (or similar) of your calendar application, and insert the URL just copied.
    34 
    35 '''Note:''' For tickets to be included in the calendar as tasks, you need to be logged in when copying the link. You will only see tickets assigned to yourself and associated with a milestone.
    36 
    37 '''Note:''' To include the milestones in Google Calendar you might need to rewrite the URL.
    38 {{{
    39 RewriteEngine on
    40 RewriteRule ([^/.]+)/roadmap/([^/.]+)/ics /$1/roadmap?user=$2&format=ics
    41 }}}
    42 
    43 More information about iCalendar can be found at [http://en.wikipedia.org/wiki/ICalendar Wikipedia].
    44 ----
    45 See also: TracTickets, TracReports, TracQuery, [trac:TracRoadmapCustomGroups]

  • wiki/pages/TracRss

    r40226 r40534  
    1 = Using RSS with Trac
    2 [[TracGuideToc]]
    3 
    4 Several of the Trac modules support content syndication using the RSS ([http://en.wikipedia.org/wiki/RSS Really Simple Syndication]) XML format. RSS pushes out updates to Trac whenever they occur and to whoever has subscribed to it. Using the RSS subscription feature in Trac, you can easily monitor progress of the project, a set of issues or even changes to a single file.
    5 
    6 Trac supports RSS feeds in:
    7 
    8  * TracTimeline — Use the RSS feed to '''subscribe to project events'''. Monitor overall project progress in your favorite RSS reader.
    9  * TracTickets, TracReports, and TracQuery — Allows syndication of report and ticket query results. Be notified about important and relevant issue tickets.
    10  * TracBrowser and TracRevisionLog — Syndication of file changes. Stay up to date with changes to a specific file or directory.
    11 
    12 == How to access RSS data
    13 Anywhere in Trac where RSS is available, you should find a small orange '''RSS''' icon, typically at the bottom of the page:
    14 {{{#!html
    15 <a rel="nofollow" style="padding-left: 20px; background: url(../../chrome/common/feed.png) left center no-repeat;  border: none;"><span style="color: #666;padding: 0 0 2px; font-size: 11px;">RSS feed</span></a>
    16 }}}
    17 Clicking the icon will access the RSS feed for that specific resource.
    18 
    19 '''Note:''' Different modules provide different data in their RSS feeds. Usually the syndicated information corresponds to the current view. For example, if you click the RSS link on a report page, the feed will be based on that report. It might be explained by thinking of the RSS feeds as an ''alternate view of the data currently displayed''.
    20 
    21 Since Trac 1.0 an RSS feed can be retrieved from a Trac site that requires authentication. Hover over the RSS icon, right click and //copy link address//.
    22 
    23 == Links
    24  * ''Specifications:''
    25    * http://blogs.law.harvard.edu/tech/rss — RSS 2.0 Specification.
    26 
    27  * ''Multi-platform RSS readers:''
    28    * http://www.rssowl.org/ — Open source, Eclipse-based, RSS reader for Linux, Mac and Windows systems that supports https and authenticated feeds.
    29 
    30  * ''Linux/BSD/*n*x systems:''
    31    * http://liferea.sourceforge.net/ — Open source GTK2 RSS Reader for Linux.
    32    * [http://akregator.sourceforge.net/ Akregator] — Open source KDE RSS Reader, part of KDE-PIM.
    33 
    34  * ''Mac OS X systems:''
    35    * http://ranchero.com/netnewswire/ — An excellent RSS reader for Mac OS X, has both free and paid versions.
    36    * http://www.utsire.com/shrook/ — An RSS reader for Max OS X that supports https, even with self signed certificates, and authenticated feeds.
    37    * http://vienna-rss.sourceforge.net/ — Open source Feed Reader for Mac OS X with smart folders support.
    38 
    39  * ''Windows systems:''
    40    * http://www.rssreader.com/ — Free and powerful RSS Reader for MS Windows.
    41    * http://www.sharpreader.net/ — A free RSS Reader written in .NET for MS Windows.
    42 
    43  * ''Firefox:''
    44    * http://www.mozilla.org/products/firefox/ — Mozilla Firefox features plenty [https://addons.mozilla.org/en-US/firefox/search/?q=rss&appver=&platform= add-ons] for supporting RSS.
    45 
    46 ----
    47 See also: TracGuide, TracTimeline, TracReports, TracBrowser

  • wiki/pages/TracSearch

    r40226 r40534  
    1 = Using Search
    2 
    3 Trac has built-in search functionality to search for occurrences of keywords and substrings in wiki pages, tickets and changeset properties, such as author, revision and log messages.
    4 
    5 Apart from the [search: Search module], you will also find a small search field above the navigation bar at all time. It provides convenient access to the search module from all pages.
    6 
    7 The search results show the most recent modifications ranked first rather than the most relevant result.
    8 
    9 == Quick searches
    10 For quick access to project resources, the quick-search field at the top of every page can be used to enter a [TracLinks wiki link], which will take you directly to the resource identified by that link:
    11 
    12  * ![42] -- Opens change set 42
    13  * !#42 -- Opens ticket number 42
    14  * !{1} -- Opens report 1
    15  * /trunk -- Opens the browser for the `trunk` directory in the default repository
    16  * /repos1/trunk -- Opens the browser for the `trunk` directory in the `repos1` repository
    17 
    18 == Advanced
    19 
    20 === Disabling Quickjump
    21 To disable the Quickjump feature for a keyword start the query with an exclamation mark (`!`): use `!TracGuide` to search for occurrences of the literal word !TracGuide.
    22 
    23 === Search Links
    24 From the Wiki, it is possible to link to a specific search, using `search:` links:
    25  * `search:?q=crash` will search for the string "crash"
    26  * `search:?q=trac+link&wiki=on` will search for "trac" and "link" in wiki pages only
    27 
    28 ----
    29 See also: TracGuide, TracLinks, TracQuery

  • wiki/pages/TracStandalone

    r40226 r40534  
    1 = Tracd
    2 
    3 Tracd is a lightweight standalone Trac web server.
    4 It can be used in a variety of situations, from a test or development server to a multiprocess setup behind another web server used as a load balancer.
    5 
    6 == Pros
    7 
    8  * Fewer dependencies: You don't need to install apache or any other web-server.
    9  * Fast: Should be almost as fast as the [wiki:TracModPython mod_python] version (and much faster than the [wiki:TracCgi CGI]), even more so since version 0.12 where the HTTP/1.1 version of the protocol is enabled by default
    10  * Automatic reloading: For development, Tracd can be used in ''auto_reload'' mode, which will automatically restart the server whenever you make a change to the code (in Trac itself or in a plugin).
    11 
    12 == Cons
    13 
    14  * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd.
    15  * No native HTTPS support: [http://www.rickk.com/sslwrap/ sslwrap] can be used instead,
    16    or [trac:wiki:STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy.
    17 
    18 == Usage examples
    19 
    20 A single project on port 8080. (http://localhost:8080/)
    21 {{{#!sh
    22  $ tracd -p 8080 /path/to/project
    23 }}}
    24 Strictly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use the `--hostname` option.
    25 {{{#!sh
    26  $ tracd --hostname=localhost -p 8080 /path/to/project
    27 }}}
    28 With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/)
    29 {{{#!sh
    30  $ tracd -p 8080 /path/to/project1 /path/to/project2
    31 }}}
    32 
    33 You can't have the last portion of the path identical between the projects since Trac uses that name to keep the URLs of the
    34 different projects unique. So if you use `/project1/path/to` and `/project2/path/to`, you will only see the second project.
    35 
    36 An alternative way to serve multiple projects is to specify a parent directory in which each subdirectory is a Trac project, using the `-e` option. The example above could be rewritten:
    37 {{{#!sh
    38  $ tracd -p 8080 -e /path/to
    39 }}}
    40 
    41 To exit the server on Windows, be sure to use `CTRL-BREAK` -- using `CTRL-C` will leave a Python process running in the background.
    42 
    43 == Installing as a Windows Service
    44 
    45 === Option 1
    46 To install as a Windows service, get the [http://www.google.com/search?q=srvany.exe SRVANY] utility and run:
    47 {{{#!cmd
    48  C:\path\to\instsrv.exe tracd C:\path\to\srvany.exe
    49  reg add HKLM\SYSTEM\CurrentControlSet\Services\tracd\Parameters /v Application /d "\"C:\path\to\python.exe\" \"C:\path\to\python\scripts\tracd-script.py\" <your tracd parameters>"
    50  net start tracd
    51 }}}
    52 
    53 '''DO NOT''' use {{{tracd.exe}}}.  Instead register {{{python.exe}}} directly with {{{tracd-script.py}}} as a parameter.  If you use {{{tracd.exe}}}, it will spawn the python process without SRVANY's knowledge.  This python process will survive a {{{net stop tracd}}}.
    54 
    55 If you want tracd to start automatically when you boot Windows, do:
    56 {{{#!cmd
    57  sc config tracd start= auto
    58 }}}
    59 
    60 The spacing here is important.
    61 
    62 {{{#!div
    63 Once the service is installed, it might be simpler to run the Registry Editor rather than use the `reg add` command documented above.  Navigate to:[[BR]]
    64 `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\tracd\Parameters`
    65 
    66 Three (string) parameters are provided:
    67 ||!AppDirectory ||C:\Python26\ ||
    68 ||Application ||python.exe ||
    69 ||!AppParameters ||scripts\tracd-script.py -p 8080 ... ||
    70 
    71 Note that, if the !AppDirectory is set as above, the paths of the executable ''and'' of the script name and parameter values are relative to the directory.  This makes updating Python a little simpler because the change can be limited, here, to a single point.
    72 (This is true for the path to the .htpasswd file, as well, despite the documentation calling out the /full/path/to/htpasswd; however, you may not wish to store that file under the Python directory.)
    73 }}}
    74 
    75 For Windows 7 User, srvany.exe may not be an option, so you can use [http://www.google.com/search?q=winserv.exe WINSERV] utility and run:
    76 {{{#!cmd
    77 "C:\path\to\winserv.exe" install tracd -displayname "tracd" -start auto "C:\path\to\python.exe" c:\path\to\python\scripts\tracd-script.py <your tracd parameters>"
    78 net start tracd
    79 }}}
    80 
    81 === Option 2
    82 
    83 Use [http://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [http://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service.
    84 
    85 === Option 3
    86 
    87 also cygwin's cygrunsrv.exe can be used:
    88 {{{#!sh
    89 $ cygrunsrv --install tracd --path /cygdrive/c/Python27/Scripts/tracd.exe --args '--port 8000 --env-parent-dir E:\IssueTrackers\Trac\Projects'
    90 $ net start tracd
    91 }}}
    92 
    93 == Using Authentication
    94 
    95 Tracd allows you to run Trac without the need for Apache, but you can take advantage of Apache's password tools (`htpasswd` and `htdigest`) to easily create a password file in the proper format for tracd to use in authentication. (It is also possible to create the password file without `htpasswd` or `htdigest`; see below for alternatives)
    96 
    97 Make sure you place the generated password files on a filesystem which supports sub-second timestamps, as Trac will monitor their modified time and changes happening on a filesystem with too coarse-grained timestamp resolution (like `ext2` or `ext3` on Linux, or HFS+ on OSX).
    98 
    99 Tracd provides support for both Basic and Digest authentication. Digest is considered more secure. The examples below use Digest; to use Basic authentication, replace `--auth` with `--basic-auth` in the command line.
    100 
    101 The general format for using authentication is:
    102 {{{#!sh
    103  $ tracd -p port --auth="base_project_dir,password_file_path,realm" project_path
    104 }}}
    105 where:
    106  * '''base_project_dir''': the base directory of the project specified as follows:
    107    * when serving multiple projects: ''relative'' to the `project_path`
    108    * when serving only a single project (`-s`): the name of the project directory
    109  Don't use an absolute path here as this won't work. ''Note:'' This parameter is case-sensitive even for environments on Windows.
    110  * '''password_file_path''': path to the password file
    111  * '''realm''': the realm name (can be anything)
    112  * '''project_path''': path of the project
    113 
    114  * **`--auth`** in the above means use Digest authentication, replace `--auth` with `--basic-auth` if you want to use Basic auth.  Although Basic authentication does not require a "realm", the command parser does, so the second comma is required, followed directly by the closing quote for an empty realm name.
    115 
    116 Examples:
    117 
    118 {{{#!sh
    119  $ tracd -p 8080 \
    120    --auth="project1,/path/to/passwordfile,mycompany.com" /path/to/project1
    121 }}}
    122 
    123 Of course, the password file can be be shared so that it is used for more than one project:
    124 {{{#!sh
    125  $ tracd -p 8080 \
    126    --auth="project1,/path/to/passwordfile,mycompany.com" \
    127    --auth="project2,/path/to/passwordfile,mycompany.com" \
    128    /path/to/project1 /path/to/project2
    129 }}}
    130 
    131 Another way to share the password file is to specify "*" for the project name:
    132 {{{#!sh
    133  $ tracd -p 8080 \
    134    --auth="*,/path/to/users.htdigest,mycompany.com" \
    135    /path/to/project1 /path/to/project2
    136 }}}
    137 
    138 === Basic Authorization: Using a htpasswd password file
    139 This section describes how to use `tracd` with Apache .htpasswd files.
    140 
    141   Note: It is necessary (at least with Python 2.6) to install the fcrypt package in order to
    142   decode some htpasswd formats.  Trac source code attempt an `import crypt` first, but there
    143   is no such package for Python 2.6. Only `SHA-1` passwords (since Trac 1.0) work without this module.
    144 
    145 To create a .htpasswd file use Apache's `htpasswd` command (see [#GeneratingPasswordsWithoutApache below] for a method to create these files without using Apache):
    146 {{{#!sh
    147  $ sudo htpasswd -c /path/to/env/.htpasswd username
    148 }}}
    149 then for additional users:
    150 {{{#!sh
    151  $ sudo htpasswd /path/to/env/.htpasswd username2
    152 }}}
    153 
    154 Then to start `tracd` run something like this:
    155 {{{#!sh
    156  $ tracd -p 8080 --basic-auth="project,/fullpath/environmentname/.htpasswd,realmname" /path/to/project
    157 }}}
    158 
    159 For example:
    160 {{{#!sh
    161  $ tracd -p 8080 --basic-auth="project,/srv/tracenv/testenv/.htpasswd,My Test Env" /path/to/project
    162 }}}
    163 ''Note:'' You might need to pass "-m" as a parameter to htpasswd on some platforms (OpenBSD).
    164 
    165 === Digest authentication: Using a htdigest password file
    166 
    167 If you have Apache available, you can use the htdigest command to generate the password file. Type 'htdigest' to get some usage instructions, or read [http://httpd.apache.org/docs/2.0/programs/htdigest.html this page] from the Apache manual to get precise instructions.  You'll be prompted for a password to enter for each user that you create.  For the name of the password file, you can use whatever you like, but if you use something like `users.htdigest` it will remind you what the file contains. As a suggestion, put it in your <projectname>/conf folder along with the [TracIni trac.ini] file.
    168 
    169 Note that you can start tracd without the `--auth` argument, but if you click on the ''Login'' link you will get an error.
    170 
    171 === Generating Passwords Without Apache
    172 
    173 Basic Authorization can be accomplished via this [http://aspirine.org/htpasswd_en.html online HTTP Password generator] which also supports `SHA-1`.  Copy the generated password-hash line to the .htpasswd file on your system. Note that Windows Python lacks the "crypt" module that is the default hash type for htpasswd. Windows Python can grok MD5 password hashes just fine and you should use MD5.
    174 
    175 Trac also provides `htpasswd` and `htdigest` scripts in `contrib`:
    176 {{{#!sh
    177 $ ./contrib/htpasswd.py -cb htpasswd user1 user1
    178 $ ./contrib/htpasswd.py -b htpasswd user2 user2
    179 }}}
    180 
    181 {{{#!sh
    182 $ ./contrib/htdigest.py -cb htdigest trac user1 user1
    183 $ ./contrib/htdigest.py -b htdigest trac user2 user2
    184 }}}
    185 
    186 ==== Using `md5sum`
    187 It is possible to use `md5sum` utility to generate digest-password file:
    188 {{{#!sh
    189 user=
    190 realm=
    191 password=
    192 path_to_file=
    193 echo ${user}:${realm}:$(printf "${user}:${realm}:${password}" | md5sum - | sed -e 's/\s\+-//') > ${path_to_file}
    194 }}}
    195 
    196 == Reference
    197 
    198 Here's the online help, as a reminder (`tracd --help`):
    199 {{{
    200 Usage: tracd [options] [projenv] ...
    201 
    202 Options:
    203   --version             show program's version number and exit
    204   -h, --help            show this help message and exit
    205   -a DIGESTAUTH, --auth=DIGESTAUTH
    206                         [projectdir],[htdigest_file],[realm]
    207   --basic-auth=BASICAUTH
    208                         [projectdir],[htpasswd_file],[realm]
    209   -p PORT, --port=PORT  the port number to bind to
    210   -b HOSTNAME, --hostname=HOSTNAME
    211                         the host name or IP address to bind to
    212   --protocol=PROTOCOL   http|scgi|ajp|fcgi
    213   -q, --unquote         unquote PATH_INFO (may be needed when using ajp)
    214   --http10              use HTTP/1.0 protocol version instead of HTTP/1.1
    215   --http11              use HTTP/1.1 protocol version (default)
    216   -e PARENTDIR, --env-parent-dir=PARENTDIR
    217                         parent directory of the project environments
    218   --base-path=BASE_PATH
    219                         the initial portion of the request URL's "path"
    220   -r, --auto-reload     restart automatically when sources are modified
    221   -s, --single-env      only serve a single project without the project list
    222   -d, --daemonize       run in the background as a daemon
    223   --pidfile=PIDFILE     when daemonizing, file to which to write pid
    224   --umask=MASK          when daemonizing, file mode creation mask to use, in
    225                         octal notation (default 022)
    226   --group=GROUP         the group to run as
    227   --user=USER           the user to run as
    228 }}}
    229 
    230 Use the -d option so that tracd doesn't hang if you close the terminal window where tracd was started.
    231 
    232 == Tips
    233 
    234 === Serving static content
    235 
    236 If `tracd` is the only web server used for the project,
    237 it can also be used to distribute static content
    238 (tarballs, Doxygen documentation, etc.)
    239 
    240 This static content should be put in the `$TRAC_ENV/htdocs` folder,
    241 and is accessed by URLs like `<project_URL>/chrome/site/...`.
    242 
    243 Example: given a `$TRAC_ENV/htdocs/software-0.1.tar.gz` file,
    244 the corresponding relative URL would be `/<project_name>/chrome/site/software-0.1.tar.gz`,
    245 which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax).
    246 
    247 === Using tracd behind a proxy
    248 
    249 In some situations when you choose to use tracd behind Apache or another web server.
    250 
    251 In this situation, you might experience issues with redirects, like being redirected to URLs with the wrong host or protocol. In this case (and only in this case), setting the `[trac] use_base_url_for_redirect` to `true` can help, as this will force Trac to use the value of `[trac] base_url` for doing the redirects.
    252 
    253 If you're using the AJP protocol to connect with `tracd` (which is possible if you have flup installed), then you might experience problems with double quoting. Consider adding the `--unquote` parameter.
    254 
    255 See also [trac:TracOnWindowsIisAjp], [trac:TracNginxRecipe].
    256 
    257 === Authentication for tracd behind a proxy
    258 It is convenient to provide central external authentication to your tracd instances, instead of using `--basic-auth`. There is some discussion about this in [trac:#9206].
    259 
    260 Below is example configuration based on Apache 2.2, mod_proxy, mod_authnz_ldap.
    261 
    262 First we bring tracd into Apache's location namespace.
    263 
    264 {{{#!apache
    265 <Location /project/proxified>
    266         Require ldap-group cn=somegroup, ou=Groups,dc=domain.com
    267         Require ldap-user somespecificusertoo
    268         ProxyPass http://localhost:8101/project/proxified/
    269         # Turns out we don't really need complicated RewriteRules here at all
    270         RequestHeader set REMOTE_USER %{REMOTE_USER}s
    271 </Location>
    272 }}}
    273 
    274 Then we need a single file plugin to recognize HTTP_REMOTE_USER header as valid authentication source. HTTP headers like '''HTTP_FOO_BAR''' will get converted to '''Foo-Bar''' during processing. Name it something like '''remote-user-auth.py''' and drop it into '''proxified/plugins''' directory:
    275 {{{#!python
    276 from trac.core import *
    277 from trac.config import BoolOption
    278 from trac.web.api import IAuthenticator
    279 
    280 class MyRemoteUserAuthenticator(Component):
    281 
    282     implements(IAuthenticator)
    283 
    284     obey_remote_user_header = BoolOption('trac', 'obey_remote_user_header', 'false',
    285                """Whether the 'Remote-User:' HTTP header is to be trusted for user logins
    286                 (''since ??.??').""")
    287 
    288     def authenticate(self, req):
    289         if self.obey_remote_user_header and req.get_header('Remote-User'):
    290             return req.get_header('Remote-User')
    291         return None
    292 
    293 }}}
    294 
    295 Add this new parameter to your TracIni:
    296 {{{#!ini
    297 [trac]
    298 ...
    299 obey_remote_user_header = true
    300 ...
    301 }}}
    302 
    303 Run tracd:
    304 {{{#!sh
    305 tracd -p 8101 -r -s proxified --base-path=/project/proxified
    306 }}}
    307 
    308 Note that if you want to install this plugin for all projects, you have to put it in your [TracPlugins#Plugindiscovery global plugins_dir] and enable it in your global trac.ini.
    309 
    310 Global config (e.g. `/srv/trac/conf/trac.ini`):
    311 {{{#!ini
    312 [components]
    313 remote-user-auth.* = enabled
    314 [inherit]
    315 plugins_dir = /srv/trac/plugins
    316 [trac]
    317 obey_remote_user_header = true
    318 }}}
    319 
    320 Environment config (e.g. `/srv/trac/envs/myenv`):
    321 {{{#!ini
    322 [inherit]
    323 file = /srv/trac/conf/trac.ini
    324 }}}
    325 
    326 === Serving a different base path than /
    327 Tracd supports serving projects with different base urls than /<project>. The parameter name to change this is
    328 {{{#!sh
    329  $ tracd --base-path=/some/path
    330 }}}
    331 
    332 ----
    333 See also: TracInstall, TracCgi, TracModPython, TracGuide, [trac:TracOnWindowsStandalone#RunningTracdasservice Running tracd.exe as a Windows service]

  • wiki/pages/TracSupport

    r40226 r40534  
    1 = Trac Support =
    2 
    3 Like in most [http://www.opensource.org/ open source projects], Trac support is available primarily through the [trac:MailingList mailing list] and the [trac: project wiki]. Both are maintained by the trac community. The [trac: project wiki] is the authoritative source for the TracGuide, consisting of the administrator and user guides for Trac.
    4 
    5 There is also an [trac:IrcChannel IRC channel] where online users can help out. Much of the 'live' development discussions also happen there.
    6 
    7 Before you start a new support query, make sure you have done the appropriate searching:
    8  * in the project's [trac:TracFaq FAQ]
    9  * in past messages to the [http://groups.google.com/group/trac-users Trac Users Mailing List]
    10  * in the Trac ticket system, using either a [trac:search:?q=&ticket=on&wiki=on full search] or a [trac:query: ticket query].
    11 
    12 Please '''don't''' create a ticket in trac.egdewall.org to ask a Trac support question. Only use it when you face a ''real'' and ''new'' bug in Trac, and do so only after having read the [trac:NewTicketGuidelines NewTicketGuidelines]. The more a bug report or enhancement request complies with those guidelines, the higher the chances are that it will be fixed or implemented promptly!
    13 
    14 ----
    15 See also: [trac:MailingList], [trac:TracTroubleshooting], [trac:CommercialServices]
Note: See TracChangeset for help on using the changeset viewer.