FastCGI Engine Contrib

Overview

FastCGI is a technology to deliver dynamic web content. It differs from CGI cause it remains persistent between requests, instead of CGI approach of a new forked process per request. This way there is a significant performance improvement, since all overhead related to create a new process, load the interpreter and compile the code is skipped.

Some FastCGI features:

• The number of persistent processes is configurable, independent of the web server. This leads to easier capacity planning/management.
• Processes can be run with a different user: more security.
• Processes can be run on another machines: easier load balancing.

Installation Instructions

This section is about how to configure FastCGIEngineContrib, considering many possible environments:

• Apache web server
  • Using only .htaccess (typically on host services)
  • With access to apache configuration files
    • Remote FastCGI processes
• Lighttpd web server
  • Remote FastCGI processes

Apache

Using only .htaccess

Using only .htaccess file it's not possible to control the number of FastCGI processes, nor the user it'll be run with. We assume the webserver is configured to recognize files with .fcgi extension to be FastCGI scripts. We also need mod_rewrite or mod_actions enabled.

The directory references in the following subsections are relative to Foswiki root.

Example using mod_rewrite:

# bin/.htaccess file

Options +ExecCGI

RewriteEngine On

# configure script is a special case, it must run as a CGI script:
RewriteCond %{REQUEST_URI} !/configure 

# avoid loops:
RewriteCond %{REQUEST_URI} !/foswiki.fcgi

RewriteRule ^(.*) /foswiki/bin/foswiki.fcgi/$1

<Files configure>
    SetHandler cgi-script
</Files>

Example using mod_actions:

# bin/.htaccess file

Options +ExecCGI

Action foswiki-fastcgi /foswiki/bin/foswiki.fcgi
SetHandler foswiki-fastcgi

<Files configure>
    SetHandler cgi-script
</Files>

<Files foswiki.fcgi>
   SetHandler fastcgi-script
</Files>

This example assume you're using mod_fastcgi. If you're using mod_fcgid replace SetHandler fastcgi-script by SetHandler fcgid-script.

With access to apache configuration files

Direct access to Apache configuration files open more possibilities than with .htaccess:

• It's possible to configure the number of FastCGI processes
• It's possible to use FastCGI processes remotely and/or control with user to run with, by using sockets

Using mod_fastcgi

We can use static or dynamic servers: static servers are initialized with Apache itself and exists as long Apache is running. Dynamic servers are loaded on demand and killed if the aren't needed anymore.

See mod_fastcgi documentation for more options.

# Simple and traditional example.
Alias /foswiki/bin/configure /var/www/foswiki/bin/configure
Alias /foswiki/bin   /var/www/foswiki/bin/foswiki.fcgi

# Commenting the next line makes foswiki to be a dynamic server, loaded on demand
FastCgiServer /var/www/foswiki/bin/foswiki.fcgi -processes 3

<Directory /var/www/foswiki/bin>
   Options +ExecCGI
    <Files configure>
        SetHandler cgi-script
    </Files>
    <Files foswiki.fcgi>
        SetHandler fastcgi-script
    </Files>
</Directory>

Refer to tuning section below for a little discussion about the number of FastCGI processes.

# External server: could be running at another machine and/or a different user from the webserver

Alias /foswiki/bin/configure /var/www/foswiki/bin/configure
Alias /foswiki/bin   /var/www/foswiki/bin/foswiki.fcgi

# Running an external server on the same machine:
FastCgiExternalServer /var/www/foswiki/bin/foswiki.fcgi -socket /path/to/foswiki.sock

# Or at another machine:
FastCgiExternalServer /var/www/foswiki/bin/foswiki.fcgi -host example.com:8080

<Directory /var/www/foswiki/bin>
    Options +ExecCGI
    <Files configure>
        SetHandler cgi-script
    </Files>
    <Files foswiki.fcgi>
        SetHandler fastcgi-script
    </Files>
</Directory>

When you're using external servers you must run the FastCGI processes manually:

$ cd /var/www/foswiki/bin
# To start a pool of processes, listening to a local UNIX socket:
$ ./foswiki.fcgi --listen /path/to/foswiki.sock --nproc 3 --pidfile /path/to/pidfile.pid --daemon
# Or listening to a local :port address:
$ ./foswiki.fcgi --listen :port --nproc 3 --pidfile /path/to/pidfile.pid --daemon

