From: Joshua Slive Date: Fri, 1 Mar 2002 22:16:23 +0000 (+0000) Subject: XML conversions of mod_cgi and mod_cgid. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f87bb121eb569aed8c65c7ffed4a54de482def57;p=apache XML conversions of mod_cgi and mod_cgid. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@93664 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_cgi.html b/docs/manual/mod/mod_cgi.html index 1a355eee58..3bd2fd073e 100644 --- a/docs/manual/mod/mod_cgi.html +++ b/docs/manual/mod/mod_cgi.html @@ -1,178 +1,273 @@ - - - - - - - Apache module mod_cgi - - - - - - -

Module mod_cgi

- -

This module provides for execution of CGI scripts.

- -

Status: Base
- Source File: mod_cgi.c
- Module Identifier: - cgi_module

- -

Summary

- - - - -

Any file that has the mime type + + + + +mod_cgi - Apache HTTP Server + + + +

+
+[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

+
+

Apache Module mod_cgi

+ + + + +
+ + + + + + + + + + +
Description: +Execution of CGI scripts +
Status:Base
Module Identifier:cgi_module
+
+

Summary

+ + + + + + +

Any file that has the mime type application/x-httpd-cgi or handler cgi-script (Apache 1.1 or later) will be treated as a CGI script, and run by the server, with its output being returned to the client. Files acquire this type either by - having a name containing an extension defined by the AddType directive, or by being - in a ScriptAlias + having a name containing an extension defined by the + AddType directive, or by being + in a ScriptAlias directory.

-

When the server invokes a CGI script, it will add a variable + +

When the server invokes a CGI script, it will add a variable called DOCUMENT_ROOT to the environment. This - variable will contain the value of the DocumentRoot configuration + variable will contain the value of the + DocumentRoot configuration variable.

-

For an introduction to using CGI scripts with Apache, see + +

For an introduction to using CGI scripts with Apache, see our tutorial on Dynamic Content With CGI.

-

When using a multi-threaded MPM under unix, the module mod_cgid should be used in place of + +

When using a multi-threaded MPM under unix, the module + mod_cgid should be used in place of this module. At the user level, the two modules are essentially identical.

-

Directives

- - - -

See also: Options, ScriptAlias, AddType and AddHandler.

- -

CGI Environment variables

- The server will set the CGI environment variables as described + +

+See also: +

+ +

Directives

+ +

CGI Environment variables

+ +

The server will set the CGI environment variables as described in the CGI - specification, with the following provisions: - -

-
PATH_INFO
- -
This will not be available if the AcceptPathInfo - directive is explicitly set to off. The default - behavior, if AcceptPathInfo is not given, is that mod_cgi will - accept path info (trailing /more/path/info following the script - filename in the URI), while the core server will return a 404 - NOT FOUND error for requests with additional path info. - Omitting the AcceptPathInfo directive has the same effect as - setting it on for mod_cgi requests.
- -
REMOTE_HOST
- -
This will only be set if HostnameLookups - is set to on (it is off by default), and if a - reverse DNS lookup of the accessing host's address indeed - finds a host name.
- -
REMOTE_IDENT
- -
This will only be set if IdentityCheck is set to + specification, with the following provisions:

+ + +
+ +
PATH_INFO
+ + +
This will not be available if the AcceptPathInfo directive is explicitly set to + off. The default behavior, if AcceptPathInfo is + not given, is that mod_cgi will accept path info (trailing + /more/path/info following the script filename in the URI), while + the core server will return a 404 NOT FOUND error for requests + with additional path info. Omitting the AcceptPathInfo + directive has the same effect as setting it on for + mod_cgi requests.
+ + +
REMOTE_HOST
+ + +
This will only be set if HostnameLookups is set to on (it + is off by default), and if a reverse DNS lookup of the accessing + host's address indeed finds a host name.
+ + +
REMOTE_IDENT
+ + +
This will only be set if IdentityCheck is set to on and the accessing host supports the ident protocol. Note that the contents of this variable cannot be relied upon because it can easily be faked, and if there is a proxy between the client and the server, it is usually totally useless.
-
REMOTE_USER
+ +
REMOTE_USER
-
This will only be set if the CGI script is subject to + +
This will only be set if the CGI script is subject to authentication.
-
- -

CGI Debugging

- Debugging CGI scripts has traditionally been difficult, mainly + +
+ +

+CGI Debugging +

+ +

Debugging CGI scripts has traditionally been difficult, mainly because it has not been possible to study the output (standard output and error) for scripts which are failing to run properly. These directives, included in Apache 1.2 and later, - provide more detailed logging of errors when they occur. + provide more detailed logging of errors when they occur.

+ -

CGI Logfile Format

- When configured, the CGI error log logs any CGI which does not +

CGI Logfile Format

+ +

When configured, the CGI error log logs any CGI which does not execute properly. Each CGI script which fails to operate causes several lines of information to be logged. The first two lines - are always of the format: -

+    are always of the format:

+
+

+
+
+
+
+

   %% [time] request-line
+

   %% HTTP-status CGI-script-filename
-
-    If the error is that CGI script cannot be run, the log file
-    will contain an extra two lines: 
-
-  %%error
-  error-message
-

-    Alternatively, if the error is the result of the script
+

+

+    
+
If the error is that CGI script cannot be run, the log file
+    will contain an extra two lines:

+
+

+
+
+
+
+

+  %%error

+  
+error-message
+

+

+    
+
Alternatively, if the error is the result of the script
     returning incorrect header information (often due to a bug in
-    the script), the following information is logged: 
-
-  %request
-  All HTTP request headers received
-  POST or PUT entity (if any)
-  %response
-  All headers output by the CGI script
-  %stdout
-  CGI standard output
-  %stderr
-  CGI standard error
-

-    (The %stdout and %stderr parts may be missing if the script did
-    not output anything on standard output or standard error). 
-    

-
-    
ScriptLog
-    directive

-    Syntax: ScriptLog
-    filename

-     Default: none

-     Context: server config

-     Status: mod_cgi 
-
-    
The ScriptLog directive sets the CGI script error
-    logfile. If no ScriptLog is given, no error log is created. If
-    given, any CGI errors are logged into the filename given as
-    argument. If this is a relative file or path it is taken
+    the script), the following information is logged: 

