HOWTO: Using CGI and FastCGI

Normal CGI

Making Hiawatha run CGI applications is easy. You can allow CGI execution per website via the ExecuteCGI option.

VirtualHost {
    ...
    ExecuteCGI = yes
}

All CGI applications can be divided into two groups: CGI scripts and CGI programs.

CGI scripts

CGI scripts need an interpreter to run. CGI scripts are nothing more than text files and don't require the execute flag. To execute a CGI script from the command line, use the filename of the script as a parameter of the interpreter.

/path/to/interpreter script.ext

If you want to use CGI scripts in your website, you have to specify where Hiawatha can find the binary that can handle those scripts. Per CGI-handler, you have to tell Hiawatha what files should be handled by listing the extensions of those files.

CGIhandler = /usr/bin/php5-cgi:php,php5
CGIhandler = /usr/bin/perl:pl
CGIhandler = /usr/bin/python:py

CGI programs

CGI programs can run by itself and are most likely compiled C programs or scripts which start with a "#!/path/to/interpreter" line. CGI programs require the execute flag. To execute a CGI program from the command line, use their filename directly at the command prompt.

./program.ext

To use CGI programs in your website, Hiawatha needs to know the extension of the CGI programs. This can be done via the CGIextension option.

CGIextension = cgi

CGI security

You can limit the maximum runtime of CGI programs (in seconds) via the TimeForCGI option.

VirtualHost {
    ...
    TimeForCGI = 10
}

FastCGI

Everytime a request for a CGI application is done, the webserver needs to run the CGI application. Starting and initializing an application takes time. To make the process of running a CGI application faster, FastCGI was invented. A FastCGI application starts once and remains in memory. It can handle multiple requests during its lifetime.

There are two kinds of FastCGI applications. The first one runs as a daemon and listens to a port for incoming connections from a webserver. The second one is started by the webserver and communicates with the webserver via pipes. Hiawatha only supports the first kind.

In the example below, we'll use PHP via FastCGI. First, install php-cgi with FastCGI support (compile PHP with --enable-fastcgi or check that your precompiled php-cgi package has FastCGI support). PHP can be started as a FastCGI daemon with the tool php-fcgi, which comes with Hiawatha. Edit the configuration file php-fcgi.conf (which is located in your Hiawatha configuration directory). For every Server configuration line, a PHP FastCGI daemon will be started. Every Server configuration line consist of at least 3 options: the path to the php-cgi binary, the binding (interface:port) and the userid the PHP FastCGI daemon must switch to. An optional fourth option tells the path to the php.ini file. A typical configuration line looks like this:

Server = /usr/bin/php5-cgi ; 127.0.0.1:2005 ; www-data

Run php-fcgi (probably in /usr/sbin or /usr/local/sbin) to start the PHP FastCGI daemon(s). Run with the '-k' option to kill the running PHP FastCGI daemons.

In httpd.conf, you have to tell Hiawatha how to reach this FastCGI daemon and when to use it (for which file extensions). Give it a unique id and use this id with the UseFastCGI option for every virtual host which must use this FastCGI server.

FastCGIserver {
    FastCGIid = PHP5
    ConnectTo = 127.0.0.1:2005
    Extension = php
}

VirtualHost {
    ...
    UseFastCGI = PHP5
}

You can also use Unix sockets to connect to a FastCGI daemon by specifying the path to the socket file:

    ConnectTo = /path/to/daemon.sock

A FastCGIserver section with the same extension as a CGIhandler, overrules this CGIhandler.

Load balanced FastCGI

If you specify more then one ConnectTo parameter, Hiawatha will switch between these FastCGI servers for every connection. You can use this load-balancing feature for heavy websites. To prevent CGI sessions from getting disrupted, Hiawatha must know the timeout (in minutes) of such session.

FastCGIserver {
    FastCGIid = PHP5
    ConnectTo = 10.0.0.100:2005, 10.0.0.101:2005, 10.0.0.102:2005
    Extension = php
    SessionTimeout = 15
}

Make sure every FastCGI server has the web application code in the same directory as configured in Hiawatha.

Writing FastCGI applications

If you don't want to use PHP, then you'll have to write your own FastCGI enabled web application. You can use one of the following examples to get started. Note that they all require the FastCGI development kit.

The tool cgi-fcgi can be used to turn a non-daemon (via pipes) FastCGI application into a FastCGI daemon:

cgi-fcgi -start -connect :2005 /path/to/your/fastcgi/program