nscgi -- Common Gateway Interface (CGI) module

$Header: /cvsroot/aolserver/aolserver/nscgi/nscgi.html,v 1.3 2004/09/08 18:06:20 dossy Exp $

Theory of Operation

The nscgi module provides the traditional Common Gateway Interface (CGI) that web servers use to run external applications. The nscgi module works well for small- to medium-sized applications. For large applications, it should not be used due to the severe load that running external applications will place on a system. More modern approaches use ADP, Tcl, and C libraries instead.

Known Issues

The Common Gateway Interface is inefficient, wasteful, and slow -- and nscgi is no exception. AOLserver provides a better solution in the form of a robust, in-process scripting language with rich Tcl and C API's. The nscgi module should only be used for legacy applications for which no redesign is possible.

Configuration Options

The following options are available for configuring the nscgi module:

Option Type Default Description
environment string N/A The name of the config section which contains the additional environment variable names and values to set before executing the CGI. The config section is a subsection of the "ns/environment" config section.
gethostbyaddr boolean false Whether to resolve the peer IP address to its hostname when setting the REMOTE_HOST environment variable. If "false", the peer IP address will be used instead. Caution: turning this option on can negatively impact performance due to the overhead of having to perform a DNS look-up on every CGI request.
interps string N/A The name of the config section which contains the mappings from file extensions to CGI interpreters to execute the CGI with. The config section is a subsection of the "ns/interps" config section.
limit integer 0 Maximum number of concurrent CGI requests to execute. "0" means unlimited.
map string N/A

Maps relative URIs or glob patterns to filesystem paths or executables. The map option's value is of the form:

method pattern path
  • method refers to the HTTP request method (i.e., HEAD, GET, POST, etc.)
  • pattern refers to either a relative URI or a glob pattern to match on the HTTP request. This is how nscgi determines whether a request is a CGI request and which map rule applies.
  • path is optional, when specified, indicates either the directory where the CGI executables can be found, or the executable that should be used to fulfill the CGI request.

If path is not specified, then the URL must refer a file which is the CGI executable. If it is specified and is a directory, then the filename portion of the URL must refer to a CGI executable in that directory. Otherwise, path must refer to a CGI executable which will handle all requests for this pattern.
maxinput integer 1024000 Maximum in bytes to accept in the HTTP request. "0" means unlimited. Mostly useful to limit the size of POST'ed data.
maxwait integer 30 Amount of time to wait in the queue when the concurrency limit has been reached. Server will respond with a 503 Service Unavailable error on timeout. If limit is set to "0", this setting will have no effect.
systemenvironment boolean false Controls whether the CGI will inherit the server process's environment variables or not. Enabling this could potentially leak sensitive information from the parent's environment if the CGI displays its environment variables which is the behavior of some common error-handling code.

Sample Configuration

#
# CGI interface -- nscgi
#
# Note: CGI is *vastly* inferior to ADP's or even built-in Tcl libraries.
#

ns_section "ns/server/${servername}/module/nscgi"
ns_param   limit            0       ;# Max number of concurrent CGI processes
ns_param   maxinput         1024000 ;# Max bytes allowed in HTTP request
ns_param   maxwait          30      ;# Max seconds to wait in limit queue
ns_param   gethostbyaddr    false   ;# Whether to do reverse DNS lookups

# /cgi/foo.cgi maps to /usr/local/cgi/foo.cgi
ns_param   map "GET /cgi /usr/local/cgi"
ns_param   map "POST /cgi /usr/local/cgi"
ns_param   map "HEAD /cgi /usr/local/cgi"

# Any request for *.pl will be executed as CGI
ns_param   map "GET *.pl"
ns_param   map "POST *.pl"
ns_param   map "HEAD *.pl"

# CGI interp. and environment variable handling -- See admin guide
ns_param   systemenvironment false  ;# Inherit environment from the nsd process
ns_param   environment      cgi     ;# Config. section which defines
                                    ;# additional environment variables.
ns_param   interps          cgi     ;# Config. section which defines
                                    ;# interpreters for CGI file extensions.

ns_section "ns/environment/cgi"
ns_param   FOO              BAR     ;# defines env. var "FOO=BAR"

ns_section "ns/interps/cgi"
ns_param   .pl              /usr/bin/perl   ;# What to use for .pl files