Mod cgi » History » Revision 29
Revision 28 (gstrauss, 2021-07-25 09:30) → Revision 29/32 (gstrauss, 2021-08-30 20:10)
h1. The CGI-Module
*Module: mod_cgi*
{{>toc}}
h2. 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
<pre>
server.breakagelog = "/var/log/lighttpd/breakage.log"
</pre>
or similar.
h2. Options
*cgi.execute-x-only*
requires +x for cgi scripts if enabled.
*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 don't forget to set cgi.fix_pathinfo = 1 in the php.ini.
To get the old cgi-bin behavior of apache:
<pre>
#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>
*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") 15) # 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"). To specify a PATH for CGI scripts, use [[Docs_ModSetenv]]:
<pre>
setenv.add-environment = ( "PATH" => "/sbin:/usr/sbin:/bin:/usr/bin" )
</pre>
In lighttpd 1.4.46 and later, <code>setenv.set-environment</code> is preferred:
<pre>
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) you just don't specify a 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 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>