# Changeset 40534

Ignore:
Timestamp:
06/15/17 06:03:07 (5 years ago)
Message:

[titan] autoupdate wiki files

Location:
wiki/pages
Files:
19 edited

Unmodified
Removed
• ## wiki/pages/TracInterfaceCustomization

 r40226 = Customizing the Trac Interface [[TracGuideToc]] [[PageOutline]] == Introduction This page gives suggestions on how to customize the look of Trac. Topics include editing the HTML templates and CSS files, but not the program code itself. The topics show users how they can modify the look of Trac to meet their specific needs. Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page. == Project Logo and Icon The easiest parts of the Trac interface to customize are the logo and the site icon. Both of these can be configured with settings in [wiki:TracIni trac.ini]. The logo or icon image should be put in a folder named "htdocs" in your project's environment folder. ''Note: in projects created with a Trac version prior to 0.9 you will need to create this folder''. '''Note''': you can actually put the logo and icon anywhere on your server (as long as it's accessible through the web server), and use their absolute or server-relative URLs in the configuration. 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 htdocs directory belonging to a Trac installation. Note that 'site/' is not a placeholder for your project name, it is the literal prefix that should be used. For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'. {{{#!ini [header_logo] src = site/my_logo.gif alt = My Project width = 300 height = 100 }}} === Icon Icons are small images displayed by your web browser next to the site's URL and in the Bookmarks menu. Icons should be a 32x32 image in .gif or .ico format. Change the icon setting to site/ followed by the name of your icon file: {{{#!ini [project] icon = site/my_icon.ico }}} == 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: {{{#!ini [mainnav] wiki.label = Home tickets.href = /report/24 [metanav] help = disabled }}} See also TracNavigation for a more detailed explanation of the mainnav and metanav terms. == Site Appearance == #SiteAppearance Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Say you want to add a link to a custom stylesheet, and then your own header and footer. Save the following content as site.html inside your projects templates/ directory (each Trac project can have their own site.html), eg /path/to/env/templates/site.html: {{{#!xml ${select('*|comment()|text()')}${select('*|text()')} }}} Notice that XSLT bears some similarities with Genshi templates. However, there are some Trac specific features, for example the ${href.chrome('site/style.css')} attribute references style.css in the environment's htdocs/ directory. In a similar fashion ${chrome.htdocs_location} is used to specify the common htdocs/ directory belonging to a Trac installation. That latter location can however be overriden using the [[TracIni#trac-section|[trac] htdocs_location]] configuration setting. 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 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 (but not shown during preview): {{{#!xml

Please make sure to search for existing tickets before reporting a new one!

• ## wiki/pages/TracModPython

 r40226 [[TracGuideToc]] = Trac and mod_python Mod_python is an [https://httpd.apache.org/ Apache] module that embeds the Python interpreter within the server, so that web-based applications in Python will run many times faster than traditional CGI and will have the ability to retain database connections. 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 using Apache 1.3, you may have some luck with [trac:wiki:TracModPython2.7 TracModPython2.7], but that is a deprecated setup. [[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: {{{#!apache LoadModule python_module modules/mod_python.so }}} '''Note''': The exact path to the module depends on how the HTTPD installation is laid out. On Debian using apt-get: {{{#!sh apt-get install libapache2-mod-python libapache2-mod-python-doc }}} Still on Debian, after you have installed mod_python, you must enable the modules in apache2, equivalent to the above Load Module directive: {{{#!sh a2enmod python }}} On Fedora use, using yum: {{{#!sh yum install mod_python }}} You can test your mod_python installation by adding the following to your httpd.conf. You should remove this when you are done testing for security reasons. Note: mod_python.testhandler is only available in mod_python 3.2+. {{{#!apache SetHandler mod_python PythonInterpreter main_interpreter PythonHandler mod_python.testhandler Order allow,deny Allow from all }}} A simple setup of Trac on mod_python looks like this: {{{#!apache SetHandler mod_python PythonInterpreter main_interpreter PythonHandler trac.web.modpython_frontend PythonOption TracEnv /var/trac/myproject PythonOption TracUriRoot /projects/myproject Order allow,deny Allow from all }}} The option '''TracUriRoot''' may or may not be necessary in your setup. Try your configuration without it; if the URLs produced by Trac look wrong, if Trac does not seem to recognize URLs correctly, or you get an odd "No handler matched request to..." error, add the '''TracUriRoot''' option. You will notice that the Location and '''TracUriRoot''' have the same path. The options available are: {{{#!apache # 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 }}} === Python Egg Cache Compressed Python eggs like Genshi are normally extracted into a directory named .python-eggs in the users home directory. Since Apache's home usually is not writeable, an alternate egg cache directory can be specified like this: {{{#!apache PythonOption PYTHON_EGG_CACHE /var/trac/myprojects/egg-cache }}} Or you can uncompress the Genshi egg to resolve problems extracting from it. === Configuring Authentication See corresponding section in the [wiki:TracModWSGI#ConfiguringAuthentication] page. == Advanced Configuration === Setting the Python Egg Cache If the Egg Cache isn't writeable by your Web server, you'll either have to change the permissions, or point Python to a location where Apache can write. This can manifest itself as a 500 internal server error and/or a complaint in the syslog. {{{#!apache ... PythonOption PYTHON_EGG_CACHE /tmp ... }}} === Setting the !PythonPath If the Trac installation isn't installed in your Python path, you will have to tell Apache where to find the Trac mod_python handler  using the PythonPath directive: {{{#!apache ... PythonPath "sys.path + ['/path/to/trac']" ... }}} Be careful about using the !PythonPath directive, and ''not'' SetEnv PYTHONPATH, as the latter won't work. === Setting up multiple projects The Trac mod_python handler supports a configuration option similar to Subversion's SvnParentPath, called TracEnvParentDir: {{{#!apache SetHandler mod_python PythonInterpreter main_interpreter PythonHandler trac.web.modpython_frontend PythonOption TracEnvParentDir /var/trac PythonOption TracUriRoot /projects }}} When you request the /projects URL, you will get a listing of all subdirectories of the directory you set as TracEnvParentDir that look like Trac environment directories. Selecting any project in the list will bring you to the corresponding Trac environment. If you don't want to have the subdirectory listing as your projects home page you can use a {{{#!apache }}} This will instruct Apache to use mod_python for all locations different from root while having the possibility of placing a custom home page for root in your !DocumentRoot folder. You can also use the same authentication realm for all of the projects using a  directive: {{{#!apache AuthType Basic AuthName "Trac" AuthUserFile /var/trac/.htpasswd Require valid-user }}} === Virtual Host Configuration Below is the sample configuration required to set up your Trac as a virtual server, ie when you access it at the URLs like http://trac.mycompany.com: {{{#!apache DocumentRoot /var/www/myproject ServerName trac.mycompany.com SetHandler mod_python PythonInterpreter main_interpreter PythonHandler trac.web.modpython_frontend PythonOption TracEnv /var/trac/myproject PythonOption TracUriRoot / AuthType Basic AuthName "MyCompany Trac Server" AuthUserFile /var/trac/myproject/.htpasswd Require valid-user }}} This does not seem to work in all cases. What you can do if it does not: * Try using  instead of . *  may, in your server setup, refer to the complete host instead of simple the root of the server. This means that everything (including the login directory referenced below) will be sent to Python and authentication does not work, ie you get the infamous Authentication information missing error. If this is the case, try using a sub-directory for Trac instead of the root, ie /web/ and /web/login instead of / and /login. * Depending on apache's NameVirtualHost configuration, you may need to use  instead of . For a virtual host that supports multiple projects replace TracEnv /var/trac/myproject with TracEnvParentDir /var/trac. '''Note''': !DocumentRoot should not point to your Trac project env. As Asmodai wrote on #trac: "suppose there's a webserver bug that allows disclosure of !DocumentRoot they could then leech the entire Trac environment". == Troubleshooting If you get server error pages, you can either check the Apache error log, or enable the PythonDebug option: {{{#!apache ... PythonDebug on }}} For multiple projects, try restarting the server as well. === Login Not Working If you've used  directive, it will override any other directives, as well as . The workaround is to use negation expression as follows (for multi project setups): {{{#!apache #this one for other pages SetHandler mod_python PythonHandler trac.web.modpython_frontend PythonOption TracEnvParentDir /projects PythonOption TracUriRoot / #this one for login page 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 }}} === Expat-related segmentation faults === #expat This problem will most certainly hit you on Unix when using Python 2.4. In Python 2.4, some version of [http://expat.sourceforge.net/ Expat] (an XML parser library written in C) is used and if Apache is using another version, this results in segmentation faults. As Trac 0.11 is using Genshi, which will indirectly use Expat, that problem can now hit you even if everything was working fine before with Trac 0.10. This problem has not been reported for Python 2.5+, so best to upgrade. === Form submission problems If you're experiencing problems submitting some of the forms in Trac (a common problem is that you get redirected to the start page after submission), check whether your {{{DocumentRoot}}} contains a folder or file with the same path that you mapped the mod_python handler to. For some reason, mod_python gets confused when it is mapped to a location that also matches a static resource. === Problem with virtual host configuration If the directive is used, setting the DocumentRoot may result in a ''403 (Forbidden)'' error. Either remove the DocumentRoot directive, or make sure that accessing the directory it points is allowed, in a corresponding  block. Using together with SetHandler resulted in having everything handled by mod_python, which leads to not being able to download any CSS or images/icons. Use SetHandler None to circumvent the problem, though this may not be the most elegant solution. === Problem with zipped egg It's possible that your version of mod_python will not import modules from zipped eggs. If you encounter an ImportError: No module named trac in your Apache logs but you think everything is where it should be, this might be your problem. Look in your site-packages directory; if the Trac module appears as a ''file'' rather than a ''directory'', then this might be your problem. To rectify this, try installing Trac using the --always-unzip option: {{{#!sh easy_install --always-unzip Trac-0.12b1.zip }}} === Using .htaccess Although it may seem trivial to rewrite the above configuration as a directory in your document root with a .htaccess file, this does not work. Apache will append a "/" to any Trac URLs, which interferes with its correct operation. 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. This also works out-of-box, with following trivial config: {{{#!apache SetHandler mod_python PythonInterpreter main_interpreter PythonHandler trac.web.modpython_frontend PythonOption TracEnv /system/path/to/this/directory PythonOption TracUriRoot /path/on/apache AuthType Basic AuthName "ProjectName" AuthUserFile /path/to/.htpasswd Require valid-user }}} The TracUriRoot is obviously the path you need to enter to the browser to get to Trac, eg domain.tld/projects/trac. === Additional .htaccess help If you are using the .htaccess method you may have additional problems if your Trac directory is inheriting .htaccess directives from another. This may also help to add to your .htaccess file: {{{#!apache RewriteEngine Off }}} === 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 When using mod_python on OS X you will not be able to restart Apache using apachectl restart. This is apparently fixed in mod_python 3.2, so please upgrade mod_python to fix this. ==== SELinux issues If Trac reports something like: Cannot get shared lock on db.lock, then the security context on the repository may need to be set: {{{#!sh chcon -R -h -t httpd_sys_content_t PATH_TO_REPOSITORY }}} See also [http://subversion.apache.org/faq.html#reposperms How do I set repository permissions correctly?] ==== FreeBSD issues The FreeBSD ports have both the new and old versions of mod_python and SQLite, but earlier versions of pysqlite and mod_python won't integrate: * pysqlite requires threaded support in Python * mod_python requires a threadless install. Apache2 does not automatically support threads on FreeBSD. You could force thread support when running ./configure for Apache, using --enable-threads, but this isn´t recommended. The best option [http://modpython.org/pipermail/mod_python/2006-September/021983.html seems to be] adding to /usr/local/apache2/bin/ennvars the line: {{{#!sh 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. A better way is to add a link to the bindings in the Python site-packages directory, or create a .pth file in that directory. If this is not the case, it's possible that you are using Subversion libraries that are binary incompatible with the Apache ones and an incompatibility of the apr libraries is usually the cause. In that case, you also won't be able to use the svn modules for Apache (mod_dav_svn). You also need a recent version of mod_python in order to avoid a runtime error ({{{argument number 2: a 'apr_pool_t *' is expected}}}) due to the default usage of multiple sub-interpreters. Version 3.2.8 ''should'' work, though it's probably better to use the workaround described in [trac:#3371 #3371], in order to force the use of the main interpreter: {{{#!apache PythonInterpreter main_interpreter }}} This is also the recommended workaround for other issues seen when using the Python bindings for Subversion within mod_python ([trac:#2611 #2611], [trac:#3455 #3455]). See in particular Graham Dumpleton's comment in [trac:comment:9:ticket:3455 #3455] explaining the issue. === Page layout issues If the formatting of the Trac pages look weird, chances are that the style sheets governing the page layout are not handled properly by the web server. Try adding the following lines to your Apache configuration: {{{#!apache Alias /myproject/css "/usr/share/trac/htdocs/css" SetHandler None }}} '''Note''': For the above configuration to have any effect it must be put after the configuration of your project root location, ie {{{}}}. Also, setting PythonOptimize On seems to mess up the page headers and footers, in addition to hiding the documentation for macros and plugins (see #Trac8956). Considering how little effect the option has, leave it Off. === HTTPS issues If you want to run Trac fully under https you might find that it tries to redirect to plain http. In this case just add the following line to your Apache configuration: {{{#!apache DocumentRoot /var/www/myproject ServerName trac.mycompany.com SetEnv HTTPS 1 .... }}} === 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 [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487 Debian bug report]. Some people also have troubles when using PHP5 compiled with its own third party libraries instead of system libraries. Check [http://www.djangoproject.com/documentation/modpython/#if-you-get-a-segmentation-fault Django segmentation fault]. ---- See also: TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI], [trac:TracNginxRecipe]

 r40226 = Trac and mod_wsgi [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi] is an Apache module for running WSGI-compatible Python applications directly on top of the Apache webserver. The mod_wsgi adapter is written completely in C and provides very good performance. [[PageOutline(2-3,Overview,inline)]] == The trac.wsgi script Trac can be run on top of mod_wsgi with the help of an application script, which is just a Python file saved with a .wsgi extension. A robust and generic version of this file can be created using the trac-admin deploy  command which automatically substitutes the required paths, see TracInstall#cgi-bin. The script should be sufficient for most installations and users not wanting more information can proceed to [#Mappingrequeststothescript configuring Apache]. If you are using Trac with multiple projects, you can specify their common parent directory using the TRAC_ENV_PARENT_DIR in trac.wsgi: {{{#!python def application(environ, start_request): # Add this to config when you have multiple projects environ.setdefault('trac.env_parent_dir', '/usr/share/trac/projects') .. }}} === A very basic script In its simplest form, the script could be: {{{#!python import os os.environ['TRAC_ENV'] = '/usr/local/trac/mysite' os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs' import trac.web.main application = trac.web.main.dispatch_request }}} The TRAC_ENV variable should naturally be the directory for your Trac environment, and the PYTHON_EGG_CACHE should be a directory where Python can temporarily extract Python eggs. If you have several Trac environments in a directory, you can also use TRAC_ENV_PARENT_DIR instead of TRAC_ENV. On Windows: - If run under the user's session, the Python Egg cache can be found in %AppData%\Roaming, for example: {{{#!python os.environ['PYTHON_EGG_CACHE'] = r'C:\Users\Administrator\AppData\Roaming\Python-Eggs' }}} - If run under a Window service, you should create a directory for Python Egg cache: {{{#!python os.environ['PYTHON_EGG_CACHE'] = r'C:\Trac-Python-Eggs' }}} === A more elaborate script If you are using multiple .wsgi files (for example one per Trac environment) you must ''not'' use os.environ['TRAC_ENV'] to set the path to the Trac environment. Using this method may lead to Trac delivering the content of another Trac environment, as the variable may be filled with the path of a previously viewed Trac environment. To solve this problem, use the following .wsgi file instead: {{{#!python import os os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs' import trac.web.main def application(environ, start_response): environ['trac.env_path'] = '/usr/local/trac/mysite' 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 its own directory, since you will expose it to Apache. If you have installed Trac and Python eggs in a path different from the standard one, you should add that path by adding the following code at the top of the wsgi script: {{{#!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. == Mapping requests to the script After preparing your .wsgi script, add the following to your Apache configuration file, typically httpd.conf: {{{#!apache WSGIScriptAlias /trac /usr/local/trac/mysite/apache/mysite.wsgi WSGIApplicationGroup %{GLOBAL} Order deny,allow Allow from all }}} Here, the script is in a subdirectory of the Trac environment. If you followed the directions [TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following: {{{#!apache WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi WSGIApplicationGroup %{GLOBAL} Order deny,allow Allow from all }}} In order to let Apache run the script, access to the directory in which the script resides is opened up to all of Apache. Additionally, the WSGIApplicationGroup directive ensures that Trac is always run in the first Python interpreter created by mod_wsgi. This is necessary because the Subversion Python bindings, which are used by Trac, don't always work in other sub-interpreters and may cause requests to hang or cause Apache to crash. After adding this configuration, restart Apache, and then it should work. 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 ['Hello World!'] }}} 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. == Configuring Authentication The following sections describe different methods for setting up authentication. See also [http://httpd.apache.org/docs/2.2/howto/auth.html Authentication, Authorization and Access Control] in the Apache guide. === Using Basic Authentication The simplest way to enable authentication with Apache is to create a password file. Use the htpasswd program as follows: {{{#!sh $htpasswd -c /somewhere/trac.htpasswd admin New password: Re-type new password: Adding password for user admin }}} After the first user, you don't need the "-c" option anymore: {{{#!sh$ htpasswd /somewhere/trac.htpasswd john New password: Re-type new password: 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 need to enable authentication against the password file in the Apache configuration: {{{#!apache AuthType Basic AuthName "Trac" AuthUserFile /somewhere/trac.htpasswd Require valid-user }}} If you are hosting multiple projects, you can use the same password file for all of them: {{{#!apache AuthType Basic AuthName "Trac" AuthUserFile /somewhere/trac.htpasswd Require valid-user }}} 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 have to create your .htpasswd file with the htdigest command instead of htpasswd, as follows: {{{#!sh $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: {{{#!apache AuthType Digest AuthName "trac" AuthDigestDomain /trac AuthUserFile /somewhere/trac.htpasswd Require valid-user }}} For multiple environments, you can use the same LocationMatch as described with the previous method. '''Note: Location cannot be used inside .htaccess files, but must instead live within the main httpd.conf file. If you are on a shared server, you therefore will not be able to provide this level of granularity. ''' Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system: {{{#!apache 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 more involved (httpd 2.2.x and OpenLDAP: slapd 2.3.19). 1. You need to load the following modules in Apache httpd.conf: {{{#!apache LoadModule ldap_module modules/mod_ldap.so LoadModule authnz_ldap_module modules/mod_authnz_ldap.so }}} 1. Your httpd.conf also needs to look something like: {{{#!apache # (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 }}} 1. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory. Use the following as your LDAP URL: {{{#!apache 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 need to use an account specifically for this task: {{{#!apache AuthLDAPBindDN ldap-auth-user@example.com AuthLDAPBindPassword "password" }}} The whole section looks like: {{{#!apache # (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 }}} Note 1: This is the case where the LDAP search will get around the multiple OUs, conecting to the Global Catalog Server portion of AD. Note the port is 3268, not the normal LDAP 389. The GCS is basically a "flattened" tree which allows searching for a user without knowing to which OU they belong. Note 2: You can also require the user be a member of a certain LDAP group, instead of just having a valid login: {{{#!apache 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: {{{#!apache AuthType SSPI AuthName "Trac Login" SSPIAuth On SSPIAuthoritative On SSPIDomain MyLocalDomain SSPIOfferBasic On SSPIOmitDomain Off SSPIBasicPreferred On Require valid-user }}} 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: {{{#!ini [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: {{{#!apache …HTTP authentication configuration… Require valid-user }}} Note that '''authFile''' need not exist (unless you are using Account Manager older than 0.4). See the !HttpAuthStore link above for examples where multiple Trac projects are hosted on a server. === 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: - serves the Trac instance from a virtualhost subdomain - 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: {{{#!sh cd /home/trac-for-my-proj/the-env htpasswd -c htpasswd firstuser ### and add more users to it as needed: htpasswd htpasswd seconduser }}} 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 the following content: {{{#!apache WSGIApplicationGroup %{GLOBAL} Order deny,allow Allow from all ServerName trac.my-proj.my-site.org DocumentRoot /home/trac-for-my-proj/the-env/htdocs/ WSGIScriptAlias / /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi AuthType Basic AuthName "Trac" AuthUserFile /home/trac-for-my-proj/the-env/htpasswd Require valid-user }}} Note: for subdomains to work you would probably also need to alter /etc/hosts and add A-Records to your host's DNS. == Troubleshooting === Use a recent version 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]. ''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'' If you plan to use mod_wsgi in embedded mode on Windows or with the MPM worker on Linux, then you will need version 3.4 or greater. See [trac:#10675] for details. === Getting Trac to work nicely with SSPI and 'Require Group' If you have set Trac up on Apache, Win32 and configured SSPI, but added a 'Require group' option to your apache configuration, then the SSPIOmitDomain option is probably not working. If it is not working, your usernames in Trac probably look like 'DOMAIN\user' rather than 'user'. This WSGI script 'fixes' that: {{{#!python import os import trac.web.main os.environ['TRAC_ENV'] = '/usr/local/trac/mysite' os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs' def application(environ, start_response): if "\\" in environ['REMOTE_USER']: 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 the database, the server ''may'' create a lot of open database connections and thus PostgreSQL processes. A somewhat brutal workaround is to disable connection pooling in Trac. This is done by setting poolable = False in trac.db.postgres_backend on the PostgreSQLConnection class. But it is not necessary to edit the source of Trac. The following lines in trac.wsgi will also work: {{{#!python import trac.db.postgres_backend trac.db.postgres_backend.PostgreSQLConnection.poolable = False }}} or {{{#!python import trac.db.mysql_backend trac.db.mysql_backend.MySQLConnection.poolable = False }}} Now Trac drops the connection after serving a page and the connection count on the database will be kept low. //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. The wsgi page also has a [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac Integration With Trac] document. ---- See also: TracGuide, TracInstall, [wiki:TracFastCgi FastCGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe] • ## wiki/pages/TracNavigation  r40226 = Trac Navigation The main and meta navigation entries can be customized in some basic ways. The [mainnav] and [metanav] configuration sections can be used to customize the navigation item text and link, change the ordering of the navigation items, or even disable them. === [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 that are accessible for the current user. ** [=#Example Example] ** In the following example we rename the link to WikiStart //Home//, and make the //View Tickets// entry link to a specific report. {{{#!ini [mainnav] wiki.label = Home tickets.href = /report/24 }}} === [metanav] #metanav-bar [metanav] corresponds to the '''meta navigation bar''', by default positioned above the main navigation bar and below the ''Search'' box. It contains the ''Login'', ''Logout'', ''!Help/Guide'' etc. entries. This navigation bar is meant to access some global information about the Trac project and the current user. There is one special entry in the [metanav] section: logout.redirect is the page the user sees after hitting the logout button. The ''!Help/Guide'' link is also hidden in the following example. [[comment(see also #Trac3808)]] ** Example ** {{{#!ini [metanav] help = disabled logout.redirect = wiki/Logout }}} === URL Formats Possible URL formats for .href or .redirect: || '''config''' || '''redirect to''' || || wiki/Logout || /projects/env/wiki/Logout || || http://hostname/ || http://hostname/ || || /projects || /projects || === Ordering #nav-order The order attribute specifies the order in which the navigation items are displayed. This can be particularly useful for plugins that add navigation items. Non-negative floating point values may be used for the order attribute. The navigation items will be arranged from left to right in increasing order. Navigation items without an order attribute are sorted alphabetically by name. The default values are: {{{#!ini [mainnav] browser.order = 4 newticket.order = 6 roadmap.order = 3 search.order = 7 tickets.order = 5 timeline.order = 2 wiki.order = 1 [metanav] about.order = 5 help.order = 4 login.order = 1 logout.order = 2 prefs.order = 3 }}} === Context Navigation #ctxtnav-bar Note that it is still not possible to customize the '''contextual navigation bar''', ie the one usually placed below the main navigation bar. ---- See also: TracInterfaceCustomization, and the [http://trac-hacks.org/wiki/NavAddPlugin TracHacks:NavAddPlugin] or [http://trac-hacks.org/wiki/MenusPlugin TracHacks:MenusPlugin] (still needed for adding entries) • ## wiki/pages/TracNotification  r40226 = Email Notification of Ticket Changes [[TracGuideToc]] Trac supports notification of ticket changes via email. Email notification is useful to keep users up-to-date on tickets/issues of interest, and also provides a convenient way to post all ticket changes to a dedicated mailing list. For example, this is how the [http://lists.edgewall.com/archive/trac-tickets/ Trac-tickets] mailing list is set up. Disabled by default, notification can be activated and configured in [wiki:TracIni trac.ini]. == Receiving Notification Mails When reporting a new ticket or adding a comment, enter a valid email address or your Trac username in the ''reporter'', ''assigned to/owner'' or ''cc'' field. Trac will automatically send you an email when changes are made to the ticket, depending on how notification is configured. === How to use your username to receive notification mails To receive notification mails, you can either enter a full email address or your Trac username. To get notified with a simple username or login, you need to specify a valid email address in the ''Preferences'' page. 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'''). === Ticket attachment notifications Since 1.0.3 Trac will send notifications when a ticket attachment is added or deleted. Usually attachment notifications will be enabled in an environment by default. To disable the attachment notifications for an environment the TicketAttachmentNotifier component must be disabled: {{{#!ini [components] trac.ticket.notification.TicketAttachmentNotifier = disabled }}} == Configuring SMTP Notification '''Important:''' For TracNotification to work correctly, the [trac] base_url option must be set in [wiki:TracIni trac.ini]. === Configuration Options These are the available options for the [notification] section in trac.ini: [[TracIni(notification)]] === Example Configuration (SMTP) {{{#!ini [notification] smtp_enabled = true smtp_server = mail.example.com smtp_from = notifier@example.com smtp_replyto = myproj@projects.example.com smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com }}} === Example Configuration (sendmail) {{{#!ini [notification] smtp_enabled = true email_sender = SendmailEmailSender sendmail_path = /usr/sbin/sendmail smtp_from = notifier@example.com smtp_replyto = myproj@projects.example.com smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com }}} === Subscriber Configuration The default subscriptions are configured in the [notification-subscriber] section in trac.ini: [[TracIni(notification-subscriber)]] Each user can override these defaults in his ''Notifications'' preferences. For example to unsubscribe from notifications for one's own changes and comments, the rule "Never notify: I update a ticket" should be added above other subscription rules. === Customizing the e-mail subject The e-mail subject can be customized with the ticket_subject_template option, which contains a [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet. The default value is: {{{#!genshi$prefix #$ticket.id:$summary }}} The following variables are available in the template: * env: The project environment (see [trac:source:/trunk/trac/env.py env.py]). * prefix: The prefix defined in smtp_subject_prefix. * summary: The ticket summary, with the old value if the summary was edited. * ticket: The ticket model object (see [trac:source:/trunk/trac/ticket/model.py model.py]). Individual ticket fields can be addressed by appending the field name separated by a dot, eg $ticket.milestone. === Customizing the e-mail content The notification e-mail content is generated based on ticket_notify_email.txt in trac/ticket/templates. You can add your own version of this template by adding a ticket_notify_email.txt to the templates directory of your environment. The default looks like this: {{{#!genshi$ticket_body_hdr $ticket_props {% choose ticket.new %}\ {% when True %}\$ticket.description {%   end %}\ {%   otherwise %}\ {%     if changes_body %}\ ${_('Changes (by %(author)s):', author=change.author)}$changes_body {%     end %}\ {%     if changes_descr %}\ {%       if not changes_body and not change.comment and change.author %}\ ${_('Description changed by %(author)s:', author=change.author)} {% end %}\$changes_descr -- {%     end %}\ {%     if change.comment %}\ ${changes_body and _('Comment:') or _('Comment (by %(author)s):', author=change.author)}$change.comment {%     end %}\ {%   end %}\ {% end %}\ -- ${_('Ticket URL: <%(link)s>', link=ticket.link)}$project.name <${project.url or abs_href()}>$project.descr }}} == Sample Email {{{ #42: testing ---------------------------+------------------------------------------------ Id:  42             |      Status:  assigned Component:  report system  |    Modified:  Fri Apr  9 00:04:31 2004 Severity:  major          |   Milestone:  0.9 Priority:  lowest         |     Version:  0.6 Owner:  anonymous      |    Reporter:  jonas@example.com ---------------------------+------------------------------------------------ Changes: * component:  changeset view => search system * priority:  low => highest * owner:  jonas => anonymous * cc:  daniel@example.com => daniel@example.com, jonas@example.com * status:  new => assigned Comment: I'm interested too! -- Ticket URL: My Project }}} == Customizing e-mail content for MS Outlook MS Outlook normally presents plain text e-mails with a variable-width font, and as a result the ticket properties table will most certainly look like a mess in MS Outlook. This can be fixed with some customization of the [#Customizingthee-mailcontent e-mail template]. Replace the following second row in the template: {{{ $ticket_props }}} with this (requires Python 2.6 or later): {{{ -------------------------------------------------------------------------- {% with pv = [(a[0].strip(), a[1].strip()) for a in [b.split(':') for b in [c.strip() for c in ticket_props.replace('|', '\n').splitlines()[1:-1]] if ':' in b]]; sel = ['Reporter', 'Owner', 'Type', 'Status', 'Priority', 'Milestone', 'Component', 'Severity', 'Resolution', 'Keywords'] %}\${'\n'.join('%s\t%s' % (format(p[0]+':', ' <12'), p[1]) for p in pv if p[0] in sel)} {% end %}\ -------------------------------------------------------------------------- }}} The table of ticket properties is replaced with a list of a selection of the properties. A tab character separates the name and value in such a way that most people should find this more pleasing than the default table when using MS Outlook. {{{#!div style="margin: 1em 1.75em; border:1px dotted" {{{#!html #42: testing
--------------------------------------------------------------------------
--------------------------------------------------------------------------
Changes:

* component:  changeset view => search system
* priority:  low => highest
* owner:  jonas => anonymous
* cc:  daniel@example.com =>
daniel@example.com, jonas@example.com
* status:  new => assigned

Comment:
I'm interested too!

--
Ticket URL: <http://example.com/trac/ticket/42>
My Project <http://myproj.example.com/>

• ## wiki/pages/TracSupport

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