+
+

+
+
+
+
+

+  %request

+  
+All HTTP request headers received
+

+  
+POST or PUT entity (if any)
+

+  %response

+  
+All headers output by the CGI script
+

+  %stdout

+  
+CGI standard output
+

+  %stderr

+  
+CGI standard error
+

+
+

+

+    
+
(The %stdout and %stderr parts may be missing if the script did
+    not output anything on standard output or standard error). 

+
+
+

+

+ScriptLog Directive
+

+
+
+
+
+

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Description: Location of the CGI script error logfile
Syntax:
+ScriptLog file-path
+
+
Context:server config
Status:Base
Module:mod_cgi, mod_cgid

+

+
+    
+
The ScriptLog directive sets the CGI
+    script error logfile. If no ScriptLog is given, no error log is
+    created. If given, any CGI errors are logged into the filename
+    given as argument. If this is a relative file or path it is taken
     relative to the server root.

 
-    
This log will be opened as the user the child processes run
-    as, ie. the user specified in the main User directive. This means that
+    
+
This log will be opened as the user the child processes run
+    as, ie. the user specified in the main User directive. This means that
     either the directory the script log is in needs to be writable
     by that user or the file needs to be manually created and set
     to be writable by that user. If you place the script log in
@@ -180,52 +275,105 @@
     directory permissions to make it writable by the user the child
     processes run as.

 
-    
Note that script logging is meant to be a debugging feature
+    
+
Note that script logging is meant to be a debugging feature
     when writing CGI scripts, and is not meant to be activated
     continuously on running servers. It is not optimized for speed
     or efficiency, and may have security problems if used in a
     manner other than that for which it was designed.

-    

-
-    
ScriptLogLength directive

