Commits

Christian Boos committed 9fe5457

0.12.3rc1: integrate TracGuide changes from t.e.o (as of now)

Comments (0)

Files changed (36)

trac/wiki/default-pages/CamelCase

  * http://en.wikipedia.org/wiki/CamelCase
 
 ----
-See also: WikiPageNames, WikiNewPage, WikiFormatting, TracWiki
+See also: WikiPageNames, WikiNewPage, WikiFormatting, TracWiki

trac/wiki/default-pages/InterMapTxt

 CPAN             http://search.cpan.org/perldoc?
 DebianBug        http://bugs.debian.org/
 DebianPackage    http://packages.debian.org/
+DebianPTS        http://packages.qa.debian.org/
 Dictionary       http://www.dict.org/bin/Dict?Database=*&Form=Dict1&Strategy=*&Query=
 Google           http://www.google.com/search?q=
 lmgtfy           http://lmgtfy.com/?q= # Well, just search for "$1", follow the link to see how to do it...
 MetaWiki         http://sunir.org/apps/meta.pl?
 MetaWikiPedia    http://meta.wikipedia.org/wiki/
 MoinMoin         http://moinmo.in/
+TracHacks        http://trac-hacks.org/wiki/
+OSM              http://www.openstreetmap.org/wiki/
 WhoIs            http://www.whois.sc/
 Why              http://clublet.com/c/c/why?
 c2Wiki           http://c2.com/cgi/wiki?
 WikiPedia        http://en.wikipedia.org/wiki/
 }}}
+
+
+----
+See also: InterWiki, InterTrac

trac/wiki/default-pages/PageTemplates

 Available templates: 
 [[TitleIndex(PageTemplates/)]]
 ----
-See also: TracWiki
+See also: TracWiki

trac/wiki/default-pages/SandBox

 
 This is just a page to practice and learn WikiFormatting. 
 
-Go ahead, edit it freely.
+Go ahead, edit it freely.

trac/wiki/default-pages/TracAccessibility

 
 Not every user has a graphic environment with a mouse or other pointing device. Some users rely on keyboard, alternative keyboard or voice input to navigate links, activate form controls, etc. In Trac, we work to assure users may interact with devices other than a pointing device.
 
+The keyboard shortcuts must be enabled for a session through the [/prefs/keybindings Keyboard Shortcuts] preferences panel.
+
 Trac supports accessibility keys for the most common operations. On Windows and Linux platforms, press any of the keys listed below in combination with the `<Alt>` key; on a Mac, use the `<ctrl>` key instead.
 
 ''Note that when using Internet Explorer on Windows, you need to hit `<Enter>` after having used the access key.''[[BR]]

trac/wiki/default-pages/TracBrowser

 listing all the configured repositories. 
 Each repository has a name which is used as a path prefix in a 
 "virtual" file hierarchy encompassing all the available repositories.
