= 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 [wiki: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? :)