Mod cgi » History » Revision 31
Revision 30 (gstrauss, 2023-02-27 09:21) → Revision 31/32 (gstrauss, 2024-03-20 04:21)
h1. The CGI-Module
*Module: mod_cgi*
{{>toc}}
h2. Description
CGI technical specification and reference:
"RFC3875":https://www.ietf.org/rfc/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"@.
h2. Options
*cgi.assign*
file-extensions that are handled by a CGI program
<pre>
cgi.assign = ( ".pl" => "/usr/bin/perl",
".cgi" => "/usr/bin/perl" )
</pre>
For PHP, do not PHP don't forget to set @cgi.fix_pathinfo cgi.fix_pathinfo = 1@ 1 in the @php.ini@. php.ini.
To get traditional "cgi-bin" the old cgi-bin behavior where scripts are under @/cgi-bin@:
of apache:
<pre>
# Note: #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 = ( "" => "" )
}
</pre>
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 [[lighttpd:Docs_ModFastCGI#X-Sendfile|X-Sendfile]]
<pre>
cgi.x-sendfile = "enable" # default "disable"
</pre>
*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 [[lighttpd:Docs_ModFastCGI#X-Sendfile|X-Sendfile]]
<pre>
cgi.x-sendfile-docroot = ( "/srv/www/html", "/srv/www/static" )
</pre>
*cgi.local-redir* (since 1.4.46)
https://www.ietf.org/rfc/rfc3875 6.2.2 Local Redirect Response optimization
<pre>
cgi.local-redir = "enable" # default "disable"
</pre>
*cgi.upgrade* (since 1.4.46)
support for Upgrade: websocket
<pre>
cgi.upgrade = "enable" # default "disable"
</pre>
Depending on the websocket application, please also review settings for [[Server_max-read-idleDetails|server.max-read-idle]] and [[Server_max-write-idleDetails|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)
<pre>
cgi.limits = ("write-timeout" => 15, "read-timeout" => 15, "tcp-fin-propagate" => "SIGTERM") # default: none
</pre>
h2. 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"@). PATH="/bin:/usr/bin"). To specify a PATH for CGI scripts, use [[Docs_ModSetenv]]:
In lighttpd 1.4.46 and later, <code>setenv.set-environment</code> is preferred:
<pre>
setenv.set-environment setenv.add-environment = ( "PATH" => "/sbin:/usr/sbin:/bin:/usr/bin" )
</pre>
For In lighttpd 1.4.45 1.4.46 and earlier, use later, <code>setenv.set-environment</code> is preferred:
<pre>
setenv.add-environment setenv.set-environment = ( "PATH" => "/sbin:/usr/sbin:/bin:/usr/bin" )
</pre>
h2. 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:
<pre>
cgi.assign = ( ".sh" => "" )
</pre>
If the file has no extension, keep in mind that lighttpd matches not the extension itself but the right part (suffix) of the URL:
<pre>
cgi.assign = ( "/testfile" => "" )
</pre>
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:
<pre>
$HTTP["url"] =~ "^/urlpath(?:/|$)" {
alias.url = ( "/urlpath" => "/path/to/script" )
cgi.assign = ( "" => "" )
}
</pre>