The CGI-Module¶

Module: mod_cgi

• Table of contents
• The CGI-Module
  • Description
  • Options
  • PATH environment variable
  • Examples

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://www.ietf.org/rfc/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 Docs_ModSetenv:
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(?:/|$)" {
  alias.url = ( "/urlpath" => "/path/to/script" )
  cgi.assign = ( "" => "" )
}