Mod cgi - Lighttpd - lighty labs (original) (raw)

The CGI-Module¶

Module: mod_cgi

Table of contents
The CGI-Module

Description¶

CGI technical specification and reference:
RFC3875 The Common Gateway Interface (CGI) Version 1.1

CGI allows you to enhance the functionality of the server by running custom scripts or programs to handle requests.

Note: to capture stderr output from CGI processes, set server.breakagelog = "/var/log/lighttpd/breakage.log".

Options¶

cgi.assign

file-extensions that are handled by a CGI program

cgi.assign = ( ".pl"  => "/usr/bin/perl",
               ".cgi" => "/usr/bin/perl" )

For PHP, do not forget to set cgi.fix_pathinfo = 1 in the php.ini.

To get traditional "cgi-bin" behavior where scripts are under /cgi-bin:

# Note: make sure that mod_alias is loaded if you use this:
alias.url += ( "/cgi-bin" => server_root + "/cgi-bin" )
$HTTP["url"] =~ "^/cgi-bin" {
    cgi.assign = ( "" => "" )
}

An empty string ("") on the left side of ( "" => "" ) matches everything.
An empty string ("") on the right side of ( "" => "" ) is a magic token that indicates that the request target is the file which should be run.
If the cgi-bin directory is not under server.document-root in the filesystem, then you need to use mod_alias alias.url to map /cgi-bin to the /filesystem/path/to/cgi-bin.

cgi.execute-x-only
requires +x for cgi scripts if enabled.

cgi.x-sendfile (since 1.4.40)
If the "x-sendfile" feature is active, an X-Sendfile response header containing a fully-qualified path will cause lighttpd to send the local file found at that path instead of the generated content from the backend. See mod_fastcgi X-Sendfile

cgi.x-sendfile = "enable"  # default "disable"

cgi.x-sendfile-docroot (since 1.4.40)
"x-sendfile-docroot" limits the directory trees (absolute filesystem paths) allowed in the path provided by X-Sendfile response header. See mod_fastcgi X-Sendfile

cgi.x-sendfile-docroot = ( "/srv/www/html", "/srv/www/static" )

cgi.local-redir (since 1.4.46)
https://datatracker.ietf.org/doc/html/rfc3875 6.2.2 Local Redirect Response optimization

cgi.local-redir = "enable"  # default "disable"

cgi.upgrade (since 1.4.46)
support for Upgrade: websocket

cgi.upgrade = "enable"  # default "disable"

Depending on the websocket application, please also review settings for server.max-read-idle and server.max-write-idle

cgi.limits (since 1.4.60)

list of limits to apply to CGI
- "write-timeout" - number of seconds before aborting when trying to write to backend (default: 0; no timeout) (since 1.4.60)
- "read-timeout" - number of seconds before aborting when trying to read from backend (default: 0; no timeout) (since 1.4.60)
- "tcp-fin-propagate" - send specified signal to CGI if TCP FIN is received from client (default: none) (since 1.4.60)
cgi.limits = ("write-timeout" => 15, "read-timeout" => 15, "tcp-fin-propagate" => "SIGTERM") # default: none

PATH environment variable¶

The default PATH environment variable in the CGI execution environment is unspecified by lighttpd and results in use of the default PATH built into the shell (e.g. PATH="/bin:/usr/bin"). To specify a PATH for CGI scripts, use mod_setenv:
In lighttpd 1.4.46 and later, setenv.set-environment is preferred:

setenv.set-environment = ( "PATH" => "/sbin:/usr/sbin:/bin:/usr/bin" )

For lighttpd 1.4.45 and earlier, use

setenv.add-environment = ( "PATH" => "/sbin:/usr/sbin:/bin:/usr/bin" )

Examples¶

To setup an executable which can run on its own (e.g. binaries, scripts with a shebang line), specify a blank handler for the extension:

cgi.assign = ( ".sh" => "" )

If the file has no extension, keep in mind that lighttpd matches not the extension itself but the right part (suffix) of the URL:

cgi.assign = ( "/testfile" => "" )

To assign a CGI script as a default handler for a URL path, even if that path is virtual, with the help of mod_alias: HTTP["url"]= "/urlpath(?:/∣HTTP["url"] =~ "^/urlpath(?:/|HTTP["url"]= "/urlpath(?:/∣)" { alias.url = ( "/urlpath" => "/path/to/script" ) cgi.assign = ( "" => "" ) }