1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
6<html xmlns="http://www.w3.org/1999/xhtml">
7  <head>
8    <meta name="generator" content="HTML Tidy, see www.w3.org" />
9
10    <title>Apache module mod_cgi</title>
11  </head>
12  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
13
14  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
15  vlink="#000080" alink="#FF0000">
16        <div align="CENTER">
17      <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />
18
19      <h3>Apache HTTP Server Version 1.3</h3>
20    </div>
21
22
23    <h1 align="CENTER">Module mod_cgi</h1>
24
25    <p>This module provides for execution of CGI scripts.</p>
26
27    <p><a href="module-dict.html#Status"
28    rel="Help"><strong>Status:</strong></a> Base<br />
29     <a href="module-dict.html#SourceFile"
30    rel="Help"><strong>Source File:</strong></a> mod_cgi.c<br />
31     <a href="module-dict.html#ModuleIdentifier"
32    rel="Help"><strong>Module Identifier:</strong></a>
33    cgi_module</p>
34
35    <h2>Summary</h2>
36    <!-- XXX: Should have references to CGI definition/RFC -->
37    Any file that has the mime type
38    <code>application/x-httpd-cgi</code> or handler
39    <code>cgi-script</code> (Apache 1.1 or later) will be treated
40    as a CGI script, and run by the server, with its output being
41    returned to the client. Files acquire this type either by
42    having a name containing an extension defined by the <a
43    href="mod_mime.html#addtype">AddType</a> directive, or by being
44    in a <a href="mod_alias.html#scriptalias">ScriptAlias</a>
45    directory. Files that are not in a <a
46    href="mod_alias.html#scriptalias">ScriptAlias</a> directory,
47    but which are of type <code>application/x-httpd-cgi</code> by
48    virtue of an <code>AddType</code> directive, will still not be
49    executed by the server unless <code>Options ExecCGI</code> is
50    enabled. See the <a
51    href="core.html#options"><code>Options</code></a> directive for
52    more details.
53
54    <p>When the server invokes a CGI script, it will add a variable
55    called <code>DOCUMENT_ROOT</code> to the environment. This
56    variable will contain the value of the <a
57    href="core.html#documentroot">DocumentRoot</a> configuration
58    variable.</p>
59
60    <p>For an introduction to using CGI scripts with Apache, see
61    our tutorial on <a href="../howto/cgi.html">Dynamic Content
62    with CGI</a>.</p>
63
64    <h2>Directives</h2>
65
66    <ul>
67      <li><a href="#scriptlog">ScriptLog</a></li>
68
69      <li><a href="#scriptloglength">ScriptLogLength</a></li>
70
71      <li><a href="#scriptlogbuffer">ScriptLogBuffer</a></li>
72    </ul>
73
74    <p>See also: <a href="core.html#options">Options</a>, <a
75    href="mod_alias.html#scriptalias">ScriptAlias</a>, <a
76    href="mod_mime.html#addtype">AddType</a> and <a
77    href="mod_mime.html#addhandler">AddHandler</a>.</p>
78
79    <h2>CGI Environment variables</h2>
80    The server will set the CGI environment variables as described
81    in the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI
82    specification</a>, with the following provisions:
83
84    <dl>
85      <dt>REMOTE_HOST</dt>
86
87      <dd>This will only be set if <a
88      href="core.html#hostnamelookups"><code>HostnameLookups</code></a>
89      is set to <code>on</code> (it is off by default), and if a
90      reverse DNS lookup of the accessing host's address indeed
91      finds a host name.</dd>
92
93      <dt>REMOTE_IDENT</dt>
94
95      <dd>This will only be set if <a
96      href="core.html#identitycheck">IdentityCheck</a> is set to
97      <code>on</code> and the accessing host supports the ident
98      protocol. Note that the contents of this variable cannot be
99      relied upon because it can easily be faked, and if there is a
100      proxy between the client and the server, it is usually
101      totally useless.</dd>
102
103      <dt>REMOTE_USER</dt>
104
105      <dd>This will only be set if the CGI script is subject to
106      authentication.</dd>
107    </dl>
108
109    <h2><a id="cgi_debug" name="cgi_debug">CGI Debugging</a></h2>
110    Debugging CGI scripts has traditionally been difficult, mainly
111    because it has not been possible to study the output (standard
112    output and error) for scripts which are failing to run
113    properly. These directives, included in Apache 1.2 and later,
114    provide more detailed logging of errors when they occur.
115
116    <h2>CGI Logfile Format</h2>
117    When configured, the CGI error log logs any CGI which does not
118    execute properly. Each CGI script which fails to operate causes
119    several lines of information to be logged. The first two lines
120    are always of the format:
121<pre>
122  %% [<em>time</em>] <em>request-line</em>
123  %% <em>HTTP-status</em> <em>CGI-script-filename</em>
124</pre>
125    If the error is that CGI script cannot be run, the log file
126    will contain an extra two lines:
127<pre>
128  %%error
129  <em>error-message</em>
130</pre>
131    Alternatively, if the error is the result of the script
132    returning incorrect header information (often due to a bug in
133    the script), the following information is logged:
134<pre>
135  %request
136  <em>All HTTP request headers received</em>
137  <em>POST or PUT entity (if any)</em>
138  %response
139  <em>All headers output by the CGI script</em>
140  %stdout
141  <em>CGI standard output</em>
142  %stderr
143  <em>CGI standard error</em>
144</pre>
145    (The %stdout and %stderr parts may be missing if the script did
146    not output anything on standard output or standard error).
147    <hr />
148
149    <h3><a id="scriptlog" name="scriptlog">ScriptLog</a>
150    directive</h3>
151    <a href="directive-dict.html#Syntax"
152    rel="Help"><strong>Syntax:</strong></a> ScriptLog
153    <em>filename</em><br />
154     <a href="directive-dict.html#Default"
155    rel="Help"><strong>Default:</strong></a> none<br />
156     <a href="directive-dict.html#Context"
157    rel="Help"><strong>Context:</strong></a> server config<br />
158     <a href="directive-dict.html#Status"
159    rel="Help"><strong>Status:</strong></a> mod_cgi
160
161    <p>The <tt>ScriptLog</tt> directive sets the CGI script error
162    logfile. If no ScriptLog is given, no error log is created. If
163    given, any CGI errors are logged into the filename given as
164    argument. If this is a relative file or path it is taken
165    relative to the server root.</p>
166
167    <p>This log will be opened as the user the child processes run
168    as, ie. the user specified in the main <a
169    href="core.html#user">User</a> directive. This means that
170    either the directory the script log is in needs to be writable
171    by that user or the file needs to be manually created and set
172    to be writable by that user. If you place the script log in
173    your main logs directory, do <strong>NOT</strong> change the
174    directory permissions to make it writable by the user the child
175    processes run as.</p>
176
177    <p>Note that script logging is meant to be a debugging feature
178    when writing CGI scripts, and is not meant to be activated
179    continuously on running servers. It is not optimized for speed
180    or efficiency, and may have security problems if used in a
181    manner other than that for which it was designed.</p>
182    <hr />
183
184    <h3><a id="scriptloglength"
185    name="scriptloglength">ScriptLogLength</a> directive</h3>
186    <a href="directive-dict.html#Syntax"
187    rel="Help"><strong>Syntax:</strong></a> ScriptLogLength
188    <em>bytes</em><br />
189     <a href="directive-dict.html#Default"
190    rel="Help"><strong>Default:</strong></a> 10385760<br />
191     <a href="directive-dict.html#Context"
192    rel="Help"><strong>Context:</strong></a> server config<br />
193     <a href="directive-dict.html#Status"
194    rel="Help"><strong>Status:</strong></a> mod_cgi
195
196    <p><tt>ScriptLogLength</tt> can be used to limit the size of
197    the CGI script logfile. Since the logfile logs a lot of
198    information per CGI error (all request headers, all script
199    output) it can grow to be a big file. To prevent problems due
200    to unbounded growth, this directive can be used to set an
201    maximum file-size for the CGI logfile. If the file exceeds this
202    size, no more information will be written to it.</p>
203    <hr />
204
205    <h3><a id="scriptlogbuffer"
206    name="scriptlogbuffer">ScriptLogBuffer</a></h3>
207    <a href="directive-dict.html#Syntax"
208    rel="Help"><strong>Syntax:</strong></a> ScriptLogBuffer
209    <em>bytes</em><br />
210     <a href="directive-dict.html#Default"
211    rel="Help"><strong>Default:</strong></a> 1024<br />
212     <a href="directive-dict.html#Context"
213    rel="Help"><strong>Context:</strong></a> server config<br />
214     <a href="directive-dict.html#Status"
215    rel="Help"><strong>Status:</strong></a> mod_cgi
216
217    <p>The size of any PUT or POST entity body that is logged to
218    the file is limited, to prevent the log file growing too big
219    too quickly if large bodies are being received. By default, up
220    to 1024 bytes are logged, but this can be changed with this
221    directive.     <hr />
222
223    <h3 align="CENTER">Apache HTTP Server Version 1.3</h3>
224    <a href="./"><img src="../images/index.gif" alt="Index" /></a>
225    <a href="../"><img src="../images/home.gif" alt="Home" /></a>
226
227    </p>
228  </body>
229</html>
230
231
232
233