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 file 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-fpm. The configuration options for php-fpm are explained here. A possible php-fpm configuration for usage with Hiawatha is this:

[www]
user = www-data
group = www-data
listen = /var/lib/hiawatha/php-fcgi.sock
pm = static
pm.max_children = 3
chdir = /

Please note that this is just an example configuration. You are adviced to use values that are best for your system and situation.

In hiawatha.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. If you use a Unix socket, make sure Hiawatha is able to read the file specified via ConnectTo.

FastCGIserver {
    FastCGIid = PHP
    ConnectTo = /var/lib/hiawatha/php-fcgi.sock
    Extension = php
}

VirtualHost {
    ...
    UseFastCGI = PHP
}

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

Load balanced FastCGI

If you specify more than 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 = PHP
    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

Back