-    Syntax: ScriptLogLength
-    bytes

-     Default: 10385760

-     Context: server config

-     Status: mod_cgi 
-
-    
ScriptLogLength can be used to limit the size of
-    the CGI script logfile. Since the logfile logs a lot of
-    information per CGI error (all request headers, all script
-    output) it can grow to be a big file. To prevent problems due
-    to unbounded growth, this directive can be used to set an
-    maximum file-size for the CGI logfile. If the file exceeds this
-    size, no more information will be written to it.

-    

-
-    
ScriptLogBuffer

-    Syntax: ScriptLogBuffer
-    bytes

-     Default: 1024

-     Context: server config

-     Status: mod_cgi 
-
-    
The size of any PUT or POST entity body that is logged to
+
+
+

+

+ScriptLogBuffer Directive
+

+
+
+
+
+

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Description: Maximum amount of PUT or POST requests that will be recorded
+in the scriptlog
Syntax:
+ScriptLogBuffer bytes
+
+
Default:ScriptLogBuffer 1024
Context:server config
Status:Base
Module:mod_cgi, mod_cgid

+

+
+    
+
The size of any PUT or POST entity body that is logged to
     the file is limited, to prevent the log file growing too big
     too quickly if large bodies are being received. By default, up
     to 1024 bytes are logged, but this can be changed with this
-    directive. 
-    

-  
+    directive.

+
+
+

+

+ScriptLogLength Directive
+

+
+
+
+
+

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Description: Size limit of the CGI script logfile
Syntax:
+ScriptLogLength bytes
+
+
Default:ScriptLogLength 10385760
Context:server config
Status:Base
Module:mod_cgi, mod_cgid

+

+
+    
+

+ScriptLogLength can be used to limit the
+    size of the CGI script logfile. Since the logfile logs a lot of
+    information per CGI error (all request headers, all script output)
+    it can grow to be a big file. To prevent problems due to unbounded
+    growth, this directive can be used to set an maximum file-size for
+    the CGI logfile. If the file exceeds this size, no more
+    information will be written to it.

+
+
+

+
Apache HTTP Server Version 2.0

+IndexHome
+
+ - diff --git a/docs/manual/mod/mod_cgi.xml b/docs/manual/mod/mod_cgi.xml new file mode 100644 index 0000000000..4c3ea9c1ef --- /dev/null +++ b/docs/manual/mod/mod_cgi.xml @@ -0,0 +1,202 @@ + + ]> + + + +mod_cgi +Execution of CGI scripts +Base +mod_cgi.c +cgi_module + + + + + + +

Any file that has the mime type + application/x-httpd-cgi or handler + cgi-script (Apache 1.1 or later) will be treated + as a CGI script, and run by the server, with its output being + returned to the client. Files acquire this type either by + having a name containing an extension defined by the + AddType directive, or by being + in a ScriptAlias + directory.

+ +

When the server invokes a CGI script, it will add a variable + called DOCUMENT_ROOT to the environment. This + variable will contain the value of the + DocumentRoot configuration + variable.

+ +

For an introduction to using CGI scripts with Apache, see + our tutorial on Dynamic Content + With CGI.

+ +

When using a multi-threaded MPM under unix, the module + mod_cgid should be used in place of + this module. At the user level, the two modules are essentially + identical.

+ + +Options +ScriptAlias +AddHandler + +
CGI Environment variables +

The server will set the CGI environment variables as described + in the CGI + specification, with the following provisions:

+ +
+
PATH_INFO
+ +
This will not be available if the AcceptPathInfo directive is explicitly set to + off. The default behavior, if AcceptPathInfo is + not given, is that mod_cgi will accept path info (trailing + /more/path/info following the script filename in the URI), while + the core server will return a 404 NOT FOUND error for requests + with additional path info. Omitting the AcceptPathInfo + directive has the same effect as setting it on for + mod_cgi requests.
+ +
REMOTE_HOST
+ +
This will only be set if HostnameLookups is set to on (it + is off by default), and if a reverse DNS lookup of the accessing + host's address indeed finds a host name.
+ +
REMOTE_IDENT
+ +
This will only be set if IdentityCheck is set to + on and the accessing host supports the ident + protocol. Note that the contents of this variable cannot be + relied upon because it can easily be faked, and if there is a + proxy between the client and the server, it is usually + totally useless.
+ +
REMOTE_USER
+ +
This will only be set if the CGI script is subject to + authentication.
+
+
+ +
CGI Debugging +

