SCGI on IIS 7 and 8

This describes installation for IIS 7 and 8. Installation for earlier versions is described elsewhere.

The Simple Common Gateway Interface (SCGI) is a standard for communication between web servers and application servers on the back end. It has several performance advantages over CGI. This chapter describes configuring IIS 7 to use SCGI to communicate with a Woof! application server on the back end. The process of running Woof! as a SCGI application server is described in the chapter Running as an SCGI server.

SCGI support is not a standard part of IIS and you need to install the isapi_scgi IIS extension to support it. You will also optionally need to install a URL rewriting filter. Both procedures are described below.

Assumptions

This scenario makes the following assumptions:

• You have full control over IIS configuration.
• The server hosts the Woof! application alongside other applications on the default web site.
• The application is rooted at /myapp, i.e. http://www.mysite.com/myapp is the entry point into the application.
• You have the means to modify the system configuration so that the Woof! SCGI server is started automatically either at boot time or when IIS is started.

Step 1 - install Woof!

Install Woof! for IIS 7 and SCGI using using the installer script.

~/woof-dist> tclsh scripts/installer.tcl install iis7 scgi -installdir /myappdir

This will create the Woof! directory structure under /myappdir. In particular, the /myappdir/public will contain the publically accessible directory tree that will be the document root for the Woof! application.

Since the Woof! application is not rooted at / we also need to tell Woof! the application root URI, /myapp in our case. For this purpose, we add the line below to the Woof! application configuration file, which in our example will reside at /myappdir/config/application.cfg.

set url_root /myapp

This will allow Woof! to correctly decode and generate URL's for the Woof! application.

Step 2 - configure the application URL in IIS

Now create a virtual directory /myapp for the site with the physical location pointing to the public subdirectory of our Woof! installation. Fill the alias as type myapp. This is the URL root under which we want the Woof! application to be accessed and must be the same as the value of the url_root Woof! configuration variable we used in Step 1 except for leaving out the leading slash.

appcmd add vdir /app.name:"Default Web Site/" /path:/myapp /physicalPath:c:\myappdir\public

Step 3 - install isapi_scgi

The isapi_scgi IIS extension for SCGI is open source software that can be freely downloaded and used. A sample installation is shown below using the IIS command line configuration tool appcmd which can be found in the %SYSTEMROOT%\system32\inetsrv directory. The isapi_scgi web site contains detailed download, installation and usage instructions using the IIS Manager as well.

Download the extension from the isapi_scgi download area. Extract the downloaded archive into a directory that is accessible to the IIS server but does not need to be in the Woof installation or under the site directory. The sample session below assumes it is extracted into the c:\isapi_scgi directory and that we are configuring the 64-bit version. For the 32-bit version, replace the isapi_scgi64.dll with isapi_scgi.dll.

We need to inform IIS that the isapi_scgi DLL should be permitted to execute.

appcmd set config /section:system.webServer/security/isapiCgiRestriction /+[path='c:\isapi_scgi\isapi_scgi64.dll',allowed='true',description='ISAPISCGI']

Next, add the isapi_scgi handler for files ending in .scgi. Note that no such file has to actually exist because the resourceType attribute value is the literal Unspecified.

appcmd set config /section:system.webServer/handlers /+[name='ISAPISCGI',path='*.scgi',scriptProcessor='c:\isapi_scgi\isapi_scgi64.dll',verb='*',modules='IsapiModule',resourceType='Unspecified',allowPathInfo='true']

It is important that the allowPathInfo attribute be specified as true in order for Woof! to route URL's to the correct controller.

Step 4 - configure SCGI

If you are not running the default SCGI server address and port, follow the steps described in the isapi_scgi configuration manual to set up isapi_scgi options. This step is not required if you are running the default SCGI configuration.

Step 5 - configure URL rewriting

This step is optional but is usually desirable for various reasons. The configuration steps described so far will result in the Woof! SCGI server being invoked for URL's starting with http://www.mysite.com/myapp/woof.scgi. A URL rewrite filter will allow this root URL to be changed to http://www.mysite.com/myapp instead. This step is optional but is recommended for all the reasons listed in Added Bytes or Wikipedia. If you choose to skip this step, you must also change value of url_root in Step 1 to /myapp/isapi_scgi.dll as that will be root URL for Woof! without URL rewriting.

Here we demonstrate URL rewriting configuration for use with Woof! using Microsoft's free URL Rewrite extension which supports IIS 7 and 8. Follow the directions there to download and install the extension.

Although the URL Rewrite extension can also be configured through the IIS manager UI or through appcmd, here we will take the simpler route of just creating a configuration file c:\myappdir\public\web.config with the following content.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <clear />
                <rule name="Let static resources be served by IIS" stopProcessing="true">
                    <match url="^(stylesheets|js|images|html)(/.*)?$" />
                    <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />
                    <action type="None" />
                </rule>
                <rule name="Insert SCGI extension into URL path" stopProcessing="false">
                    <match url="^(.*)?$" />
                    <conditions logicalGrouping="MatchAll" trackAllCaptures="true" />
                    <action type="Rewrite" url="woof.scgi/{R:0}" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

The main purpose of the rules is to permit browsers to access our site application as /myapp/path/to/resource as opposed to /myapp/isapi_scgi.dll/path/to/resource. Explaining functionality of the URL Rewrite extension would take as much room as this entire guide so we just summarise how the above configuration works to make this happen.

Because the file is placed in the location for the myapp virtual directory, the rules in the file only impact URLs that begin with /myapp. There are two rules listed, each defined via the <rule> tag. The <match> tag under each rule defines the regular expression pattern to be matched against the portion of the URL beyond the /myapp prefix.

The first rule is to ensure that static resources like images and stylesheets in the public directory are directly served by IIS and not passed to our SCGI server. Therefore, the first rule is written with an <action> type of None which means the URL being processed will be unchanged. More important, the rule has an stopProcessing attribute of true which mean further rules will not be applied. The URL will therefore be entirely unchanged and directly served by IIS.

The second rule is the primary rule that accomplishes what we want to do. It basically says that any URL under /myapp should be rewritten with a isapi_scgi.dll/ prefix. The {R:0} is a regular expression back-reference and is replaced by the matched expression in the URL. When a client accesses the URL /myapp/path/to/resource, {R:0} will match path/to/resource and that portion of the URL will be replaced by woof.scgi/path/to/resource.

After creating the configuration file, the service may need to be restarted.

Step 6 - starting the SCGI server

The Woof! SCGI server script that handles connections passed by Apache needs to be started whenever Apache runs. This step is actually independent of the web server and is described in Running as an SCGI server.

Completing the installation

Once the steps described there are done, configuration is complete. You can now move on to completing the installation.