Mod cgi » History » Revision 30
Revision 29 (gstrauss, 2021-08-30 20:10) → Revision 30/31 (gstrauss, 2023-02-27 09: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 programs allow you to enhance the functionality of the server by running custom scripts or programs to handle requests. in a very straight-forward and simple way.
Note: Note that to capture see stderr output from CGI processes, you need to set @server.breakagelog
<pre>
server.breakagelog = "/var/log/lighttpd/breakage.log"@.
"/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.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"). 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), line) you just don't specify a blank handler for the extension:
<pre>
cgi.assign = ( ".sh" => "" )
</pre>
If the file has no extension, 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>