Debugging CGI scripts has traditionally been difficult, mainly + because it has not been possible to study the output (standard + output and error) for scripts which are failing to run + properly. These directives, included in Apache 1.2 and later, + provide more detailed logging of errors when they occur.

+ +
CGI Logfile Format +

When configured, the CGI error log logs any CGI which does not + execute properly. Each CGI script which fails to operate causes + several lines of information to be logged. The first two lines + are always of the format:

+ + %% [time] request-line
+ %% HTTP-status CGI-script-filename + +

If the error is that CGI script cannot be run, the log file + will contain an extra two lines:

+ + %%error
+ error-message + +

Alternatively, if the error is the result of the script + returning incorrect header information (often due to a bug in + the script), the following information is logged:

+ + %request
+ All HTTP request headers received
+ POST or PUT entity (if any)
+ %response
+ All headers output by the CGI script
+ %stdout
+ CGI standard output
+ %stderr
+ CGI standard error
+ +

(The %stdout and %stderr parts may be missing if the script did + not output anything on standard output or standard error).

+
+
+ + +ScriptLog +Location of the CGI script error logfile +ScriptLog file-path +server config +mod_cgimod_cgid + + + +

The ScriptLog directive sets the CGI + script error logfile. If no ScriptLog is given, no error log is + created. If given, any CGI errors are logged into the filename + given as argument. If this is a relative file or path it is taken + relative to the server root.

+ +

This log will be opened as the user the child processes run + as, ie. the user specified in the main User directive. This means that + either the directory the script log is in needs to be writable + by that user or the file needs to be manually created and set + to be writable by that user. If you place the script log in + your main logs directory, do NOT change the + directory permissions to make it writable by the user the child + processes run as.

+ +

Note that script logging is meant to be a debugging feature + when writing CGI scripts, and is not meant to be activated + continuously on running servers. It is not optimized for speed + or efficiency, and may have security problems if used in a + manner other than that for which it was designed.

+ + + + +ScriptLogLength +Size limit of the CGI script logfile +ScriptLogLength bytes +ScriptLogLength 10385760 +server config +mod_cgimod_cgid + + + +

ScriptLogLength can be used to limit the + size of the CGI script logfile. Since the logfile logs a lot of + information per CGI error (all request headers, all script output) + it can grow to be a big file. To prevent problems due to unbounded + growth, this directive can be used to set an maximum file-size for + the CGI logfile. If the file exceeds this size, no more + information will be written to it.

+ + + + +ScriptLogBuffer +Maximum amount of PUT or POST requests that will be recorded +in the scriptlog +ScriptLogBuffer bytes +ScriptLogBuffer 1024 +server config +mod_cgimod_cgid + + + +

The size of any PUT or POST entity body that is logged to + the file is limited, to prevent the log file growing too big + too quickly if large bodies are being received. By default, up + to 1024 bytes are logged, but this can be changed with this + directive.

+ + + + \ No newline at end of file diff --git a/docs/manual/mod/mod_cgid.html b/docs/manual/mod/mod_cgid.html index ac3c8e4f8f..97e8a9f749 100644 --- a/docs/manual/mod/mod_cgid.html +++ b/docs/manual/mod/mod_cgid.html @@ -1,40 +1,56 @@ - - - - - - - Apache module mod_cgi - - - - - - -

Module mod_cgid

- -

This module provides for execution of CGI scripts using an - external CGI daemon.

- -

Status: Base (unix threaded - MPMs only)
- Source File: mod_cgid.c
- Module Identifier: - cgid_module

- -

Summary

