Running Trac on IIS 6 using AJP

Contributed by:
Wilfred Berger, Statistisches Landesamt, Stuttgart, Germany, wilfred.berger@stala.bwl.de

Setup:

• Windows Server 2003 SP2
• IIS 6
• Trac 0.11

Also tested with Trac 0.11.6 on Windows Server 2008, as well as Trac 0.12.2 without any problems or modifications.

Why this?

If you want to run Trac on a Windows system, your first choice will be running tracd stand-alone. However, this may be impossible for several reasons:

• tracd does not support HTTPS. If you want to serve HTTPS, you will have to connect Trac to a common web server.
• If you want to mix Trac with other content in your web site, you will again have to connect Trac to another web server.

In both cases, the web server on a Windows system will most probably be IIS.

Generally, it is not a good idea to use CGI on a Windows system. CGI implies starting a new system process for every single request, which, on Windows, causes significant overhead and makes things slow.

The following solution uses ​AJP. This protocol was developed for connecting Tomcat to a web server which is very similar to what we are doing here.

1. Install Trac

Exactly as if you were going to run tracd stand-alone, with two exceptions:

• Since port 80 will be occupied by IIS, choose a different port, adding -p 8009 to the tracd start command.

8009 is the standard port for AJP. Of course, you are free to use any other port.

At this point you should check whether Trac is running properly.

• Add --protocol=ajp to the tracd start command to make tracd use AJP instead of HTTP. You may also add --unquote if you have problems browsing repositories with spaces in filenames.

Now you may get an error message indicating that module flup.server.ajp is missing. If you don't get this message, flup is already installed and you may skip the following step.

2. Install flup

• Copy flup-1.0-py2.5.egg from ​Saddi Software binaries to C:\Python25\Scripts (or whatever may be your Python installation directory).
• Run easy_install flup.

Now tracd should start without an error.

3. Install ​Tomcat AJP Connector for IIS

• Set up the directory structure.

We assume there will be a base directory named C:\AJP-Connector and three subdirectories bin, conf and logs. Of course, you may choose anything else for the base directory.

• Copy tomcat-connectors-1.2.37-windows-i386-iis.zip (or tomcat-connectors-1.2.37-windows-x86_64-iis.zip in a 64 bit environment) or a newer version from ​Apache binaries and extract isapi_redirect.dll to the bin subdirectory.
• Create a configuration file isapi_redirect.properties for the ISAPI redirector.

This must be in the same directory as the DLL and have exactly the same name but with a .properties extension. The configuration file should contain this:

# Configuration file for the ISAPI Redirector

# The path to the ISAPI Redirector Extension, relative to the website
# This must be in a virtual directory with execute privileges
extension_uri=/AJP-Connector/isapi_redirect.dll

# Full path to the log file for the ISAPI Redirector
log_file=C:\AJP-Connector\logs\isapi_redirect.log

# Log level (debug, info, warn, error or trace)
log_level=info

# Full path to the workers.properties file
worker_file=C:\AJP-Connector\conf\workers.properties

# Full path to the uriworkermap.properties file
worker_mount_file=C:\AJP-Connector\conf\uriworkermap.properties

Replace "C:\AJP-Connector" with your actual directory.

• Create the workers.properties file with the following content:

# Define 1 real worker
worker.list=trac
# Set properties for trac (ajp13)
worker.trac.type=ajp13
worker.trac.host=localhost
worker.trac.port=8009
worker.trac.socket_keepalive=0

Replace the host name and port where applicable.

• Create the uriworkermap.properties file with the following content:

/foo*=trac
/bar*=trac

Replace foo and bar with your Trac project names.

4. Define the virtual directory for AJP-Connector

• Start the IIS Manager, normally found at %SystemRoot%\system32\inetsrv\iis.msc.
• Inside the web site where you want to publish Trac, define a virtual directory named AJP-Connector, pointing to your bin subdirectory, with permissions to execute executables, not only scripts.

The only purpose for this virtual directory is to allow the ISAPI filter defined in step 6 to find the DLL.

5. Allow execution of the DLL as Web Service Extension

• In the IIS Manager, open Web Service Extensions.
• Define a new Web Service Extension called AJP-Connector, or whatever name you choose.
• Add C:\AJP-Connector\bin\isapi_redirect.dll to the required files and replace "C:\AJP-Connector" with your actual directory.
• Set extension status to Allowed.
• Click OK.

This step may not be necessary for IIS 5.1 as IIS 6.0 introduced the Web Service Extension.

6. Add AJP-Connector to the ISAPI filters

• In the IIS Manager, open the properties of the web site where you want to publish Trac.
• Open "ISAPI Filters".
• Add a new filter with any filter name (I prefer "AJP-Connector") and the complete path to isapi_redirect-1.2.28.dll as executable.
• Close the two property windows, clicking OK in each of them.

You may have to restart IIS.

7. Any further questions?

Feel free to send me a mail. My address is given at the top of this page.

Trouble with Authentication

I had some trouble with authentication. If tracd uses Digest Authentication it does not support Basic Authentication. But if Basic Authentication is enabled in IIS, it sends an additional Basic Authentication HTTP header. Some browsers (including Firefox) try to use Basic Authentication if both Basic and Digest Authentication headers are sent by the server. tracd can not handle this information and will resend the authentication request. So be sure to turn off Basic Authentication on IIS.