-If a default repository has been configured, its top-level files and directories 
+One of the repositories can be configured with an empty name; this is the default repository.  When such a default repository is present, its top-level files and directories 
 are also listed, in a '''Default Repository''' section placed before the 
 repository index. If the default repository is the only repository associated 
 with the Trac environment the '''Repository Index''' will be omitted ^[#note-multirepos (1)]^.
  - `'r'` can be used to force the reload of an already expanded directory
  - `'A'` can be used to directly visit a file in annotate (blame) mode
  - `'L'` to view the log for the selected entry
-If no row has been selected using `'j'` or `'k'` these keys will operate on the entry under the mouse .
+If no row has been selected using `'j'` or `'k'` these keys will operate on the entry under the mouse.
 
 {{{#!comment
 MMM: I guess that some keys are upper case and some lower to avoid conflicts with browser defined keys.

trac/wiki/default-pages/TracCgi

 {{{
 trac-admin /path/to/env deploy /path/to/www/trac
 }}}
-`trac.cgi` will be in the `cgi-bin` folder inside the given path. Make sure it is executable by your web server. This command also copies `static resource` files to a `htdocs` directory of a given destination.
+`trac.cgi` will be in the `cgi-bin` folder inside the given path. ''Make sure it is executable by your web server''. This command also copies `static resource` files to a `htdocs` directory of a given destination.
 
 == Apache web-server configuration ==
 
 
 On some systems, you ''may'' need to edit the shebang line in the `trac.cgi` file to point to your real Python installation path. On a Windows system you may need to configure Windows to know how to execute a .cgi file (Explorer -> Tools -> Folder Options -> File Types -> CGI).
 
+=== Using WSGI ===
+
+You can run a [http://henry.precheur.org/python/how_to_serve_cgi WSGI handler] [http://pythonweb.org/projects/webmodules/doc/0.5.3/html_multipage/lib/example-webserver-web-wsgi-simple-cgi.html under CGI].  You can [wiki:TracModWSGI#Thetrac.wsgiscript write your own application function], or use the deployed trac.wsgi's application.
+
 == Mapping Static Resources ==
 
-Out of the box, Trac will pass static resources such as style sheets or images through itself. For a CGI setup this is '''highly undesirable''', because this way CGI script is invoked for documents that could be much more efficiently served directly by web server.
-
-Web servers such as [http://httpd.apache.org/ Apache] allow you to create “Aliases” to resources, giving them a virtual URL that doesn't necessarily reflect the layout of the servers file system. We already used this capability by defining a `ScriptAlias` for the CGI script. We also can map requests for static resources directly to the directory on the file system, avoiding processing these requests by CGI script.
-
-There are two primary URL paths for static resources - `/chrome/common` and `/chrome/site`. Plugins can add their own resources usually accessible by `/chrome/plugin` path, so its important to override only known paths and not try to make universal `/chrome` alias for everything.
-
-Add the following snippet to Apache configuration '''before''' the `ScriptAlias` for the CGI script, changing paths to match your deployment:
-{{{
-Alias /trac/chrome/common /path/to/trac/htdocs/common
-Alias /trac/chrome/site /path/to/trac/htdocs/site
-<Directory "/path/to/www/trac/htdocs">
-  Order allow,deny
-  Allow from all
-</Directory>
-}}}
-
-If using mod_python, you might want to add this too (otherwise, the alias will be ignored):
-{{{
-<Location "/trac/chrome/common/">
-  SetHandler None
-</Location>
-}}}
-
-Note that we mapped `/trac` part of the URL to the `trac.cgi` script, and the path `/chrome/common` is the path you have to append to that location to intercept requests to the static resources. 
-
-For example, if Trac is mapped to `/cgi-bin/trac.cgi` on your server, the URL of the Alias should be `/cgi-bin/trac.cgi/chrome/common`.
-
-Similarly, if you have static resources in a project's htdocs directory (which is referenced by /chrome/site URL in themes), you can configure Apache to serve those resources (again, put this '''before''' the `ScriptAlias` for the CGI script, and adjust names and locations to match your installation):
-
-{{{
-Alias /trac/chrome/site /path/to/projectenv/htdocs
-<Directory "/path/to/projectenv/htdocs">
-  Order allow,deny
-  Allow from all
-</Directory>
-}}}
-
-Alternatively to hacking `/trac/chrome/site`, you can directly specify path to static resources using `htdocs_location` configuration option in [wiki:TracIni trac.ini]:
-{{{
-[trac]
-htdocs_location = http://yourhost.example.org/trac-htdocs
-}}}
-
-Trac will then use this URL when embedding static resources into HTML pages. Of course, you still need to make the Trac `htdocs` directory available through the web server at the specified URL, for example by copying (or linking) the directory into the document root of the web server:
-{{{
-$ ln -s /path/to/www/trac/htdocs /var/www/yourhost.example.org/trac-htdocs
-}}}
-
-Note that in order to get this `htdocs` directory, you need first to extract the relevant Trac resources using the `deploy` command of TracAdmin:
-[[TracAdminHelp(deploy)]]
-
+See TracInstall#MappingStaticResources.
 
 == Adding Authentication ==
 
-The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program to create the password file:
-{{{
-$ htpasswd -c /somewhere/trac.htpasswd admin
-New password: <type password>
-Re-type new password: <type password again>
-Adding password for user admin
-}}}
-
-After the first user, you dont need the "-c" option anymore:
-{{{
-$ htpasswd /somewhere/trac.htpasswd john
-New password: <type password>
-Re-type new password: <type password again>
-Adding password for user john
-}}}
-
-  ''See the man page for `htpasswd` for full documentation.''
-
-After you've created the users, you can set their permissions using TracPermissions.
-
-Now, you'll need to enable authentication against the password file in the Apache configuration:
-{{{
-<Location "/trac/login">
-  AuthType Basic
-  AuthName "Trac"
-  AuthUserFile /somewhere/trac.htpasswd
-  Require valid-user
-</Location>
-}}}
-
-If you're hosting multiple projects you can use the same password file for all of them:
-{{{
-<LocationMatch "/trac/[^/]+/login">
-  AuthType Basic
-  AuthName "Trac"
-  AuthUserFile /somewhere/trac.htpasswd
-  Require valid-user
-</LocationMatch>
-}}}
-
-For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”. Please read the [http://httpd.apache.org/docs/2.0/ Apache HTTPD documentation] to find out more. For example, on a Debian 4.0r1 (etch) system the relevant section  in apache configuration can look like this:
-{{{
-<Location "/trac/login">
-    LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
-    AuthType Digest
-    AuthName "trac"
-    AuthDigestDomain /trac
-    AuthUserFile /somewhere/trac.htpasswd
-    Require valid-user
-</Location>
-}}}
-and you'll have to create your .htpasswd file with htdigest instead of htpasswd as follows:
-{{{
-# htdigest /somewhere/trac.htpasswd trac admin
-}}}
-where the "trac" parameter above is the same as !AuthName above  ("Realm" in apache-docs). 
+See TracInstall#ConfiguringAuthentication.
 
 ----
 See also:  TracGuide, TracInstall, [wiki:TracModWSGI], TracFastCgi, TracModPython

trac/wiki/default-pages/TracChangeset

 In front of each listed file, you'll find  a colored rectangle. The color
 indicates how the file is affected by the changeset.
  
- * Green: Added
- * Red: Removed
- * Yellow: Modified
- * Blue: Copied
- * Gray: Moved
-
+ * [[span(style=background:#bfb;border:1px solid #999,` `)]] Green: Added
+ * [[span(style=background:#f88;border:1px solid #999,` `)]] Red: Removed
+ * [[span(style=background:#fd8;border:1px solid #999,` `)]] Yellow: Modified
+ * [[span(style=background:#88f;border:1px solid #999,` `)]] Blue: Copied
+ * [[span(style=background:#ccc;border:1px solid #999,` `)]] Gray: Moved
 The color legend is located below the header as a reminder.
 
 == Diff Views ==

trac/wiki/default-pages/TracFastCgi

+[[PageOutline]]
+
 = Trac with FastCGI =
 
-[http://www.fastcgi.com/ FastCGI] interface allows Trac to remain resident much like with [wiki:TracModPython mod_python]. It is faster than external CGI interfaces which must start a new process for each request. However, unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], i.e. run with different permissions than web server. Additionally, it is supported by much wider variety of web servers.
+[http://www.fastcgi.com/ FastCGI] interface allows Trac to remain resident much like with [wiki:TracModPython mod_python] or [wiki:TracModWSGI mod_wsgi]. It is faster than external CGI interfaces which must start a new process for each request.  Additionally, it is supported by much wider variety of web servers.
 
-'''Note for Windows:''' Trac's FastCGI does not run under Windows, as Windows does not implement `Socket.fromfd`, which is used by `_fcgi.py`. If you want to connect to IIS, you may want to try [trac:TracOnWindowsIisAjp AJP].
+Note that unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], i.e. run with different permissions than web server running with (`mod_wsgi` supports the `WSGIDaemonProcess` with user / group parameters to achieve the same effect).
+
+'''Note for Windows:''' Trac's FastCGI does not run under Windows, as Windows does not implement `Socket.fromfd`, which is used by `_fcgi.py`. If you want to connect to IIS, you may want to try [trac:TracOnWindowsIisAjp AJP]/[trac:TracOnWindowsIisAjp ISAPI].
+
+[[PageOutline(2-3,Overview,inline)]]
+
 
 == Simple Apache configuration ==
 
 There are two FastCGI modules commonly available for Apache: `mod_fastcgi` and
 `mod_fcgid` (preferred). The latter is more up-to-date.
 
-==== setup with `mod_fastcgi` ====
+The following sections focus on the FCGI specific setup, see also [wiki:TracModWSGI#ConfiguringAuthentication] for configuring the authentication in Apache.
+
+Regardless of which cgi module is used, be sure the web server has executable permissions on the cgi-bin folder. While FastCGI will throw specific permissions errors, mod_fcgid will throw an ambiguous error if this has not been done. (Connection reset by peer: mod_fcgid: error reading data from FastCGI server) 
+
+=== Set up with `mod_fastcgi` ===
 `mod_fastcgi` uses `FastCgiIpcDir` and `FastCgiConfig` directives that should be added to an appropriate Apache configuration file:
 {{{
 # Enable fastcgi for .fcgi files
 Configure `ScriptAlias` or similar options as described in TracCgi, but
 calling `trac.fcgi` instead of `trac.cgi`.
 
-You can set up the `TRAC_ENV` as an overall default:
+Add the following to the Apache configuration file (below the `FastCgiIpcDir` line) if you intend to set up the `TRAC_ENV` as an overall default:
 {{{
 FastCgiConfig -initial-env TRAC_ENV=/path/to/env/trac
 }}}
 
-Or you can serve multiple Trac projects in a directory like:
+Alternatively, you can serve multiple Trac projects in a directory by adding this:
 {{{
 FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects
 }}}
 
-==== setup with `mod_fcgid` ====
+=== Set up with `mod_fcgid` ===
 Configure `ScriptAlias` (see TracCgi for details), but call `trac.fcgi`
 instead of `trac.cgi`. Note that slash at the end - it is important.
 {{{
 ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.fcgi/
 }}}
 
-To setup Trac environment for `mod_fcgid` it is necessary to use
+To set up Trac environment for `mod_fcgid` it is necessary to use
 `DefaultInitEnv` directive. It cannot be used in `Directory` or
 `Location` context, so if you need to support multiple projects, try
 alternative environment setup below.
 DefaultInitEnv TRAC_ENV /path/to/env/trac/
 }}}
 
-==== alternative environment setup ====
-A better method to specify path to Trac environment it to embed the path
+=== alternative environment setup ===
+A better method to specify path to Trac environment is to embed the path
 into `trac.fcgi` script itself. That doesn't require configuration of server
 environment variables, works for both FastCgi modules
 (and for [http://www.lighttpd.net/ lighttpd] and CGI as well):
 If the port was not reachable, the interpreter command would be launched. Note that, in the definition of the information source, you will have to manually launch the spawner if you use a ''Remote host'' as ''Information source'' instead of a ''Local interpreter''.
 
 After doing this, we will just have to create a new rule managed by the SCGI handler to access Trac. It can be created in a new virtual server, trac.example.net for instance, and will only need two rules. The '''default''' one will use the SCGI handler associated to the previously created information source.
-The second rule will be there to serve the few static files needed to correctly display the Trac interface. Create it as ''Directory rule'' for ''/chrome/common'' and just set it to the ''Static files'' handler and with a ''Document root'' that points to the appropriate files: ''/usr/share/trac/htdocs/''
+The second rule will be there to serve the few static files needed to correctly display the Trac interface. Create it as ''Directory rule'' for ''/common'' and just set it to the ''Static files'' handler and with a ''Document root'' that points to the appropriate files: ''$TRAC_LOCAL/htdocs/'' (where $TRAC_LOCAL is a directory defined by the user or the system administrator to place local trac resources).
 
 Note:\\
 If the tracd process fails to start up, and cherokee displays a 503 error page, you might be missing the [http://trac.saddi.com/flup python-flup] package.\\
 sudo apt-get install python-flup
 }}}
 
+
 == Simple Lighttpd Configuration ==
 
 The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.lighttpd.net/ lighttpd].
 and you may set one of the two in `trac.fcgi` instead of in `lighttpd.conf`
 using `bin-environment` (as in the section above on Apache configuration).
 
-Note that lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example, see #Trac2418. This should be fixed since lighttpd 1.4.23, and you may need to add `"fix-root-scriptname" => "enable"` as parameter of fastcgi.server.
+Note that lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example (see [trac:#2418]). This should be fixed since lighttpd 1.4.23, and you may need to add `"fix-root-scriptname" => "enable"` as parameter of fastcgi.server.
 
 For using two projects with lighttpd add the following to your `lighttpd.conf`:
 {{{
 `first.fcgi` and `second.fcgi`, and reference them in the above settings.
 Note that the above will result in different processes in any event, even
 if both are running from the same `trac.fcgi` script.
+
 {{{
 #!div class=important
 '''Note''' It's very important the order on which server.modules are loaded, if mod_auth is not loaded '''BEFORE''' mod_fastcgi, then the server will fail to authenticate the user.
 }}}
+
 For authentication you should enable mod_auth in lighttpd.conf 'server.modules', select auth.backend and auth rules:
 {{{
 server.modules              = (
 # Aliasing functionality is needed
 server.modules += ("mod_alias")
 
-# Setup an alias for the static resources
+# Set up an alias for the static resources
 alias.url = ("/trac/chrome/common" => "/usr/share/trac/htdocs")
 
 # Use negative lookahead, matching all requests that ask for any resource under /trac, EXCEPT in
 }}}
 For details about languages specification see [trac:TracFaq TracFaq] question 2.13.
 
-Other important information like [http://trac.lighttpd.net/trac/wiki/TracInstall this updated TracInstall page], [wiki:TracCgi#MappingStaticResources and this] are useful for non-fastcgi specific installation aspects.
-
-If you use trac-0.9, read [http://lists.edgewall.com/archive/trac/2005-November/005311.html about small bug]
+Other important information like the [wiki:TracInstall#MappingStaticResources mapping static resources advices] are useful for non-fastcgi specific installation aspects.
+]
 
 Relaunch lighttpd, and browse to `http://yourhost.example.org/trac` to access Trac.
 
 Note about running lighttpd with reduced permissions:
 
-  If nothing else helps and trac.fcgi doesn't start with lighttpd settings `server.username = "www-data"`, `server.groupname = "www-data"`, then in the `bin-environment` section set `PYTHON_EGG_CACHE` to the home directory of `www-data` or some other directory accessible to this account for writing.
+If nothing else helps and trac.fcgi doesn't start with lighttpd settings `server.username = "www-data"`, `server.groupname = "www-data"`, then in the `bin-environment` section set `PYTHON_EGG_CACHE` to the home directory of `www-data` or some other directory accessible to this account for writing.
 
 
 == Simple !LiteSpeed Configuration ==
 
 !LiteSpeed web server is an event-driven asynchronous Apache replacement designed from the ground-up to be secure, scalable, and operate with minimal resources. !LiteSpeed can operate directly from an Apache config file and is targeted for business-critical environments.
 
-=== Setup ===
-
  1. Please make sure you have first have a working install of a Trac project. Test install with “tracd” first.
 
  2. Create a Virtual Host for this setup. From now on we will refer to this vhost as !TracVhost. For this tutorial we will be assuming that your trac project will be accessible via:
 http://yourdomain.com/trac/
 }}}
 
+
 == Simple Nginx Configuration ==
 
- 1. Nginx configuration snippet - confirmed to work on 0.6.32
+Nginx is able to communicate with FastCGI processes, but can not spawn them. So you need to start FastCGI server for Trac separately.
+
+ 1. Nginx configuration with basic authentication handled by Nginx - confirmed to work on 0.6.32
 {{{
     server {
         listen       10.9.8.7:443;
              set $path_info /$1;
         }
 
+        # it makes sense to serve static resources through Nginx
+        location /chrome/ {
+             alias /home/trac/instance/static/htdocs/;
+        }
+
         # You can copy this whole location to ``location [/some/prefix]/login``
         # and remove the auth entries below if you want Trac to enforce
         # authorization where appropriate instead of needing to authenticate
             fastcgi_param  SERVER_NAME        $server_name;
             fastcgi_param  SERVER_PORT        $server_port;
             fastcgi_param  SERVER_PROTOCOL    $server_protocol;
-            fastcgi_param  QUERY_STRING     $query_string;
+            fastcgi_param  QUERY_STRING       $query_string;
 
-            # for authentication to work
+            # For Nginx authentication to work - do not forget to comment these
+            # lines if not using Nginx for authentication
             fastcgi_param  AUTH_USER          $remote_user;
             fastcgi_param  REMOTE_USER        $remote_user;
+
+            # for ip to work
+            fastcgi_param REMOTE_ADDR         $remote_addr;
+
+            # For attchments to work
+            fastcgi_param    CONTENT_TYPE     $content_type;
+            fastcgi_param    CONTENT_LENGTH   $content_length;
         }
     }
 }}}

trac/wiki/default-pages/TracFineGrainedPermissions

 
 
 === !AuthzPolicy === 
-
- - Install [http://www.voidspace.org.uk/python/configobj.html ConfigObj] (required).
- - Copy authz_policy.py into your plugins directory.
- - Put a [http://swapoff.org/files/authzpolicy.conf authzpolicy.conf] file somewhere, preferably on a secured location on the server, not readable for others than the webuser. If the  file contains non-ASCII characters, the UTF-8 encoding should be used.
- - Update your `trac.ini`:
-   1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section
+==== Configuration ====
+* Install [http://www.voidspace.org.uk/python/configobj.html ConfigObj] (still needed for 0.12).
+* Copy authz_policy.py into your plugins directory.
+* Put a [http://swapoff.org/files/authzpolicy.conf authzpolicy.conf] file somewhere, preferably on a secured location on the server, not readable for others than the webuser. If the  file contains non-ASCII characters, the UTF-8 encoding should be used.
+* Update your `trac.ini`:
+  1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section
 {{{
 [trac]
 ...
 permission_policies = AuthzPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
 }}}
-   2. add a new `[authz_policy]` section
+  2. add a new `[authz_policy]` section
 {{{
 [authz_policy]
 authz_file = /some/trac/env/conf/authzpolicy.conf
 }}}
-   3. enable the single file plugin
+  3. enable the single file plugin
 {{{
 [components]
 ...
 # for Trac 0.11 use this
 #authz_policy.* = enabled 
 }}}
-
+==== Usage Notes ====
 Note that the order in which permission policies are specified is quite critical, 
 as policies will be examined in the sequence provided.
 
-A policy will return either `True`, `False` or `None` for a given permission check.
-Only if the return value is `None` will the ''next'' permission policy be consulted.
-If no policy explicitly grants the permission, the final result will be `False` 
-(i.e. no permission).
+A policy will return either `True`, `False` or `None` for a given permission check. `True` is returned if the policy explicitly grants the permission. `False` is returned if the policy explicitly denies the permission. `None` is returned if the policy is unable to either grant or deny the permission.
+
+NOTE: Only if the return value is `None` will the ''next'' permission policy be consulted.
+If none of the policies explicitly grants the permission, the final result will be `False` 
+(i.e. permission denied).
+
+The `authzpolicy.conf` file is a `.ini` style configuration file:
+{{{
+[wiki:PrivatePage@*]
+john = WIKI_VIEW, !WIKI_MODIFY
+jack = WIKI_VIEW
+* =
+}}}
+* Each section of the config is a glob pattern used to match against a Trac resource
+  descriptor. These descriptors are in the form:
+{{{
+<realm>:<id>@<version>[/<realm>:<id>@<version> ...]
+}}}
+  Resources are ordered left to right, from parent to child. If any
+  component is inapplicable, `*` is substituted. If the version pattern is
+  not specified explicitely, all versions (`@*`) is added implicitly
+
+  Example: Match the WikiStart page
+{{{
+[wiki:*]
+[wiki:WikiStart*]
+[wiki:WikiStart@*]
+[wiki:WikiStart]
+}}}
+
+  Example: Match the attachment `wiki:WikiStart@117/attachment/FOO.JPG@*`
+  on WikiStart
+{{{
+[wiki:*]
+[wiki:WikiStart*]
+[wiki:WikiStart@*]
+[wiki:WikiStart@*/attachment/*]
+[wiki:WikiStart@117/attachment/FOO.JPG]
+}}}
+
+* Sections are checked against the current Trac resource descriptor '''IN ORDER''' of
+  appearance in the configuration file. '''ORDER IS CRITICAL'''.
+
+* Once a section matches, the current username is matched against the keys 
+  (usernames) of the section, '''IN ORDER'''. 
+  * If a key (username) is prefixed with a `@`, it is treated as a group. 
+  * If a value (permission) is prefixed with a `!`, the permission is
+    denied rather than granted.
+
+  The username will match any of 'anonymous',
+  'authenticated', <username> or '*', using normal Trac permission rules.
 
 For example, if the `authz_file` contains:
 {{{
 
 [wiki:PrivatePage@*]
 john = WIKI_VIEW
-* =
+* = !WIKI_VIEW
 }}}
 and the default permissions are set like this:
 {{{
 }}}
 
 Then: 
- - All versions of WikiStart will be viewable by everybody (including anonymous)
- - !PrivatePage will be viewable only by john
- - other pages will be viewable only by john and jack
+  * All versions of WikiStart will be viewable by everybody (including anonymous)
+  * !PrivatePage will be viewable only by john
+  * other pages will be viewable only by john and jack
+
+Groups:
+{{{
+[groups]
+admins = john, jack
+devs = alice, bob
+
+[wiki:Dev@*]
+@admins = TRAC_ADMIN
+@devs = WIKI_VIEW
+* =
+
+[*]
+@admins = TRAC_ADMIN
+* =
+}}}
+
+Then:
+- everything is blocked (whitelist approach), but
+- admins get all TRAC_ADMIN everywhere and
+- devs can view wiki pages.
+
+Some repository examples (Browse Source specific):
+{{{
+# A single repository:
+[repository:test_repo@*]
+john = BROWSER_VIEW, FILE_VIEW
+# John has BROWSER_VIEW and FILE_VIEW for the entire test_repo
+
+# All repositories:
+[repository:*@*]
+jack = BROWSER_VIEW, FILE_VIEW
+# John has BROWSER_VIEW and FILE_VIEW for all repositories
+}}}
+
+Very fine grain repository access:
+{{{
+# John has BROWSER_VIEW and FILE_VIEW access to trunk/src/some/location/ only
+[repository:test_repo@*/source:trunk/src/some/location/*@*]
+john = BROWSER_VIEW, FILE_VIEW
+
+
+# John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of all files at trunk/src/some/location only
+[repository:test_repo@*/source:trunk/src/some/location/*@1]
+john = BROWSER_VIEW, FILE_VIEW
+
+
+# John has BROWSER_VIEW and FILE_VIEW access to all revisions of 'somefile' at trunk/src/some/location only 
+[repository:test_repo@*/source:trunk/src/some/location/somefile@*]
+john = BROWSER_VIEW, FILE_VIEW
+
+
+# John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of 'somefile' at trunk/src/some/location only
+[repository:test_repo@*/source:trunk/src/some/location/somefile@1]
+john = BROWSER_VIEW, FILE_VIEW
+}}}
+
+Note: In order for Timeline to work/visible for John, we must add CHANGESET_VIEW to the above permission list.
 
 
 === !AuthzSourcePolicy  (mod_authz_svn-like permission policy) === #AuthzSourcePolicy

trac/wiki/default-pages/TracImport

 = Importing ticket data =
+[[PageOutline]]
+
+By means of migrating from other issue-tracking systems, perform some external actions over tickets or simply synchronize different data bases, there are some available tools, plug-ins or scripts which lets you import or up-date tickets into Trac.
+
+Below, follows a collection of some of those.
+
+== !TicketImportPlugin ==
+
+ th:TicketImportPlugin:: mainly, but not only, this plug-in lets you import or up-date into Trac a series of tickets from a '''CSV file''' or (if the [http://pypi.python.org/pypi/xlrd xlrd library] is installed) from an '''Excel file'''. 
+
+== !ExportImportXlsPlugin ==
+
+ th:ExportImportXlsPlugin:: this plug-in add an admin panel for export and import tickets via '''XLS file'''.
+  * It depends on the python packages xlwt/rxld.
 
 == Bugzilla ==
 
+ th:BugzillaIssueTrackingPlugin:: integrates Bugzilla into Trac keeping TracLinks
+
 Ticket data can be imported from Bugzilla using the [http://trac.edgewall.org/browser/trunk/contrib/bugzilla2trac.py bugzilla2trac.py] script, available in the contrib/ directory of the Trac distribution.
 
 {{{
 
 For more details on the available options, see the configuration section at the top of the script.
 
-== Sourceforge ==
+== Jira ==
 
-Ticket data can be imported from Sourceforge using the [http://trac.edgewall.org/browser/trunk/contrib/sourceforge2trac.py sourceforge2trac.py] script, available in the contrib/ directory of the Trac distribution.
-
-See #Trac3521 for an updated sourceforge2trac script.
+ th:JiraToTracIntegration:: provides tools to import Atlassian Jira backup files into Trac. The plug-in consists of a Python 3.1 commandline tool that:
+   - Parses the Jira backup XML file
+   - Sends the imported Jira data and attachments to Trac using the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin]
+   - Generates a htpasswd file containing the imported Jira users and their SHA-512 base64 encoded passwords
 
 == Mantis ==
 
-The mantis2trac script now lives at http://trac-hacks.org/wiki/MantisImportScript. You can always get the latest version from http://trac-hacks.org/changeset/latest/mantisimportscript?old_path=/&filename=mantisimportscript&format=zip
-
-Mantis bugs can be imported using the attached script.
-
-Currently, the following data is imported from Mantis:
+ th:MantisImportScript:: script to import from Mantis into Trac the following data:
   * bugs
   * bug comments
   * bug activity (field changes)
-  * attachments (as long as the files live in the mantis db, not on the filesystem) 
+  * attachments (as long as the files live in the mantis db, not on the filesystem) .
 
-If you use the script, please read the NOTES section (at the top of the file) and make sure you adjust the config parameters for your environment.
+== !PlanetForge ==
 
-mantis2trac.py has the same parameters as the bugzilla2trac.py script:
-{{{
-mantis2trac - Imports a bug database from Mantis into Trac.
+ th:PlanetForgeImportExportPlugin:: this plugin exports Trac data (wiki, tickets, compoments, permissions, repositories, etc.) using the open format designed by the COCLICO project. It extends the webadmin panel and the 'trac admin ...' command. Still has no 'import' feature. 
 
-Usage: mantis2trac.py [options] 
+== Scarab ==
 
-Available Options:
-  --db <MySQL dbname>              - Mantis database
-  --tracenv /path/to/trac/env      - Full path to Trac db environment
-  -h | --host <MySQL hostname>     - Mantis DNS host name
-  -u | --user <MySQL username>     - Effective Mantis database user
-  -p | --passwd <MySQL password>   - Mantis database user password
-  -c | --clean                     - Remove current Trac tickets before importing
-  --help | help                    - This help info
+ th:ScarabToTracScript:: script that migrates Scarab issues to Trac tickets
+    * Requires [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin]
 
-Additional configuration options can be defined directly in the script.
-}}} 
+== Sourceforge ==
 
-== Jira ==
+ th:SfnToTracScript:: importer of !SourceForge's new backup file (originated from #Trac3521)
 
-The [http://trac-hacks.org/wiki/JiraToTracIntegration Jira2Trac plugin] provides you with tools to import Atlassian Jira backup files into Trac.
-
-The plugin consists of a Python 3.1 commandline tool that:
-
- - Parses the Jira backup XML file
- - Sends the imported Jira data and attachments to Trac using the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin]
- - Generates a htpasswd file containing the imported Jira users and their SHA-512 base64 encoded passwords
+Also, ticket data can be imported from Sourceforge using the [http://trac.edgewall.org/browser/trunk/contrib/sourceforge2trac.py sourceforge2trac.py] script, available in the contrib/ directory of the Trac distribution.
 
 == Other ==
 
 Since trac uses a SQL database to store the data, you can import from other systems by examining the database tables. Just go into [http://www.sqlite.org/sqlite.html sqlite] command line to look at the tables and import into them from your application.
 
-=== Using a comma delimited file - CSV ===
+=== Comma delimited file - CSV ===
 See [http://trac.edgewall.org/attachment/wiki/TracSynchronize/csv2trac.2.py] for details.  This approach is particularly useful if one needs to enter a large number of tickets by hand. (note that the ticket type type field, (task etc...) is also needed for this script to work with more recent Trac releases)
 Comments on script: The script has an error on line 168, ('Ticket' needs to be 'ticket').  Also, the listed values for severity and priority are swapped. 
 
-=== Using an Excel (.xls) or comma delimited file (.csv) ===
-This plugin http://trac-hacks.org/wiki/TicketImportPlugin lets you import into Trac a series of tickets from a CSV file or (if the xlrd library is installed) from an Excel file.
-
-You can also use it to modify tickets in batch, by saving a report as CSV, editing the CSV file, and re-importing the tickets.
-
-This plugin is very useful when starting a new project: you can import a list of requirements that may have come from meeting notes, list of features, other ticketing systems... It's also great to review the tickets off-line, or to do massive changes to tickets.
-
-Based on the ticket id (or, if no id exists, on the summary) in the imported file, tickets are either created or updated. 
-
-
+----
+See also: 
+ * to import/export wiki pages: TracAdmin, 
+ * to export tickets: TracTickets, TracQuery

trac/wiki/default-pages/TracIni

 = The Trac Configuration File =
 
 [[TracGuideToc]]
+[[PageOutline]]
 
 Trac configuration is done by editing the '''`trac.ini`''' config file, located in `<projectenv>/conf/trac.ini`.  Changes to the configuration are usually reflected immediately, though changes to the `[components]` or `[logging]` sections will require restarting the web server. You may also need to restart the web server after creating a global configuration file when none was previously present.
 
-The `trac.ini` configuration file should be writable by the web server, as Trac currently relies on the possibility to trigger a complete environment reload to flush its caches.
+The `trac.ini` configuration file and its parent directory should be writable by the web server, as Trac currently relies on the possibility to trigger a complete environment reload to flush its caches.
 
 == Global Configuration ==
 
 
 See also: TracPlugins
 
+=== [extra-permissions] === #extra-permissions-section
+''(since 0.12)''
+
+Custom additional permissions can be defined in this section when [wiki:ExtraPermissionsProvider] is enabled.
+
 === [milestone-groups] === #milestone-groups-section
 ''(since 0.11)''
 

trac/wiki/default-pages/TracInstall

 
 Trac is written in the Python programming language and needs a database, [http://sqlite.org/ SQLite], [http://www.postgresql.org/ PostgreSQL], or [http://mysql.com/ MySQL]. For HTML rendering, Trac uses the [http://genshi.edgewall.org Genshi] templating system.
 
-Since version 0.12, Trac can also be localized, and there's probably a translation available for your language. If you want to be able to use the Trac interface in other languages, then make sure you **first** have installed the optional package [#OtherPythonPackages Babel]. Lacking Babel, you will only get the default english version, as usual. If you install Babel later on, you will need to re-install Trac.
+Since version 0.12, Trac can also be localized, and there's probably a translation available for your language. If you want to be able to use the Trac interface in other languages, then make sure you **first** have installed the optional package [#OtherPythonPackages Babel]. Lacking Babel, you will only get the default English version, as usual. If you install Babel later on, you will need to re-install Trac.
 
 If you're interested in contributing new translations for other languages or enhance the existing translations, then please have a look at [trac:wiki:TracL10N TracL10N].
 
-What follows are generic instructions for installing and setting up Trac and its requirements. While you may find instructions for installing Trac on specific systems at TracInstallPlatforms on the main Trac site, please be sure to '''first read through these general instructions''' to get a good understanding of the tasks involved.
+What follows are generic instructions for installing and setting up Trac and its requirements. While you may find instructions for installing Trac on specific systems at [trac:wiki:TracInstallPlatforms TracInstallPlatforms] on the main Trac site, please be sure to '''first read through these general instructions''' to get a good understanding of the tasks involved.
 
 [[PageOutline(2-3,Installation Steps,inline)]]
 
 To install Trac, the following software packages must be installed:
 
  * [http://www.python.org/ Python], version >= 2.4 and < 3.0
-   (note that we dropped the support for Python 2.3 in this release)
+   //(note that we dropped the support for Python 2.3 in this release and that this will be the last Trac release supporting Python 2.4)//
  * [http://peak.telecommunity.com/DevCenter/setuptools setuptools], version >= 0.6
  * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6
 
 ==== Version Control System ====
 
 ===== Subversion =====
- * [http://subversion.apache.org/ Subversion], 1.5.x or 1.6.x and the '''''corresponding''''' Python bindings. Older versions starting from 1.4.0, etc. should still work. For troubleshooting information, check the [trac:TracSubversion#Troubleshooting TracSubversion] page. Versions prior to 1.4.0 won't probably work since trac uses svn core functionality (e.g. svn_path_canonicalize) that is not implemented in the python swig wrapper in svn <= 1.3.x (although it exists in the svn lib itself).
 
-There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. (Good luck finding precompiled SWIG bindings for any Windows package at that listing. TracSubversion points you to [http://alagazam.net Algazam], which works for me under Python 2.6.)
+[http://subversion.apache.org/ Subversion] 1.5.x or 1.6.x and the '''''corresponding''''' Python bindings. 
 
-Note that Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], neither does it work yet with the newer `ctype`-style bindings. [Is there a ticket for implementing ctype bindings?]
+There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. See also the TracSubversion page for details about Windows packages.
 
+Older versions starting from 1.4.0, etc. should still work. For troubleshooting information, check the [trac:TracSubversion#Troubleshooting TracSubversion] page. Versions prior to 1.4.0 won't probably work since trac uses svn core functionality (e.g. svn_path_canonicalize) that is not implemented in the python swig wrapper in svn <= 1.3.x (although it exists in the svn lib itself).
 
-'''Please note:''' if using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported].
+Note that Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], neither does it work yet with the newer `ctype`-style bindings. 
+
+'''Please note:''' if using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:#493 not supported].
 
 
 ===== Others =====
 
 Alternatively you configure Trac to run in any of the following environments.
  * [http://httpd.apache.org/ Apache] with 
-   - [http://code.google.com/p/modwsgi/ mod_wsgi], see [wiki:TracModWSGI] and 
-     http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac
-   - [http://modpython.org/ mod_python 3.3.1], deprecated: see TracModPython)
- * a [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi)
- * an [http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web
-   server (see [trac:TracOnWindowsIisAjp])
- * a CGI-capable web server (see TracCgi), '''but usage of Trac as a cgi script 
-   is highly discouraged''', better use one of the previous options. 
+   - [http://code.google.com/p/modwsgi/ mod_wsgi], see [wiki:TracModWSGI] (preferred)
+   - //[http://modpython.org/ mod_python 3.3.1], see TracModPython (deprecated)//
+ * any [http://www.fastcgi.com/ FastCGI]-capable web server, see TracFastCgi
+ * any [http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web
+   server, see [trac:TracOnWindowsIisAjp]
+ * IIS with [http://code.google.com/p/isapi-wsgi/ Isapi-wsgi], see [trac:TracOnWindowsIisIsapi]
+ * //as a last resort, a CGI-capable web server (see TracCgi), but usage of Trac as a cgi script 
+   is highly discouraged, better use one of the previous options.//
    
 
 ==== Other Python Packages ====
 
- * [http://babel.edgewall.org Babel], version >= 0.9.5, 
+ * [http://babel.edgewall.org Babel], version 0.9.5, 
    needed for localization support[[BR]]
    ''Note: '' If you want to be able to use the Trac interface in other languages, then make sure you first have installed the optional package Babel. Lacking Babel, you will only get the default english version, as usual. If you install Babel later on, you will need to re-install Trac. 
  * [http://docutils.sourceforge.net/ docutils], version >= 0.3.9 
 
 A few examples:
 
- - first install of the latest stable version Trac 0.12.1, with i18n support:
+ - first install of the latest stable version Trac 0.12.2, with i18n support:
    {{{
-   easy_install Babel==0.9.5 Genshi==0.6
+   easy_install Babel==0.9.5
    easy_install Trac
    }}}
    ''It's very important to run the two `easy_install` commands separately, otherwise the message catalogs won't be generated.''
 === From source
 If you want more control, you can download the source in archive form, or do a checkout from one of the official [[Trac:TracRepositories|source code repositories]].
 
-Be sure to have the prerequisites already installed. You can also obtain the Genshi and Babel source packages from http://www.edgewall.org and follow for them a similar installation procedure, or you can just easy_install those, see [#Usingeasy_install above].
+Be sure to have the prerequisites already installed. You can also obtain the Genshi and Babel source packages from http://www.edgewall.org and follow for them a similar installation procedure, or you can just `easy_install` those, see [#Usingeasy_install above].
 
 Once you've unpacked the Trac archive or performed the checkout, move in the top-level folder and do:
 {{{
 $ python ./setup.py install
 }}}
 
-''You'll need root permissions or equivalent for this step.''
+You'll need root permissions or equivalent for this step.
 
 This will byte-compile the python source code and install it as an .egg file or folder in the `site-packages` directory
 of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as htdocs and templates.
 
 === Advanced Options ===
 
+==== Custom location with `easy_install`
+
 To install Trac to a custom location, or find out about other advanced installation options, run:
 {{{
 easy_install --help
 
 The above will place your `tracd` and `trac-admin` commands into `/usr/local/bin` and will install the Trac libraries and dependencies into `/Library/Python/2.5/site-packages`, which is Apple's preferred location for third-party Python application installations.
 
-=== Using `pip`
+==== Using `pip`
 'pip' is an easy_install replacement that is very useful to quickly install python packages.
 To get a trac installation up and running in less than 5 minutes:
 
 }}}
 
 
-== Running the Standalone Server ==
+== Deploying Trac
+
+=== Running the Standalone Server ===
 
 After having created a Trac environment, you can easily try the web interface by running the standalone server [wiki:TracStandalone tracd]:
 {{{
 $ tracd -s --port 8000 /path/to/myproject
 }}}
 
-== Running Trac on a Web Server ==
+=== Running Trac on a Web Server ===
 
-Trac provides various options for connecting to a "real" web server: [wiki:TracCgi CGI], [wiki:TracFastCgi FastCGI], [wiki:TracModWSGI mod_wsgi] and [wiki:TracModPython mod_python]. For decent performance, it is recommended that you use either FastCGI or mod_wsgi.
+Trac provides various options for connecting to a "real" web server: 
+ - [wiki:TracFastCgi FastCGI]
+ - [wiki:TracModWSGI mod_wsgi] 
+ - //[wiki:TracModPython mod_python] (no longer recommended, as mod_python is not actively maintained anymore)//
+ - //[wiki:TracCgi CGI] (should not be used, as the performance is far from optimal)//
 
-Trac also supports [trac:TracOnWindowsIisAjp AJP] which may be your choice if you want to connect to IIS.
+Trac also supports [trac:TracOnWindowsIisAjp AJP] which may be your choice if you want to connect to IIS. Other deployment scenarios are possible: [trac:TracNginxRecipe nginx], [http://projects.unbit.it/uwsgi/wiki/Example#Traconapacheinasub-uri uwsgi], [trac:TracOnWindowsIisIsapi Isapi-wsgi] etc.
 
-==== Generating the Trac cgi-bin directory ====
+==== Generating the Trac cgi-bin directory ==== #cgi-bin
 
 In order for Trac to function properly with FastCGI you need to have a `trac.fcgi` file and for mod_wsgi a `trac.wsgi` file. These are Python scripts which load the appropriate Python code. They can be generated using the `deploy` option of [wiki:TracAdmin trac-admin].
 
 mv /tmp/deploy/* /usr/share/trac
 }}}
 
+
+==== Mapping Static Resources ====
+
+Out of the box, Trac will pass static resources such as style sheets or images through itself. For anything but a tracd only based deployment, this is far from optimal as the web server could be set up to directly serve those static resources (for CGI setup, this is '''highly undesirable''' and will cause abysmal performance).
+
+Web servers such as [http://httpd.apache.org/ Apache] allow you to create “Aliases” to resources, giving them a virtual URL that doesn't necessarily reflect the layout of the servers file system. We also can map requests for static resources directly to the directory on the file system, avoiding processing these requests by Trac itself.
+
+There are two primary URL paths for static resources - `/chrome/common` and `/chrome/site`. Plugins can add their own resources, usually accessible by `/chrome/<plugin>` path, so its important to override only known paths and not try to make universal `/chrome` alias for everything.
+
+Note that in order to get those static resources on the filesystem, you need first to extract the relevant resources from Trac using the [TracAdmin trac-admin]` <environment> deploy` command:
+[[TracAdminHelp(deploy)]]
+
+The target `<directory>` will then contain an `htdocs` directory with:
+ - `site/` - a copy of the environment's directory `htdocs/` 
+ - `common/` - the static resources of Trac itself
+ - `<plugins>/` - one directory for each resource directory managed by the plugins enabled for this environment
+
+===== Example: Apache and `ScriptAlias` ===== #ScriptAlias-example
+
+Assuming the deployment has been done this way:
+{{{
+$ trac-admin /var/trac/env deploy /path/to/trac/htdocs/common
+}}}
+
+Add the following snippet to Apache configuration ''before'' the `ScriptAlias` or `WSGIScriptAlias` (which map all the other requests to the Trac application), changing paths to match your deployment:
+{{{
+Alias /trac/chrome/common /path/to/trac/htdocs/common
+Alias /trac/chrome/site /path/to/trac/htdocs/site
+
+<Directory "/path/to/www/trac/htdocs">
+  Order allow,deny
+  Allow from all
+</Directory>
+}}}
+
+If using mod_python, you might want to add this too (otherwise, the alias will be ignored):
+{{{
+<Location "/trac/chrome/common/">
+  SetHandler None
+</Location>
+}}}
+
+Note that we mapped `/trac` part of the URL to the `trac.*cgi` script, and the path `/trac/chrome/common` is the path you have to append to that location to intercept requests to the static resources. 
+
+Similarly, if you have static resources in a project's `htdocs` directory (which is referenced by `/trac/chrome/site` URL in themes), you can configure Apache to serve those resources (again, put this ''before'' the `ScriptAlias` or `WSGIScriptAlias` for the .*cgi scripts, and adjust names and locations to match your installation):
+{{{
+Alias /trac/chrome/site /path/to/projectenv/htdocs
+
+<Directory "/path/to/projectenv/htdocs">
+  Order allow,deny
+  Allow from all
+</Directory>
+}}}
+
+Alternatively to aliasing `/trac/chrome/common`, you can tell Trac to generate direct links for those static resources (and only those), using the [[wiki:TracIni#trac-section| [trac] htdocs_location]] configuration setting:
+{{{
+[trac]
+htdocs_location = http://static.example.org/trac-common/
+}}}
+Note that this makes it easy to have a dedicated domain serve those static resources (preferentially [http://code.google.com/speed/page-speed/docs/request.html#ServeFromCookielessDomain cookie-less]).
+
+Of course, you still need to make the Trac `htdocs/common` directory available through the web server at the specified URL, for example by copying (or linking) the directory into the document root of the web server:
+{{{
+$ ln -s /path/to/trac/htdocs/common /var/www/static.example.org/trac-common
+}}}
+
+
 ==== Setting up the Plugin Cache ====
 
 Some Python plugins need to be extracted to a cache directory. By default the cache resides in the home directory of the current user. When running Trac on a Web Server as a dedicated user (which is highly recommended) who has no home directory, this might prevent the plugins from starting. To override the cache location you can set the PYTHON_EGG_CACHE environment variable. Refer to your server documentation for detailed instructions on how to set environment variables.
 
 == Configuring Authentication ==
 
-The process of adding, removing, and configuring user accounts for authentication depends on the specific way you run Trac. The basic procedure is described in the [wiki:TracCgi#AddingAuthentication "Adding Authentication"] section on the TracCgi page. To learn how to setup authentication for the frontend you're using, please refer to one of the following pages:
+Trac uses HTTP authentication. You'll need to configure your webserver to request authentication when the `.../login` URL is hit (the virtual path of the "login" button). Trac will automatically pick the REMOTE_USER variable up after you provide your credentials. Therefore, all user management goes through your web server configuration. Please consult the documentation of your web server for more info.
 
- * TracStandalone if you use the standalone server, `tracd`.
- * TracCgi if you use the CGI or FastCGI web front ends.
- * [wiki:TracModWSGI] if you use the Apache mod_wsgi web front end.
- * TracModPython if you use the Apache mod_python web front end.
+The process of adding, removing, and configuring user accounts for authentication depends on the specific way you run Trac. 
 
+Please refer to one of the following sections:
+ * TracStandalone#UsingAuthentication if you use the standalone server, `tracd`.
+ * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: `mod_wsgi` of course, but the same instructions applies also for `mod_python`, `mod_fcgi` or `mod_fastcgi`.
+ * TracFastCgi if you're using another web server with FCGI support (Cherokee, Lighttpd, !LiteSpeed, nginx)
 
-== Automatic reference to the SVN changesets in Trac tickets ==
+== Granting admin rights to the admin user
+Grant admin rights to user admin:
+{{{
+$ trac-admin /path/to/myproject permission add admin TRAC_ADMIN
+}}}
+This user will have an "Admin" entry menu that will allow you to admin your trac project.
+
+== Finishing the install
+
+=== Automatic reference to the SVN changesets in Trac tickets ===
 
 You can configure SVN to automatically add a reference to the changeset into the ticket comments, whenever changes are committed to the repository. The description of the commit needs to contain one of the following formulas:
  * '''`Refs #123`''' - to reference this changeset in `#123` ticket
 }}}
 For more information, see the documentation of the `CommitTicketUpdater` component in the "Plugins" admin panel.
 
-== Using Trac ==
+=== Using Trac ===
 
 Once you have your Trac site up and running, you should be able to create tickets, view the timeline, browse your version control repository if configured, etc.
 
-Keep in mind that anonymous (not logged in) users can by default access most but not all of the features. You will need to configure authentication and grant additional [wiki:TracPermissions permissions] to authenticated users to see the full set of features.
+Keep in mind that //anonymous// (not logged in) users can by default access only a few of the features, in particular they will have a read-only access to the resources. You will need to configure authentication and grant additional [wiki:TracPermissions permissions] to authenticated users to see the full set of features.
 
 '' Enjoy! ''
 
 [trac:TracTeam The Trac Team]
 
 ----
-See also: [trac:TracInstallPlatforms TracInstallPlatforms], TracGuide, TracCgi, TracFastCgi, TracModPython, [wiki:TracModWSGI], TracUpgrade, TracPermissions
+See also: [trac:TracInstallPlatforms TracInstallPlatforms], TracGuide, TracUpgrade, TracPermissions

trac/wiki/default-pages/TracInterfaceCustomization

 = Customizing the Trac Interface =
 [[TracGuideToc]]
+[[PageOutline]]
 
 == Introduction ==
 This page is meant to give users suggestions on how they can customize the look of Trac.  Topics on this page cover editing the HTML templates and CSS files, but not the program code itself.  The topics are intended to show users how they can modify the look of Trac to meet their specific needs.  Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page.
 Now configure the appropriate section of your [wiki:TracIni trac.ini]:
 
 === Logo ===
-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 ones). Note that 'site/' is not a placeholder for your project name, it is the actual prefix that should be used (literally). For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'.
+Change the `src` setting to `site/` followed by the name of your image file.  The `width` and `height` settings should be modified to match your image's dimensions (the Trac chrome handler uses "`site/`" for files within the project directory `htdocs`, and "`common/`" for the common `htdocs` directory belonging to a Trac installation). Note that 'site/' is not a placeholder for your project name, it is the actual prefix that should be used (literally). For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'.
 
 {{{
 [header_logo]
 }}}
 
 === Icon ===
-Icons should be a 16x16 image in `.gif` or `.ico` format.  Change the `icon` setting to `site/` followed by the name of your icon file.  Icons will typically be displayed by your web browser next to the site's URL and in the `Bookmarks` menu.
+Icons should be a 32x32 image in `.gif` or `.ico` format.  Change the `icon` setting to `site/` followed by the name of your icon file.  Icons will typically be displayed by your web browser next to the site's URL and in the `Bookmarks` menu.
 
 {{{
 [project]
 == Custom Navigation Entries ==
 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).
 
-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 .
+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 .
 {{{
 [mainnav]
 wiki.label = Home
 Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Documentation is yet to be written, in the meantime the following tip should work.
 
 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), e.g. {{{/path/to/env/templates/site.html}}}:
+header and footer. Save the following content as `site.html` inside your projects `templates/` directory (each Trac project can have their own `site.html`), e.g. {{{/path/to/env/templates/site.html}}}:
 
 {{{
 #!xml
 </html>
 }}}
 
-Those who are familiar with XSLT may notice that Genshi templates bear some similarities. However, there are some Trac specific features - for example '''${href.chrome('site/style.css')}''' attribute references template placed into environment's ''htdocs/''  In a similar fashion '''${chrome.htdocs_location}''' is used to specify common ''htdocs/'' directory from Trac installation.
+Those who are familiar with XSLT may notice that Genshi templates bear some similarities. However, there are some Trac specific features - for example `${href.chrome('site/style.css')}` attribute references a CSS file placed into environment's `htdocs/` directory. In a similar fashion `${chrome.htdocs_location}` is used to specify the common `htdocs/` directory belonging to a Trac installation. That latter location can however be overriden using the [[TracIni#trac-config|[trac] htdocs_location]] configuration setting.
 
-`site.html` is one file to contain all your modifications. It usually works by the py:match (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
+`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.
 See [http://groups.google.com/group/trac-users/browse_thread/thread/70487fb2c406c937/ this thread] for a detailed explanation of the above example `site.html`.
-A site.html can contain any number of such py:match sections for whatever you need to modify. This is all [http://genshi.edgewall.org/ Genshi], so the docs on the exact syntax can be found there.
+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.
 
 
-Example snippet of adding introduction text to the new ticket form (hide when preview):
+Example snippet of adding introduction text to the new ticket form (but not shown during preview):
 
-{{{
-#!xml
+{{{#!xml
 <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')">
   <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)">
     <p>Please make sure to search for existing tickets before reporting a new one!</p>
 </form>
 }}}
 
-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.
+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.
 
 More examples snippets for `site.html` can be found at [trac:wiki:CookBook/SiteHtml CookBook/SiteHtml].
 
 </form>
 }}}
 
-Also note that the `site.html` (despite its name) can be put in a common templates directory - see the `[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.
+Also note that the `site.html` (despite its name) can be put in a common templates directory - see the [[TracIni#inherit-section|[inherit] templates_dir]] option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global `site.html` file can be made to include any existing header, footer and newticket snippets.
 
 == Project List == #ProjectList
 

trac/wiki/default-pages/TracModPython

 
 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.
 
-These instructions are for Apache 2; if you are still using Apache 1.3, you may have some luck with [trac:wiki:TracModPython2.7 TracModPython2.7].
-
-== A Word of Warning ==
+{{{#!div class="important"
+** A Word of Warning **
 
 As of 16^th^ June 2010, the mod_python project is officially dead.  If you are considering using mod_python for a new installation, '''please don't'''!  There are known issues which will not be fixed and there are now better alternatives.  Check out the main TracInstall pages for your target version for more information.
+}}}
 
-== Simple configuration ==
+
+These instructions are for Apache 2; if you are still using Apache 1.3, you may have some luck with [trac:wiki:TracModPython2.7 TracModPython2.7], but you'll be totally on your own.
+
+[[PageOutline(2-3,Overview,inline)]]
+
+== Simple configuration: single project == #Simpleconfiguration
 
 If you just installed mod_python, you may have to add a line to load the module in the Apache configuration:
 {{{
 {{{
     # For a single project
     PythonOption TracEnv /var/trac/myproject
+
     # For multiple projects
     PythonOption TracEnvParentDir /var/trac/myprojects
+
     # For the index of multiple projects
     PythonOption TracEnvIndexTemplate /srv/www/htdocs/trac/project_list_template.html
+
     # A space delimitted list, with a "," between key and value pairs.
     PythonOption TracTemplateVars key1,val1 key2,val2
+
     # Useful to get the date in the wanted order
     PythonOption TracLocale en_GB.UTF8
+
     # See description above        
     PythonOption TracUriRoot /projects/myproject
 }}}
 }}}
 
 or you can uncompress the Genshi egg to resolve problems extracting from it.
+
 === Configuring Authentication ===
 
-Creating password files and configuring authentication works similar to the process for [wiki:TracCgi#AddingAuthentication CGI]:
-{{{
-#!xml
-<Location /projects/myproject/login>
-  AuthType Basic
-  AuthName "myproject"
-  AuthUserFile /var/trac/myproject/.htpasswd
-  Require valid-user
-</Location>
-}}}
+See corresponding section in the [wiki:TracModWSGI#ConfiguringAuthentication] page.
 
-Configuration for mod_ldap authentication in Apache is a bit tricky (httpd 2.2.x and OpenLDAP: slapd 2.3.19)
 
-1. You need to load the following modules in Apache httpd.conf
-{{{
-LoadModule ldap_module modules/mod_ldap.so
-LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
-}}}
-
-2. Your httpd.conf also needs to look something like:
-
-{{{
-#!xml
-<Location /trac/>
-  SetHandler mod_python
-  PythonInterpreter main_interpreter
-  PythonHandler trac.web.modpython_frontend
-  PythonOption TracEnv /home/trac/
-  PythonOption TracUriRoot /trac/
-  Order deny,allow
-  Deny from all
-  Allow from 192.168.11.0/24
-  AuthType Basic
-  AuthName "Trac"
-  AuthBasicProvider "ldap"
-  AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=co,dc=ke?uid?sub?(objectClass=inetOrgPerson)"
-  authzldapauthoritative Off
-  require valid-user
-</Location>
-}}}
-
-Or the LDAP interface to a Microsoft Active Directory:
-
-{{{
-#!xml
-<Location /trac/>
-  SetHandler mod_python
-  PythonInterpreter main_interpreter
-  PythonHandler trac.web.modpython_frontend
-  PythonOption TracEnv /home/trac/
-  PythonOption TracUriRoot /trac/
-  Order deny,allow
-  Deny from all
-  Allow from 192.168.11.0/24
-  AuthType Basic
-  AuthName "Trac"
-  AuthBasicProvider "ldap"
-  AuthLDAPURL "ldap://adserver.company.com:3268/DC=company,DC=com?sAMAccountName?sub?(objectClass=user)"
-  AuthLDAPBindDN       ldap-auth-user@company.com
-  AuthLDAPBindPassword "the_password"
-  authzldapauthoritative Off
-  # require valid-user
-  require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
-</Location>
-}}}
-
-Note 1: This is the case where the LDAP search will get around the multiple OUs, conecting to Global Catalog Server portion of AD (Notice the port is 3268, not the normal LDAP 389). The GCS is basically a "flattened" tree which allows searching for a user without knowing to which OU they belong.
-
-Note 2: Active Directory requires an authenticating user/password to access records (AuthLDAPBindDN and AuthLDAPBindPassword).
-
-Note 3: The directive "require ldap-group ..."  specifies an AD group whose members are allowed access.
-
+== Advanced Configuration
 
 === Setting the Python Egg Cache ===
 
 
 Be careful about using the !PythonPath directive, and ''not'' `SetEnv PYTHONPATH`, as the latter won't work.
 
-== Setting up multiple projects ==
+=== Setting up multiple projects ===
 
 The Trac mod_python handler supports a configuration option similar to Subversion's `SvnParentPath`, called `TracEnvParentDir`:
 {{{
 </LocationMatch>
 }}}
 
-== Virtual Host Configuration ==
+=== Virtual Host Configuration ===
 
 Below is the sample configuration required to set up your trac as a virtual server (i.e. when you access it at the URLs like
 !http://trac.mycompany.com):
 
 For multiple projects, try restarting the server as well.
 
+===Login Not Working===
+If you've used <Location /> directive, it will override any other directives, as well as <Location /Login>.
+The workaround is to use negation expression as follows (for multi project setups):
+{{{
+#!xml
+#this one for other pages
+<Location ~ "/*(?!login)">
+   SetHandler mod_python
+   PythonHandler trac.web.modpython_frontend
+   PythonOption TracEnvParentDir /projects
+   PythonOption TracUriRoot /
+
+</Location>
+#this one for login page
+<Location ~ "/[^/]+/login">
+   SetHandler mod_python
+   PythonHandler trac.web.modpython_frontend
+   PythonOption TracEnvParentDir /projects
+   PythonOption TracUriRoot /
+
+   #remove these if you don't want to force SSL
+   RewriteEngine On 
+   RewriteCond %{HTTPS} off
+   RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
+
+   AuthType Basic
+   AuthName "Trac"
+   AuthUserFile /projects/.htpasswd
+   Require valid-user
+</Location>
+}}}
+
 === Expat-related segmentation faults === #expat
 
 This problem will most certainly hit you on Unix when using Python 2.4.
 It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth. Stick to the provided instructions. :)
 
 A success story: For me it worked out-of-box, with following trivial config:
-{{{
+{{{#!xml
 SetHandler mod_python
 PythonInterpreter main_interpreter
 PythonHandler trac.web.modpython_frontend 
 </IfModule>
 }}}
 
-
-=== Win32 Issues ===
+=== Platform specific issues
+==== Win32 Issues ====
 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.
 
 
-=== OS X issues ===
+==== OS X issues ====
 
 When using mod_python on OS X you will not be able to restart Apache using `apachectl restart`. This is apparently fixed in mod_python 3.2, but there's also a patch available for earlier versions [http://www.dscpl.com.au/projects/vampire/patches.html here].
 
-=== SELinux issues ===
+==== SELinux issues ====
 
 If Trac reports something like: ''Cannot get shared lock on db.lock''
 The security context on the repository may need to be set:
 
 See also [http://subversion.tigris.org/faq.html#reposperms]
 
-=== FreeBSD issues ===
+==== FreeBSD issues ====
 Pay attention to the version of the installed mod_python and sqlite packages. Ports have both the new and old ones, but earlier versions of pysqlite and mod_python won't integrate as the former requires threaded support in python, and the latter requires a threadless install.
 
 If you compiled and installed apache2, apache wouldn´t support threads (cause it doesn´t work very well on FreeBSD). You could force thread support when running ./configure for apache, using --enable-threads, but this isn´t recommendable.
 export LD_PRELOAD=/usr/lib/libc_r.so
 }}}
 
+
+==== Fedora 7 Issues ====
+Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython but not for tracd
+
+
 === Subversion issues ===
 
 If you get the following Trac Error `Unsupported version control system "svn"` only under mod_python, though it works well on the command-line and even with TracStandalone, chances are that you forgot to add the path to the Python bindings with the [TracModPython#ConfiguringPythonPath PythonPath] directive. (The better way is to add a link to the bindings in the Python `site-packages` directory, or create a `.pth` file in that directory.)
 </VirtualHost>
 }}}
 
-=== Fedora 7 Issues ===
-Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython but not for tracd
-
 
 === Segmentation fault with php5-mhash or other php5 modules ===
 You may encounter segfaults (reported on debian etch) if php5-mhash module is installed. Try to remove it to see if this solves the problem. See debian bug report [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487]

trac/wiki/default-pages/TracModWSGI

 = Trac and mod_wsgi =
 
-'''Important note:''' ''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. 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].''
 
-[http://code.google.com/p/modwsgi/ mod_wsgi] is an Apache module for running WSGI-compatible Python applications directly on top of Apache. The mod_wsgi adapter is written completely in C and provides significantly better performance than using existing WSGI adapters for mod_python or CGI.
+[http://code.google.com/p/modwsgi/ mod_wsgi] is an Apache module for running WSGI-compatible Python applications directly on top of the Apache webserver. The mod_wsgi adapter is written completely in C and provides very good performances.
 
-Trac can be run on top of mod_wsgi with the help of the following application script, which is just a Python file, though usually saved with a .wsgi extension). This file can be created using '''trac-admin <env> deploy <dir>''' command which automatically substitutes required paths.
+[[PageOutline(2-3,Overview,inline)]]
 
-{{{
-#!python
+== The `trac.wsgi` script
+
+Trac can be run on top of mod_wsgi with the help of the following application script, which is just a Python file, though usually saved with a `.wsgi` extension). 
+
+=== A very basic script
+In its simplest form, the script could be:
+
+{{{#!python
 import os
 
 os.environ['TRAC_ENV'] = '/usr/local/trac/mysite'
 
 The `TRAC_ENV` variable should naturally be the directory for your Trac environment (if you have several Trac environments in a directory, you can also use `TRAC_ENV_PARENT_DIR` instead), while the `PYTHON_EGG_CACHE` should be a directory where Python can temporarily extract Python eggs.
 
-'''Important note:''' If you're using multiple `.wsgi` files (for example one per Trac environment) you must ''not'' use `os.environ['TRAC_ENV']` to set the path to the Trac environment. Using this method may lead to Trac delivering the content of another Trac environment. (The variable may be filled with the path of a previously viewed Trac environment.) To solve this problem, use the following `.wsgi` file instead:
+=== A more elaborate script
 
-{{{
-#!python
+If you're using multiple `.wsgi` files (for example one per Trac environment) you must ''not'' use `os.environ['TRAC_ENV']` to set the path to the Trac environment. Using this method may lead to Trac delivering the content of another Trac environment, as the variable may be filled with the path of a previously viewed Trac environment. 
+
+To solve this problem, use the following `.wsgi` file instead:
+{{{#!python
 import os
 
 os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'
   return trac.web.main.dispatch_request(environ, start_response)
 }}}
 
-For clarity, you should give this file a `.wsgi` extension. You should probably put the file in it's own directory, since you will open up its directory to Apache. You can create a .wsgi files which handles all this for you by running the TracAdmin command `deploy`.
+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. 
 
-If you have installed trac and eggs in a path different from the standard one you should add that path by adding the following code on top of the wsgi script:
+If you have installed Trac and eggs in a path different from the standard one you should add that path by adding the following code at the top of the wsgi script:
 
-{{{
-#!python
+{{{#!python
 import site
 site.addsitedir('/usr/local/trac/lib/python2.4/site-packages')
 }}}
 
-Change it according to the path you installed the trac libs at.
+Change it according to the path you installed the Trac libs at.
 
-After you've done preparing your wsgi-script, add the following to your httpd.conf.
+=== Recommended `trac.wsgi` script
+
+A somewhat robust and generic version of this file can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths (see TracInstall#cgi-bin).
+
+
+== Mapping requests to the script
+
+After you've done preparing your .wsgi script, add the following to your Apache configuration file (`httpd.conf` for example).
 
 {{{
 WSGIScriptAlias /trac /usr/local/trac/mysite/apache/mysite.wsgi
 </Directory>
 }}}
 
-Here, the script is in a subdirectory of the Trac environment. 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 subinterpreters and may cause requests to hang or cause Apache to crash as a result. After adding this configuration, restart Apache, and then it should work.
+Here, the script is in a subdirectory of the Trac environment.
 
-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):
+If you followed the directions [http://trac.edgewall.org/wiki/TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following:
 
 {{{
+WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi
+
+<Directory /usr/share/trac/cgi-bin>
+    WSGIApplicationGroup %{GLOBAL}
+    Order deny,allow
+    Allow from all
+</Directory>
+}}}
+
+In order to let Apache run the script, access to the directory in which the script resides is opened up to all of Apache. Additionally, the `WSGIApplicationGroup` directive ensures that Trac is always run in the first Python interpreter created by mod_wsgi; this is necessary because the Subversion Python bindings, which are used by Trac, don't always work in other sub-interpreters and may cause requests to hang or cause Apache to crash as a result. After adding this configuration, restart Apache, and then it should work.
+
+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):
+
+{{{#!python
 def application(environ, start_response):
         start_response('200 OK',[('Content-type','text/html')])
         return ['<html><body>Hello World!</body></html>']
 }}}
 
-See also the mod_wsgi [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac installation instructions] for Trac.
+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.
 
-For troubleshooting tips, see 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.
 
-''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''
+== Configuring Authentication
 
-== Apache Basic Authentication for Trac thru mod_wsgi ==
+We describe in the the following sections different methods for setting up authentication.
 
-Per the mod_wsgi documentation linked to above, here is an example Apache configuration that a) serves the trac from a virtualhost subdomain and b) uses Apache basic authentication for Trac authentication.
+See also [http://httpd.apache.org/docs/2.2/howto/auth.html Authentication, Authorization and Access Control] in the Apache guide.
 
+=== Using Basic Authentication ===
 
-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:
+The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program to create the password file:
+{{{
+$ htpasswd -c /somewhere/trac.htpasswd admin
+New password: <type password>
+Re-type new password: <type password again>
+Adding password for user admin
+}}}
 
-create the htpasswd file:
+After the first user, you dont need the "-c" option anymore:
+{{{
+$ htpasswd /somewhere/trac.htpasswd john
+New password: <type password>
+Re-type new password: <type password again>
+Adding password for user john
+}}}
+
+  ''See the man page for `htpasswd` for full documentation.''
+
+After you've created the users, you can set their permissions using TracPermissions.
+
+Now, you'll need to enable authentication against the password file in the Apache configuration:
+{{{
+<Location "/trac/login">
+  AuthType Basic
+  AuthName "Trac"
+  AuthUserFile /somewhere/trac.htpasswd
+  Require valid-user
+</Location>
+}}}
+
+If you're hosting multiple projects you can use the same password file for all of them:
+{{{
+<LocationMatch "/trac/[^/]+/login">
+  AuthType Basic
+  AuthName "Trac"
+  AuthUserFile /somewhere/trac.htpasswd
+  Require valid-user
+</LocationMatch>
+}}}
+Note that neither a file nor a directory named 'login' needs to exist.[[BR]]
+See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html mod_auth_basic] documentation.
+
+=== Using Digest Authentication ===
+
+For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”. 
+
+You'll have to create your `.htpasswd` file with the `htdigest` command instead of `htpasswd`, as follows:
+{{{
+# htdigest -c /somewhere/trac.htpasswd trac admin
+}}}
+
+The "trac" parameter above is the "realm", and will have to be reused in the Apache configuration in the !AuthName directive:
+
+{{{
+<Location "/trac/login">
+
+    AuthType Digest
+    AuthName "trac"
+    AuthDigestDomain /trac
+    AuthUserFile /somewhere/trac.htpasswd
+    Require valid-user
+</Location>
+}}}
+
+For multiple environments, you can use the same `LocationMatch` as described with the previous method.
+
+Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system:
+{{{
+    LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
+}}}
+
+
+See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_digest.html mod_auth_digest] documentation.
+
+=== Using LDAP Authentication 
+
+Configuration for [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap] authentication in Apache is a bit tricky (httpd 2.2.x and OpenLDAP: slapd 2.3.19)
+
+1. You need to load the following modules in Apache httpd.conf
+{{{
+LoadModule ldap_module modules/mod_ldap.so
+LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
+}}}
+
+2. Your httpd.conf also needs to look something like:
+
+{{{
+<Location /trac/>
+  # (if you're using it, mod_python specific settings go here)
+  Order deny,allow
+  Deny from all
+  Allow from 192.168.11.0/24
+  AuthType Basic
+  AuthName "Trac"
+  AuthBasicProvider "ldap"
+  AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=co,dc=ke?uid?sub?(objectClass=inetOrgPerson)"
+  authzldapauthoritative Off
+  Require valid-user
+</Location>
+}}}
+
+
+3. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory:
+
+
+Use the following as your LDAP URL:
+{{{
+    AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)"
+}}}
+
+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 should be sure to use an account specifically for this task:
+{{{
+    AuthLDAPBindDN ldap-auth-user@example.com
+    AuthLDAPBindPassword "password"
+}}}
+
+The whole section looks like:
+{{{
+<Location /trac/>
+  # (if you're using it, mod_python specific settings go here)
+  Order deny,allow
+  Deny from all
+  Allow from 192.168.11.0/24
+  AuthType Basic
+  AuthName "Trac"
+  AuthBasicProvider "ldap"
+  AuthLDAPURL "ldap://adserver.company.com:3268/DC=company,DC=com?sAMAccountName?sub?(objectClass=user)"
+  AuthLDAPBindDN       ldap-auth-user@company.com
+  AuthLDAPBindPassword "the_password"
+  authzldapauthoritative Off
+  # require valid-user
+  require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
+</Location>
+}}}
+
+Note 1: This is the case where the LDAP search will get around the multiple OUs, conecting to Global Catalog Server portion of AD (Notice the port is 3268, not the normal LDAP 389). The GCS is basically a "flattened" tree which allows searching for a user without knowing to which OU they belong.
+
+Note 2: You can also require the user be a member of a certain LDAP group, instead of
+just having a valid login:
+{{{
+    Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com
+}}}
+
+See also:
+  - [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html mod_authnz_ldap], documentation for mod_authnz_ldap
+    
+ - [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.
+ - [http://trac-hacks.org/wiki/LdapPlugin TracHacks:LdapPlugin] for storing TracPermissions in LDAP.
+
+=== Using SSPI Authentication
+
+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:
+{{{
+    <Location /trac/login>
+        AuthType SSPI
+        AuthName "Trac Login"
+        SSPIAuth On
+        SSPIAuthoritative On
+        SSPIDomain MyLocalDomain
+        SSPIOfferBasic On
+        SSPIOmitDomain Off
+        SSPIBasicPreferred On
+        Require valid-user
+    </Location>
+}}}
+
+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.
+
+Some common problems with SSPI authentication: [trac:#1055], [trac:#1168] and [trac:#3338].
+
+See also [trac:TracOnWindows/Advanced].
+
+=== Using Apache authentication with the Account Manager plugin's Login form ===
+
+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].
+
+'''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.
+
+Here is an example (from the !HttpAuthStore link) using acct_mgr-0.4 for hosting a single project:
+{{{
+[components]
+; be sure to enable the component
+acct_mgr.http.HttpAuthStore = enabled
+
+[account-manager]
+; configure the plugin to use a page that is secured with http authentication
+authentication_url = /authFile
+password_store = HttpAuthStore
+}}}
+This will generally be matched with an Apache config like:
+{{{
+<Location /authFile>
+   …HTTP authentication configuration…
+   Require valid-user
+</Location>
+}}}
+Note that '''authFile''' need not exist. See the !HttpAuthStore link above for examples where multiple Trac projects are hosted on a server.
+
+=== Example: Apache/mod_wsgi with Basic Authentication, Trac being at the root of a virtual host
+
+Per the mod_wsgi documentation linked to above, here is an example Apache configuration that a) serves the Trac instance from a virtualhost subdomain and b) uses Apache basic authentication for Trac authentication.
+
+
+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:
+
+Create the htpasswd file:
 {{{
 cd /home/trac-for-my-proj/the-env
 htpasswd -c htpasswd firstuser
 ### and add more users to it as needed:
 htpasswd htpasswd seconduser
 }}}
-(for security keep the file above your document root)
+(keep the file above your document root for security reasons)
 
-create this file e.g. (ubuntu) {{{/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf}}} with these contents:
+Create this file e.g. (ubuntu) `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` with the following contents:
 
 {{{
 <Directory /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi>
 
 }}}
 
+Note: for subdomains to work you would probably also need to alter `/etc/hosts` and add A-Records to your host's DNS.
 
-(for subdomains to work you would probably also need to alter /etc/hosts and add A-Records to your host's DNS.)
 
-== Trac with PostgreSQL ==
+== Troubleshooting
 
-When using the mod_wsgi adapter with multiple Trac instances and PostgreSQL (or MySQL?) as a database back-end the server can get a lot of open database connections. (and thus PostgreSQL processes)
+=== Use a recent version
 
-A workable solution is to disabled connection pooling in Trac. This is done by setting poolable = False in trac.db.postgres_backend on the PostgreSQLConnection class.
+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].
 
-But it's not necessary to edit the source of trac, the following lines in trac.wsgi will also work:
+''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''
 
-{{{
-import trac.db.postgres_backend
-trac.db.postgres_backend.PostgreSQLConnection.poolable = False
-}}}
-
-Now Trac drops the connection after serving a page and the connection count on the database will be kept minimal.
-
-== Getting Trac to work nicely with SSPI and 'Require Group' ==
+=== Getting Trac to work nicely with SSPI and 'Require Group' ===
 If like me you've set Trac up on Apache, Win32 and configured SSPI, but added a 'Require group' option to your apache configuration, then the SSPIOmitDomain option is probably not working.  If its not working your usernames in trac are probably looking like 'DOMAIN\user' rather than 'user'.
 
 This WSGI script 'fixes' things, hope it helps:
-{{{
+{{{#!python
 import os
 import trac.web.main
 
         environ['REMOTE_USER'] = environ['REMOTE_USER'].split("\\", 1)[1]
     return trac.web.main.dispatch_request(environ, start_response)
 }}}
+
+
+=== Trac with PostgreSQL ===
+
+When using the mod_wsgi adapter with multiple Trac instances and PostgreSQL (or MySQL?) as a database back-end, the server ''may'' create a lot of open database connections and thus PostgreSQL processes.
+
+A somewhat brutal workaround is to disabled connection pooling in Trac. This is done by setting `poolable = False` in `trac.db.postgres_backend` on the `PostgreSQLConnection` class.
+
+But it's not necessary to edit the source of Trac, the following lines in `trac.wsgi` will also work:
+
+{{{
+import trac.db.postgres_backend
+trac.db.postgres_backend.PostgreSQLConnection.poolable = False
+}}}
+
+Now Trac drops the connection after serving a page and the connection count on the database will be kept minimal.
+
+//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.//
+
+=== Other resources
+
+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.
+
+
 ----
 See also:  TracGuide, TracInstall, [wiki:TracFastCgi FastCGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]

trac/wiki/default-pages/TracNavigation

 
 Starting with Trac 0.11, it is now possible to customize the main and meta navigation entries in some basic ways.
 
-The new `[mainnav]` and `[metanav]` configuration sections can now be used to customize the text and link used for the navigation items, or even to disable them.
+The new `[mainnav]` and `[metanav]` configuration sections can now be used to customize the text and link used for the navigation items, or even to disable them.  The `mainnav` and `metanav` options in the `[trac]` configuration section can also be used to change the order.
 
 === `[mainnav]` #mainnav-bar
-`[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 and accessible for the current user.
+`[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.
 
 
 ** [=#Example Example] ** 
 
-In the following example, we rename the link to the Wiki start "Home", and hide the "!Help/Guide" link. 
-We also make the "View Tickets" entry link to a specific report.
+In the following example, we rename the link to the Wiki start "Home", and make the "View Tickets" entry link to a specific report.  The second example (below) also hides the "!Help/Guide" link.
 
 Relevant excerpt from the TracIni:
 {{{
 || `/projects` || `/projects` ||
 
 
+=== `[trac]` #nav-order
+The `mainnav` and `metanav` options in the `[trac]` configuration section control the order in which the navigation items are displayed (left to right).  This can be useful with plugins that add navigation items.
+
+** Example ** 
+
+In the following example, we change the order to prioritise the ticket related items further left.
+
+Relevant excerpt from the TracIni:
+{{{
+[trac]
+mainnav = wiki,tickets,newticket,timeline,roadmap,browser,search,admin
+}}}
+
+The default order and item names can be found in the source, which at the time of writing [source:trunk/trac/web/chrome.py@10883:397,402-403#L396 is here]
+
+=== Context Navigation #ctxtnav-bar
+
 Note that it is still not possible to customize the '''contextual navigation bar''', i.e. the one usually placed below the main navigation bar.
 
 

trac/wiki/default-pages/TracNotification

 
 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.
 
+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`''').
+
 == Configuring SMTP Notification ==
 
 '''Important:''' For TracNotification to work correctly, the `[trac] base_url` option must be set in [wiki:TracIni trac.ini]. 
  * '''`always_notify_updater`''': (''since 0.10'') Always send a notification to the updater of a ticket (default: true).
  * '''`use_public_cc`''': (''since 0.10'') Addresses in To: (owner, reporter) and Cc: lists are visible by all recipients (default is ''Bcc:'' - hidden copy).
  * '''`use_short_addr`''': (''since 0.10'') Enable delivery of notifications to addresses that do not contain a domain (i.e. do not end with ''@<domain.com>'').This option is useful for intranets, where the SMTP server can handle local addresses and map the username/login to a local mailbox. See also `smtp_default_domain`. Do not use this option with a public SMTP server. 
+ * '''`ignore_domains`''': Comma-separated list of domains that should not be considered part of email addresses (for usernames with Kerberos domains).
  * '''`mime_encoding`''': (''since 0.10'') This option allows selecting the MIME encoding scheme. Supported values:
    * `none`: default value, uses 7bit encoding if the text is plain ASCII, or 8bit otherwise. 
    * `base64`: works with any kind of content. May cause some issues with touchy anti-spam/anti-virus engines.
  * '''`ticket_subject_template`''': (''since 0.11'') A [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet used to get the notification subject.
  * '''`email_sender`''': (''since 0.12'') Name of the component implementing `IEmailSender`. This component is used by the notification system to send emails. Trac currently provides the following components:
    * `SmtpEmailSender`: connects to an SMTP server (default).
-   * `SendmailEmailSender`: runs a `sendmail`-compatible executable.
+   * `SendmailEmailSender`: runs a `sendmail`-compatible executable.