The CGI-Module¶

Module: mod_cgi

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

Description¶

CGI programs allow you to enhance the functionality of the server in a very straight-forward and simple way.

Note that to see stderr output from CGI processes, you need to set

    server.breakagelog = "/var/log/lighttpd/breakage.log" 

or similar.

Options¶

cgi.execute-x-only

requires +x for cgi scripts if enabled.

cgi.assign

file-extensions that are handled by a CGI program

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

For PHP don't forget to set cgi.fix_pathinfo = 1 in the php.ini.

To get the old cgi-bin behavior of apache:

    #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 = ( "" => "" )
    }

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)

    cgi.limits = ("write-timeout" => 15, "read-timeout" => 15)  # 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:

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

In lighttpd 1.4.46 and later, setenv.set-environment is preferred:

    setenv.set-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) you just don't specify a 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 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 = ( "" => "" )
}