- -

Except for the optimizations and the additional ScriptSock - directive noted below, mod_cgid behaves similarly to mod_cgi. - See the mod_cgi Summary - for additional details about Apache and CGI.

- -

On certain unix operating systems, forking a process from a + + + + +mod_cgid - Apache HTTP Server + + + +

+
+[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

+
+

Apache Module mod_cgid

+ + + + +
+ + + + + + + + + + + + + +
Description: +Execution of CGI scripts using an + external CGI daemon +
Status:Base
Module Identifier:cgid_module
Compatibility: +Unix threaded MPMs only +
+
+

Summary

+ + +

Except for the optimizations and the additional ScriptSock directive noted below, + mod_cgid behaves similarly to mod_cgi. See the + mod_cgi Summary for additional details about + Apache and CGI. +

+ + +

On certain unix operating systems, forking a process from a multi-threaded server is a very expensive operation because the new process will replicate all the threads of the parent process. In order to avoid incurring this expense on each CGI @@ -43,51 +59,77 @@ main server communicates with this daemon using a unix domain socket.

-

This module is used by default whenever a multi-threaded MPM + +

This module is used by default whenever a multi-threaded MPM is selected during the compilation process. At the user level, - this module is identical in configuration and operation to mod_cgi. The only exception is the + this module is identical in configuration and operation to + mod_cgi. The only exception is the additional directive ScriptSock which gives the name of the socket to use for communication with the cgi daemon.

-

Directives

- - -
- -

ScriptSock - directive

- -

Syntax: Scriptsock - filename
- Default: logs/cgisock
- Context: server config
- Status: Base
- Module: mod_cgid

- -

This directive sets the name of the socket to use for +

 +

Directives

+ +
+

+ScriptSock Directive +

+ + + + +
+ + + + + + + + + + + + + + + + + + + +
Description:
Syntax: +ScriptSock file-path + +
Default:ScriptSock logs/cgisock
Context:server config
Status:Base
Module:mod_cgid
+
+ + +

This directive sets the name of the socket to use for communication with the CGI daemon. The socket will be opened using the permissions of the user who starts Apache (usually root). To maintain the security of communications with CGI scripts, it is important that no other user has permission to write in the directory where the socket is located.

- - - + +
+

Apache HTTP Server Version 2.0

+IndexHome +
+ + diff --git a/docs/manual/mod/mod_cgid.xml b/docs/manual/mod/mod_cgid.xml new file mode 100644 index 0000000000..bebea4f7c3 --- /dev/null +++ b/docs/manual/mod/mod_cgid.xml @@ -0,0 +1,68 @@ + + ]> + + + +mod_cgid +Execution of CGI scripts using an + external CGI daemon +Base +mod_cgid.c +cgid_module +Unix threaded MPMs only + + +

Except for the optimizations and the additional ScriptSock directive noted below, + mod_cgid behaves similarly to mod_cgi. See the + mod_cgi Summary for additional details about + Apache and CGI.

+ +

On certain unix operating systems, forking a process from a + multi-threaded server is a very expensive operation because the + new process will replicate all the threads of the parent + process. In order to avoid incurring this expense on each CGI + invocation, mod_cgid creates an external daemon that is + responsible for forking child processes to run CGI scripts. The + main server communicates with this daemon using a unix domain + socket.

+ +

This module is used by default whenever a multi-threaded MPM + is selected during the compilation process. At the user level, + this module is identical in configuration and operation to + mod_cgi. The only exception is the + additional directive ScriptSock which gives the + name of the socket to use for communication with the cgi + daemon.

+ + + +ScriptLog + + + +ScriptLogLength + + + +ScriptLogBuffer + + + +ScriptSock +ScriptSock file-path +ScriptSock logs/cgisock +server config + + +

This directive sets the name of the socket to use for + communication with the CGI daemon. The socket will be opened + using the permissions of the user who starts Apache (usually + root). To maintain the security of communications with CGI + scripts, it is important that no other user has permission to + write in the directory where the socket is located.

+ + + + +