Changes between Version 2 and Version 3 of TracModWSGI


Ignore:
Timestamp:
Apr 16, 2016, 7:07:21 PM (9 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracModWSGI

    v2 v3  
    1 = Trac and mod_wsgi =
    2 
    3 [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 performance.
     1= Trac and mod_wsgi
     2
     3[https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi] is an Apache module for running WSGI-compatible Python applications directly on top of the Apache webserver. The mod_wsgi adapter is written completely in C and provides very good performance.
    44
    55[[PageOutline(2-3,Overview,inline)]]
    … …  
    77== The `trac.wsgi` script
    88
    9 Trac can be run on top of mod_wsgi with the help of the following application script, which is just a Python file, though usually saved with a `.wsgi` extension.
     9Trac can be run on top of mod_wsgi with the help of an application script, which is just a Python file saved with a `.wsgi` extension.
     10
     11A robust and generic version of this file can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths, see TracInstall#cgi-bin. The script should be sufficient for most installations and users not wanting more information can proceed to [#Mappingrequeststothescript configuring Apache].
     12
     13If you are using Trac with multiple projects, you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` in trac.wsgi:
     14{{{#!python
     15def application(environ, start_request):
     16    # Add this to config when you have multiple projects                                             
     17    environ.setdefault('trac.env_parent_dir', '/usr/share/trac/projects') 
     18    ..
     19}}}
    1020
    1121=== A very basic script
    … …  
    6171Change it according to the path you installed the Trac libs at.
    6272
    63 === Recommended `trac.wsgi` script
    64 
    65 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.
    66 
    67 If you are using Trac with multiple projects, you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` in the trac.wsgi in trac.wsgi: ''
    68 
    69 {{{#!python
    70   def application(environ, start_request):
    71       Add this to config when you have multiple projects                                             
    72       environ.setdefault('trac.env_parent_dir', '/usr/share/trac/projects') 
    73       ..
    74       ..
    75 }}}
    76 
    7773== Mapping requests to the script
    7874
    7975After preparing your .wsgi script, add the following to your Apache configuration file, typically `httpd.conf`:
    8076
    81 {{{
     77{{{#!apache
    8278WSGIScriptAlias /trac /usr/local/trac/mysite/apache/mysite.wsgi
    8379
    8480<Directory /usr/local/trac/mysite/apache>
    8581    WSGIApplicationGroup %{GLOBAL}
    86     Order deny,allow
    87     Allow from all
     82    # For Apache 2.2
     83    <IfModule !mod_authz_core.c>
     84        Order deny,allow
     85        Allow from all
     86    </IfModule>
     87    # For Apache 2.4
     88    <IfModule mod_authz_core.c>
     89        Require all granted
     90    </IfModule>
    8891</Directory>
    8992}}}
    … …  
    9396If you followed the directions [TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following:
    9497
    95 {{{
     98{{{#!apache
    9699WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi
    97100
    98101<Directory /usr/share/trac/cgi-bin>
    99102    WSGIApplicationGroup %{GLOBAL}
    100     Order deny,allow
    101     Allow from all
     103    # For Apache 2.2
     104    <IfModule !mod_authz_core.c>
     105        Order deny,allow
     106        Allow from all
     107    </IfModule>
     108    # For Apache 2.4
     109    <IfModule mod_authz_core.c>
     110        Require all granted
     111    </IfModule>
    102112</Directory>
    103113}}}
    … …  
    119129The 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.
    120130
    121 === Using Basic Authentication ===
     131=== Using Basic Authentication
    122132
    123133The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program as follows:
    124 {{{
     134{{{#!sh
    125135$ htpasswd -c /somewhere/trac.htpasswd admin
    126136New password: <type password>
    … …  
    130140
    131141After the first user, you don't need the "-c" option anymore:
    132 {{{
     142{{{#!sh
    133143$ htpasswd /somewhere/trac.htpasswd john
    134144New password: <type password>
    … …  
    142152
    143153Now, you need to enable authentication against the password file in the Apache configuration:
    144 {{{
     154{{{#!apache
    145155<Location "/trac/login">
    146156  AuthType Basic
    … …  
    152162
    153163If you are hosting multiple projects, you can use the same password file for all of them:
    154 {{{
     164{{{#!apache
    155165<LocationMatch "/trac/[^/]+/login">
    156166  AuthType Basic
    … …  
    163173See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html mod_auth_basic] documentation.
    164174
    165 === Using Digest Authentication ===
     175=== Using Digest Authentication
    166176
    167177For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”.
    168178
    169179You have to create your `.htpasswd` file with the `htdigest` command instead of `htpasswd`, as follows:
    170 {{{
    171 # htdigest -c /somewhere/trac.htpasswd trac admin
     180{{{#!sh
     181$ htdigest -c /somewhere/trac.htpasswd trac admin
    172182}}}
    173183
    174184The "trac" parameter above is the "realm", and will have to be reused in the Apache configuration in the !AuthName directive:
    175185
    176 {{{
     186{{{#!apache
    177187<Location "/trac/login">
    178 
    179     AuthType Digest
    180     AuthName "trac"
    181     AuthDigestDomain /trac
    182     AuthUserFile /somewhere/trac.htpasswd
    183     Require valid-user
     188  AuthType Digest
     189  AuthName "trac"
     190  AuthDigestDomain /trac
     191  AuthUserFile /somewhere/trac.htpasswd
     192  Require valid-user
    184193</Location>
    185194}}}
    … …  
    190199
    191200Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system:
    192 {{{
    193     LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
     201{{{#!apache
     202  LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
    194203}}}
    195204
    … …  
    201210
    2022111. You need to load the following modules in Apache httpd.conf:
    203 {{{
    204 LoadModule ldap_module modules/mod_ldap.so
    205 LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
    206 }}}
    207 
    208 2. Your httpd.conf also needs to look something like:
    209 
    210 {{{
     212{{{#!apache
     213  LoadModule ldap_module modules/mod_ldap.so
     214  LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
     215}}}
     2161. Your httpd.conf also needs to look something like:
     217{{{#!apache
    211218<Location /trac/>
    212219  # (if you're using it, mod_python specific settings go here)
    … …  
    222229</Location>
    223230}}}
    224 
    225 3. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory:
    226 
    227 Use the following as your LDAP URL:
    228 {{{
    229     AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)"
    230 }}}
    231 
    232 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:
    233 {{{
    234     AuthLDAPBindDN ldap-auth-user@example.com
    235     AuthLDAPBindPassword "password"
    236 }}}
    237 
    238 The whole section looks like:
    239 {{{
     2311. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory. Use the following as your LDAP URL:
     232{{{#!apache
     233  AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)"
     234}}}
     235 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:
     236{{{#!apache
     237  AuthLDAPBindDN ldap-auth-user@example.com
     238  AuthLDAPBindPassword "password"
     239}}}
     240 The whole section looks like:
     241{{{#!apache
    240242<Location /trac/>
    241243  # (if you're using it, mod_python specific settings go here)
    … …  
    251253  authzldapauthoritative Off
    252254  # require valid-user
    253   require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
     255  Require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
    254256</Location>
    255257}}}
    … …  
    258260
    259261Note 2: You can also require the user be a member of a certain LDAP group, instead of just having a valid login:
    260 {{{
    261     Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com
     262{{{#!apache
     263  Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com
    262264}}}
    263265
    … …  
    270272
    271273If 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:
    272 {{{
    273     <Location /trac/login>
    274         AuthType SSPI
    275         AuthName "Trac Login"
    276         SSPIAuth On
    277         SSPIAuthoritative On
    278         SSPIDomain MyLocalDomain
    279         SSPIOfferBasic On
    280         SSPIOmitDomain Off
    281         SSPIBasicPreferred On
    282         Require valid-user
    283     </Location>
     274{{{#!apache
     275<Location /trac/login>
     276  AuthType SSPI
     277  AuthName "Trac Login"
     278  SSPIAuth On
     279  SSPIAuthoritative On
     280  SSPIDomain MyLocalDomain
     281  SSPIOfferBasic On
     282  SSPIOmitDomain Off
     283  SSPIBasicPreferred On
     284  Require valid-user
     285</Location>
    284286}}}
    285287
    … …  
    290292See also [trac:TracOnWindows/Advanced].
    291293
     294=== Using CA !SiteMinder Authentication
     295Setup CA !SiteMinder to protect your Trac login URL (e.g. /trac/login).  Then modify the trac.wsgi script generated using `trac-admin <env> deploy <dir>` to add the following lines, which extract the HTTP_SM_USER variable and set it to REMOTE_USER:
     296
     297{{{#!python
     298def application(environ, start_request):
     299    # Set authenticated username on CA SiteMinder to REMOTE_USER variable
     300    # strip() is used to remove any spaces on the end of the string
     301    if 'HTTP_SM_USER' in environ:
     302        environ['REMOTE_USER'] = environ['HTTP_SM_USER'].strip()
     303    ...
     304}}}
     305
     306Note:  you do not need any Apache "Location" directives.
     307
    292308=== Using Apache authentication with the Account Manager plugin's Login form ===
    293309
    … …  
    297313
    298314Here is an example (from the !HttpAuthStore link) using acct_mgr-0.4 for hosting a single project:
    299 {{{
     315{{{#!ini
    300316[components]
    301317; be sure to enable the component
    … …  
    308324}}}
    309325This will generally be matched with an Apache config like:
    310 {{{
     326{{{#!apache
    311327<Location /authFile>
    312328   …HTTP authentication configuration…
    … …  
    325341
    326342Create the htpasswd file:
    327 {{{
     343{{{#!sh
    328344cd /home/trac-for-my-proj/the-env
    329345htpasswd -c htpasswd firstuser
    … …  
    335351Create this file e.g. (ubuntu) `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` with the following content:
    336352
    337 {{{
     353{{{#!apache
    338354<Directory /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi>
    339355  WSGIApplicationGroup %{GLOBAL}
    … …  
    366382''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''
    367383
    368 If you plan to use `mod_wsgi` in embedded mode on Windows or with the MPM worker on Linux, then you will need version 0.3.4 or greater. See [trac:#10675] for details.
    369 
    370 === Getting Trac to work nicely with SSPI and 'Require Group' ===
     384If 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.
     385
     386=== Getting Trac to work nicely with SSPI and 'Require Group'
    371387
    372388If 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'.
    … …  
    386402}}}
    387403
    388 === Trac with PostgreSQL ===
     404=== Trac with PostgreSQL
    389405
    390406When 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.