Run ./foswiki.fcgi --help for details on the options.

Using mod_fcgid

As I understood from the mod_fcgid documentation, only dynamic servers are supported and there is no way to use processes running on another machine.

# Simple and traditional example.
Alias /foswiki/bin/configure /var/www/foswiki/bin/configure
Alias /foswiki/bin   /var/www/foswiki/bin/foswiki.fcgi

<Directory /var/www/foswiki/bin>
   Options +ExecCGI
    <Files configure>
        SetHandler cgi-script
    </Files>
    <Files foswiki.fcgi>
        SetHandler fcgid-script
    </Files>
</Directory>

ApacheLogin

If you use ApacheLogin instead of TemplateLogin you'll need to add something like the following directives:

<LocationMatch "^/+foswiki/+bin/+(attach|edit|manage|rename|save|upload|.*auth|rest|login|logon)">
   AuthType Basic
   AuthName "Foswiki login realm"
   AuthUserFile "/var/www/foswiki/data/.htpasswd"
   Require valid-user
</LocationMatch>

Lighttpd

You need to load both mod_cgi and mod_fastcgi. The first is used to run configure script. From what I understood from the documentation, lighttpd doesn't support dynamic servers.

# Example with FastCGI processes launched by the webserver
$HTTP["url"] =~ "^/foswiki/bin/configure" {
    alias.url += ( "/foswiki/bin" => "/var/www/foswiki/bin" )
    cgi.assign = ( "" => "" )
}

$HTTP["url"] =~ "^/foswiki/bin/" {
    alias.url += ( "/foswiki/bin" => "/var/www/foswiki/bin/foswiki.fcgi" )
    fastcgi.server = ( ".fcgi" => (
            (
                "socket"    => "/var/www/foswiki/working/tmp/foswiki.sock",
                "bin-path"  => "/var/www/foswiki/bin/foswiki.fcgi",
                "max-procs" => 3
            ),
        )
    )
}

# Example with external FastCGI processes (running on the same host, with another user or at a remote machine)
$HTTP["url"] =~ "^/foswiki/bin/configure" {
    alias.url += ( "/foswiki/bin" => "/var/www/foswiki/bin" )
    cgi.assign = ( "" => "" )
}

$HTTP["url"] =~ "^/foswiki/bin/" {
    alias.url += ( "/foswiki/bin" => "/var/www/foswiki/bin/foswiki.fcgi" )
    fastcgi.server = ( ".fcgi" => (
            (
                "host"    => "example.com",
                "port"    => "8080",
            ),
        )
    )
}

Tuning

Except from Apache using only .htaccess file, it's possible to adjust the number of FastCGI processes. There is no magic number: it depends on some variables, like the hardware resources and access load. If you set this number too low, users may experience high latencies and you'll not use all hardware potential, on the other hand if this setting is adjusted too high then the server can be forced to use swap, what degrades performance a lot.

Dynamic servers are more useful when foswiki access load on the server is low and/or it's used to something else. Under high loads, static servers can deliver better performance.

Known Issues

FastCGI specification defines an authorizer role besides the common used responder. Foswiki, by default, doesn't check access to attachments, unless you use viewfile script. The problem with that script is that it's slow and resource-hungry. In future releases, this contrib will provide a way to add access checks to attachments with very little overhead, using the authorizer role.

This is a persistent engine, so you need to restart the web server after some configuration update is performed. However, there is an auto-reload mechanism that apply changes without a web server restart. Unfortunately, there is a delay: after the update, each process will still serve one more request before reloading itself (e.g. if you're using 3 processes, the next 3 requests after the update will not be affected. The update will take effect on the requests made after the initial 3). This reloading mechanism works only on operating systems that have the exec(2) system call, like Linux and other POSIX compliant systems.

All examples above have an exception to configure script. This script needs to run as a plain CGI script. There are some legacy extensions (not updated to Foswiki:Development/FoswikiStandAlone design) that adds scripts to the bin/ directory. You need to add exceptions to these scripts as well.

FastCGI support on IIS 6.0 (and maybe other versions) is broken with respect to the STDERR stream. This may cause problems.

Info