Simple CGI support for Nginx (fcgiwrap)

What?

fcgiwrap is a simple server for running CGI applications over FastCGI. It hopes to provide clean CGI support to Nginx (and other web servers that may need it).

Features and limitations

Features

• very lightweight (84KB of private memory per instance)
• fixes broken CR/LF in headers
• handles environment in a sane way (CGI scripts get HTTP-related env. vars from FastCGI parameters and inherit all the others from fcgiwrap's environment)
• no configuration, so you can run several sites off the same fcgiwrap pool
• passes CGI stderr output to fcgiwrap's stderr (this is by design but stderr could be also passed to FastCGI stderr stream)

Limitations

• only one request at a time (but it's cheap to run a bunch of them)
• passes the whole request to CGI before reading the reply (won't work if you stream the request and expect streamed response back)

Download

You can download fcgiwrap from github, either as a tarball, or as a git repo:

tarball

http://github.com/gnosek/fcgiwrap/tarball/master

git repo

git://github.com/gnosek/fcgiwrap.git

Install

To run fcgiwrap, you need libfcgi headers and libraries. If you're on Debian, apt-get install libfcgi-dev should be enough, as long as you already have a compiler.

Enter the directory where you downloaded (and unpacked) the sources and simply run make install. This will compile fcgiwrap and put it in /usr/local/bin. If you want a different location, run make without any arguments and copy the resulting fcgiwrap file manually.

Configure

fcgiwrap doesn't have any configuration options. However, there are two FastCGI parameters that must be provided by Nginx (note that your CGI script will probably need them too). They are DOCUMENT_ROOT and SCRIPT_NAME.

A basic FastCGI configuration could look like this (mostly stolen from Nginx wiki: http://wiki.codemongers.com/NginxFcgiExample)

fastcgi_param  QUERY_STRING       $query_string;
fastcgi_param  REQUEST_METHOD     $request_method;
fastcgi_param  CONTENT_TYPE       $content_type;
fastcgi_param  CONTENT_LENGTH     $content_length;
fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
fastcgi_param  REQUEST_URI        $request_uri;
fastcgi_param  DOCUMENT_URI       $document_uri;
fastcgi_param  DOCUMENT_ROOT      $document_root;
fastcgi_param  SERVER_PROTOCOL    $server_protocol;
fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
fastcgi_param  SERVER_SOFTWARE    nginx;
fastcgi_param  REMOTE_ADDR        $remote_addr;
fastcgi_param  REMOTE_PORT        $remote_port;
fastcgi_param  SERVER_ADDR        $server_addr;
fastcgi_param  SERVER_PORT        $server_port;
fastcgi_param  SERVER_NAME        $server_name;
fastcgi_param  REMOTE_USER        $remote_user;

You can then start fcgiwrap (possibly in several instances) using spawn-fcgi or a similar tool (you must pass an open socket as fd 0; my Spawner? will be very nice for this once I actually make it usable and publish it) and send requests to it using fastcgi_pass. That's it.

Note: If you don't have a FastCGI launcher handy, this Perl script should do the trick (not tested actually but compiles and basically works):

#!/usr/bin/perl

use strict;
use warnings FATAL => qw( all );

use IO::Socket::UNIX;

my $bin_path = '/usr/local/bin/fcgiwrap';
my $socket_path = $ARGV[0] || '/tmp/cgi.sock';
my $num_children = $ARGV[1] || 1;

close STDIN;

unlink $socket_path;
my $socket = IO::Socket::UNIX->new(
    Local => $socket_path,
    Listen => 100,
);

die "Cannot create socket at $socket_path: $!\n" unless $socket;

for (1 .. $num_children) {
    my $pid = fork;
    die "Cannot fork: $!" unless defined $pid;
    next if $pid;

    exec $bin_path;
    die "Failed to exec $bin_path: $!\n";
}

Security

fcgiwrap doesn't chroot(), drop privileges or do anything like this. It is expected that you do this beforehand (after all, you know your setup, not me). If you run it as an unprivileged user, you'll be fine. If you run it as root, you're already insane :)

fcgiwrap doesn't verify the SCRIPT_FILENAME passed to it and will happily traverse directories upwards. I consider this the responsibility of the web server (Nginx does this just fine) but feel free to bug me if you disagree.

What fcgiwrap does is to disallow requests to non-regular and non-executable files.

Performance

Come on, it's CGI, what do you expect? :)