Changes between Version 1 and Version 2 of TracModWSGI


Ignore:
Timestamp:
2015-04-01T12:42:00Z (10 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracModWSGI

    v1 v2  
    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
    … …  
    9389If you followed the directions [TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following:
    9490
    95 {{{
     91{{{#!apache
    9692WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi
    9793
    … …  
    119115The 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.
    120116
    121 === Using Basic Authentication ===
     117=== Using Basic Authentication
    122118
    123119The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program as follows:
    124 {{{
     120{{{#!sh
    125121$ htpasswd -c /somewhere/trac.htpasswd admin
    126122New password: <type password>
    … …  
    130126
    131127After the first user, you don't need the "-c" option anymore:
    132 {{{
     128{{{#!sh
    133129$ htpasswd /somewhere/trac.htpasswd john
    134130New password: <type password>
    … …  
    142138
    143139Now, you need to enable authentication against the password file in the Apache configuration:
    144 {{{
     140{{{#!apache
    145141<Location "/trac/login">
    146142  AuthType Basic
    … …  
    152148
    153149If you are hosting multiple projects, you can use the same password file for all of them:
    154 {{{
     150{{{#!apache
    155151<LocationMatch "/trac/[^/]+/login">
    156152  AuthType Basic
    … …  
    163159See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html mod_auth_basic] documentation.
    164160
    165 === Using Digest Authentication ===
     161=== Using Digest Authentication
    166162
    167163For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”.
    168164
    169165You have to create your `.htpasswd` file with the `htdigest` command instead of `htpasswd`, as follows:
    170 {{{
    171 # htdigest -c /somewhere/trac.htpasswd trac admin
     166{{{#!sh
     167$ htdigest -c /somewhere/trac.htpasswd trac admin
    172168}}}
    173169
    174170The "trac" parameter above is the "realm", and will have to be reused in the Apache configuration in the !AuthName directive:
    175171
    176 {{{
     172{{{#!apache
    177173<Location "/trac/login">
    178 
    179     AuthType Digest
    180     AuthName "trac"
    181     AuthDigestDomain /trac
    182     AuthUserFile /somewhere/trac.htpasswd
    183     Require valid-user
     174  AuthType Digest
     175  AuthName "trac"
     176  AuthDigestDomain /trac
     177  AuthUserFile /somewhere/trac.htpasswd
     178  Require valid-user
    184179</Location>
    185180}}}
    … …  
    190185
    191186Don'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
     187{{{#!apache
     188  LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
    194189}}}
    195190
    … …  
    201196
    2021971. 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 {{{
     198{{{#!apache
     199  LoadModule ldap_module modules/mod_ldap.so
     200  LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
     201}}}
     2021. Your httpd.conf also needs to look something like:
     203{{{#!apache
    211204<Location /trac/>
    212205  # (if you're using it, mod_python specific settings go here)
    … …  
    222215</Location>
    223216}}}
    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 [email protected]
    235     AuthLDAPBindPassword "password"
    236 }}}
    237 
    238 The whole section looks like:
    239 {{{
     2171. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory. Use the following as your LDAP URL:
     218{{{#!apache
     219  AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)"
     220}}}
     221 You will also need to provide an account for Apache to use when checking credentials. As this password will be listed in plaintext in the config, you need to use an account specifically for this task:
     222{{{#!apache
     223  AuthLDAPBindDN [email protected]
     224  AuthLDAPBindPassword "password"
     225}}}
     226 The whole section looks like:
     227{{{#!apache
    240228<Location /trac/>
    241229  # (if you're using it, mod_python specific settings go here)
    … …  
    251239  authzldapauthoritative Off
    252240  # require valid-user
    253   require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
     241  Require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
    254242</Location>
    255243}}}
    … …  
    258246
    259247Note 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
     248{{{#!apache
     249  Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com
    262250}}}
    263251
    … …  
    270258
    271259If 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>
     260{{{#!apache
     261<Location /trac/login>
     262  AuthType SSPI
     263  AuthName "Trac Login"
     264  SSPIAuth On
     265  SSPIAuthoritative On
     266  SSPIDomain MyLocalDomain
     267  SSPIOfferBasic On
     268  SSPIOmitDomain Off
     269  SSPIBasicPreferred On
     270  Require valid-user
     271</Location>
    284272}}}
    285273
    … …  
    297285
    298286Here is an example (from the !HttpAuthStore link) using acct_mgr-0.4 for hosting a single project:
    299 {{{
     287{{{#!ini
    300288[components]
    301289; be sure to enable the component
    … …  
    308296}}}
    309297This will generally be matched with an Apache config like:
    310 {{{
     298{{{#!apache
    311299<Location /authFile>
    312300   …HTTP authentication configuration…
    … …  
    325313
    326314Create the htpasswd file:
    327 {{{
     315{{{#!sh
    328316cd /home/trac-for-my-proj/the-env
    329317htpasswd -c htpasswd firstuser
    … …  
    335323Create this file e.g. (ubuntu) `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` with the following content:
    336324
    337 {{{
     325{{{#!apache
    338326<Directory /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi>
    339327  WSGIApplicationGroup %{GLOBAL}
    … …  
    368356If 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.
    369357
    370 === Getting Trac to work nicely with SSPI and 'Require Group' ===
     358=== Getting Trac to work nicely with SSPI and 'Require Group'
    371359
    372360If 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'.
    … …  
    386374}}}
    387375
    388 === Trac with PostgreSQL ===
     376=== Trac with PostgreSQL
    389377
    390378When 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.