- -
diff --git a/docs/manual/handler.html b/docs/manual/handler.html
deleted file mode 100644
index 80592161123..00000000000
--- a/docs/manual/handler.html
+++ /dev/null
@@ -1,141 +0,0 @@
-
-
-
-Apache's Handler Use
- -What is a Handler
- -A "handler" is an internal Apache representation of the action to be -performed when a file is called. Generally, files have implicit -handlers, based on the file type. Normally, all files are simply -served by the server, but certain file typed are "handled" -separately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.
- -Apache 1.1 adds the additional ability to use handlers -explicitly. Either based on filename extensions or on location, these -handlers are unrelated to file type. This is advantageous both because -it is a more elegant solution, but it also allows for both a type -and a handler to be associated with a file.
- -Handlers can either be built into the server or to a module, or -they can be added with the Action directive. The built-in -handlers in the standard distribution are as follows:
- --
-
- send-as-is: - Send file with HTTP headers as is. - (mod_asis) -
- cgi-script: - Treat the file as a CGI script. - (mod_cgi) -
- imap-file: - Imagemap rule file. - (mod_imap) -
- server-info: - Get the server's configuration information - (mod_info) -
- server-parsed: - Parse for server-side includes - (mod_include) -
- server-status: - Get the server's status report - (mod_status) -
- type-map: - Parse as a type map file for content negotiation - (mod_negotiation) -
- -
Directives
--
-
- AddHandler -
- SetHandler -
- -
AddHandler
- -Syntax: <AddHandler handler-name extension>-Context: server config, virtual host, directory, .htaccess
-Status: Base
-Module: mod_mime - -
AddHandler maps the filename extension extension to the
-handler handler-name. For example, to activate CGI scripts
-with the file extension ".cgi", you might use:
-
- AddHandler cgi-script cgi -- -
Once that has been put into your srm.conf or httpd.conf file, any
-file ending with ".cgi" will be treated as a CGI
-program.
- -
SetHandler
- -Syntax: <SetHandler handler-name>-Context: directory, .htaccess
-Status: Base
-Module: mod_mime - -
When placed into an .htaccess file or a
-<Directory> or <Location> section,
-this directive forces all matching files to be parsed through the
-handler given by handler-name. For example, if you had a
-directory you wanted to be parsed entirely as imagemap rule files,
-regardless of extension, you might put the following into an
-.htaccess file in that directory:
-
- SetHandler imap-file --
Another example: if you wanted to have the server display a status
-report whenever a URL of http://servername/status was
-called, you might put the following into access.conf:
-
- <Location /status> - SetHandler server-status - </Location> -- -
- -
Programmer's Note
- -In order to implement the handler features, an addition has been
-made to the Apache API that you may wish to
-make use of. Specifically, a new record has been added to the
-request_rec structure:
- char *handler --
If you wish to have your module engage a handler, you need only to
-set r->handler to the name of the handler at any time
-prior to the invoke_handler stage of the
-request. Handlers are implemented as they were before, albeit using
-the handler name instead of a content type. While it is not
-necessary, the naming convention for handlers is to use a
-dash-separated word, with no slashes, so as to not invade the media
-type name-space.
Apache's Handler Use
- -What is a Handler
- -A "handler" is an internal Apache representation of the action to be -performed when a file is called. Generally, files have implicit -handlers, based on the file type. Normally, all files are simply -served by the server, but certain file typed are "handled" -separately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.
- -Apache 1.1 adds the additional ability to use handlers -explicitly. Either based on filename extensions or on location, these -handlers are unrelated to file type. This is advantageous both because -it is a more elegant solution, but it also allows for both a type -and a handler to be associated with a file.
- -Handlers can either be built into the server or to a module, or -they can be added with the Action directive. The built-in -handlers in the standard distribution are as follows:
- --
-
- send-as-is: - Send file with HTTP headers as is. - (mod_asis) -
- cgi-script: - Treat the file as a CGI script. - (mod_cgi) -
- imap-file: - Imagemap rule file. - (mod_imap) -
- server-info: - Get the server's configuration information - (mod_info) -
- server-parsed: - Parse for server-side includes - (mod_include) -
- server-status: - Get the server's status report - (mod_status) -
- type-map: - Parse as a type map file for content negotiation - (mod_negotiation) -
- -
Directives
--
-
- AddHandler -
- SetHandler -
- -
AddHandler
- -Syntax: <AddHandler handler-name extension>-Context: server config, virtual host, directory, .htaccess
-Status: Base
-Module: mod_mime - -
AddHandler maps the filename extension extension to the
-handler handler-name. For example, to activate CGI scripts
-with the file extension ".cgi", you might use:
-
- AddHandler cgi-script cgi -- -
Once that has been put into your srm.conf or httpd.conf file, any
-file ending with ".cgi" will be treated as a CGI
-program.
- -
SetHandler
- -Syntax: <SetHandler handler-name>-Context: directory, .htaccess
-Status: Base
-Module: mod_mime - -
When placed into an .htaccess file or a
-<Directory> or <Location> section,
-this directive forces all matching files to be parsed through the
-handler given by handler-name. For example, if you had a
-directory you wanted to be parsed entirely as imagemap rule files,
-regardless of extension, you might put the following into an
-.htaccess file in that directory:
-
- SetHandler imap-file --
Another example: if you wanted to have the server display a status
-report whenever a URL of http://servername/status was
-called, you might put the following into access.conf:
-
- <Location /status> - SetHandler server-status - </Location> -- -
- -
Programmer's Note
- -In order to implement the handler features, an addition has been
-made to the Apache API that you may wish to
-make use of. Specifically, a new record has been added to the
-request_rec structure:
- char *handler --
If you wish to have your module engage a handler, you need only to
-set r->handler to the name of the handler at any time
-prior to the invoke_handler stage of the
-request. Handlers are implemented as they were before, albeit using
-the handler name instead of a content type. While it is not
-necessary, the naming convention for handlers is to use a
-dash-separated word, with no slashes, so as to not invade the media
-type name-space.
![[APACHE DOCUMENTATION]](images/sub.gif)
-Compiling and Installing Apache 1.2
- -If you wish to download and install an earlier version of Apache please -read Compiling and Installing Apache 1.1.
- -UnixWare users will want to consult build notes -for various UnixWare versions before compiling. - -Downloading Apache
- -Information on the latest version of Apache can be found on the Apache -web server at http://www.apache.org/. This will -list the current release, any more recent beta-test release, together -with details of mirror web and anonymous ftp sites. - -- -If you downloaded a binary distribution, skip to Installing Apache. Otherwise read the next section -for how to compile the server. - -
Compiling Apache
- -Compiling Apache consists of three steps: Firstly select which Apache -modules you want to include into the server. Secondly create a -configuration for your operating system. Thirdly compile the -executable. -
-
-All configuration of Apache is performed in the src
-directory of the Apache distribution. Change into this directory.
-
-
-
-
-
- Select modules to compile into Apache in the
-
Configurationfile. Uncomment lines corresponding to - those optional modules you wish to include (among the Module lines - at the bottom of the file), or add new lines corresponding to - additional modules you have downloaded or written. (See API.html for preliminary docs on how to - write Apache modules). Advanced users can comment out some of the - default modules if they are sure they will not need them (be careful - though, since many of the default modules are vital for the correct - operation and security of the server). -- - You should also read the instructions in the
Configuration- file to see if you need to set any of theRulelines. - - - -
- Configure Apache for your operating system. Normally you can just
- type run the
Configurescript as given below. However - if this fails or you have any special requirements (e.g. to include - an additional library required by an optional module) you might need - to edit one or more of the following options in the -Configurationfile: -EXTRA_CFLAGS, LIBS, LFLAGS, INCLUDES. -- - Run the
Configurescript: --
- - (*: Depending on Configuration and your system, Configure - make not print these lines. That's OK).- % Configure - Using 'Configuration' as config file - + configured for <whatever> platform - + setting C compiler to <whatever> * - + setting C compiler optimization-level to <whatever> * - % -
-- - This generates a Makefile for use in stage 3. It also creates a - Makefile in the support directory, for compilation of the optional - support programs. -
- - (If you want to maintain multiple configurations, you can give a - option to
Configureto tell it to read an alternative - Configuration file, such asConfigure -file - Configuration.ai). -- -
-
- Type
make. -
Installing Apache
- -You will have a binary file calledhttpd in the
-src directory. A binary distribution of Apache will
-supply this file.
-
-The next step is to install the program and configure it. Apache is
-designed to be configured and run from the same set of directories
-where it is compiled. If you want to run it from somewhere else, make
-a directory and copy the conf, logs and
-icons directories into it.
-
-The next step is to edit the configuration files for the server. This
-consists of setting up various directives in up to three
-central configuration files. By default, these files are located in
-the conf directory and are called srm.conf,
-access.conf and httpd.conf. To help you get
-started there are same files in the conf directory of the
-distribution, called srm.conf-dist,
-access.conf-dist and httpd.conf-dist. Copy
-or rename these files to the names without the -dist.
-Then edit each of the files. Read the comments in each file carefully.
-Failure to setup these files correctly could lead to your server not
-working or being insecure. You should also have an additional file in
-the conf directory called mime.types. This
-file usually does not need editing.
-
-
-
-First edit httpd.conf. This sets up general attributes
-about the server: the port number, the user it runs as, etc. Next
-edit the srm.conf file; this sets up the root of the
-document tree, special functions like server-parsed HTML or internal
-imagemap parsing, etc. Finally, edit the access.conf
-file to at least set the base cases of access.
-
-
-
-In addition to these three files, the server behavior can be configured
-on a directory-by-directory basis by using .htaccess
-files in directories accessed by the server.
-
-
Starting and Stopping the Server
- -To start the server, simply runhttpd. This will look for
-httpd.conf in the location compiled into the code (by
-default /usr/locale/etc/httpd/conf/httpd.conf). If
-this file is somewhere else, you can give the real
-location with the -f argument. For example:
-
-- /usr/local/etc/apache/src/httpd -f /usr/local/etc/apache/conf/httpd.conf -- -If all goes well this will return to the command prompt almost -immediately. This indicates that the server is now up and running. If -anything goes wrong during the initialization of the server you will -see an error message on the screen. - -If the server started ok, you can now use your browser to -connect to the server and read the documentation. If you are running -the browser on the same machine as the server and using the default -port of 80, a suitable URL to enter into your browser is - -
- http://localhost/ -- -
- -Note that when the server starts it will create a number of -child processes to handle the requests. If you started Apache -as the root user, the parent process will continue to run as root -while the children will change to the user as given in the httpd.conf -file. - -
-
-If when you run httpd it complained about being unable to
-"bind" to an address, then either some other process is already using
-the port you have configured Apache to use, or you are running httpd
-as a normal user but trying to use port below 1024 (such as the
-default port 80).
-
-
-
-If the server is not running, read the error message displayed
-when you run httpd. You should also check the server
-error_log for additional information (with the default configuration,
-this will be located in the file error_log in the
-logs directory).
-
-
-
-If you want your server to continue running after a system reboot, you
-should add a call to httpd to your system startup files
-(typically rc.local or a file in an
-rc.N directory). This will start Apache as root.
-Before doing this ensure that your server is properly configured
-for security and access restrictions.
-
-
-
-To stop Apache send the parent process a TERM signal. The PID of this
-process is written to the file httpd.pid in the
-logs directory (unless configured otherwise). Do not
-attempt to kill the child processes because they will be renewed by
-the parent. A typical command to stop the server is:
-
-
- kill -TERM `cat /usr/local/etc/apache/logs/httpd.pid` -- -
- -For more information about Apache command line options, configuration -and log files, see Starting Apache. For a -reference guide to all Apache directives supported by the distributed -modules, see the Apache directives. - -
Compiling Support Programs
- -In addition to the mainhttpd server which is compiled
-and configured as above, Apache includes a number of support programs.
-These are not compiled by default. The support programs are in the
-support directory of the distribution. To compile
-the support programs, change into this directory and type
-- make -- - - - diff --git a/docs/manual/install.html.en b/docs/manual/install.html.en deleted file mode 100644 index 52e84b0c54a..00000000000 --- a/docs/manual/install.html.en +++ /dev/null @@ -1,249 +0,0 @@ - - - -
Compiling and Installing Apache 1.2
- -If you wish to download and install an earlier version of Apache please -read Compiling and Installing Apache 1.1.
- -UnixWare users will want to consult build notes -for various UnixWare versions before compiling. - -Downloading Apache
- -Information on the latest version of Apache can be found on the Apache -web server at http://www.apache.org/. This will -list the current release, any more recent beta-test release, together -with details of mirror web and anonymous ftp sites. - -- -If you downloaded a binary distribution, skip to Installing Apache. Otherwise read the next section -for how to compile the server. - -
Compiling Apache
- -Compiling Apache consists of three steps: Firstly select which Apache -modules you want to include into the server. Secondly create a -configuration for your operating system. Thirdly compile the -executable. -
-
-All configuration of Apache is performed in the src
-directory of the Apache distribution. Change into this directory.
-
-
-
-
-
- Select modules to compile into Apache in the
-
Configurationfile. Uncomment lines corresponding to - those optional modules you wish to include (among the Module lines - at the bottom of the file), or add new lines corresponding to - additional modules you have downloaded or written. (See API.html for preliminary docs on how to - write Apache modules). Advanced users can comment out some of the - default modules if they are sure they will not need them (be careful - though, since many of the default modules are vital for the correct - operation and security of the server). -- - You should also read the instructions in the
Configuration- file to see if you need to set any of theRulelines. - - - -
- Configure Apache for your operating system. Normally you can just
- type run the
Configurescript as given below. However - if this fails or you have any special requirements (e.g. to include - an additional library required by an optional module) you might need - to edit one or more of the following options in the -Configurationfile: -EXTRA_CFLAGS, LIBS, LFLAGS, INCLUDES. -- - Run the
Configurescript: --
- - (*: Depending on Configuration and your system, Configure - make not print these lines. That's OK).- % Configure - Using 'Configuration' as config file - + configured for <whatever> platform - + setting C compiler to <whatever> * - + setting C compiler optimization-level to <whatever> * - % -
-- - This generates a Makefile for use in stage 3. It also creates a - Makefile in the support directory, for compilation of the optional - support programs. -
- - (If you want to maintain multiple configurations, you can give a - option to
Configureto tell it to read an alternative - Configuration file, such asConfigure -file - Configuration.ai). -- -
-
- Type
make. -
Installing Apache
- -You will have a binary file calledhttpd in the
-src directory. A binary distribution of Apache will
-supply this file.
-
-The next step is to install the program and configure it. Apache is
-designed to be configured and run from the same set of directories
-where it is compiled. If you want to run it from somewhere else, make
-a directory and copy the conf, logs and
-icons directories into it.
-
-The next step is to edit the configuration files for the server. This
-consists of setting up various directives in up to three
-central configuration files. By default, these files are located in
-the conf directory and are called srm.conf,
-access.conf and httpd.conf. To help you get
-started there are same files in the conf directory of the
-distribution, called srm.conf-dist,
-access.conf-dist and httpd.conf-dist. Copy
-or rename these files to the names without the -dist.
-Then edit each of the files. Read the comments in each file carefully.
-Failure to setup these files correctly could lead to your server not
-working or being insecure. You should also have an additional file in
-the conf directory called mime.types. This
-file usually does not need editing.
-
-
-
-First edit httpd.conf. This sets up general attributes
-about the server: the port number, the user it runs as, etc. Next
-edit the srm.conf file; this sets up the root of the
-document tree, special functions like server-parsed HTML or internal
-imagemap parsing, etc. Finally, edit the access.conf
-file to at least set the base cases of access.
-
-
-
-In addition to these three files, the server behavior can be configured
-on a directory-by-directory basis by using .htaccess
-files in directories accessed by the server.
-
-
Starting and Stopping the Server
- -To start the server, simply runhttpd. This will look for
-httpd.conf in the location compiled into the code (by
-default /usr/locale/etc/httpd/conf/httpd.conf). If
-this file is somewhere else, you can give the real
-location with the -f argument. For example:
-
-- /usr/local/etc/apache/src/httpd -f /usr/local/etc/apache/conf/httpd.conf -- -If all goes well this will return to the command prompt almost -immediately. This indicates that the server is now up and running. If -anything goes wrong during the initialization of the server you will -see an error message on the screen. - -If the server started ok, you can now use your browser to -connect to the server and read the documentation. If you are running -the browser on the same machine as the server and using the default -port of 80, a suitable URL to enter into your browser is - -
- http://localhost/ -- -
- -Note that when the server starts it will create a number of -child processes to handle the requests. If you started Apache -as the root user, the parent process will continue to run as root -while the children will change to the user as given in the httpd.conf -file. - -
-
-If when you run httpd it complained about being unable to
-"bind" to an address, then either some other process is already using
-the port you have configured Apache to use, or you are running httpd
-as a normal user but trying to use port below 1024 (such as the
-default port 80).
-
-
-
-If the server is not running, read the error message displayed
-when you run httpd. You should also check the server
-error_log for additional information (with the default configuration,
-this will be located in the file error_log in the
-logs directory).
-
-
-
-If you want your server to continue running after a system reboot, you
-should add a call to httpd to your system startup files
-(typically rc.local or a file in an
-rc.N directory). This will start Apache as root.
-Before doing this ensure that your server is properly configured
-for security and access restrictions.
-
-
-
-To stop Apache send the parent process a TERM signal. The PID of this
-process is written to the file httpd.pid in the
-logs directory (unless configured otherwise). Do not
-attempt to kill the child processes because they will be renewed by
-the parent. A typical command to stop the server is:
-
-
- kill -TERM `cat /usr/local/etc/apache/logs/httpd.pid` -- -
- -For more information about Apache command line options, configuration -and log files, see Starting Apache. For a -reference guide to all Apache directives supported by the distributed -modules, see the Apache directives. - -
Compiling Support Programs
- -In addition to the mainhttpd server which is compiled
-and configured as above, Apache includes a number of support programs.
-These are not compiled by default. The support programs are in the
-support directory of the distribution. To compile
-the support programs, change into this directory and type
-- make -- - - - diff --git a/docs/manual/invoking.html b/docs/manual/invoking.html deleted file mode 100644 index 62e6a41af9a..00000000000 --- a/docs/manual/invoking.html +++ /dev/null @@ -1,124 +0,0 @@ - - - -
Starting Apache
- -Invoking Apache
-Thehttpd program is usually run as a daemon which executes
-continuously, handling requests. It is possible to invoke Apache by
-the Internet daemon inetd each time a connection to the HTTP
-service is made (use the
-ServerType directive)
-but this is not recommended.
-
-Command line options
-The following options are recognized on the httpd command line: --
-
-dserverroot -- Set the initial value for the
-ServerRoot variable to
-serverroot. This can be overridden by the ServerRoot command in the
-configuration file. The default is
/usr/local/etc/httpd. - - -fconfig -- Execute the commands in the file config on startup. If
-config does not begin with a
/, then it is taken to be a -path relative to the ServerRoot. The -default isconf/httpd.conf. - - -X-- Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do NOT -use this mode to provide ordinary web service. - -
-v-- Print the version of httpd, and then exit. - -
-h-- Give a list of directives together with expected arguments and -places where the directive is valid. (New in Apache 1.2) - -
-l-- Give a list of all modules compiled into the server. - -
-?-- Print a list of the httpd options, and then exit. -
Configuration files
-The server will read three files for configuration directives. Any directive -may appear in any of these files. The the names of these files are taken -to be relative to the server root; this is set by the -ServerRoot directive, or the --d command line flag.
-
-Conventionally, the files are:
--
-
conf/httpd.conf-- Contains directives that control the operation of the server daemon.
-The filename may be overridden with the
-fcommand line flag. - - conf/srm.conf-- Contains directives that control the specification of documents that -the server can provide to clients. The filename may be overridden with -the ResourceConfig directive. - -
conf/access.conf-- Contains directives that control access to documents. -The filename may be overridden with the -AccessConfig directive. -
-The server also reads a file containing mime document types; the filename
-is set by the TypesConfig directive,
-and is conf/mime.types by default.
-
-
Log files
-security warning
-Anyone who can write to the directory where Apache is writing a -log file can almost certainly gain access to the uid that the server is -started as, which is normally root. Do NOT give people write -access to the directory the logs are stored in without being aware of -the consequences; see the security tips -document for details. -pid file
-On daemon startup, it saves the process id of the parent httpd process to -the filelogs/httpd.pid. This filename can be changed with the
-PidFile directive. The process-id is for
-use by the administrator in restarting and terminating the daemon;
-A HUP or USR1 signal causes the daemon to re-read its configuration files and
-a TERM signal causes it to die gracefully. For more information
-see the Stopping and Restarting page.
--If the process dies (or is killed) abnormally, then it will be necessary to -kill the children httpd processes. - -
Error log
-The server will log error messages to a log file,logs/error_log
-by default. The filename can be set using the
-ErrorLog directive; different error logs can
-be set for different virtual hosts.
-
-Transfer log
-The server will typically log each request to a transfer file, -logs/access_log by default. The filename can be set using a
-TransferLog directive; different
-transfer logs can be set for different virtual
-hosts.
-
-
-
-
diff --git a/docs/manual/invoking.html.en b/docs/manual/invoking.html.en
deleted file mode 100644
index 62e6a41af9a..00000000000
--- a/docs/manual/invoking.html.en
+++ /dev/null
@@ -1,124 +0,0 @@
-
-
-
-Starting Apache
- -Invoking Apache
-Thehttpd program is usually run as a daemon which executes
-continuously, handling requests. It is possible to invoke Apache by
-the Internet daemon inetd each time a connection to the HTTP
-service is made (use the
-ServerType directive)
-but this is not recommended.
-
-Command line options
-The following options are recognized on the httpd command line: --
-
-dserverroot -- Set the initial value for the
-ServerRoot variable to
-serverroot. This can be overridden by the ServerRoot command in the
-configuration file. The default is
/usr/local/etc/httpd. - - -fconfig -- Execute the commands in the file config on startup. If
-config does not begin with a
/, then it is taken to be a -path relative to the ServerRoot. The -default isconf/httpd.conf. - - -X-- Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do NOT -use this mode to provide ordinary web service. - -
-v-- Print the version of httpd, and then exit. - -
-h-- Give a list of directives together with expected arguments and -places where the directive is valid. (New in Apache 1.2) - -
-l-- Give a list of all modules compiled into the server. - -
-?-- Print a list of the httpd options, and then exit. -
Configuration files
-The server will read three files for configuration directives. Any directive -may appear in any of these files. The the names of these files are taken -to be relative to the server root; this is set by the -ServerRoot directive, or the --d command line flag.
-
-Conventionally, the files are:
--
-
conf/httpd.conf-- Contains directives that control the operation of the server daemon.
-The filename may be overridden with the
-fcommand line flag. - - conf/srm.conf-- Contains directives that control the specification of documents that -the server can provide to clients. The filename may be overridden with -the ResourceConfig directive. - -
conf/access.conf-- Contains directives that control access to documents. -The filename may be overridden with the -AccessConfig directive. -
-The server also reads a file containing mime document types; the filename
-is set by the TypesConfig directive,
-and is conf/mime.types by default.
-
-
Log files
-security warning
-Anyone who can write to the directory where Apache is writing a -log file can almost certainly gain access to the uid that the server is -started as, which is normally root. Do NOT give people write -access to the directory the logs are stored in without being aware of -the consequences; see the security tips -document for details. -pid file
-On daemon startup, it saves the process id of the parent httpd process to -the filelogs/httpd.pid. This filename can be changed with the
-PidFile directive. The process-id is for
-use by the administrator in restarting and terminating the daemon;
-A HUP or USR1 signal causes the daemon to re-read its configuration files and
-a TERM signal causes it to die gracefully. For more information
-see the Stopping and Restarting page.
--If the process dies (or is killed) abnormally, then it will be necessary to -kill the children httpd processes. - -
Error log
-The server will log error messages to a log file,logs/error_log
-by default. The filename can be set using the
-ErrorLog directive; different error logs can
-be set for different virtual hosts.
-
-Transfer log
-The server will typically log each request to a transfer file, -logs/access_log by default. The filename can be set using a
-TransferLog directive; different
-transfer logs can be set for different virtual
-hosts.
-
-
-
-
diff --git a/docs/manual/location.html b/docs/manual/location.html
deleted file mode 100644
index 96ab3a85447..00000000000
--- a/docs/manual/location.html
+++ /dev/null
@@ -1,59 +0,0 @@
-
-
-
-Access Control by URL
- -The <Location> Directive
-
-Syntax: <Location URL prefix>-Context: server config, virtual host
-Status: core
- -
The <Location> directive provides for access control by
-URL. It is comparable to the <Directory> directive, and
-should be matched with a </Location> directive. Directives that
-apply to the URL given should be listen
-within. <Location> sections are processed in the
-order they appear in the configuration file, after the
-<Directory> sections and .htaccess files are
-read.
Note that, due to the way HTTP functions, URL prefix
-should, save for proxy requests, be of the form /path/,
-and should not include the http://servername. It doesn't
-necessarily have to protect a directory (it can be an individual
-file, or a number of files), and can include wild-cards. In a wild-card
-string, `?' matches any single character, and `*' matches any
-sequences of characters.
-
-
This functionality is especially useful when combined with the
-SetHandler
-directive. For example, to enable status requests, but allow them only
-from browsers at foo.com, you might use:
-
-
- <Location /status> - SetHandler server-status - order deny,allow - deny from all - allow from .foo.com - </Location> -- - - - - diff --git a/docs/manual/misc/API.html b/docs/manual/misc/API.html deleted file mode 100644 index ad539e2abbb..00000000000 --- a/docs/manual/misc/API.html +++ /dev/null @@ -1,1004 +0,0 @@ - - -
Apache API notes
- -These are some notes on the Apache API and the data structures you -have to deal with, etc. They are not yet nearly complete, but -hopefully, they will help you get your bearings. Keep in mind that -the API is still subject to change as we gain experience with it. -(See the TODO file for what might be coming). However, -it will be easy to adapt modules to any changes that are made. -(We have more modules to adapt than you do). -- -A few notes on general pedagogical style here. In the interest of -conciseness, all structure declarations here are incomplete --- the -real ones have more slots that I'm not telling you about. For the -most part, these are reserved to one component of the server core or -another, and should be altered by modules with caution. However, in -some cases, they really are things I just haven't gotten around to -yet. Welcome to the bleeding edge.
- -Finally, here's an outline, to give you some bare idea of what's -coming up, and in what order: - -
-
-
- Basic concepts. - -
- How handlers work - -
- Resource allocation and resource pools -
- Configuration, commands and the like - -
Basic concepts.
- -We begin with an overview of the basic concepts behind the -API, and how they are manifested in the code. - -Handlers, Modules, and Requests
- -Apache breaks down request handling into a series of steps, more or -less the same way the Netscape server API does (although this API has -a few more stages than NetSite does, as hooks for stuff I thought -might be useful in the future). These are: - --
-
- URI -> Filename translation -
- Auth ID checking [is the user who they say they are?] -
- Auth access checking [is the user authorized here?] -
- Access checking other than auth -
- Determining MIME type of the object requested -
- `Fixups' --- there aren't any of these yet, but the phase is
- intended as a hook for possible extensions like
-
SetEnv, which don't really fit well elsewhere. - - Actually sending a response back to the client. -
- Logging the request -
-
-
- Handle the request, and indicate that it has done so
- by returning the magic constant
OK. - - Decline to handle the request, by returning the magic
- integer constant
DECLINED. In this case, the - server behaves in all respects as if the handler simply hadn't - been there. - - Signal an error, by returning one of the HTTP error codes. - This terminates normal handling of the request, although an - ErrorDocument may be invoked to try to mop up, and it will be - logged in any case. -
*/* (i.e., a
-wildcard MIME type specification). However, wildcard handlers are
-only invoked if the server has already tried and failed to find a more
-specific response handler for the MIME type of the requested object
-(either none existed, or they all declined).
-
-The handlers themselves are functions of one argument (a
-request_rec structure. vide infra), which returns an
-integer, as above.
- -
A brief tour of a module
- -At this point, we need to explain the structure of a module. Our -candidate will be one of the messier ones, the CGI module --- this -handles both CGI scripts and theScriptAlias config file
-command. It's actually a great deal more complicated than most
-modules, but if we're going to have only one example, it might as well
-be the one with its fingers in every place.
-
-Let's begin with handlers. In order to handle the CGI scripts, the
-module declares a response handler for them. Because of
-ScriptAlias, it also has handlers for the name
-translation phase (to recognize ScriptAliased URIs), the
-type-checking phase (any ScriptAliased request is typed
-as a CGI script).
-
-The module needs to maintain some per (virtual)
-server information, namely, the ScriptAliases in effect;
-the module structure therefore contains pointers to a functions which
-builds these structures, and to another which combines two of them (in
-case the main server and a virtual server both have
-ScriptAliases declared).
-
-Finally, this module contains code to handle the
-ScriptAlias command itself. This particular module only
-declares one command, but there could be more, so modules have
-command tables which declare their commands, and describe
-where they are permitted, and how they are to be invoked.
-
-A final note on the declared types of the arguments of some of these
-commands: a pool is a pointer to a resource pool
-structure; these are used by the server to keep track of the memory
-which has been allocated, files opened, etc., either to service a
-particular request, or to handle the process of configuring itself.
-That way, when the request is over (or, for the configuration pool,
-when the server is restarting), the memory can be freed, and the files
-closed, en masse, without anyone having to write explicit code to
-track them all down and dispose of them. Also, a
-cmd_parms structure contains various information about
-the config file being read, and other status information, which is
-sometimes of use to the function which processes a config-file command
-(such as ScriptAlias).
-
-With no further ado, the module itself:
-
-
-/* Declarations of handlers. */
-
-int translate_scriptalias (request_rec *);
-int type_scriptalias (request_rec *);
-int cgi_handler (request_rec *);
-
-/* Subsidiary dispatch table for response-phase handlers, by MIME type */
-
-handler_rec cgi_handlers[] = {
-{ "application/x-httpd-cgi", cgi_handler },
-{ NULL }
-};
-
-/* Declarations of routines to manipulate the module's configuration
- * info. Note that these are returned, and passed in, as void *'s;
- * the server core keeps track of them, but it doesn't, and can't,
- * know their internal structure.
- */
-
-void *make_cgi_server_config (pool *);
-void *merge_cgi_server_config (pool *, void *, void *);
-
-/* Declarations of routines to handle config-file commands */
-
-extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
- char *real);
-
-command_rec cgi_cmds[] = {
-{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
- "a fakename and a realname"},
-{ NULL }
-};
-
-module cgi_module = {
- STANDARD_MODULE_STUFF,
- NULL, /* initializer */
- NULL, /* dir config creator */
- NULL, /* dir merger --- default is to override */
- make_cgi_server_config, /* server config */
- merge_cgi_server_config, /* merge server config */
- cgi_cmds, /* command table */
- cgi_handlers, /* handlers */
- translate_scriptalias, /* filename translation */
- NULL, /* check_user_id */
- NULL, /* check auth */
- NULL, /* check access */
- type_scriptalias, /* type_checker */
- NULL, /* fixups */
- NULL, /* logger */
- NULL /* header parser */
-};
-
-
-How handlers work
- -The sole argument to handlers is arequest_rec structure.
-This structure describes a particular request which has been made to
-the server, on behalf of a client. In most cases, each connection to
-the client generates only one request_rec structure.- -
A brief tour of the request_rec
-
-The request_rec contains pointers to a resource pool
-which will be cleared when the server is finished handling the
-request; to structures containing per-server and per-connection
-information, and most importantly, information on the request itself.- -The most important such information is a small set of character -strings describing attributes of the object being requested, including -its URI, filename, content-type and content-encoding (these being filled -in by the translation and type-check handlers which handle the -request, respectively).
-
-Other commonly used data items are tables giving the MIME headers on
-the client's original request, MIME headers to be sent back with the
-response (which modules can add to at will), and environment variables
-for any subprocesses which are spawned off in the course of servicing
-the request. These tables are manipulated using the
-table_get and table_set routines.
-
- Note that the Content-type header value cannot be - set by module content-handlers using the table_*() - routines. Rather, it is set by pointing the content_type - field in the request_rec structure to an appropriate - string. E.g., --Finally, there are pointers to two data structures which, in turn, -point to per-module configuration structures. Specifically, these -hold pointers to the data structures which the module has built to -describe the way it has been configured to operate in a given -directory (via- r->content_type = "text/html"; --
.htaccess files or
-<Directory> sections), for private data it has
-built in the course of servicing the request (so modules' handlers for
-one phase can pass `notes' to their handlers for other phases). There
-is another such configuration vector in the server_rec
-data structure pointed to by the request_rec, which
-contains per (virtual) server configuration data.- -Here is an abridged declaration, giving the fields most commonly used:
- -
-struct request_rec {
-
- pool *pool;
- conn_rec *connection;
- server_rec *server;
-
- /* What object is being requested */
-
- char *uri;
- char *filename;
- char *path_info;
- char *args; /* QUERY_ARGS, if any */
- struct stat finfo; /* Set by server core;
- * st_mode set to zero if no such file */
-
- char *content_type;
- char *content_encoding;
-
- /* MIME header environments, in and out. Also, an array containing
- * environment variables to be passed to subprocesses, so people can
- * write modules to add to that environment.
- *
- * The difference between headers_out and err_headers_out is that
- * the latter are printed even on error, and persist across internal
- * redirects (so the headers printed for ErrorDocument handlers will
- * have them).
- */
-
- table *headers_in;
- table *headers_out;
- table *err_headers_out;
- table *subprocess_env;
-
- /* Info about the request itself... */
-
- int header_only; /* HEAD request, as opposed to GET */
- char *protocol; /* Protocol, as given to us, or HTTP/0.9 */
- char *method; /* GET, HEAD, POST, etc. */
- int method_number; /* M_GET, M_POST, etc. */
-
- /* Info for logging */
-
- char *the_request;
- int bytes_sent;
-
- /* A flag which modules can set, to indicate that the data being
- * returned is volatile, and clients should be told not to cache it.
- */
-
- int no_cache;
-
- /* Various other config info which may change with .htaccess files
- * These are config vectors, with one void* pointer for each module
- * (the thing pointed to being the module's business).
- */
-
- void *per_dir_config; /* Options set in config files, etc. */
- void *request_config; /* Notes on *this* request */
-
-};
-
-
-
-Where request_rec structures come from
- -Mostrequest_rec structures are built by reading an HTTP
-request from a client, and filling in the fields. However, there are
-a few exceptions:
-
--
-
- If the request is to an imagemap, a type map (i.e., a
-
*.varfile), or a CGI script which returned a - local `Location:', then the resource which the user requested - is going to be ultimately located by some URI other than what - the client originally supplied. In this case, the server does - an internal redirect, constructing a new -request_recfor the new URI, and processing it - almost exactly as if the client had requested the new URI - directly.- -
- If some handler signaled an error, and an
-
ErrorDocumentis in scope, the same internal - redirect machinery comes into play.- -
- Finally, a handler occasionally needs to investigate `what
- would happen if' some other request were run. For instance,
- the directory indexing module needs to know what MIME type
- would be assigned to a request for each directory entry, in
- order to figure out what icon to use.
- - Such handlers can construct a sub-request, using the - functions
sub_req_lookup_fileand -sub_req_lookup_uri; this constructs a new -request_recstructure and processes it as you - would expect, up to but not including the point of actually - sending a response. (These functions skip over the access - checks if the sub-request is for a file in the same directory - as the original request).- - (Server-side includes work by building sub-requests and then - actually invoking the response handler for them, via the - function
run_sub_request). -
Handling requests, declining, and returning error codes
- -As discussed above, each handler, when invoked to handle a particular -request_rec, has to return an int to
-indicate what happened. That can either be
-
--
-
- OK --- the request was handled successfully. This may or may - not terminate the phase. -
- DECLINED --- no erroneous condition exists, but the module - declines to handle the phase; the server tries to find another. -
- an HTTP error code, which aborts handling of the request. -
REDIRECT, then
-the module should put a Location in the request's
-headers_out, to indicate where the client should be
-redirected to. - -
Special considerations for response handlers
- -Handlers for most phases do their work by simply setting a few fields -in therequest_rec structure (or, in the case of access
-checkers, simply by returning the correct error code). However,
-response handlers have to actually send a request back to the client.
-
-They should begin by sending an HTTP response header, using the
-function send_http_header. (You don't have to do
-anything special to skip sending the header for HTTP/0.9 requests; the
-function figures out on its own that it shouldn't do anything). If
-the request is marked header_only, that's all they should
-do; they should return after that, without attempting any further
-output.
-
-Otherwise, they should produce a request body which responds to the
-client as appropriate. The primitives for this are rputc
-and rprintf, for internally generated output, and
-send_fd, to copy the contents of some FILE *
-straight to the client.
-
-At this point, you should more or less understand the following piece
-of code, which is the handler which handles GET requests
-which have no more specific handler; it also shows how conditional
-GETs can be handled, if it's desirable to do so in a
-particular response handler --- set_last_modified checks
-against the If-modified-since value supplied by the
-client, if any, and returns an appropriate code (which will, if
-nonzero, be USE_LOCAL_COPY). No similar considerations apply for
-set_content_length, but it returns an error code for
-symmetry.
- -
-int default_handler (request_rec *r)
-{
- int errstatus;
- FILE *f;
-
- if (r->method_number != M_GET) return DECLINED;
- if (r->finfo.st_mode == 0) return NOT_FOUND;
-
- if ((errstatus = set_content_length (r, r->finfo.st_size))
- || (errstatus = set_last_modified (r, r->finfo.st_mtime)))
- return errstatus;
-
- f = fopen (r->filename, "r");
-
- if (f == NULL) {
- log_reason("file permissions deny server access",
- r->filename, r);
- return FORBIDDEN;
- }
-
- register_timeout ("send", r);
- send_http_header (r);
-
- if (!r->header_only) send_fd (f, r);
- pfclose (r->pool, f);
- return OK;
-}
-
-
-Finally, if all of this is too much of a challenge, there are a few
-ways out of it. First off, as shown above, a response handler which
-has not yet produced any output can simply return an error code, in
-which case the server will automatically produce an error response.
-Secondly, it can punt to some other handler by invoking
-internal_redirect, which is how the internal redirection
-machinery discussed above is invoked. A response handler which has
-internally redirected should always return OK.
-
-(Invoking internal_redirect from handlers which are
-not response handlers will lead to serious confusion).
-
-
Special considerations for authentication handlers
- -Stuff that should be discussed here in detail: - --
-
- Authentication-phase handlers not invoked unless auth is - configured for the directory. -
- Common auth configuration stored in the core per-dir
- configuration; it has accessors
auth_type, -auth_name, andrequires. - - Common routines, to handle the protocol end of things, at least
- for HTTP basic authentication (
get_basic_auth_pw, - which sets theconnection->userstructure field - automatically, andnote_basic_auth_failure, which - arranges for the properWWW-Authenticate:header - to be sent back). -
Special considerations for logging handlers
- -When a request has internally redirected, there is the question of -what to log. Apache handles this by bundling the entire chain of -redirects into a list ofrequest_rec structures which are
-threaded through the r->prev and r->next
-pointers. The request_rec which is passed to the logging
-handlers in such cases is the one which was originally built for the
-initial request from the client; note that the bytes_sent field will
-only be correct in the last request in the chain (the one for which a
-response was actually sent).
-
-Resource allocation and resource pools
- -One of the problems of writing and designing a server-pool server is -that of preventing leakage, that is, allocating resources (memory, -open files, etc.), without subsequently releasing them. The resource -pool machinery is designed to make it easy to prevent this from -happening, by allowing resource to be allocated in such a way that -they are automatically released when the server is done with -them.- -The way this works is as follows: the memory which is allocated, file -opened, etc., to deal with a particular request are tied to a -resource pool which is allocated for the request. The pool -is a data structure which itself tracks the resources in question.
- -When the request has been processed, the pool is cleared. At -that point, all the memory associated with it is released for reuse, -all files associated with it are closed, and any other clean-up -functions which are associated with the pool are run. When this is -over, we can be confident that all the resource tied to the pool have -been released, and that none of them have leaked.
- -Server restarts, and allocation of memory and resources for per-server -configuration, are handled in a similar way. There is a -configuration pool, which keeps track of resources which were -allocated while reading the server configuration files, and handling -the commands therein (for instance, the memory that was allocated for -per-server module configuration, log files and other files that were -opened, and so forth). When the server restarts, and has to reread -the configuration files, the configuration pool is cleared, and so the -memory and file descriptors which were taken up by reading them the -last time are made available for reuse.
-
-It should be noted that use of the pool machinery isn't generally
-obligatory, except for situations like logging handlers, where you
-really need to register cleanups to make sure that the log file gets
-closed when the server restarts (this is most easily done by using the
-function pfopen, which also
-arranges for the underlying file descriptor to be closed before any
-child processes, such as for CGI scripts, are execed), or
-in case you are using the timeout machinery (which isn't yet even
-documented here). However, there are two benefits to using it:
-resources allocated to a pool never leak (even if you allocate a
-scratch string, and just forget about it); also, for memory
-allocation, palloc is generally faster than
-malloc.
- -We begin here by describing how memory is allocated to pools, and then -discuss how other resources are tracked by the resource pool -machinery. - -
Allocation of memory in pools
- -Memory is allocated to pools by calling the function -palloc, which takes two arguments, one being a pointer to
-a resource pool structure, and the other being the amount of memory to
-allocate (in chars). Within handlers for handling
-requests, the most common way of getting a resource pool structure is
-by looking at the pool slot of the relevant
-request_rec; hence the repeated appearance of the
-following idiom in module code:
-
-
-int my_handler(request_rec *r)
-{
- struct my_structure *foo;
- ...
-
- foo = (foo *)palloc (r->pool, sizeof(my_structure));
-}
-
-
-Note that there is no pfree ---
-palloced memory is freed only when the associated
-resource pool is cleared. This means that palloc does not
-have to do as much accounting as malloc(); all it does in
-the typical case is to round up the size, bump a pointer, and do a
-range check.
-
-(It also raises the possibility that heavy use of palloc
-could cause a server process to grow excessively large. There are
-two ways to deal with this, which are dealt with below; briefly, you
-can use malloc, and try to be sure that all of the memory
-gets explicitly freed, or you can allocate a sub-pool of
-the main pool, allocate your memory in the sub-pool, and clear it out
-periodically. The latter technique is discussed in the section on
-sub-pools below, and is used in the directory-indexing code, in order
-to avoid excessive storage allocation when listing directories with
-thousands of files).
-
-
Allocating initialized memory
- -There are functions which allocate initialized memory, and are -frequently useful. The functionpcalloc has the same
-interface as palloc, but clears out the memory it
-allocates before it returns it. The function pstrdup
-takes a resource pool and a char * as arguments, and
-allocates memory for a copy of the string the pointer points to,
-returning a pointer to the copy. Finally pstrcat is a
-varargs-style function, which takes a pointer to a resource pool, and
-at least two char * arguments, the last of which must be
-NULL. It allocates enough memory to fit copies of each
-of the strings, as a unit; for instance:
-
-- pstrcat (r->pool, "foo", "/", "bar", NULL); -- -returns a pointer to 8 bytes worth of memory, initialized to -
"foo/bar".
-
-Tracking open files, etc.
- -As indicated above, resource pools are also used to track other sorts -of resources besides memory. The most common are open files. The -routine which is typically used for this ispfopen, which
-takes a resource pool and two strings as arguments; the strings are
-the same as the typical arguments to fopen, e.g.,
-
-
- ...
- FILE *f = pfopen (r->pool, r->filename, "r");
-
- if (f == NULL) { ... } else { ... }
-
-
-There is also a popenf routine, which parallels the
-lower-level open system call. Both of these routines
-arrange for the file to be closed when the resource pool in question
-is cleared.
-
-Unlike the case for memory, there are functions to close
-files allocated with pfopen, and popenf,
-namely pfclose and pclosef. (This is
-because, on many systems, the number of files which a single process
-can have open is quite limited). It is important to use these
-functions to close files allocated with pfopen and
-popenf, since to do otherwise could cause fatal errors on
-systems such as Linux, which react badly if the same
-FILE* is closed more than once.
-
-(Using the close functions is not mandatory, since the
-file will eventually be closed regardless, but you should consider it
-in cases where your module is opening, or could open, a lot of files).
-
-
Other sorts of resources --- cleanup functions
- -More text goes here. Describe the the cleanup primitives in terms of -which the file stuff is implemented; also,spawn_process.
-
-Fine control --- creating and dealing with sub-pools, with a note -on sub-requests
- -On rare occasions, too-free use ofpalloc() and the
-associated primitives may result in undesirably profligate resource
-allocation. You can deal with such a case by creating a
-sub-pool, allocating within the sub-pool rather than the main
-pool, and clearing or destroying the sub-pool, which releases the
-resources which were associated with it. (This really is a
-rare situation; the only case in which it comes up in the standard
-module set is in case of listing directories, and then only with
-very large directories. Unnecessary use of the primitives
-discussed here can hair up your code quite a bit, with very little
-gain).
-
-The primitive for creating a sub-pool is make_sub_pool,
-which takes another pool (the parent pool) as an argument. When the
-main pool is cleared, the sub-pool will be destroyed. The sub-pool
-may also be cleared or destroyed at any time, by calling the functions
-clear_pool and destroy_pool, respectively.
-(The difference is that clear_pool frees resources
-associated with the pool, while destroy_pool also
-deallocates the pool itself. In the former case, you can allocate new
-resources within the pool, and clear it again, and so forth; in the
-latter case, it is simply gone).
-
-One final note --- sub-requests have their own resource pools, which
-are sub-pools of the resource pool for the main request. The polite
-way to reclaim the resources associated with a sub request which you
-have allocated (using the sub_req_lookup_... functions)
-is destroy_sub_request, which frees the resource pool.
-Before calling this function, be sure to copy anything that you care
-about which might be allocated in the sub-request's resource pool into
-someplace a little less volatile (for instance, the filename in its
-request_rec structure).
-
-(Again, under most circumstances, you shouldn't feel obliged to call
-this function; only 2K of memory or so are allocated for a typical sub
-request, and it will be freed anyway when the main request pool is
-cleared. It is only when you are allocating many, many sub-requests
-for a single main request that you should seriously consider the
-destroy... functions).
-
-
Configuration, commands and the like
- -One of the design goals for this server was to maintain external -compatibility with the NCSA 1.3 server --- that is, to read the same -configuration files, to process all the directives therein correctly, -and in general to be a drop-in replacement for NCSA. On the other -hand, another design goal was to move as much of the server's -functionality into modules which have as little as possible to do with -the monolithic server core. The only way to reconcile these goals is -to move the handling of most commands from the central server into the -modules.
-
-However, just giving the modules command tables is not enough to
-divorce them completely from the server core. The server has to
-remember the commands in order to act on them later. That involves
-maintaining data which is private to the modules, and which can be
-either per-server, or per-directory. Most things are per-directory,
-including in particular access control and authorization information,
-but also information on how to determine file types from suffixes,
-which can be modified by AddType and
-DefaultType directives, and so forth. In general, the
-governing philosophy is that anything which can be made
-configurable by directory should be; per-server information is
-generally used in the standard set of modules for information like
-Aliases and Redirects which come into play
-before the request is tied to a particular place in the underlying
-file system.
-
-Another requirement for emulating the NCSA server is being able to
-handle the per-directory configuration files, generally called
-.htaccess files, though even in the NCSA server they can
-contain directives which have nothing at all to do with access
-control. Accordingly, after URI -> filename translation, but before
-performing any other phase, the server walks down the directory
-hierarchy of the underlying filesystem, following the translated
-pathname, to read any .htaccess files which might be
-present. The information which is read in then has to be
-merged with the applicable information from the server's own
-config files (either from the <Directory> sections
-in access.conf, or from defaults in
-srm.conf, which actually behaves for most purposes almost
-exactly like <Directory />).
-
-Finally, after having served a request which involved reading
-.htaccess files, we need to discard the storage allocated
-for handling them. That is solved the same way it is solved wherever
-else similar problems come up, by tying those structures to the
-per-transaction resource pool.
- -
Per-directory configuration structures
- -Let's look out how all of this plays out inmod_mime.c,
-which defines the file typing handler which emulates the NCSA server's
-behavior of determining file types from suffixes. What we'll be
-looking at, here, is the code which implements the
-AddType and AddEncoding commands. These
-commands can appear in .htaccess files, so they must be
-handled in the module's private per-directory data, which in fact,
-consists of two separate tables for MIME types and
-encoding information, and is declared as follows:
-
-
-typedef struct {
- table *forced_types; /* Additional AddTyped stuff */
- table *encoding_types; /* Added with AddEncoding... */
-} mime_dir_config;
-
-
-When the server is reading a configuration file, or
-<Directory> section, which includes one of the MIME
-module's commands, it needs to create a mime_dir_config
-structure, so those commands have something to act on. It does this
-by invoking the function it finds in the module's `create per-dir
-config slot', with two arguments: the name of the directory to which
-this configuration information applies (or NULL for
-srm.conf), and a pointer to a resource pool in which the
-allocation should happen.
-
-(If we are reading a .htaccess file, that resource pool
-is the per-request resource pool for the request; otherwise it is a
-resource pool which is used for configuration data, and cleared on
-restarts. Either way, it is important for the structure being created
-to vanish when the pool is cleared, by registering a cleanup on the
-pool if necessary).
-
-For the MIME module, the per-dir config creation function just
-pallocs the structure above, and a creates a couple of
-tables to fill it. That looks like this:
-
-
-void *create_mime_dir_config (pool *p, char *dummy)
-{
- mime_dir_config *new =
- (mime_dir_config *) palloc (p, sizeof(mime_dir_config));
-
- new->forced_types = make_table (p, 4);
- new->encoding_types = make_table (p, 4);
-
- return new;
-}
-
-
-Now, suppose we've just read in a .htaccess file. We
-already have the per-directory configuration structure for the next
-directory up in the hierarchy. If the .htaccess file we
-just read in didn't have any AddType or
-AddEncoding commands, its per-directory config structure
-for the MIME module is still valid, and we can just use it.
-Otherwise, we need to merge the two structures somehow. - -To do that, the server invokes the module's per-directory config merge -function, if one is present. That function takes three arguments: -the two structures being merged, and a resource pool in which to -allocate the result. For the MIME module, all that needs to be done -is overlay the tables from the new per-directory config structure with -those from the parent: - -
-void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
-{
- mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
- mime_dir_config *subdir = (mime_dir_config *)subdirv;
- mime_dir_config *new =
- (mime_dir_config *)palloc (p, sizeof(mime_dir_config));
-
- new->forced_types = overlay_tables (p, subdir->forced_types,
- parent_dir->forced_types);
- new->encoding_types = overlay_tables (p, subdir->encoding_types,
- parent_dir->encoding_types);
-
- return new;
-}
-
-
-As a note --- if there is no per-directory merge function present, the
-server will just use the subdirectory's configuration info, and ignore
-the parent's. For some modules, that works just fine (e.g., for the
-includes module, whose per-directory configuration information
-consists solely of the state of the XBITHACK), and for
-those modules, you can just not declare one, and leave the
-corresponding structure slot in the module itself NULL.- -
Command handling
- -Now that we have these structures, we need to be able to figure out -how to fill them. That involves processing the actual -AddType and AddEncoding commands. To find
-commands, the server looks in the module's command table.
-That table contains information on how many arguments the commands
-take, and in what formats, where it is permitted, and so forth. That
-information is sufficient to allow the server to invoke most
-command-handling functions with pre-parsed arguments. Without further
-ado, let's look at the AddType command handler, which
-looks like this (the AddEncoding command looks basically
-the same, and won't be shown here):
-
-
-char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
-{
- if (*ext == '.') ++ext;
- table_set (m->forced_types, ext, ct);
- return NULL;
-}
-
-
-This command handler is unusually simple. As you can see, it takes
-four arguments, two of which are pre-parsed arguments, the third being
-the per-directory configuration structure for the module in question,
-and the fourth being a pointer to a cmd_parms structure.
-That structure contains a bunch of arguments which are frequently of
-use to some, but not all, commands, including a resource pool (from
-which memory can be allocated, and to which cleanups should be tied),
-and the (virtual) server being configured, from which the module's
-per-server configuration data can be obtained if required.
-
-Another way in which this particular command handler is unusually
-simple is that there are no error conditions which it can encounter.
-If there were, it could return an error message instead of
-NULL; this causes an error to be printed out on the
-server's stderr, followed by a quick exit, if it is in
-the main config files; for a .htaccess file, the syntax
-error is logged in the server error log (along with an indication of
-where it came from), and the request is bounced with a server error
-response (HTTP error status, code 500).
- -The MIME module's command table has entries for these commands, which -look like this: - -
-command_rec mime_cmds[] = {
-{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2,
- "a mime type followed by a file extension" },
-{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,
- "an encoding (e.g., gzip), followed by a file extension" },
-{ NULL }
-};
-
-
-The entries in these tables are:
-
--
-
- The name of the command -
- The function which handles it -
- a
(void *)pointer, which is passed in the -cmd_parmsstructure to the command handler --- - this is useful in case many similar commands are handled by the - same function. - - A bit mask indicating where the command may appear. There are
- mask bits corresponding to each
AllowOverride- option, and an additional mask bit,RSRC_CONF, - indicating that the command may appear in the server's own - config files, but not in any.htaccess- file. - - A flag indicating how many arguments the command handler wants
- pre-parsed, and how they should be passed in.
-
TAKE2indicates two pre-parsed arguments. Other - options areTAKE1, which indicates one pre-parsed - argument,FLAG, which indicates that the argument - should beOnorOff, and is passed in - as a boolean flag,RAW_ARGS, which causes the - server to give the command the raw, unparsed arguments - (everything but the command name itself). There is also -ITERATE, which means that the handler looks the - same asTAKE1, but that if multiple arguments are - present, it should be called multiple times, and finally -ITERATE2, which indicates that the command handler - looks like aTAKE2, but if more arguments are - present, then it should be called multiple times, holding the - first argument constant. - - Finally, we have a string which describes the arguments that
- should be present. If the arguments in the actual config file
- are not as required, this string will be used to help give a
- more specific error message. (You can safely leave this
-
NULL). -
request_rec's per-directory configuration vector by using
-the get_module_config function.
-
-
-int find_ct(request_rec *r)
-{
- int i;
- char *fn = pstrdup (r->pool, r->filename);
- mime_dir_config *conf = (mime_dir_config *)
- get_module_config(r->per_dir_config, &mime_module);
- char *type;
-
- if (S_ISDIR(r->finfo.st_mode)) {
- r->content_type = DIR_MAGIC_TYPE;
- return OK;
- }
-
- if((i=rind(fn,'.')) < 0) return DECLINED;
- ++i;
-
- if ((type = table_get (conf->encoding_types, &fn[i])))
- {
- r->content_encoding = type;
-
- /* go back to previous extension to try to use it as a type */
-
- fn[i-1] = '\0';
- if((i=rind(fn,'.')) < 0) return OK;
- ++i;
- }
-
- if ((type = table_get (conf->forced_types, &fn[i])))
- {
- r->content_type = type;
- }
-
- return OK;
-}
-
-
-
-Side notes --- per-server configuration, virtual servers, etc.
- -The basic ideas behind per-server module configuration are basically -the same as those for per-directory configuration; there is a creation -function and a merge function, the latter being invoked where a -virtual server has partially overridden the base server configuration, -and a combined structure must be computed. (As with per-directory -configuration, the default if no merge function is specified, and a -module is configured in some virtual server, is that the base -configuration is simply ignored).
-
-The only substantial difference is that when a command needs to
-configure the per-server private module data, it needs to go to the
-cmd_parms data to get at it. Here's an example, from the
-alias module, which also indicates how a syntax error can be returned
-(note that the per-directory configuration argument to the command
-handler is declared as a dummy, since the module doesn't actually have
-per-directory config data):
-
-
-char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
-{
- server_rec *s = cmd->server;
- alias_server_conf *conf = (alias_server_conf *)
- get_module_config(s->module_config,&alias_module);
- alias_entry *new = push_array (conf->redirects);
-
- if (!is_url (url)) return "Redirect to non-URL";
-
- new->fake = f; new->real = url;
- return NULL;
-}
-
-
-
diff --git a/docs/manual/misc/FAQ.html b/docs/manual/misc/FAQ.html
deleted file mode 100644
index 94d257d6614..00000000000
--- a/docs/manual/misc/FAQ.html
+++ /dev/null
@@ -1,1397 +0,0 @@
-
-
-
- Apache Server Frequently Asked Questions
-- $Revision: 1.63 $ ($Date: 1997/06/04 11:42:55 $) -
-- The latest version of this FAQ is always available from the main - Apache web site, at - <http://www.apache.org/docs/misc/FAQ>. -
- - - - - - - - - - - - -- If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. -
-The Questions
- - - - - - - - - - - - - - - - - - - - - - - - - - - - --
-
- Background
-
-
-
- What is Apache? - -
- Why was Apache created? - -
- How does The Apache Group's work relate to - other servers? - -
- Why the name "Apache"? - -
- OK, so how does Apache compare to other servers? - -
- How thoroughly tested is Apache? - -
- What are the future plans for Apache? - -
- Whom do I contact for support? - -
- Is there any more information on Apache? - -
- Where can I get Apache? - -
- - Technical Questions
-
-
-
- "Why can't I ...? Why won't ... - work?" What to do in case of problems - -
- How compatible is Apache with my existing - NCSA 1.3 setup? - -
- How do I enable CGI execution - in directories other than the ScriptAlias? - -
- What does it mean when my - CGIs fail with "Premature end of script - headers"? - -
- How do I enable SSI (parsed HTML)? - -
- Why don't my parsed files get cached? - -
- How can I have my script output parsed? - -
- Does or will Apache act as a Proxy server? - -
- What are "multiviews"? - -
- Why can't I run more than <n> - virtual hosts? - -
- Why do I keep getting "access denied" for - form POST requests? - -
- Can I use my /etc/passwd file - for Web page authentication? - -
- Why doesn't my
ErrorDocument - 401work? -
- - Why do I get "setgid: Invalid - argument" at startup? - -
- Why does Apache send a cookie on every response? - -
- Why don't my cookies work, I even compiled in - mod_cookies? - -
- Why do my Java app[let]s give me plain text - when I request an URL from an Apache server? - -
- Why can't I publish to my Apache server - using PUT on Netscape Gold and other programs? - -
- Why isn't FastCGI included with Apache any - more? - -
- Why am I getting "httpd: could not - set socket option TCP_NODELAY" in my error log? - -
- How can I get my script's output without - Apache buffering it? - -
- Why do I get complaints about redefinition - of `struct iovec' when compiling under Linux? - -
- The errorlog says Apache dumped core, - but where's the dump file? - -
- Why isn't restricting access by host or domain name - working correctly? - -
- Why doesn't Apache include SSL? - -
- Why do I get core dumps under HPUX using - HP's ANSI C compiler? - -
- How do I get Apache to send a MIDI file so the - browser can play it? - -
- Why won't Apache compile with my - system's cc? - -
- How do I add browsers and referrers to my - logs? - -
-
- -
The Answers
--
-- Background -
--
-
-
- What is Apache?
-
-
- Apache was originally based on code and ideas found in the most - popular HTTP server of the time.. NCSA httpd 1.3 (early 1995). It has - since evolved into a far superior system which can rival (and probably - surpass) almost any other UNIX based HTTP server in terms of functionality, - efficiency and speed. -
-- Since it began, it has been completely rewritten, and includes many new - features. Apache is, as of January 1997, the most popular WWW server on - the Internet, according to the - Netcraft Survey. -
-
-
- -
- Why was Apache created?
-
-
- To address the concerns of a group of WWW providers and part-time httpd - programmers that httpd didn't behave as they wanted it to behave. - Apache is an entirely volunteer effort, completely funded by its - members, not by commercial sales. -
- -
- -
- How does The Apache Group's work relate to other
- server efforts, such as NCSA's?
-
-
- We, of course, owe a great debt to NCSA and their programmers for - making the server Apache was based on. We now, however, have our own - server, and our project is mostly our own. The Apache Project is an - entirely independent venture. -
-
-
- -
- Why the name "Apache"?
-
-
- A cute name which stuck. Apache is "A - PAtCHy server". It was - based on some existing code and a series of "patch files". -
-
-
- -
- OK, so how does Apache compare to other servers?
-
-
- For an independent assessment, see - Web Compare's - comparison chart. -
-- Apache has been shown to be substantially faster than many other - free servers. Although certain commercial servers have claimed to - surpass Apache's speed (it has not been demonstrated that any of these - "benchmarks" are a good way of measuring WWW server speed at any - rate), we feel that it is better to have a mostly-fast free server - than an extremely-fast server that costs thousands of dollars. Apache - is run on sites that get millions of hits per day, and they have - experienced no performance difficulties. -
-
-
- -
- How thoroughly tested is Apache?
-
-
- Apache is run on over 400,000 Internet servers (as of April 1997). It has - been tested thoroughly by both developers and users. The Apache Group - maintains rigorous standards before releasing new versions of their - server, and our server runs without a hitch on over one third of all - WWW servers available on the Internet. When bugs do show up, we - release patches and new versions as soon as they are available. -
-- The Apache project's web site includes a page with a partial list of - sites running Apache. -
-
-
- -
- What are the future plans for Apache?
-
-
-
-
-
- to continue as a public domain HTTP server, - -
- to keep up with advances in HTTP protocol and web developments in - general, - -
- to collect suggestions for fixes/improvements from its users, - -
- to respond to needs of large volume providers as well as - occasional users. - -
-
- -
- Whom do I contact for support?
-
-
- There is no official support for Apache. None of the developers want to - be swamped by a flood of trivial questions that can be resolved elsewhere. - Bug reports and suggestions should be sent via - the bug report page. - Other questions should be directed to the - comp.infosystems.www.servers.unix - newsgroup, where some of the Apache team lurk, - in the company of many other httpd gurus who should be able - to help. -
-- Commercial support for Apache is, however, available from a number - of third parties. -
-
-
- -
- Is there any more information available on
- Apache?
-
-
- Indeed there is. See the main - Apache web site. - There is also a regular electronic publication called - Apache Week - available. Links to relevant Apache Week articles are - included below where appropriate. -
-
-
- -
- Where can I get Apache?
-
-
- You can find out how to download the source for Apache at the - project's - main web page. -
-
-
-
- Technical Questions -
--
-
-
- "Why can't I ...? Why won't ... work?" What to
- do in case of problems
-
-
- If you are having trouble with your Apache server software, you should - take the following steps: -
--
-
- Check the errorlog!
-
- Apache tries to be helpful when it encounters a problem. In many - cases, it will provide some details by writing one or messages to - the server error log. Sometimes this is enough for you to diagnose - & fix the problem yourself (such as file permissions or the like). - The default location of the error log is -
-/usr/local/etc/httpd/logs/error_log, but see the - ErrorLog - directive in your config files for the location on your server. -
- - Check the
- FAQ!
-
- The latest version of the Apache Frequently-Asked Questions list can - always be found at the main Apache web site. -
-
- - Check the Apache bug database
-
- Most problems that get reported to The Apache Group are recorded in - the - bug database. - Please check the existing reports, open - and closed, before adding one. If you find - that your issue has already been reported, please don't add - a "me, too" report. If the original report isn't closed - yet, we suggest that you check it periodically. You might also - consider contacting the original submitter, because there may be an - email exchange going on about the issue that isn't getting recorded - in the database. -
-
- - Ask in the comp.infosystems.www.servers.unix
- USENET newsgroup
-
- A lot of common problems never make it to the bug database because - there's already high Q&A traffic about them in the - comp.infosystems.www.servers.unix - newsgroup. Many Apache users, and some of the developers, can be - found roaming its virtual halls, so it is suggested that you seek - wisdom there. The chances are good that you'll get a faster answer - there than from the bug database, even if you don't see - your question already posted. -
-
- - If all else fails, report the problem in the bug
- database
-
- If you've gone through those steps above that are appropriate and - have obtained no relief, then please do let The Apache - Group know about the problem by - logging a bug report. -
-- If your problem involves the server crashing and generating a core - dump, please include a backtrace (if possible). As an example, -
--
----
-
- # cd ServerRoot - -
- # dbx httpd core - -
- (dbx) where - -
- (Substitute the appropriate locations for your - ServerRoot and your httpd and - core files. You may have to use
-gdb- instead ofdbx.) -
-
-
- - Check the errorlog!
-
-
- How compatible is Apache with my existing NCSA 1.3
- setup?
-
-
- Apache attempts to offer all the features and configuration options - of NCSA httpd 1.3, as well as many of the additional features found in - NCSA httpd 1.4 and NCSA httpd 1.5. -
-- NCSA httpd appears to be moving toward adding experimental features - which are not generally required at the moment. Some of the experiments - will succeed while others will inevitably be dropped. The Apache - philosophy is to add what's needed as and when it is needed. -
-- Friendly interaction between Apache and NCSA developers should ensure - that fundamental feature enhancements stay consistent between the two - servers for the foreseeable future. -
-
-
- -
- How do I enable CGI execution in directories other than
- the ScriptAlias?
-
-
- Apache recognizes all files in a directory named as a - ScriptAlias - as being eligible for execution rather than processing as normal - documents. This applies regardless of the file name, so scripts in a - ScriptAlias directory don't need to be named - "*.cgi" or "*.pl" or - whatever. In other words, all files in a ScriptAlias - directory are scripts, as far as Apache is concerned. -
-- To persuade Apache to execute scripts in other locations, such as in - directories where normal documents may also live, you must tell it how - to recognize them - and also that it's okay to execute them. For - this, you need to use something like the - AddHandler - directive. -
--
-
- In an appropriate section of your server configuration files, add
- a line such as
-
-
-
-
AddHandler cgi-script .cgi-
-
- - Make sure that the directory location is covered by an - Options - declaration that includes the ExecCGI option. - -
-
- - In an appropriate section of your server configuration files, add
- a line such as
-
-
- What does it mean when my CGIs fail with
- "Premature end of script headers"?
-
-
- It means just what it says: the server was expecting a complete set of - HTTP headers (one or more followed by a blank line), and didn't get - them. The most common cause of this (aside from people not - outputting the required headers at all) a result of an interaction - with perl's output buffering. To make perl flush its buffers - after each output statement, insert the following statements before your - first
-printorwritestatement: --
----
-
- $cfh = select (STDOUT); - -
- $| = 1; - -
- select ($cfh); - -
- This is generally only necessary when you are calling external - programs from your script that send output to stdout. -
- If your script isn't written in Perl, do the equivalent thing for - whatever language you are using (e.g., for C, call -
-fflush()after writing the headers). -
-
- -
- How do I enable SSI (parsed HTML)?
-
-
- SSI (an acronym for Server-Side Include) directives allow static HTML - documents to be enhanced at run-time (e.g., when delivered to - a client by Apache). The format of SSI directives is covered - in the mod_include manual; - suffice it to say that Apache supports not only SSI but - xSSI (eXtended SSI) directives. -
-- Processing a document at run-time is called parsing it; hence - the term "parsed HTML" sometimes used for documents that - contain SSI instructions. Parsing tends to be extremely - resource-consumptive, and is not enabled by default. -
-- To enable SSI processing, you need to -
--
-
- Build your server with the - mod_include - module. This is normally compiled in by default. - -
- Make sure your server configuration files have an - Options - directive which permits Includes. - -
- Make sure that the directory where you want the SSI documents to
- live is covered by the "server-parsed" content handler,
- either explicitly or in some ancestral location. That can be done
- with the following
- AddHandler
- directive:
-
-
-
-
AddHandler server-parsed .shtml-
-
-
- For additional information, see the Apache Week article - on - Using Server Side Includes. -
-
-
- -
- Why don't my parsed files get cached?
-
-
- Since the server is performing run-time processing of your SSI - directives, which may change the content shipped to the client, it - can't know at the time it starts parsing what the final size of the - result will be, or whether the parsed result will always be the same. - This means that it can't generate Content-Length or - Last-Modified headers. Caches commonly work by comparing - the Last-Modified of what's in the cache with that being - delivered by the server. Since the server isn't sending that header - for a parsed document, whatever's doing the caching can't tell whether - the document has changed or not - and so fetches it again to be on the - safe side. -
-- You can work around this in some cases by causing an - Expires header to be generated. (See the - mod_expires - documentation for more details.) Another possibility is to use the - XBitHack Full - mechanism, which tells Apache to send (under certain circumstances - detailed in the XBitHack directive description) a - Last-Modified header based upon the last modification - time of the file being parsed. Note that this may actually be lying - to the client if the parsed file doesn't change but the SSI-inserted - content does; if the included content changes often, this can result - in stale copies being cached. -
-
-
- -
- How can I have my script output parsed?
-
-
- So you want to include SSI directives in the output from your CGI - script, but can't figure out how to do it? - The short answer is "you can't." This is potentially - a security liability and, more importantly, it can not be cleanly - implemented under the current server API. The best workaround - is for your script itself to do what the SSIs would be doing. - After all, it's generating the rest of the content. -
-- This is a feature The Apache Group hopes to add in the next major - release after 1.2. -
-
-
- -
- Does or will Apache act as a Proxy server?
-
-
- Apache version 1.1 and above comes with a proxy module. If compiled - in, this will make Apache act as a caching-proxy server. -
-
-
- -
- What are "multiviews"?
-
-
- "Multiviews" is the general name given to the Apache - server's ability to provide language-specific document variants in - response to a request. This is documented quite thoroughly in the - content negotiation - description page. In addition, Apache Week carried an - article on this subject entitled - "Content Negotiation Explained". -
-
-
- -
- Why can't I run more than <n>
- virtual hosts?
-
-
- You are probably running into resource limitations in your - operating system. The most common limitation is the - per-process limit on file descriptors, - which is almost always the cause of problems seen when adding - virtual hosts. Apache often does not give an intuitive error - message because it is normally some library routine (such as -
-gethostbyname()) which needs file descriptors and - doesn't complain intelligibly when it can't get them. -- Each log file requires a file descriptor, which means that if you are - using separate access and error logs for each virtual host, each - virtual host needs two file descriptors. Each - Listen - directive also needs a file descriptor. -
-- Typical values for <n> that we've seen are in - the neighborhood of 128 or 250. When the server bumps into the file - descriptor limit, it may dump core with a SIGSEGV, it might just - hang, or it may limp along and you'll see (possibly meaningful) errors - in the error log. One common problem that occurs when you run into - a file descriptor limit is that CGI scripts stop being executed - properly. -
-- As to what you can do about this: -
--
-
- Reduce the number of - Listen - directives. If there are no other servers running on the machine - and all of them are running on the same port, you normally don't - need any Listen directives at all. - -
- Reduce the number of log files. You can use - mod_log_config - to log all requests to a single log file while including the name - of the virtual host in the log file. You can then write a - script to split the logfile into separate files later if - necessary. - -
- Increase the number of file descriptors available to the server
- (see your system's documentation on the
limitor -ulimitcommands). For some systems, information on - how to do this is available in the - performance hints - page. -
- - "Don't do that" - try to run with fewer virtual hosts - -
- Spread your operation across multiple server processes (using - Listen - for example, but see the first point) and/or ports. - -
- Since this is an operating-system limitation, there's not much else - available in the way of solutions. -
-
- -
- Why do I keep getting "access denied" for form POST
- requests?
-
-
- The most common cause of this is a <Limit> section - that only names the GET method. Look in your - configuration files for something that resembles the following and - would affect the location where the POST-handling script resides: -
--
----
-
- <Limit GET> - -
- : - -
- Change that to <Limit GET POST> and the problem - will probably go away. -
-
-
- -
- Can I use my /etc/passwd file
- for Web page authentication?
-
-
- Yes, you can - but it's a very bad idea. Here are - some of the reasons: -
--
-
- The Web technology provides no governors on how often or how - rapidly password (authentication failure) retries can be made. That - means that someone can hammer away at your system's - root password using the Web, using a dictionary or - similar mass attack, just as fast as the wire and your server can - handle the requests. Most operating systems these days include - attack detection (such as n failed passwords for the same - account within m seconds) and evasion (breaking the - connection, disabling the account under attack, disabling - all logins from that source, et cetera), but the - Web does not. - -
- An account under attack isn't notified (unless the server is - heavily modified); there's no "You have 19483 login - failures" message when the legitimate owner logs in. - -
- Without an exhaustive and error-prone examination of the server - logs, you can't tell whether an account has been compromised. - Detecting that an attack has occurred, or is in progress, is fairly - obvious, though - if you look at the logs. - -
- Web authentication passwords (at least for Basic authentication) - generally fly across the wire, and through intermediate proxy - systems, in what amounts to plaintext. "O'er the net we - go/Caching all the way;/O what fun it is to surf/Giving my password - away!" - -
- Since HTTP is stateless, information about the authentication is - transmitted each and every time a request is made to the - server. Essentially, the client caches it after the first - successful access, and transmits it without asking for all - subsequent requests to the same server. - -
- It's relatively trivial for someone on your system to put up a - page that will steal the cached password from a client's cache - without them knowing. Can you say "password grabber"? - -
- If you still want to do this in light of the above disadvantages, the - method is left as an exercise for the reader. It'll void your Apache - warranty, though, and you'll lose all accumulated UNIX guru points. -
-
- -
- Why doesn't my
ErrorDocument 401work? - -- You need to use it with a URL in the form "/foo/bar" and not one - with a method and hostname such as "http://host/foo/bar". See the - ErrorDocument - documentation for details. This was incorrectly documented in the past. -
-
-
- -
- Why do I get "setgid: Invalid
- argument" at startup?
-
-
- Your - Group - directive (probably in conf/httpd.conf) needs to name a - group that actually exists in the /etc/group file (or - your system's equivalent). -
-
-
- -
- Why does Apache send a cookie on every response?
-
-
- Apache does not send automatically send a cookie on every - response, unless you have re-compiled it with the - mod_cookies - module. - This module was distributed with Apache prior to 1.2. - This module may help track users, and uses cookies to do this. If - you are not using the data generated by mod_cookies, do - not compile it into Apache. Note that in 1.2 this module was renamed - to the more correct name - mod_usertrack, - and cookies - have to be specifically enabled with the - CookieTracking - directive. -
-
-
- -
- Why don't my cookies work, I even compiled in
- mod_cookies?
-
-
-
- Firstly, you do not need to compile in - mod_cookies in order for your scripts to work (see the - previous question - for more about mod_cookies). Apache passes on your - Set-Cookie header fine, with or without this module. If - cookies do not work it will be because your script does not work - properly or your browser does not use cookies or is not set-up to - accept them. -
-
-
- -
- Why do my Java app[let]s give me plain text when I request
- an URL from an Apache server?
-
-
- As of version 1.2, Apache is an HTTP/1.1 (HyperText Transfer Protocol - version 1.1) server. This fact is reflected in the protocol version - that's included in the response headers sent to a client when - processing a request. Unfortunately, low-level Web access classes - included in the Java Development Kit (JDK) version 1.0.2 expect to see - the version string "HTTP/1.0" and do not correctly interpret - the "HTTP/1.1" value Apache is sending (this part of the - response is a declaration of what the server can do rather than a - declaration of the dialect of the response). The result - is that the JDK methods do not correctly parse the headers, and - include them with the document content by mistake. -
-- This is definitely a bug in the JDK 1.0.2 foundation classes from Sun, - and it has been fixed in version 1.1. However, the classes in - question are part of the virtual machine environment, which means - they're part of the Web browser (if Java-enabled) or the Java - environment on the client system - so even if you develop - your classes with a recent JDK, the eventual users might - encounter the problem. - The classes involved are replaceable by vendors implementing the - Java virtual machine environment, and so even those that are based - upon the 1.0.2 version may not have this problem. -
-- In the meantime, a workaround is to tell - Apache to "fake" an HTTP/1.0 response to requests that come - from the JDK methods; this can be done by including a line such as the - following in your server configuration files: -
--
-
-
BrowserMatch Java/1.0 force-response-1.0-
-
- More information about this issue can be found in the - Java and HTTP/1.1 - page at the Apache web site. -
-
-
- -
- Why can't I publish to my Apache server using PUT on
- Netscape Gold and other programs?
-
-
- Because you need to install and configure a script to handle - the uploaded files. This script is often called a "PUT" handler. - There are several available, but they may have security problems. - Using FTP uploads may be easier and more secure, at least for now. - For more information, see the Apache Week article - Publishing Pages with PUT. -
-
-
- -
- Why isn't FastCGI included with Apache any more?
-
-
- The simple answer is that it was becoming too difficult to keep the - version being included with Apache synchronized with the master copy - at the - FastCGI web site. When a new version of Apache was released, the - version of the FastCGI module included with it would soon be out of date. -
-- You can still obtain the FastCGI module for Apache from the master - FastCGI web site. -
-
-
- -
- Why am I getting "httpd: could not set socket
- option TCP_NODELAY" in my error log?
-
-
- This message almost always indicates that the client disconnected - before Apache reached the point of calling
-setsockopt()- for the connection. It shouldn't occur for more than about 1% of the - requests your server handles, and it's advisory only in any case. -
-
- -
- How can I get my script's output without Apache buffering
- it?
-
-
- In order to improve network performance, Apache buffers script output - into relatively large chunks. If you have a script that sends - information in bursts (such as partial-done messages in a multi-commit - database transaction, perhaps), the client will not necessarily get - the output as the script is generating it. -
-- To avoid this, Apache recognizes scripts whose names begin with - "nph-" as non-parsed-header scripts. - That is, Apache won't buffer their output, but connect it directly to - the socket going back to the client. -
-- While this will probably do what you want, there are some - disadvantages to it: -
--
-
- YOU (the script) are responsible for generating - ALL of the HTTP headers, and no longer - just the "Content-type" or - "Location" headers - -
- Unless your script generates its output carefully, you will see a - performance penalty as excessive numbers of packets go back and forth - -
- As an example how you might handle the former (in a Perl script): -
----
-
- if ($0 =~ m:/*nph-:) {
-
- - $HTTP_headers = - "HTTP/1.1 200 OK\015\012"; -
- - $HTTP_headers .= - "Connection: close\015\012"; -
- - printf ($HTTP_headers); -
- }; -
-
- and then follow with your normal non-nph headers. -
-
-
- -
- Why do I get complaints about redefinition
- of `struct iovec' when compiling under Linux?
-
-
- This is a conflict between your C library includes and your kernel - includes. You need to make sure that the versions of both are matched - properly. There are two workarounds, either one will solve the problem: -
--
-
- Remove the definition of
struct iovecfrom your C - library includes. It is located in/usr/include/sys/uio.h. - Or, -
- - Add
-DNO_WRITEVto theEXTRA_CFLAGS- line in your Configuration and reconfigure/rebuild. - This hurts performance and should only be used as a last resort. -
-
-
- - Remove the definition of
-
- The errorlog says Apache dumped core, but where's the dump
- file?
-
-
- In Apache version 1.2 (beginning with 1.2b8), the error log message - about dumped core includes the directory where the dump file should be - located. However, many Unixes do not allow a process that has - called
-setuid()to dump core for security reasons; - the typical Apache setup has the server started as root to bind to - port 80, after which it changes UIDs to a non-privileged user to - serve requests. -- Dealing with this is extremely operating system-specific, and may - require rebuilding your system kernel. Consult your operating system - documentation or vendor for more information about whether your system - does this and how to bypass it. If there is a documented way - of bypassing it, it is recommended that you bypass it only for the - httpd server process if possible. -
-- The canonical location for Apache's core-dump files is the - ServerRoot - directory. -
-
-
- -
- Why isn't restricting access by host or domain name
- working correctly?
-
-
- Two of the most common causes of this are: -
--
-
- An error, inconsistency, or unexpected mapping in the DNS
- registration
-
- This happens frequently: your configuration restricts access to - Host.FooBar.Com, but you can't get in from that host. - The usual reason for this is that Host.FooBar.Com is - actually an alias for another name, and when Apache performs the - address-to-name lookup it's getting the real name, not - Host.FooBar.Com. You can verify this by checking the - reverse lookup yourself. The easiest way to work around it is to - specify the correct host name in your configuration. -
- - Inadequate checking and verification in your
- configuration of Apache
-
- If you intend to perform access checking and restriction based upon - the client's host or domain name, you really need to configure - Apache to double-check the origin information it's supplied. You do - this by adding the -DMAXIMUM_DNS clause to the - EXTRA_CFLAGS definition in your - Configuration file. For example: --
-
EXTRA_CFLAGS=-DMAXIMUM_DNS-
-
- This will cause Apache to be very paranoid about making sure a - particular host address is really assigned to the name it - claims to be. Note that this can incur a significant - performance penalty, however, because of all the name resolution - requests being sent to a nameserver. -
-
-
-
- - An error, inconsistency, or unexpected mapping in the DNS
- registration
-
-
- Why doesn't Apache include SSL?
-
-
- SSL (Secure Socket Layer) data transport requires encryption, and many - governments have restrictions upon the import, export, and use of - encryption technology. If Apache included SSL in the base package, - its distribution would involve all sorts of legal and bureaucratic - issues, and it would no longer be freely available. Also, some of - the technology required to talk to current clients using SSL is - patented by RSA Data Security, - who restricts its use without a license. -
-- Some SSL implementations of Apache are available, however; see the - "related projects" - page at the main Apache web site. -
-- You can find out more about this topic in the Apache Week - article about - Apache and Secure Transactions. -
-
-
- -
- Why do I get core dumps under HPUX using HP's ANSI
- C compiler?
-
-
- We have had numerous reports of Apache dumping core when compiled - with HP's ANSI C compiler using optimization. Disabling the compiler - optimization has fixed these problems. -
-
-
- -
- How do I get Apache to send a MIDI file so the browser can
- play it?
-
-
- Even though the registered MIME type for MIDI files is - audio/midi, some browsers are not set up to recognize it - as such; instead, they look for audio/x-midi. There are - two things you can do to address this: -
--
-
- Configure your browser to treat documents of type - audio/midi correctly. This is the type that Apache - sends by default. This may not be workable, however, if you have - many client installations to change, or if some or many of the - clients are not under your control. - -
- Instruct Apache to send a different Content-type
- header for these files by adding the following line to your server's
- configuration files:
-
-
-
AddType audio/x-midi .mid .midi .kar-
-
- Note that this may break browsers that do recognize the - audio/midi MIME type unless they're prepared to also - handle audio/x-midi the same way. -
-
-
-
- -
- Why won't Apache compile with my system's
- cc?
-
-
- If the server won't compile on your system, it is probably due to one - of the following causes: -
--
-
- The Configure script doesn't recognize your system
- environment.
-
- This might be either because it's completely unknown or because - the specific environment (include files, OS version, et - cetera) isn't explicitly handled. If this happens, you may - need to port the server to your OS yourself. -
- - Your system's C compiler is garbage.
-
- Some operating systems include a default C compiler that is either - not ANSI C-compliant or suffers from other deficiencies. The usual - recommendation in cases like this is to acquire, install, and use - gcc. -
- - Your include files may be confused.
-
- In some cases, we have found that a compiler installation or system - upgrade has left the C header files in an inconsistent state. Make - sure that your include directory tree is in sync with the compiler and - the operating system. -
- - Your operating system or compiler may be out of
- revision.
-
- Software vendors (including those that develop operating systems) - issue new releases for a reason; sometimes to add functionality, but - more often to fix bugs that have been discovered. Try upgrading - your compiler and/or your operating system. -
-
- The Apache Group tests the ability to build the server on many - different platforms. Unfortunately, we can't test all of the OS - platforms there are. If you have verified that none of the above - issues is the cause of your problem, and it hasn't been reported - before, please submit a - problem report. - Be sure to include complete details, such as the compiler - & OS versions and exact error messages. -
-
-
- - The Configure script doesn't recognize your system
- environment.
-
-
- How do I add browsers and referrers to my logs?
-
-
- Apache provides a couple of different ways of doing this. The - recommended method is to compile the - mod_log_config - module into your configuration and use the - CustomLog - directive. -
-- You can either log the additional information in files other than your - normal transfer log, or you can add them to the records already being - written. For example: -
--
-- CustomLog logs/access_log "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"" --- This will add the values of the User-agent: and - Referer: headers, which indicate the client and the - referring page, respectively, to the end of each line in the access - log. -
-- You may want to check out the Apache Week article - entitled: - "Gathering Visitor Information: Customising Your - Logfiles". -
-
-
- -
- Why do Java applets and applications not work
- with documents on my Apache server?
-
-
- The Java Development Kit (JDK) libraries versions 1.0.2 and 1.1 do not - correctly interpret the "HTTP/1.1" response - header that Apache 1.2 sends. Instead, if they don't see an exact - match for "HTTP/1.0", they assume the headers - are part of the document content. -
-- This is a known problem, and it has been reported to Sun's JavaSoft - unit. In the meantime, Apache 1.2 servers can work around this by - adding the following lines to their configuration files: -
--
-
- BrowserMatch Java1.0 force-response-1.0 - -
- -
-
Reading Client Input in Apache 1.2
- -- -
Apache 1.1 and earlier let modules handle POST and PUT requests by
-themselves. The module would, on its own, determine whether the
-request had an entity, how many bytes it was, and then called a
-function (read_client_block) to get the data.
-
-
However, HTTP/1.1 requires several things of POST and PUT request -handlers that did not fit into this module, and all existing modules -have to be rewritten. The API calls for handling this have been -further abstracted, so that future HTTP protocol changes can be -accomplished while remaining backwards-compatible.
- -- -
The New API Functions
- -- int setup_client_block (request_rec *, int read_policy); - int should_client_block (request_rec *); - long get_client_block (request_rec *, char *buffer, int buffer_size); -- -
-
-
- Call
setup_client_block()near the beginning of the request - handler. This will set up all the necessary properties, and - will return either OK, or an error code. If the latter, - the module should return that error code. The second parameter - selects the policy to apply if the request message indicates a - body, and how a chunked - transfer-coding should be interpreted. Choose one of -- REQUEST_NO_BODY Send 413 error if message has any body - REQUEST_CHUNKED_ERROR Send 411 error if body without Content-Length - REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me. - REQUEST_CHUNKED_PASS Pass the chunks to me without removal. -
- In order to use the last two options, the caller MUST provide a buffer - large enough to hold a chunk-size line, including any extensions. - - - - - When you are ready to possibly accept input, call
-
should_client_block(). - This will tell the module whether or not to read input. If it is 0, - the module should assume that the input is of a non-entity type - (e.g. a GET request). A nonzero response indicates that the module - should proceed (to step 3). - This step also sends a 100 Continue response - to HTTP/1.1 clients, so should not be called until the module - is *definitely* ready to read content. (otherwise, the point of the - 100 response is defeated). Never call this function more than once. - - - Finally, call
get_client_blockin a loop. Pass it a - buffer and its - size. It will put data into the buffer (not necessarily the full - buffer, in the case of chunked inputs), and return the length of - the input block. When it is done reading, it will - return 0 if EOF, or -1 if there was an error. - -
As an example, please look at the code in
-mod_cgi.c. This is properly written to the new API
-guidelines.
Compatibility Notes with NCSA's Server
- -- -While Apache 0.8.x and beyond are for the most part a drop-in -replacement for NCSA's httpd and earlier versions of Apache, there are -a couple gotcha's to watch out for. These are mostly due to the fact -that the parser for config and access control files was rewritten from -scratch, so certain liberties the earlier servers took may not be -available here. These are all easily fixable. If you know of other -non-fatal problems that belong here, let us know. - -
Please also check the known bugs page. - - - -
-
-
-
- The basic mod_auth
AuthGroupFile-specified group file - format allows commas between user names - Apache does not.
- - added 12/1/96 - - AddTypeonly accepts one file extension per line, without -any dots (.) in the extension, and does not take full filenames. -If you need multiple extensions per type, use multiple lines, e.g. -
-To map-AddType application/foo foo
-AddType application/foo bar -.fooand.bartoapplication/foo-- - - -
If you follow the NCSA guidelines for setting up access restrictions - based on client domain, you may well have added entries for, -
AuthType, AuthName, AuthUserFileorAuthGroupFile. - None of these are needed (or appropriate) for restricting access - based on client domain. - -When Apache sees
AuthTypeit (reasonably) assumes you - are using some authorization type based on username and password. - -Please remove
AuthType, it's unnecessary even for NCSA. - -- -
AuthUserFilerequires a full pathname. In earlier - versions of NCSA httpd and Apache, you could use a filename - relative to the .htaccess file. This could be a major security hole, - as it made it trivially easy to make a ".htpass" file in the a - directory easily accessible by the world. We recommend you store - your passwords outside your document tree. - -- -
OldScriptAliasis no longer supported. - -- -
exec cgi=""produces reasonable malformed header - responses when used to invoke non-CGI scripts.
- The NCSA code ignores the missing header. (bad idea)
- Solution: write CGI to the CGI spec or useexec cmd=""instead. -We might add
virtualsupport toexec cmdto - make up for this difference. - -- -
- <Limit> silliness - in the old Apache 0.6.5, a
- directive of <Limit GET> would also restrict POST methods - Apache 0.8.8's new
- core is correct in not presuming a limit on a GET is the same limit on a POST,
- so if you are relying on that behavior you need to change your access configurations
- to reflect that.
-
-
- -
- Icons for FancyIndexing broken - well, no, they're not broken, we've just upgraded the
- icons from flat .xbm files to pretty and much smaller .gif files, courtesy of
-Kevin Hughes at
-EIT.
- If you are using the same srm.conf from an old distribution, make sure you add the new
- AddIcon, AddIconByType, and DefaultIcon commands.
-
-
- -
- Under IRIX, the "Group" directive in httpd.conf needs to be a valid group name
- (i.e. "nogroup") not the numeric group ID. The distribution httpd.conf, and earlier
- ones, had the default Group be "#-1", which was causing silent exits at startup.
- -
.asisfiles: Apache 0.6.5 did not require a Status header; -it added one automatically if the .asis file contained a Location header. -0.8.14 requires a Status header.- -
-
- Apache versions before 1.2b1 will ignore the last line of configuration - files if the last line does not have a trailing newline. This affects - configuration files (httpd.conf, access.conf and srm.conf), and - htpasswd and htgroup files. - -
Connections in the FIN_WAIT_2 state and Apache
--
-
What is the FIN_WAIT_2 state?
-Starting with the Apache 1.2 betas, people are reporting many more -connections in the FIN_WAIT_2 state (as reported by -netstat) than they saw using older versions. When the -server closes a TCP connection, it sends a packet with the FIN bit -sent to the client, which then responds with a packet with the ACK bit -set. The client then sends a packet with the FIN bit set to the -server, which responds with an ACK and the connection is closed. The -state that the connection is in during the period between when the -server gets the ACK from the client and the server gets the FIN from -the client is known as FIN_WAIT_2. See the TCP RFC for the -technical details of the state transitions.- -The FIN_WAIT_2 state is somewhat unusual in that there is no timeout -defined in the standard for it. This means that on many operating -systems, a connection in the FIN_WAIT_2 state will stay around until -the system is rebooted. If the system does not have a timeout and -too many FIN_WAIT_2 connections build up, it can fill up the space -allocated for storing information about the connections and crash -the kernel. The connections in FIN_WAIT_2 do not tie up an httpd -process.
- -
But why does it happen?
- -There are several reasons for it happening, and not all of them are -fully understood by the Apache team yet. What is known follows.- -
Buggy clients and persistent connections
- -Several clients have a bug which pops up when dealing with -persistent connections (aka keepalives). -When the connection is idle and the server closes the connection -(based on the -KeepAliveTimeout), the client is programmed so that the client does -not send back a FIN and ACK to the server. This means that the -connection stays in the FIN_WAIT_2 state until one of the following -happens:-
-
-
- The client opens a new connection to the same or a different - site, which causes it to fully close the older connection on - that socket. -
- The user exits the client, which on some (most?) clients - causes the OS to fully shutdown the connection. -
- The FIN_WAIT_2 times out, on servers that have a timeout - for this state. -
-If you are lucky, this means that the buggy client will fully close the -connection and release the resources on your server. However, there -are some cases where the socket is never fully closed, such as a dialup -client disconnecting from their provider before closing the client. -In addition, a client might sit idle for days without making another -connection, and thus may hold its end of the socket open for days -even though it has no further use for it. -This is a bug in the browser or in its operating system's -TCP implementation.
- -The clients on which this problem has been verified to exist:
-
-
-
- Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE i386) -
- Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE i386) -
- Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m) -
- MSIE 3.01 on the Macintosh -
- MSIE 3.01 on Windows 95 -
- -This does not appear to be a problem on: -
-
-
- Mozilla/3.01 (Win95; I) -
- -It is expected that many other clients have the same problem. What a -client should do is periodically check its open -socket(s) to see if they have been closed by the server, and close their -side of the connection if the server has closed. This check need only -occur once every few seconds, and may even be detected by a OS signal -on some systems (e.g., Win95 and NT clients have this capability, but -they seem to be ignoring it).
- -Apache cannot avoid these FIN_WAIT_2 states unless it -disables persistent connections for the buggy clients, just -like we recommend doing for Navigator 2.x clients due to other bugs. -However, non-persistent connections increase the total number of -connections needed per client and slow retrieval of an image-laden -web page. Since non-persistent connections have their own resource -consumptions and a short waiting period after each closure, a busy server -may need persistence in order to best serve its clients.
- -As far as we know, the client-caused FIN_WAIT_2 problem is present for -all servers that support persistent connections, including Apache 1.1.x -and 1.2.
- -
Something in Apache may be broken
- -While the above bug is a problem, it is not the whole problem. -Some users have observed no FIN_WAIT_2 problems with Apache 1.1.x, -but with 1.2b enough connections build up in the FIN_WAIT_2 state to -crash their server. We have not yet identified why this would occur -and welcome additional test input.- -One possible (and most likely) source for additional FIN_WAIT_2 states -is a function called
lingering_close()which was added -between 1.1 and 1.2. This function is necessary for the proper -handling of persistent connections and any request which includes -content in the message body (e.g., PUTs and POSTs). -What it does is read any data sent by the client for -a certain time after the server closes the connection. The exact -reasons for doing this are somewhat complicated, but involve what -happens if the client is making a request at the same time the -server sends a response and closes the connection. Without lingering, -the client might be forced to reset its TCP input buffer before it -has a chance to read the server's response, and thus understand why -the connection has closed. -See the appendix for more details.- -We have not yet tracked down the exact reason why -
lingering_close()causes problems. Its code has been -thoroughly reviewed and extensively updated in 1.2b6. It is possible -that there is some problem in the BSD TCP stack which is causing the -observed problems. It is also possible that we fixed it in 1.2b6. -Unfortunately, we have not been able to replicate the problem on our -test servers.- -
- What can I do about it?
-
-There are several possible workarounds to the problem, some of
-which work better than others.
- -
Add a timeout for FIN_WAIT_2
- -The obvious workaround is to simply have a timeout for the FIN_WAIT_2 state. -This is not specified by the RFC, and could be claimed to be a -violation of the RFC, but it is widely recognized as being necessary. -The following systems are known to have a timeout: --
-
-
- FreeBSD versions starting at 2.0 or possibly earlier. -
- NetBSD version 1.2(?) -
- OpenBSD all versions(?) -
- BSD/OS 2.1, with the - - K210-027 patch installed. -
- Solaris as of around version
- 2.2. The timeout can be tuned by using
nddto - modifytcp_fin_wait_2_flush_interval, but the - default should be appropriate for most servers and improper - tuning can have negative impacts. - - SCO TCP/IP Release 1.2.1 - can be modified to have a timeout by following - SCO's instructions. -
- Linux 2.0.x and - earlier(?) -
- HP-UX 10.x defaults to
- terminating connections in the FIN_WAIT_2 state after the
- normal keepalive timeouts. This does not
- refer to the persistent connection or HTTP keepalive
- timeouts, but the
SO_LINGERsocket option - which is enabled by Apache. This parameter can be adjusted - by usingnettuneto modify parameters such as -tcp_keepstartandtcp_keepstop. - In later revisions, there is an explicit timer for - connections in FIN_WAIT_2 that can be modified; contact HP - support for details. - - SGI IRIX can be patched to - support a timeout. For IRIX 5.3, 6.2, and 6.3, - use patches 1654, 1703 and 1778 respectively. If you - have trouble locating these patches, please contact your - SGI support channel for help. -
- NCR's MP RAS Unix 2.xx and - 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it is non-tunable - at 600 seconds, while in 3.xx it defaults to 600 seconds and - is calculated based on the tunable "max keep alive probes" - (default of 8) multiplied by the "keep alive interval" (default - 75 seconds). -
- Squent's ptx/TCP/IP for - DYNIX/ptx has had a FIN_WAIT_2 timeout since around - release 4.1 in mid-1994. -
-The following systems are known to not have a timeout: -
-
-
-
- SunOS 4.x does not and - almost certainly never will have one because it as at the - very end of its development cycle for Sun. If you have kernel - source should be easy to patch. -
-There is a - -patch available for adding a timeout to the FIN_WAIT_2 state; it -was originally intended for BSD/OS, but should be adaptable to most -systems using BSD networking code. You need kernel source code to be -able to use it. If you do adapt it to work for any other systems, -please drop me a note at marc@apache.org. -
-
Compile without using
- -It is possible to compile Apache 1.2 without using the -lingering_close()lingering_close()function. This will result in that -section of code being similar to that which was in 1.1. If you do -this, be aware that it can cause problems with PUTs, POSTs and -persistent connections, especially if the client uses pipelining. -That said, it is no worse than on 1.1, and we understand that keeping your -server running is quite important.- -To compile without the
lingering_close()function, add --DNO_LINGCLOSEto the end of the -EXTRA_CFLAGSline in yourConfigurationfile, -rerunConfigureand rebuild the server. --
Use
- -On most systems, there is an option calledSO_LINGERas an alternative to -lingering_close()SO_LINGERthat -can be set withsetsockopt(2). It does something very -similar tolingering_close(), except that it is broken -on many systems so that it causes far more problems than -lingering_close. On some systems, it could possibly work -better so it may be worth a try if you have no other alternatives.- -To try it, add
-DUSE_SO_LINGER -DNO_LINGCLOSEto the end of the -EXTRA_CFLAGSline in yourConfiguration-file, rerunConfigureand rebuild the server.- -NOTE: Attempting to use
SO_LINGERand -lingering_close()at the same time is very likely to do -very bad things, so don't.- -
Increase the amount of memory used for storing connection state
--
-
- BSD based networking code: -
- BSD stores network data, such as connection states,
-in something called an mbuf. When you get so many connections
-that the kernel does not have enough mbufs to put them all in, your
-kernel will likely crash. You can reduce the effects of the problem
-by increasing the number of mbufs that are available; this will not
-prevent the problem, it will just make the server go longer before
-crashing.
- -The exact way to increase them may depend on your OS; look -for some reference to the number of "mbufs" or "mbuf clusters". On -many systems, this can be done by adding the line -
NMBCLUSTERS="n", wherenis the number of -mbuf clusters you want to your kernel config file and rebuilding your -kernel.-
- Feedback
-
-If you have any information to add to this page, please contact me at
-marc@apache.org.
- -
-- Appendix
-Below is a message from Roy Fielding, one of the authors of HTTP/1.1. - -
Why the lingering close functionality is necessary with HTTP
- -The need for a server to linger on a socket after a close is noted a couple -times in the HTTP specs, but not explained. This explanation is based on -discussions between myself, Henrik Frystyk, Robert S. Thau, Dave Raggett, -and John C. Mallery in the hallways of MIT while I was at W3C.- -If a server closes the input side of the connection while the client -is sending data (or is planning to send data), then the server's TCP -stack will signal an RST (reset) back to the client. Upon -receipt of the RST, the client will flush its own incoming TCP buffer -back to the un-ACKed packet indicated by the RST packet argument. -If the server has sent a message, usually an error response, to the -client just before the close, and the client receives the RST packet -before its application code has read the error message from its incoming -TCP buffer and before the server has received the ACK sent by the client -upon receipt of that buffer, then the RST will flush the error message -before the client application has a chance to see it. The result is -that the client is left thinking that the connection failed for no -apparent reason.
- -There are two conditions under which this is likely to occur: -
-
-
- sending POST or PUT data without proper authorization -
- sending multiple requests before each response (pipelining) - and one of the middle requests resulting in an error or - other break-the-connection result. -
-The solution in all cases is to send the response, close only the -write half of the connection (what shutdown is supposed to do), and -continue reading on the socket until it is either closed by the -client (signifying it has finally read the response) or a timeout occurs. -That is what the kernel is supposed to do if SO_LINGER is set. -Unfortunately, SO_LINGER has no effect on some systems; on some other -systems, it does not have its own timeout and thus the TCP memory -segments just pile-up until the next reboot (planned or not).
- -Please note that simply removing the linger code will not solve the -problem -- it only moves it to a different and much harder one to detect. -
- -
-
diff --git a/docs/manual/misc/header.html b/docs/manual/misc/header.html
deleted file mode 100644
index 8b23a1ccba0..00000000000
--- a/docs/manual/misc/header.html
+++ /dev/null
@@ -1,3 +0,0 @@
-![[APACHE DOCUMENTATION]](../images/sub.gif)
-Apache HOWTO documentation
- -How to: --
-
- redirect an entire server or directory to a single URL -
- reset your log files -
- stop/restrict robots -
-
How to redirect an entire server or directory to a single URL
- -There are two chief ways to redirect all requests for an entire
-server to a single location: one which requires the use of
-mod_rewrite, and another which uses a CGI script.
-
-
First: if all you need to do is migrate a server from one name to
-another, simply use the Redirect directive, as supplied
-by mod_alias:
-
-
- -- Redirect / http://www.apache.org/ -
Since Redirect will forward along the complete path,
-however, it may not be appropriate - for example, when the directory
-structure has changed after the move, and you simply want to direct people
-to the home page.
-
-
The best option is to use the standard Apache module mod_rewrite.
-If that module is compiled in, the following lines:
-
-
- -This will send an HTTP 302 Redirect back to the client, and no matter -what they gave in the original URL, they'll be sent to -"http://www.apache.org". - -The second option is to set up aRewriteEngine On -RewriteRule /.* http://www.apache.org/ [R] -
ScriptAlias pointing to
-a cgi script which outputs a 301 or 302 status and the location
-of the other server.
-
-By using a cgi-script you can intercept various requests and -treat them specially, e.g. you might want to intercept POST -requests, so that the client isn't redirected to a script on the other -server which expects POST information (a redirect will lose the POST -information.) You might also want to use a CGI script if you don't -want to compile mod_rewrite into your server. - -
Here's how to redirect all requests to a script... In the server -configuration file, -
- -and here's a simple perl script to redirect requests: - -ScriptAlias / /usr/local/httpd/cgi-bin/redirect_script
- --#!/usr/local/bin/perl - -print "Status: 302 Moved Temporarily\r -Location: http://www.some.where.else.com/\r\n\r\n"; - -
- -
How to reset your log files
- -Sooner or later, you'll want to reset your log files (access_log and -error_log) because they are too big, or full of old information you don't -need.
- -access.log typically grows by 1Mb for each 10,000 requests.
Most people's first attempt at replacing the logfile is to just move the -logfile or remove the logfile. This doesn't work.
- -Apache will continue writing to the logfile at the same offset as before the -logfile moved. This results in a new logfile being created which is just -as big as the old one, but it now contains thousands (or millions) of null -characters.
- -The correct procedure is to move the logfile, then signal Apache to tell it to reopen the logfiles.
- -Apache is signaled using the SIGHUP (-1) signal. e.g. -
-mv access_log access_log.old
-kill -1 `cat httpd.pid`
-Note: httpd.pid is a file containing the process id
-of the Apache httpd daemon, Apache saves this in the same directory as the log
-files.
Many people use this method to replace (and backup) their logfiles on a -nightly or weekly basis.
-- -
How to stop or restrict robots
- -Ever wondered why so many clients are interested in a file called
-robots.txt which you don't have, and never did have?
These clients are called robots (also known as crawlers, -spiders and other cute name) - special automated clients which -wander around the web looking for interesting resources.
- -Most robots are used to generate some kind of web index which -is then used by a search engine to help locate information.
- -robots.txt provides a means to request that robots limit their
-activities at the site, or more often than not, to leave the site alone.
When the first robots were developed, they had a bad reputation for sending hundreds/thousands of requests to each site, often resulting in the site being overloaded. Things have improved dramatically since then, thanks to Guidelines for Robot Writers, but even so, some robots may exhibit unfriendly behavior which the webmaster isn't willing to tolerate, and will want to stop.
- -Another reason some webmasters want to block access to robots, is to -stop them indexing dynamic information. Many search engines will use the -data collected from your pages for months to come - not much use if your -serving stock quotes, news, weather reports or anything else that will be -stale by the time people find it in a search engine.
- -If you decide to exclude robots completely, or just limit the areas
-in which they can roam, create a robots.txt file; refer
-to the robot information pages provided by Martijn Koster for the syntax.
Apache Miscellaneous Documentation
- -- Below is a list of additional documentation pages that apply to the - Apache web server development project. -
--
-
- API - -
- Description of Apache's Application Programming Interface. - -
- FAQ - -
- Frequently-Asked Questions concerning the Apache project and server - -
- Reading Client Input in Apache 1.2 - -
- Describes differences between Apache 1.1 and 1.2 in how modules - read information from the client - -
- Compatibility with NCSA - -
- Notes about Apache's compatibility with the NCSA server - -
- FIN_WAIT_2 - -
- A description of the causes of Apache processes going into the - FIN_WAIT_2 state, and what you can do about it - -
- "How-To" - -
- Instructions about how to accomplish some commonly-desired server - functionality changes - -
- Known Bugs - -
- Just what it says - a list of known bugs in each of the Apache releases - -
- No PGP - -
- Why we took PEM and PGP support out of the base Apache distribution - -
- Performance Notes (BSD 4.4) - -
- Some notes about ways to improve/optimize Apache performance on - BSD 4.4 systems - -
- Performance Notes (Digital UNIX) - -
- Extracts of USENET postings describing how to optimize Apache - performance on Digital UNIX systems - -
- Performance Notes (General) - -
- Some generic notes about how to improve Apache performance - -
- Security Tips - -
- Some "do"s - and "don't"s - for keeping your - Apache web site secure - -
- Virtual Hosts (IP-based) - -
- Excerpts and notes about configuring and using Apache IP-based virtual - hosts - -
- Windows Bug with Web Keepalive - -
- A brief description of a known problem with Microsoft Windows and - web sites accessed using keepalive connections - -
Security Tips for Server Configuration
- -- -
Some hints and tips on security issues in setting up a web server. Some of -the suggestions will be general, others specific to Apache. - -
- -
Permissions on Log File Directories
-When Apache starts, it opens the log files as the user who started the -server before switching to the user defined in the -User directive. Anyone who -has write permission for the directory where any log files are -being written to can append pseudo-arbitrary data to any file on the -system which is writable by the user who starts Apache. Since the -server is normally started by root, you should NOT give anyone -write permission to the directory where logs are stored unless you -want them to have root access. -
-
-
Server Side Includes
-Server side includes (SSI) can be configured so that users can execute -arbitrary programs on the server. That thought alone should send a shiver -down the spine of any sys-admin.
- -One solution is to disable that part of SSI. To do that you use the -IncludesNOEXEC option to the Options -directive.
- -
- -
Non Script Aliased CGI
-Allowing users to execute CGI scripts in any directory should only -be considered if; -
-
-
- You trust your users not to write scripts which will deliberately or -accidentally expose your system to an attack. -
- You consider security at your site to be so feeble in other areas, as to -make one more potential hole irrelevant. -
- You have no users, and nobody ever visits your server. -
-
- -
Script Alias'ed CGI
-Limiting CGI to special directories gives the admin control over -what goes into those directories. This is inevitably more secure than -non script aliased CGI, but only if users with write access to the -directories are trusted or the admin is willing to test each new CGI -script/program for potential security holes.
- -Most sites choose this option over the non script aliased CGI approach.
- -
-
CGI in general
-Always remember that you must trust the writers of the CGI script/programs -or your ability to spot potential security holes in CGI, whether they were -deliberate or accidental.
- -All the CGI scripts will run as the same user, so they have potential to -conflict (accidentally or deliberately) with other scripts e.g. -User A hates User B, so he writes a script to trash User B's CGI -database. One program which can be used to allow scripts to run -as different users is suEXEC which is -included with Apache as of 1.2 and is called from special hooks in -the Apache server code. Another popular way of doing this is with -CGIWrap.
- -
- - -
Stopping users overriding system wide settings...
-To run a really tight ship, you'll want to stop users from setting
-up .htaccess files which can override security features
-you've configured. Here's one way to do it...
- -In the server configuration file, put -
-<Directory />
-AllowOverride None
-Options None
-allow from all
-</Directory>
-- -This stops all overrides, Includes and accesses in all directories apart -from those named.
-
-
- Protect server files by default -
--One aspect of Apache which is occasionally misunderstood is the feature -of default access. That is, unless you take steps to change it, if the -server can find its way to a file through normal URL mapping rules, it -can serve it to clients. -
--For instance, consider the following example: -
--
-
- # cd /; ln -s / public_html - -
- Accessing http://localhost/~root/ - -
-This would allow clients to walk through the entire filesystem. To work -around this, add the following block to your server's configuration: -
-- <Directory /> - Order deny,allow - Deny from all - </Directory> --
-This will forbid default access to filesystem locations. Add -appropriate -<Directory> -blocks to allow access only -in those areas you wish. For example, -
-- <Directory /usr/users/*/public_html> - Order deny,allow - Allow from all - </Directory> - <Directory /usr/local/httpd> - Order deny,allow - Allow from all - </Directory> --
-Pay particular attention to the interactions of -<Location> -and -<Directory> -directives; for instance, even if <Directory /> -denies access, a <Location /> directive might -overturn it. -
--Also be wary of playing games with the -UserDir -directive; setting it to something like "./" -would have the same effect, for root, as the first example above. -
- --
Please send any other useful security tips to The Apache Group -by filling out a -problem report, or by -sending mail to -apache-bugs@mail.apache.org -
-
- - - - diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html deleted file mode 100644 index fde6c351a23..00000000000 --- a/docs/manual/mod/core.html +++ /dev/null @@ -1,1429 +0,0 @@ - - - -
Apache Core Features
- -These configuration parameters control the core Apache features, and are -always available. - - --
-
- AccessConfig -
- AccessFileName -
- AddModule -
- AllowOverride -
- AuthName -
- AuthType -
- BindAddress -
- ClearModuleList -
- DefaultType -
- <Directory> -
- DocumentRoot -
- ErrorDocument -
- ErrorLog -
- <Files> -
- Group -
- HostNameLookups -
- IdentityCheck -
- <IfModule> -
- KeepAlive -
- KeepAliveTimeout -
- <Limit> -
- Listen -
- <Location> -
- MaxClients -
- MaxKeepAliveRequests -
- MaxRequestsPerChild -
- MaxSpareServers -
- MinSpareServers -
- Options -
- PidFile -
- Port -
- require -
- ResourceConfig -
- RLimitCPU -
- RLimitMEM -
- RLimitNPROC -
- Satisfy -
- ScoreBoardFile -
- SendBufferSize -
- ServerAdmin -
- ServerAlias -
- ServerName -
- ServerPath -
- ServerRoot -
- ServerType -
- StartServers -
- TimeOut -
- User -
- <VirtualHost> -
- -
AccessConfig directive
- -Syntax: AccessConfig filename-Default:
AccessConfig conf/access.conf-Context: server config, virtual host
-Status: core
- -The server will read this file for more directives after reading the -ResourceConfig file. Filename is -relative to the ServerRoot. -This feature can be disabled using: -
AccessConfig /dev/null- -
AccessFileName directive
- -Syntax: AccessFileName filename-Default:
AccessFileName .htaccess-Context: server config, virtual host
-Status: core
- -When returning a document to the client the server looks for an -access control file with this name in every directory of the path to -the document, if access control files are enabled for that directory. - -For example: -
AccessFileName .acl
-<Directory />
-AllowOverride None
-</Directory>- -
AddModule directive
- -Syntax: AddModule module module ...-Context: server config
-Status: core
-Compatibility: AddModule is only available in Apache 1.2 and later
- -The server can have modules compiled in which are not actively in use. -This directive can be used to enable the use of those modules. The -server comes with a pre-loaded list of active modules; this list can -be cleared with the ClearModuleList -directive.
- -
AllowOverride directive
- -Syntax: AllowOverride override override ...-Default:
AllowOverride All-Context: directory
-Status: core
- -When the server finds an .htaccess file (as specified by -AccessFileName) it needs to know which -directives declared in that file can override earlier access information.
-
-Override can be set to None, in which case the server
-will not read the file, All in which case the server will
-allow all the directives, or one or more of the following:
-
-
-
- AuthConfig -
- - -Allow use of the authorization directives -(AuthDBMGroupFile, -AuthDBMUserFile, -AuthGroupFile, -AuthName, AuthType, -AuthUserFile, -require, etc.). -
- FileInfo -
- - -Allow use of the directives controlling document types -(AddEncoding, -AddLanguage, -AddType, -DefaultType, -ErrorDocument, -LanguagePriority, etc.). -
- Indexes -
- - -Allow use of the directives controlling directory indexing -(AddDescription, -AddIcon, -AddIconByEncoding, -AddIconByType, -DefaultIcon, -DirectoryIndex, -FancyIndexing, -HeaderName, -IndexIgnore, -IndexOptions, -ReadmeName, etc.). -
- Limit -
- - -Allow use of the directives controlling host access (allow, deny and order). -
- Options -
- - -Allow use of the directives controlling specific directory features -(Options and -XBitHack). -
- -
AuthName directive
- -Syntax: AuthName auth-domain-Context: directory, .htaccess
-Override: AuthConfig
-Status: core
- -This directive sets the name of the authorization realm for a directory. -This realm is given to the client so that the user knows which username and -password to send. -It must be accompanied by AuthType and -require directives, and directives such as -AuthUserFile and -AuthGroupFile to work.
- -
AuthType directive
- -Syntax: AuthType type-Context: directory, .htaccess
-Override: AuthConfig
-Status: core
-
-This directive selects the type of user authentication for a directory.
-Only Basic is currently implemented.
-
-It must be accompanied by AuthName and
-require directives, and directives such as
-AuthUserFile and
-AuthGroupFile to work.
- -
BindAddress directive
- -Syntax: BindAddress saddr-Default:
BindAddress *-Context: server config
-Status: core
- -A Unix® http server can either listen for connections to every -IP address of the server machine, or just one IP address of the server -machine. Saddr can be - -
-If the value is *, then the server will listen for connections on -every IP address, otherwise it will only listen on the IP address -specified.- -This option can be used as an alternative method for supporting -virtual hosts instead of using -<VirtualHost> sections. - -
See Also:
-DNS Issues
-See Also:
-Setting which addresses and ports Apache uses
- -
ClearModuleList directive
- -Syntax: ClearModuleList-Context: server config
-Status: core
-Compatibility: ClearModuleList is only available in Apache 1.2 and later
- -The server comes with a built-in list of active modules. This -directive clears the list. It is assumed that the list will then be -re-populated using the AddModule directive.
- -
DefaultType directive
- -Syntax: DefaultType mime-type-Default:
DefaultType text/html-Context: server config, virtual host, directory, .htaccess
-Override: FileInfo
-Status: core
- -There will be times when the server is asked to provide a document -whose type cannot be determined by its MIME types mappings.
-
-The server must inform the client of the content-type of the document, so in
-the event of an unknown type it uses the DefaultType. For
-example:
-
DefaultType image/gif- -
<Directory> directive
- -Syntax: <Directory directory> ... </Directory>-Context: server config, virtual host
-Status: Core.
- -<Directory> and </Directory> are used to enclose a group of -directives which will apply only to the named directory and sub-directories -of that directory. Any directive which is allowed in a directory -context may be used. Directory is either the full path to a directory, -or a wild-card string. In a wild-card string, `?' matches any single character, -and `*' matches any sequences of characters. Example: -
- <Directory /usr/local/httpd/htdocs> - Options Indexes FollowSymLinks - </Directory> -- -
Apache 1.2 and above:
-Extended regular expressions can also be used, with the addition of the
-~ character. For example:
- <Directory ~ "^/www/.*/[0-9]{3}">
-
-
-would match directories in /www/ that consisted of three numbers.- -
If multiple directory sections match the directory (or its parents) containing -a document, then the directives are applied in the order of shortest match -first, interspersed with the directives from the -.htaccess files. For example, with -
-<Directory />
-AllowOverride None
-</Directory>
-<Directory /home/*>
-AllowOverride FileInfo
-</Directory>/home/web/dir/doc.html the
-steps are:
-
-
-- -Note that the default Apache access for <Directory /> is -Allow from All. This means that Apache will serve any file -mapped from an URL. It is recommended that you change this with a block -such as - -
- <Directory /> - Order Deny,Allow - Deny from All - </Directory> --
- -and then override this for directories you want accessible. -See the -Security Tips -page for more details. - -
- -The directory sections typically occur in the access.conf file, but they -may appear in any configuration file. <Directory> directives cannot -nest, and cannot appear in a <Limit> section. -- -
DocumentRoot directive
- -Syntax: DocumentRoot directory-filename-Default:
DocumentRoot
-/usr/local/etc/httpd/htdocs-Context: server config, virtual host
-Status: core
- -This directive sets the directory from which httpd will serve files. -Unless matched by a directive like Alias, the server appends the path -from the requested URL to the document root to make the path to the -document. Example: -
DocumentRoot /usr/webhttp://www.my.host.com/index.html refers
-to /usr/web/index.html.
-
-There appears to be a bug in mod_dir which causes problems when the -DocumentRoot has a trailing slash (i.e. "DocumentRoot /usr/web/") so -please avoid that. - -
- -
ErrorDocument directive
- -Syntax: ErrorDocument error-code document-Context server config, virtual host, directory, .htaccess
-Status: core
-Override: FileInfo
-Compatibility: The directory and .htaccess contexts -are only available in Apache 1.1 and later.
- -In the event of a problem or error, Apache can be configured to do -one of four things, - -
-
-
- output a simple hardcoded error message -
- output a customized message -
- redirect to a local URL to handle the problem/error -
- redirect to an external URL to handle the problem/error -
The first option is the default, while options 2-4 are configured
-using the ErrorDocument directive, which is followed by
-the HTTP response code and a message or URL.
-
-
Messages in this context begin with a single quote
-("), which does not form part of the message itself.
-Apache will sometimes offer additional information regarding the
-problem/error.
-
-
URLs can begin with a slash (/) for local URLs, or be a full -URL which the client can resolve. Examples: -
-ErrorDocument 500 http://foo.example.com/cgi-bin/tester
-ErrorDocument 404 /cgi-bin/bad_urls.pl
-ErrorDocument 401 /subscription_info.html
-ErrorDocument 403 "Sorry can't allow you access today
-Note that when you specify an ErrorDocument that
-points to a remote URL (ie. anything with a method such as "http" in
-front of it) Apache will send a redirect to the client to tell it
-where to find the document, even if the document ends up being
-on the same server.. This has several implications, the
-most important being that if you use an "ErrorDocument 401"
-directive then it must refer to a local document. This results
-from the nature of the HTTP basic authentication scheme.
-
-
See Also: documentation of customizable -responses.
- -
ErrorLog directive
- -Syntax: ErrorLog filename-Default:
ErrorLog logs/error_log-Context: server config, virtual host
-Status: core
- -The error log directive sets the name of the file to which the server will log -any errors it encounters. If the filename does not begin with a slash (/) -then it is assumed to be relative to the ServerRoot. -Example: -
ErrorLog /dev/null- -SECURITY: See the security tips -document for details on why your security could be compromised if -the directory where logfiles are stored is writable by anyone other -than the user that starts the server. - -
- -
<Files>
-Syntax: <Files filename> -... </Files>-Context: server config, virtual host, htaccess
-Status: core
-Compatibility: only available in Apache -1.2 and above.
- -
The <Files> directive provides for access control by
-filename. It is comparable to the <Directory> directive and
-<Location> directives. It
-should be matched with a </Files> directive. Directives that
-apply to the filename given should be listed
-within. <Files> sections are processed in the
-order they appear in the configuration file, after the
-<Directory> sections and .htaccess files are
-read, but before <Location> sections.
The filename argument should include a filename, or a
-wild-card string, where `?' matches any single character, and `*' matches any
-sequences of characters. Extended regular expressions can also be used, with the addition of
-the ~ character. For example:
- <Files ~ "\.(gif|jpe?g|png)$"> -- -would match most common Internet graphics formats. - -
Note that unlike <Directory> and <Location> sections,
-<Files> sections can be used inside .htaccess
-files. This allows users to control access to their own files, at a
-file-by-file level. When used in an .htaccess file, if the
-filename does not begin with a / character,
-the directory being applied will be prefixed automatically.
-
-
- -
Group directive
- -Syntax: Group unix-group-Default:
Group #-1-Context: server config, virtual host
-Status: core
- -The Group directive sets the group under which the server will answer requests. -In order to use this directive, the stand-alone server must be run initially -as root. Unix-group is one of: -
-
-
- A group name -
- Refers to the given group by name. -
- # followed by a group number. -
- Refers to a group by its number. -
nobody, but this is not always
-possible or desirable.- -Note: if you start the server as a non-root user, it will fail to change -to the specified group, and will instead continue to run as the group of the -original user.
- -Special note: Use of this directive in <VirtualHost> requires a -properly configured suEXEC wrapper. -When used inside a <VirtualHost> in this manner, only the group -that CGIs are run as is affected. Non-CGI requests are still processed -as the group specified in the main Group directive.
- -SECURITY: See User for a discussion of the security -considerations.
- -
HostNameLookups directive
- -Syntax: HostNameLookups boolean-Default:
HostNameLookups on-Context: server config, virtual host
-Status: core
-
-This directive enables DNS lookups so that host names can be logged.
-Having this directive set on also enables the use of names
-in <Limit> blocks for access control.
-
-Heavily loaded sites should set this directive off, since DNS
-lookups can take considerable amounts of time. The utility logresolve,
-provided in the /support directory, can be used to look up host names
-from logged IP addresses offline.
- -
IdentityCheck directive
- -Syntax: IdentityCheck boolean-Default:
IdentityCheck off-Context: server config, virtual host
-Status: core
-
-This directive enables RFC1413-compliant logging of the remote user name
-for each connection, where the client machine runs identd or something similar.
-This information is logged in the access log. Boolean is either
-on or off.
- -The information should not be trusted in any way except for rudimentary usage -tracking.
- -Note that this can cause serious latency problems accessing your server -since every request requires one of these lookups to be performed. When -firewalls are involved each lookup might possibly fail and add 30 seconds -of latency to each hit. So in general this is not very useful on public -servers accessible from the Internet. -
- -
<IfModule>
-Syntax: <IfModule [!]module-name> ... -</IfModule>-Default: None
-Context: all
-Status: Core -Compatibility: ScriptLog is only available in 1.2 and -later.
- -
- -The <IfModule test>...</IfModule> -section is used to mark directives that are conditional. The -directives within an IfModule section are only -processed if the test is true. If test -is false, everything between the start and end markers -is ignored.
- -The test in the <IfModule> section directive -can be one of two forms: - -
-
-
- module name -
- !module name -
In the former case, the directives between the start and end markers -are only processed if the module named module name is compiled -in to Apache. The second format reverses the test, and only processes -the directives if module name is not compiled in. - -
The module name argument is a module name as given as the file
-name of the module, at the time it was compiled. For example,
-mod_rewrite.c.
-
-
<IfModule> sections are nest-able, which can be used to implement -simple multiple-module tests. - -
- -
KeepAlive
-Syntax: (Apache 1.1) KeepAlive max-requests-Default: (Apache 1.1)
KeepAlive 5-Syntax: (Apache 1.2) KeepAlive on/off
-Default: (Apache 1.2)
KeepAlive On-Context: server config
-Status: Core
-Compatibility: KeepAlive is only available in Apache -1.1 and later.
- -This directive enables -Keep-Alive -support. - -
Apache 1.1: Set max-requests
-to the maximum number of requests you want Apache to entertain per
-request. A limit is imposed to prevent a client from hogging your
-server resources. Set this to 0 to disable support.
-
-
Apache 1.2 and later: Set to "On" to enable -persistent connections, "Off" to disable. See also the MaxKeepAliveRequests directive.
- -KeepAliveTimeout
-Syntax: KeepAliveTimeout seconds-Default:
KeepAliveTimeout 15-Context: server config
-Status: Core
-Compatibility: KeepAliveTimeout is only available in Apache -1.1 and later.
-
-The number of seconds Apache will wait for a subsequent request before
-closing the connection. Once a request has been received, the timeout
-value specified by the Timeout directive
-applies.
-
- -
Listen
-Syntax: -Listen [IP address:]port number-Context: server config
-Status: core
-Compatibility: Listen is only available in Apache -1.1 and later.
- -
The Listen directive instructs Apache to listen to more than one IP -address or port; by default it responds to requests on all IP -interfaces, but only on the port given by the Port -directive.
- -See Also:
-DNS Issues
-See Also:
-Setting which addresses and ports Apache uses
-See Also:
-Known Bugs
- -
<Limit> directive
- -Syntax: - <Limit method method ... > ... </Limit>-Context: any
-Status: core
- -<Limit> and </Limit> are used to enclose a group of -access control directives which will then apply only to the specified -access methods, where method is any valid HTTP method. -Any directive except another <Limit> or -<Directory> may be used; the majority will be -unaffected by the <Limit>. Example: -
-<Limit GET POST>
-require valid-user
-</Limit>- -
<Location>
- -Syntax: <Location URL> -... </Location>-Context: server config, virtual host
-Status: core
-Compatibility: Location is only available in Apache -1.1 and later.
- -
The <Location> directive provides for access control by
-URL. It is comparable to the <Directory> directive, and
-should be matched with a </Location> directive. Directives that
-apply to the URL given should be listed
-within. <Location> sections are processed in the
-order they appear in the configuration file, after the
-<Directory> sections and .htaccess files are
-read.
Note that, due to the way HTTP functions, URL prefix
-should, save for proxy requests, be of the form /path/,
-and should not include the http://servername. It doesn't
-necessarily have to protect a directory (it can be an individual
-file, or a number of files), and can include wild-cards. In a wild-card
-string, `?' matches any single character, and `*' matches any
-sequences of characters.
-
-
Apache 1.2 and above:
-Extended regular expressions can also be used, with the addition of
-the
-~ character. For example:
- <Location ~ "/(extra|special)/data"> -- -would match URLs that contained the substring "/extra/data" or -"/special/data". - -
The Location functionality is especially useful when
-combined with the SetHandler directive. For example, to enable status requests, but allow them only
-from browsers at foo.com, you might use:
-
-
- <Location /status> - SetHandler server-status - order deny,allow - deny from all - allow from .foo.com - </Location> --
- -
MaxClients directive
- -Syntax: MaxClients number-Default:
MaxClients 256-Context: server config
-Status: core
- -The MaxClients directive sets the limit on the number of simultaneous -requests that can be supported; not more than this number of child server -processes will be created.
- -
MaxKeepAliveRequests
-Syntax: MaxKeepAliveRequests number-Default:
MaxKeepAliveRequests 100-Context: server config
-Status: core
-Compatibility: Only available in Apache -1.2 and later. - -
The MaxKeepAliveRequests directive limits the number of requests
-allowed per connection when KeepAlive is
-on. If it is set to "0", unlimited requests will be
-allowed. We recommend that this setting be kept to a high value for
-maximum server performance.
-
-MaxRequestsPerChild directive
-
-Syntax: MaxRequestsPerChild number
-Default: MaxRequestsPerChild 0
-Context: server config
-Status: core
- -The MaxRequestsPerChild directive sets the limit on the number of requests -that an individual child server process will handle. After MaxRequestsPerChild -requests, the child process will die. If MaxRequestsPerChild is 0, then -the process will never expire.
- -Setting MaxRequestsPerChild to a non-zero limit has two beneficial effects: -
-
-
- it limits the amount of memory that process can consume by (accidental) -memory leakage; -
- by giving processes a finite lifetime, it helps reduce the -number of processes when the server load reduces. -
- -
MaxSpareServers directive
- -Syntax: MaxSpareServers number-Default:
MaxSpareServers 10-Context: server config
-Status: core
- -The MaxSpareServers directive sets the desired maximum number of idle -child server processes. An idle process is one which is not handling -a request. If there are more than MaxSpareServers idle, then the parent -process will kill off the excess processes.
- -Tuning of this parameter should only be necessary on very busy sites. -Setting this parameter to a large number is almost always a bad idea.
- -See also MinSpareServers and -StartServers.
- -
MinSpareServers directive
- -Syntax: MinSpareServers number-Default:
MinSpareServers 5-Context: server config
-Status: core
- -The MinSpareServers directive sets the desired minimum number of idle -child server processes. An idle process is one which is not handling -a request. If there are fewer than MinSpareServers idle, then the parent -process creates new children at a maximum rate of 1 per second.
- -Tuning of this parameter should only be necessary on very busy sites. -Setting this parameter to a large number is almost always a bad idea.
- -See also MaxSpareServers and -StartServers.
- -
Options directive
- -Syntax: Options [+|-]option [+|-]option ...-Context: server config, virtual host, directory, .htaccess
-Override: Options
-Status: core
- -The Options directive controls which server features are available in -a particular directory. -
-option can be set to None, in which case none of
-the extra features are enabled, or one or more of the following:
-
-
-
- All -
- All options except for MultiViews. -
- ExecCGI -
- - -Execution of CGI scripts is permitted. -
- FollowSymLinks -
- - -The server will follow symbolic links in this directory. -
- Includes -
- - -Server-side includes are permitted. -
- IncludesNOEXEC -
- - -Server-side includes are permitted, but the #exec command and -#include of CGI scripts are disabled. -
- Indexes -
- - -If a URL which maps to a directory is requested, and the there is no -DirectoryIndex (e.g. index.html) in that directory, then the server will -return a formatted listing of the directory. -
- MultiViews -
- - -Content negotiated MultiViews are -allowed. -
- SymLinksIfOwnerMatch -
- - -The server will only follow symbolic links for which the target -file or directory is owned by the same user id as the link. -
Options could apply to a directory,
-then the most specific one is taken complete; the options are not
-merged. However if all the options on the Options
-directive are preceded by a + or - symbol, the options are
-merged. Any options preceded by a + are added to the options
-currently in force, and any options preceded by a - are removed from
-the options currently in force. - -For example, without any + and - symbols: - -
-<Directory /web/docs>
-Options Indexes FollowSymLinks
-</Directory>
-<Directory /web/docs/spec>
-Options Includes
-</Directory>
-Includes will be set for the /web/docs/spec
-directory. However if the second Options directive uses the +
-and - symbols:- -
-<Directory /web/docs>
-Options Indexes FollowSymLinks
-</Directory>
-<Directory /web/docs/spec>
-Options +Includes -Indexes
-</Directory>
-FollowSymLinks and Includes
-are set for the /web/docs/spec directory.
-- -
PidFile directive
- -Syntax: PidFile filename-Default:
PidFile logs/httpd.pid-Context: server config
-Status: core
- -The PidFile directive sets the file to which the server records the -process id of the daemon. If the filename does not begin with a slash (/) -then it is assumed to be relative to the ServerRoot. -The PidFile is only used in standalone mode.
- -It is often useful to be able to send the server a signal, so that it closes -and then reopens its ErrorLog and TransferLog, and -re-reads its configuration files. This is done by sending a SIGHUP (kill -1) -signal to the process id listed in the PidFile.
- -The PidFile is subject to the same warnings about log file placement and -security. - -
- -
Port directive
- -Syntax: Port number-Default:
Port 80-Context: server config
-Status: core
-
-Number is a number from 0 to 65535; some port numbers (especially below
-1024) are reserved for particular protocols. See /etc/services
-for a list of some defined ports; the standard port for the http protocol
-is 80.
- -The Port directive has two behaviors, the first of which is necessary for -NCSA backwards compatibility (and which is confusing in the context of -Apache).
- -
-
-
-
-In the absence of any Listen or
-BindAddress directives specifying a port number,
-the Port directive sets the network port on which the server listens.
-If there are any Listen or BindAddress directives specifying
-
:numberthen Port has no effect on what address the server -listens at. - - - The Port directive
-sets the
SERVER_PORTenvironment variable (for -CGI and SSI), -and is used when the server must generate a URL that refers to itself -(for example when creating an external redirect to itself). -
- -The primary behaviour of Port should be considered to be similar to that of -the ServerName directive. The ServerName -and Port together specify what you consider to be the canonical -address of the server.
- -Port 80 is one of Unix's special ports. All ports numbered -below 1024 are reserved for system use, i.e. regular (non-root) users cannot -make use of them; instead they can only use higher port numbers. -To use port 80, you must start the server from the root account. -After binding to the port and before accepting requests, Apache will change -to a low privileged user as set by the User directive.
- -If you cannot use port 80, choose any other unused port. Non-root users -will have to choose a port number higher than 1023, such as 8000.
- -SECURITY: if you do start the server as root, be sure -not to set User to root. If you run the server as -root whilst handling connections, your site may be open to a major security -attack.
- -
require directive
- -Syntax: require entity-name entity entity...-Context: directory, .htaccess
-Override: AuthConfig
-Status: core
- -This directive selects which authenticated users can access a directory. -The allowed syntaxes are: -
-
-
- require user userid userid ...
-Only the named users can access the directory.
-
- require group group-name group-name ...
-Only users in the named groups can access the directory.
-
- require valid-user
-All valid users can access the directory. -
-If require appears in a <Limit>
-section, then it restricts access to the named methods, otherwise
-it restricts access for all methods. Example:
-
-AuthType Basic
-AuthName somedomain
-AuthUserFile /web/users
-AuthGroupFile /web/groups
-<Limit GET POST>
-require group admin
-</Limit>
-- -
ResourceConfig directive
- -Syntax: ResourceConfig filename-Default:
ResourceConfig conf/srm.conf-Context: server config, virtual host
-Status: core
- -The server will read this file for more directives after reading the -httpd.conf file. Filename is relative to the -ServerRoot. -This feature can be disabled using: -
ResourceConfig /dev/null- -See also AccessConfig.
- - -
RLimitCPU directive
- -Syntax: RLimitCPU # or 'max' [# or 'max']-Default:
Unset uses operating system defaults-Context: server config, virtual host
-Status: core
-Compatibility: RLimitCPU is only available in Apache 1.2 and later
- -Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all -processes and the second parameter sets the maximum resource limit. Either parameter -can be a number, or max to indicate to the server that the limit should -be set to the maximum allowed by the operating system configuration. Raising the -maximum resource limit requires that the server is running as root, or in the initial -startup phase.
- -CPU resource limits are expressed in seconds per process.
- -See also RLimitMEM or RLimitNPROC.
- -
RLimitMEM directive
- -Syntax: RLimitMEM # or 'max' [# or 'max']-Default:
Unset uses operating system defaults-Context: server config, virtual host
-Status: core
-Compatibility: RLimitMEM is only available in Apache 1.2 and later
- -Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all -processes and the second parameter sets the maximum resource limit. Either parameter -can be a number, or max to indicate to the server that the limit should -be set to the maximum allowed by the operating system configuration. Raising the -maximum resource limit requires that the server is running as root, or in the initial -startup phase.
- -Memory resource limits are expressed in bytes per process.
- -See also RLimitCPU or RLimitNPROC.
- -
RLimitNPROC directive
- -Syntax: RLimitNPROC # or 'max' [# or 'max']-Default:
Unset uses operating system defaults-Context: server config, virtual host
-Status: core
-Compatibility: RLimitNPROC is only available in Apache 1.2 and later
- -Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all -processes and the second parameter sets the maximum resource limit. Either parameter -can be a number, or max to indicate to the server that the limit should -be set to the maximum allowed by the operating system configuration. Raising the -maximum resource limit requires that the server is running as root, or in the initial -startup phase.
- -Process limits control the number of processes per user.
- -Note: If CGI processes are not running under userids other than the -web server userid, this directive will limit the number of processes that the -server itself can create. Evidence of this situation will be indicated by -cannot fork messages in the error_log.
- -See also RLimitMEM or RLimitCPU. - -
- -
Satisfy
- -Syntax: Satisfy 'any' or 'all'-Default: Satisfy all
-Context: directory, .htaccess
-Status: core
-Compatibility: Satisfy is only available in Apache 1.2 and later
- -Access policy if both allow and require used. The parameter can be -either 'all' or 'any'. This directive is only useful -if access to a particular area is being restricted by both -username/password and client host address. In this case the -default behavior ("all") is to require that the client passes the -address access restriction and enters a valid username and -password. With the "any" option the client will be granted access if -they either pass the host restriction or enter a valid username and -password. This can be used to password restrict an area, but to let -clients from particular addresses in without prompting for a password. - - -
- -
ScoreBoardFile directive
- -Syntax: ScoreBoardFile filename-Default:
ScoreBoardFile logs/apache_status-Context: server config
-Status: core
- -The ScoreBoardFile directive is required on some architectures to place -a file that the server will use to communicate between its children and -the parent. The easiest way to find out if your architecture requires -a scoreboard file is to run Apache and see if it creates the file named -by the directive. If your architecture requires it then you must ensure -that this file is not used at the same time by more than one invocation -of Apache.
- -If you have to use a ScoreBoardFile then you may see improved speed by -placing it on a RAM disk. But be careful that you heed the same warnings -about log file placement and -security.
- -Apache 1.2 and above:
-
-Linux 1.x users might be able to add -DHAVE_SHMGET to
-the EXTRA_CFLAGS in your Configuration. This
-might work with some 1.x installations, but won't work with all of
-them.
-
-SVR4 users should consider adding -DHAVE_SHMGET to the
-EXTRA_CFLAGS in your Configuration. This
-is believed to work, but we were unable to test it in time for 1.2
-release.
- -See Also: -Stopping and Restarting Apache
- -- -
SendBufferSize directive
- -Syntax: SendBufferSize bytes-Context: server config, virtual host
-Status: core
- -The server will set the TCP buffer size to the number of bytes -specified. Very useful to increase past standard OS defaults on high -speed high latency (i.e. 100ms or so, such as transcontinental -fast pipes) -
- -
ServerAdmin directive
- -Syntax: ServerAdmin email-address-Context: server config, virtual host
-Status: core
- -The ServerAdmin sets the e-mail address that the server includes in any -error messages it returns to the client.
- -It may be worth setting up a dedicated address for this, e.g. -
ServerAdmin www-admin@foo.bar.com- -
ServerAlias directive
- -Syntax: ServerAlias host1 host2 ...-Context: virtual host
-Status: core
-Compatibility: ServerAlias is only available in Apache -1.1 and later.
- -The ServerAlias directive sets the alternate names for a host, for use -with -Host-header based virtual hosts. -
See Also: -In-depth description of Virtual Host matching
- -- -
ServerName directive
- -Syntax: ServerName fully-qualified domain name-Context: server config, virtual host
-Status: core
- -The ServerName directive sets the hostname of the server; this is only -used when creating redirection URLs. If it is not specified, then the -server attempts to deduce it from its own IP address; however this may -not work reliably, or may not return the preferred hostname. For example: -
ServerName www.wibble.commonster.wibble.com.-
See Also: -DNS Issues
-- -
ServerPath directive
- -Syntax: ServerPath pathname-Context: virtual host
-Status: core
-Compatibility: ServerPath is only available in Apache -1.1 and later.
- -The ServerPath directive sets the legacy URL pathname for a host, for -use with Host-header based virtual hosts. -
See Also: -In-depth description of Virtual Host matching
-- -
ServerRoot directive
- -Syntax: ServerRoot directory-filename-Default:
ServerRoot /usr/local/etc/httpd-Context: server config
-Status: core
-
-The ServerRoot directive sets the directory in which the server lives.
-Typically it will contain the subdirectories conf/ and
-logs/. Relative paths for other configuration files are taken
-as relative to this directory.
-See also the -d option to httpd.
- -
ServerType directive
- -Syntax: ServerType type-Default:
ServerType standalone-Context: server config
-Status: core
- -The ServerType directive sets how the server is executed by the system. -Type is one of -
-
-
- inetd -
- The server will be run from the system process inetd; the command to start
-the server is added to
/etc/inetd.conf- - standalone -
- The server will run as a daemon process; the command to start the server
-is added to the system startup scripts. (
/etc/rc.localor -/etc/rc3.d/....) -
- -Standalone is the most common setting for ServerType since -it is far more efficient. The server is started once, and services all -subsequent connections. If you intend running Apache to serve a busy site, -standalone will probably be your only option.
- -SECURITY: if you are paranoid about security, run in inetd mode. Security -cannot be guaranteed in either, but whilst most people are happy to use -standalone, inetd is probably least prone to attack.
- -
StartServers directive
- -Syntax: StartServers number-Default:
StartServers 5-Context: server config
-Status: core
- -The StartServers directive sets the number of child server processes created -on startup. As the number of processes is dynamically controlled depending -on the load, there is usually little reason to adjust this parameter.
- -See also MinSpareServers and -MaxSpareServers.
- -
TimeOut directive
- -Syntax: TimeOut number-Default:
TimeOut 300-Context: server config
-Status: core
- -The TimeOut directive currently defines the amount of time Apache will -wait for three things: - -
-
-
- The total amount of time it takes to receive a GET request. -
- The amount of time between receipt of TCP packets on a POST or - PUT request. -
- The amount of time between ACKs on transmissions of TCP packets - in responses. -
- -
User directive
- -Syntax: User unix-userid-Default:
User #-1-Context: server config, virtual host
-Status: core
- -The User directive sets the userid as which the server will answer requests. -In order to use this directive, the standalone server must be run initially -as root. Unix-userid is one of: -
-
-
- A username -
- Refers to the given user by name. -
- # followed by a user number. -
- Refers to a user by their number. -
nobody, but this is not always possible or desirable.- -Notes: If you start the server as a non-root user, it will fail to change -to the lesser privileged user, and will instead continue to run as -that original user. If you do start the server as root, then it is normal -for the parent process to remain running as root.
- -Special note: Use of this directive in <VirtualHost> requires a -properly configured suEXEC wrapper. -When used inside a <VirtualHost> in this manner, only the user -that CGIs are run as is affected. Non-CGI requests are still processed -with the user specified in the main User directive.
-
-SECURITY: Don't set User (or Group) to
-root unless you know exactly what you are doing, and what the
-dangers are.
- -
<VirtualHost> directive
- -Syntax: <VirtualHost addr[:port] ...> ... -</VirtualHost>-Context: server config
-Status: Core.
-Compatibility: Non-IP address-based Virtual Hosting only -available in Apache 1.1 and later.
-Compatibility: Multiple address support only available in -Apache 1.2 and later.
- -<VirtualHost> and </VirtualHost> are used to enclose a group of -directives which will apply only to a particular virtual host. -Any directive which is allowed in a virtual host context may be used. -When the server receives a request for a document on a particular virtual -host, it uses the configuration directives enclosed in the <VirtualHost> -section. Addr can be -
Example: -
-
-<VirtualHost 10.1.2.3>
-ServerAdmin webmaster@host.foo.com
-DocumentRoot /www/docs/host.foo.com
-ServerName host.foo.com
-ErrorLog logs/host.foo.com-error_log
-TransferLog logs/host.foo.com-access_log
-</VirtualHost>
-
-
-Each VirtualHost must correspond to a different IP address or a
-different host name for the server, in the latter case the server
-machine must be configured to accept IP packets for multiple
-addresses. (If the machine does not have multiple network interfaces,
-then this can be accomplished with the ifconfig alias
-command (if your OS supports it), or with kernel patches like VIF (for SunOS(TM) 4.1.x)).
-
-The special name _default_ can be specified in which case
-this virtual host will match any IP address that is not explicitly listed
-in another virtual host. In the absence of any _default_ virtual host
-the "main" server config, consisting of all those definitions outside
-any VirtualHost section, is used when no match occurs.
-
-You can specify a :port to change the port that is matched.
-If unspecified then it defaults to the same port as the most recent
-Port statement of the main server. You
-may also specify :* to match all ports on that address.
-(This is recommended when used with _default_.)
- -SECURITY: See the -security tips -document for details on why your security could be compromised if -the directory where logfiles are stored is writable by anyone other -than the user that starts the server. - -
See also:
-Warnings about DNS and Apache
-See also:
-Information on Virtual Hosts.
-(multihome)
-See also:
-Non-IP address-based Virtual Hosts
-See also:
-In-depth description of Virtual Host matching
-
Apache directives
- --
-
- AccessConfig -
- AccessFileName -
- Action -
- AddAlt -
- AddAltByEncoding -
- AddAltByType -
- AddDescription -
- AddEncoding -
- AddHandler -
- AddIcon -
- AddIconByEncoding -
- AddIconByType -
- AddLanguage -
- AddModule -
- AddType -
- AgentLog -
- Alias -
- allow -
- AllowOverride -
- Anonymous -
- Anonymous_Authoritative -
- Anonymous_LogEmail -
- Anonymous_MustGiveEmail -
- Anonymous_NoUserID -
- Anonymous_VerifyEmail -
- AuthAuthoritative -
- AuthDBAuthoritative -
- AuthDBGroupFile -
- AuthDBMAuthoritative -
- AuthDBMGroupFile -
- AuthDBMGroupFile -
- AuthDBUserFile -
- AuthDBMUserFile -
- AuthDigestFile -
- AuthGroupFile -
- AuthName -
- AuthType -
- AuthUserFile -
- BindAddress -
- BrowserMatch -
- BrowserMatchNoCase -
- CacheDefaultExpire -
- CacheDirLength -
- CacheDirLevels -
- CacheGcInterval -
- CacheLastModifiedFactor -
- CacheMaxExpire -
- CacheNegotiatedDocs -
- CacheRoot -
- CacheSize -
- ClearModuleList -
- CookieExpires -
- CookieLog (mod_cookies) -
- CookieLog (mod_log_config) -
- CookieTracking -
- CustomLog -
- DefaultIcon -
- DefaultType -
- deny -
- <Directory> -
- DirectoryIndex -
- DocumentRoot -
- ErrorDocument -
- ErrorLog -
- Example -
- ExpiresActive -
- ExpiresByType -
- ExpiresDefault -
- FancyIndexing -
- <Files> -
- ForceType -
- Group -
- Header -
- HeaderName -
- HostNameLookups -
- IdentityCheck -
- <IfModule> -
- ImapBase -
- ImapDefault -
- ImapMenu -
- IndexIgnore -
- IndexOptions -
- KeepAlive -
- KeepAliveTimeout -
- LanguagePriority -
- <Limit> -
- Listen -
- LoadFile -
- LoadModule -
- <Location> -
- LogFormat -
- MaxClients -
- MaxKeepAliveRequests -
- MaxRequestsPerChild -
- MaxSpareServers -
- MetaDir -
- MetaSuffix -
- MinSpareServers -
- NoCache -
- Options -
- order -
- PassEnv -
- PidFile -
- Port -
- ProxyBlock -
- ProxyPass -
- ProxyRemote -
- ProxyRequests -
- ReadmeName -
- Redirect -
- RedirectPermanent -
- RedirectTemp -
- RefererIgnore -
- RefererLog -
- require -
- ResourceConfig -
- RewriteBase -
- RewriteCond -
- RewriteEngine -
- RewriteLog -
- RewriteLogLevel -
- RewriteMap -
- RewriteOptions -
- RewriteRule -
- RLimitCPU -
- RLimitMEM -
- RLimitNPROC -
- Satisfy -
- ScoreBoardFile -
- Script -
- ScriptAlias -
- ScriptLog -
- ScriptLogBuffer -
- ScriptLogLength -
- SendBufferSize -
- ServerAdmin -
- ServerAlias -
- ServerName -
- ServerPath -
- ServerRoot -
- ServerType -
- SetEnv -
- SetHandler -
- StartServers -
- TimeOut -
- TransferLog (mod_log_common) -
- TransferLog (mod_log_config) -
- TypesConfig -
- UnsetEnv -
- User -
- UserDir -
- <VirtualHost> -
- XBitHack -
- -
-
diff --git a/docs/manual/mod/header.html b/docs/manual/mod/header.html
deleted file mode 100644
index 8b23a1ccba0..00000000000
--- a/docs/manual/mod/header.html
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Apache modules
- --Below is a list of all of the modules that come as part of the -Apache distribution. See also the complete alphabetical list of -all Apache directives. -
- --
-
- Core -
- Core Apache features. -
- mod_access -
- Host based access control. -
- mod_actions Apache 1.1 and later. -
- Filetype/method-based script execution -
- mod_alias -
- Aliases and redirects. -
- mod_asis -
- The .asis file handler. -
- mod_auth -
- User authentication using text files. -
- mod_auth_anon -
- Anonymous user authentication, FTP-style. -
- mod_auth_db -
- User authentication using Berkeley DB files. -
- mod_auth_dbm -
- User authentication using DBM files. -
- mod_auth_msql -
- User authentication using mSQL files. -
- mod_browser Apache 1.2 and up -
- Set environment variables based on User-Agent strings -
- mod_cern_meta -
- Support for HTTP header metafiles. -
- mod_cgi -
- Invoking CGI scripts. -
- mod_cookies up to Apache 1.1.1 -
- Support for Netscape-like cookies. Replaced in Apache 1.2 by -mod_usertrack -
- mod_digest -
- MD5 authentication -
- mod_dir -
- Automatic directory listings. -
- mod_dld -
- Start-time linking with the GNU libdld. -
- mod_env -
- Passing of environments to CGI scripts -
- mod_example Apache 1.2 and up -
- Demonstrates Apache API -
- mod_expires Apache 1.2 and up -
- Apply Expires: headers to resources -
- mod_headers Apache 1.2 and up -
- Add arbitrary HTTP headers to resources -
- mod_imap -
- The imagemap file handler. -
- mod_include -
- Server-parsed documents. -
- mod_info -
- Server configuration information -
- mod_log_agent -
- Logging of User Agents. -
- mod_log_common up to Apache 1.1.1 -
- Standard logging in the Common Logfile Format. Replaced by the -mod_log_config module in Apache 1.2 and up -
- mod_log_config -
- User-configurable logging replacement for mod_log_common. -
- mod_log_referer -
- Logging of document references. -
- mod_mime -
- Determining document types. -
- mod_negotiation -
- Content negotiation. -
- mod_rewrite Apache 1.2 and up -
- Powerful URI-to-filename mapping using regular expressions -
- mod_proxy -
- Caching proxy abilities -
- mod_status -
- Server status display -
- mod_userdir -
- User home directories. -
- mod_usertrack Apache 1.2 and up -
- User tracking using Cookies (replacement for mod_cookies.c) -
Module mod_access
- -This module is contained in themod_access.c file, and
-is compiled in by default. It provides access control based on client
-hostname or IP address.
-
-
-
-- - -
allow
- -Syntax: allow from host host ...-Context: directory, .htaccess
-Override: Limit
-Status: Base
-Module: mod_access
- -The allow directive affects which hosts can access a given directory. -Host is one of the following: -
-
-
all-- all hosts are allowed access -
- A (partial) domain-name -
- host whose name is, or ends in, this string are allowed access. -
- A full IP address -
- An IP address of a host allowed access -
- A partial IP address -
- The first 1 to 3 bytes of an IP address, for subnet restriction. -
allow from .ncsa.uiuc.edu
-
-Note that this compares whole components; bar.edu
-would not match foobar.edu.
- -See also deny, order, and -BrowserMatch.
-
-Syntax: allow from env=variablename
-Context: directory, .htaccess
-Override: Limit
-Status: Base
-Module: mod_access
-Compatibility: Apache 1.2 and above
- -The allow from env directive controls access to a directory by the -existence (or non-existence) of an environment variable. - -Example:
- -See also deny from env -and order.-BrowserMatch ^KnockKnock/2.0 let_me_in -<Directory /docroot> -order allow,deny -allow from env=let_me_in -deny from all -</Directory> -
- -
deny
- -Syntax: deny from host host ...-Context: directory, .htaccess
-Override: Limit
-Status: Base
-Module: mod_access
- -The deny directive affects which hosts can access a given directory. -Host is one of the following: -
-
-
all-- all hosts are denied access -
- A (partial) domain-name -
- host whose name is, or ends in, this string are denied access. -
- A full IP address -
- An IP address of a host denied access -
- A partial IP address -
- The first 1 to 3 bytes of an IP address, for subnet restriction. -
deny from 16
-
-Note that this compares whole components; bar.edu
-would not match foobar.edu.
-
-Syntax: deny from env=variablename
-Context: directory, .htaccess
-Override: Limit
-Status: Base
-Module: mod_access
-Compatibility: Apache 1.2 and above
- -The deny from env directive controls access to a directory by the -existence (or non-existence) of an environment variable. - -Example:
- -See also allow from env -and order.-BrowserMatch ^BadRobot/0.9 go_away -<Directory /docroot> -order deny,allow -deny from env=go_away -allow from all -</Directory> -
- -
order
- -Syntax: order ordering-Default:
order deny,allow-Context: directory, .htaccess
-Override: Limit
-Status: Base
-Module: mod_access
- -The order directive controls the order in which allow and -deny directives are evaluated. Ordering is one -of -
-
-
- deny,allow -
- the deny directives are evaluated before the allow directives. (The -initial state is OK.) -
- allow,deny -
- the allow directives are evaluated before the deny directives. (The -initial state is FORBIDDEN.) -
- mutual-failure -
- Only those hosts which appear on the allow list and do not appear -on the deny list are granted access. (The initial state is irrelevant.) -
allow and deny
-statement is evaluated, there is no "short-circuiting".
-
-Example: -
-order deny,allow
-deny from all
-allow from .ncsa.uiuc.edu
-Module mod_actions
- -This module is contained in themod_actions.c file, and
-is compiled in by default. It provides for
-executing CGI scripts based on media type or request method. It is not
-present in versions prior to Apache 1.1.
-
-Summary
- -This module lets you run CGI scripts whenever a file of a certain type -is requested. This makes it much easier to execute scripts that -process files. - -Directives
- - -- -
Action
-Syntax: Action mime-type cgi-script-Context: server config, virtual host, directory, .htaccess
-Override: FileInfo
-Status: Base
-Module: mod_actions
-Compatibility: Action is only available in Apache 1.1 -and later
- -This directive adds an action, which will activate cgi-script when -a file of content type mime-type is requested. It sends the -URL and file path of the requested document using the standard -CGI PATH_INFO and PATH_TRANSLATED environment variables. - -
- -
Script
-Syntax: Script method cgi-script-Context: server config, virtual host, directory
-Status: Base
-Module: mod_actions
-Compatibility: Script is only available in Apache 1.1 -and later
- -
This directive adds an action, which will activate cgi-script when
-a file is requested using the method of method, which can be
-one of GET, POST, PUT or
-DELETE. It sends the
-URL and file path of the requested document using the standard
-CGI PATH_INFO and PATH_TRANSLATED environment variables.
-
-
Note that the Script command defines default actions only. If a CGI
-script is called, or some other resource that is capable of handling
-the requested method internally, it will do so. Also note that script
-with a method of GET will only be called if there are
-query arguments present (e.g. foo.html?hi). Otherwise, the request
-will proceed normally.
-
-
Examples: -
- Script GET /cgi-bin/search #e.g. for <ISINDEX>-style searching - Script PUT /~bob/put.cgi - -- - - - - diff --git a/docs/manual/mod/mod_alias.html b/docs/manual/mod/mod_alias.html deleted file mode 100644 index c5c89250e30..00000000000 --- a/docs/manual/mod/mod_alias.html +++ /dev/null @@ -1,146 +0,0 @@ - - - -
Module mod_alias
- -This module is contained in themod_alias.c file, and
-is compiled in by default. It provides for mapping different parts of the
-host filesystem in the the document tree, and for URL redirection.
-
-
-
-- - -
Alias
- -Syntax: Alias url-path directory-filename-Context: server config, virtual host
-Status: Base
-Module: mod_alias
- -The Alias directive allows documents to be stored in the local filesystem -other than under the DocumentRoot. -URLs with a (%-decoded) path beginning with url-path will be -mapped to local files beginning with directory-filename. -Example: -
Alias /image /ftp/pub/image
-
-Note that if you include a trailing / on the url-path then the
-server will require a trailing / in order to expand the alias. That is,
-if you use Alias /icons/ /usr/local/etc/httpd/icons/ then
-the url /icons will not be aliased.
- -See also ScriptAlias.
- -
Redirect
- -Syntax: Redirect [ status ] url-path url-Context: server config, virtual host, directory, .htaccess
-Status: Base
-Module: mod_alias
-Compatibility: The directory and .htaccess context's -are only available in versions 1.1 and later. The status argument is only available in Apache 1.2 or later.
- -The Redirect directive maps an old URL into a new one. The new URL is returned -to the client which attempts to fetch it again with the new address. -Url-path a (%-decoded) path; any requests for documents beginning with -this path will be returned a redirect error to a new (%-encoded) url -beginning with url. Example: -
Redirect /service
-http://foo2.bar.com/service- -Note: Redirect directives take precedence over Alias and ScriptAlias -directives, irrespective of their ordering in the configuration file. Also, -Url-path must be an absolute path, not a relative path, even when used with -.htaccess files or inside of <Directory> sections.
- -If no status argument is given, the redirect will be -"temporary" (HTTP status 302). This indicates to the client that the -resources is has moved temporarily. The status -argument can be used to return other HTTP status codes: -
-
-
- permanent
- Returns a permanent redirect status (301) indicating that -the resource has moved permanently. -
- temp
- Returns a temporary redirect status (302). This is the -default. -
- seeother
- Returns a "See Other" status (303) indicating that -the resource has been replaced. -
- gone
- Returns a "Gone" status (410) indicating that the resource -has been permanently removed. When this status is used the url -argument should be omitted. -
send_error_response in http_protocol.c).
-
-RedirectTemp
- -Syntax: RedirectTemp url-path url-Context: server config, virtual host, directory, .htaccess
-Status: Base
-Module: mod_alias
-Compatibility: This directive is only available in 1.2
-
-This directive makes the client know that the Redirect is only
-temporary. (Status 302). Exactly equivalent to Redirect temporary
-
-RedirectPermanent
-
-Syntax: RedirectPermanent url-path url
-Context: server config, virtual host, directory, .htaccess
-Status: Base
-Module: mod_alias
-Compatibility: This directive is only available in 1.2
-
-This directive makes the client know that the Redirect is permanent.
-(Status 301). Exactly equivalent to Redirect permanent
- -
-
ScriptAlias
- -Syntax: ScriptAlias url-path directory-filename-Context: server config, virtual host
-Status: Base
-Module: mod_alias
- -The ScriptAlias directive has the same behavior as the -Alias directive, except that in addition it -marks the target directory as containing CGI scripts. -URLs with a (%-decoded) path beginning with url-path will be -mapped to scripts beginning with directory-filename. -Example: -
ScriptAlias /cgi-bin/ /web/cgi-bin/- - - - - diff --git a/docs/manual/mod/mod_asis.html b/docs/manual/mod/mod_asis.html deleted file mode 100644 index 85e628115e1..00000000000 --- a/docs/manual/mod/mod_asis.html +++ /dev/null @@ -1,68 +0,0 @@ - - -
-Module mod_asis
- -This module is contained in themod_asis.c file, and
-is compiled in by default. It provides for .asis files. Any
-document with mime type httpd/send-as-is will be processed by
-this module.
-
-
-Purpose
-To allow file types to be defined such that Apache sends them without -adding HTTP headers.- -This can be used to send any kind of data from the server, including redirects -and other special HTTP responses, without requiring a cgi-script or an nph -script. -
Usage
-In the server configuration file, define a new mime type called -httpd/send-as-is e.g.
-AddType httpd/send-as-is asis.asis file extension as being of the new
-httpd/send-as-is mime type. The contents of any file with a
-.asis extension will then be sent by Apache to the client with
-almost no changes. Clients will need HTTP headers to be attached, so do not
-forget them. A Status: header is also required; the data should be the
-3-digit HTTP response code, followed by a textual message.- -Here's an example of a file whose contents are sent as is so as to -tell the client that a file has redirected. -
-Status: 302 Now where did I leave that URL
-Location: http://xyz.abc.com/foo/bar.html
-Content-type: text/html
-
-<HTML>
-<HEAD>
-<TITLE>Lame excuses'R'us</TITLE>
-</HEAD>
-<BODY>
-<H1>Fred's exceptionally wonderful page has moved to
-<A HREF="http://xyz.abc.com/foo/bar.html">Joe's</A> site.
-</H1>
-</BODY>
-</HTML>
-- - - - diff --git a/docs/manual/mod/mod_auth.html b/docs/manual/mod/mod_auth.html deleted file mode 100644 index bfb47a795aa..00000000000 --- a/docs/manual/mod/mod_auth.html +++ /dev/null @@ -1,145 +0,0 @@ - - -
-Module mod_auth
- -This module is contained in themod_auth.c file, and
-is compiled in by default. It provides for user authentication using
-textual files.
-
-
-
-- - -
AuthGroupFile
- -Syntax: AuthGroupFile filename-Context: directory, .htaccess
-Override: AuthConfig
-Status: Base
-Module: mod_auth
- -The AuthGroupFile directive sets the name of a textual file containing the list -of user groups for user authentication. Filename is the absolute path -to the group file.
-Each line of the group file contains a groupname followed by a colon, followed -by the member usernames separated by spaces. Example: -
mygroup: bob joe anne- -Security: make sure that the AuthGroupFile is stored outside the -document tree of the web-server; do not put it in the directory that -it protects. Otherwise, clients will be able to download the AuthGroupFile.
- -See also AuthName, -AuthType and -AuthUserFile.
- -
AuthUserFile
- -Syntax: AuthUserFile filename-Context: directory, .htaccess
-Override: AuthConfig
-Status: Base
-Module: mod_auth
- -The AuthUserFile directive sets the name of a textual file containing -the list of users and passwords for user -authentication. Filename is the absolute path to the user -file.
Each line of the user file file contains a username followed -by a colon, followed by the crypt() encrypted password. The behavior -of multiple occurrences of the same user is undefined.
Note that -searching user groups files is inefficient; AuthDBMUserFile should be -used instead.
- -Security: make sure that the AuthUserFile is stored outside the -document tree of the web-server; do not put it in the directory that -it protects. Otherwise, clients will be able to download the AuthUserFile.
- -See also AuthName, -AuthType and -AuthGroupFile.
-
-
AuthAuthoritative
- -Syntax: AuthAuthoritative < on(default) | off >-Context: directory, .htaccess
-Override: AuthConfig
-Status: Base
-Module: mod_auth
-
-Setting the AuthAuthoritative directive explicitly to 'off'
-allows for both authentication and authorization to be passed on to
-lower level modules (as defined in the Configuration and
-modules.c files) if there is no userID or
-rule matching the supplied userID. If there is a userID and/or
-rule specified; the usual password and access checks will be applied
-and a failure will give an Authorization Required reply.
-
-
- -So if a userID appears in the database of more than one module; or if -a valid require directive applies to more than one module; then the -first module will verify the credentials; and no access is passed on; -regardless of the AuthAuthoritative setting. - -
-
-A common use for this is in conjunction with one of the database
-modules; such as mod_auth_db.c, mod_auth_dbm.c, mod_auth_msql.c and mod_auth_anon.c. These modules
-supply the bulk of the user credential checking; but a few
-(administrator) related accesses fall through to a lower level with a
-well protected AuthUserFile.
-
-
- -Default: By default; control is not passed on; and an unknown -userID or rule will result in an Authorization Required reply. Not -setting it thus keeps the system secure; and forces an NSCA compliant -behaviour. - -
- -Security: Do consider the implications of allowing a user to allow -fall-through in his .htaccess file; and verify that this is really -what you want; Generally it is easier to just secure a single -.htpasswd file, than it is to secure a database such as mSQL. Make -sure that the AuthUserFile is stored outside the document tree of the -web-server; do not put it in the directory that it -protects. Otherwise, clients will be able to download the -AuthUserFile. - -
-See also AuthName, -AuthType and -AuthGroupFile.
- - - - - diff --git a/docs/manual/mod/mod_auth_anon.html b/docs/manual/mod/mod_auth_anon.html deleted file mode 100644 index c880c34ee10..00000000000 --- a/docs/manual/mod/mod_auth_anon.html +++ /dev/null @@ -1,249 +0,0 @@ - - -
-Module mod_auth_anon
- -This module is contained in themod_auth_anon.c file and
-is not compiled in by default. It is only available in Apache 1.1 and
-later. It allows "anonymous" user access to authenticated areas.
-
-Summary
- -It does access control in a manner similar to anonymous-ftp sites; i.e. -have a 'magic' user id 'anonymous' and the email address as a password. -These email addresses can be logged. --Combined with other (database) access control methods, this allows for -effective user tracking and customization according to a user profile -while still keeping the site open for 'unregistered' users. One advantage -of using Auth-based user tracking is that, unlike magic-cookies and -funny URL pre/postfixes, it is completely browser independent and it -allows users to share URLs. -
- -Directives / -Example / -Compile time options / -RevisionHistory / -Person to blame / -Sourcecode -
- -
Directives
--
-
- Anonymous -
- Anonymous_Authoritative -
- Anonymous_LogEmail -
- Anonymous_MustGiveEmail -
- Anonymous_NoUserID -
- Anonymous_VerifyEmail -
- -
Anonymous
- -Syntax: Anonymous user user ...-Default: none
-Context: directory, .htaccess
-Override: AuthConfig
-Status: Extension
-Module: mod_auth_anon
- - A list of one or more 'magic' userIDs which are allowed access - without password verification. The userIDs are space separated. - It is possible to use the ' and " quotes to allow a space in - a userID as well as the \ escape character. -
- Please note that the comparison is case-IN-sensitive.
-
- I strongly suggest that the magic username 'anonymous'
- is always one of the allowed userIDs.
-
- Example:
-
- Anonymous: anonymous "Not Registered" 'I don\'t know'
-
- This would allow the user to enter without password verification - by using the userId's 'anonymous', 'AnonyMous','Not Registered' and - 'I Don't Know'. -
- -
Anonymous_Authoritative
-Syntax: Anonymous_Authoritative on | off-Default:
Anonymous_Authoritative off-Context: directory, .htaccess
-Override: AuthConfig
-Status: Extension
-Module: mod_auth_anon
-
- When set 'on', there is no
- fall-through to other authorization methods. So if a
- userID does not match the values specified in the
- Anonymous directive, access is denied.
-
- Be sure you know what you are doing when you decide to switch - it on. And remember that it is the linking order of the modules - (in the Configuration / Make file) which details the order - in which the Authorization modules are queried. -
- -
Anonymous_LogEmail
-Syntax: Anonymous_LogEmail on | off-Default:
off-Context: directory, .htaccess
-Override: AuthConfig
-Status: Extension
-Module: mod_auth_anon
- - When set 'on', the default, the 'password' entered (which hopefully - contains a sensible email address) is logged in the httpd-log file. -
- -
Anonymous_MustGiveEmail
- -Syntax: Anonymous_MustGiveEmail on | off-Default: off
-Context: directory, .htaccess
-Override: AuthConfig
-Status: Extension
-Module: mod_auth_anon
- - Specifies whether the user must specify an email - address as the password. This prohibits blank passwords. -
- -
Anonymous_NoUserID
-Syntax: Anonymous_NoUserID on | off-Default:
Anonymous_NoUserID off-Context: directory, .htaccess
-Override: AuthConfig
-Status: Extension
-Module: mod_auth_anon
- - When set 'on', users can leave - the userID (and perhaps the password field) empty. This - can be very convenient for MS-Explorer users who can - just hit return or click directly on the OK button; which - seems a natural reaction. - -
- -
Anonymous_VerifyEmail
-Syntax: Anonymous on | off-Default:
Anonymous_VerifyEmail off-Context: directory, .htaccess
-Override: AuthConfig
-Status: Extension
-Module: mod_auth_anon
-
- When set 'on' the 'password' entered is
- checked for at least one '@' and a '.' to encourage users to enter
- valid email addresses (see the above Auth_LogEmail).
-
-
Example
- -The example below (when combined with the Auth directives -of a htpasswd-file based (or GDM, mSQL etc) base access -control system allows users in as 'guests' with the -following properties: --
-
-
-It insists that the user enters a userId. (
Anonymous_NoUserId) - -
-It insists that the user enters a password. (
Anonymous_MustGiveEmail) - -
-The password entered must be a valid email address, ie. contain at least one '@' and a '.'.
-(
Anonymous_VerifyEmail) - -
-The userID must be one of
anonymous guest www test welcome-and comparison is not case sensitive. -<directory /web/docs/public>- -
-And the Email addresses entered in the passswd field are logged to
-the httpd-log file
-(
Anonymous_LogEmail) -
-Excerpt of access.conf: -
-
-
-Anonymous anonymous guest www test welcome-Anonymous_MustGiveEmail on
-Anonymous_VerifyEmail on
-Anonymous_NoUserId off
-Anonymous_LogEmail on
--AuthName Use 'anonymous' & Email address for guest entry
-AuthType basic- -
--
- Normal Apache/NCSA tokens for access control
-
-
<limit get post head>
-order deny,allow
-allow from all
--
require valid-user
-<limit>
-
-
Compile Time Options
- -Currently there are no Compile options. - -Revision History
- -This version: 23 Nov 1995, 24 Feb 1996, 16 May 1996. - --
-
-
- Version 0.4
- First release - -
- Version 0.5
- Added 'VerifyEmail' and 'LogEmail' options. Multiple - 'anonymous' tokens allowed. more docs. Added Authoritative - functionality. - -
Contact/person to blame
- -This module was written for the -European Wide Service Exchange by -<Dirk.vanGulik@jrc.it>.
-Feel free to contact me if you have any problems, ice-creams or bugs. This
-documentation, courtesy of Nick Himba,
-<himba@cs.utwente.nl>.
-- - -
Sourcecode
- -The source code can be found at
-http://www.apache.org. A snapshot of a development version
-usually resides at
-http://me-www.jrc.it/~dirkx/mod_auth_anon.c. Please make sure
-that you always quote the version you use when filing a bug report.
-- - - - - diff --git a/docs/manual/mod/mod_auth_db.html b/docs/manual/mod/mod_auth_db.html deleted file mode 100644 index d97035bf0ff..00000000000 --- a/docs/manual/mod/mod_auth_db.html +++ /dev/null @@ -1,160 +0,0 @@ - - -
-Module mod_auth_db
- -This module is contained in themod_auth_db.c file, and
-is not compiled in by default. It provides for user authentication using
-Berkeley DB files. It is an alternative to DBM
-files for those systems which support DB and not DBM. It is only
-available in Apache 1.1 and later.
-
-
-
-- - -
AuthDBGroupFile
- -Syntax: AuthDBGroupFile filename-Context: directory, .htaccess
-Override: AuthConfig
-Status: Extension
-Module: mod_auth_db
- -The AuthDBGroupFile directive sets the name of a DB file containing the list -of user groups for user authentication. Filename is the absolute path -to the group file.
- -The group file is keyed on the username. The value for a user is a -comma-separated list of the groups to which the users belongs. There must -be no whitespace within the value, and it must never contain any colons.
- -Security: make sure that the AuthDBGroupFile is stored outside the -document tree of the web-server; do not put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBGroupFile unless otherwise protected.
- -Combining Group and Password DB files: In some cases it is easier to -manage a single database which contains both the password and group -details for each user. This simplifies any support programs that need -to be written: they now only have to deal with writing to and locking -a single DBM file. This can be accomplished by first setting the group -and password files to point to the same DB file:
- -
-AuthDBGroupFile /www/userbase
-AuthDBUserFile /www/userbase
-- -
-Unix Crypt-ed Password : List of Groups [ : (ignored) ]
-- -See also AuthName, -AuthType and -AuthDBUserFile.
- -
AuthDBUserFile
- -Syntax: AuthDBUserFile filename-Context: directory, .htaccess
-Override: AuthConfig
-Status: Extension
-Module: mod_auth_db
- -The AuthDBUserFile directive sets the name of a DB file containing the list -of users and passwords for user authentication. Filename is the -absolute path to the user file.
- -The user file is keyed on the username. The value for a user is the -crypt() encrypted password, optionally followed by a colon and -arbitrary data. The colon and the data following it will be ignored -by the server.
- -Security: make sure that the AuthDBUserFile is stored outside the -document tree of the web-server; do not put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBUserFile.
- -Important compatibility note: The implementation of "dbmopen" in the -apache modules reads the string length of the hashed values from the -DB data structures, rather than relying upon the string being -NULL-appended. Some applications, such as the Netscape web server, -rely upon the string being NULL-appended, so if you are having trouble -using DB files interchangeably between applications this may be a -part of the problem.
- -See also AuthName, -AuthType and -AuthDBGroupFile.
-
-
AuthDBAuthoritative
- -Syntax: AuthDBAuthoritative < on(default) | off >-Context: directory, .htaccess
-Override: AuthConfig
-Status: Base
-Module: mod_auth
-
-Setting the AuthDBAuthoritative directive explicitly to 'off'
-allows for both authentication and authorization to be passed on
-to lower level modules (as defined in the Configuration
-and modules.c file if there is no userID or
-rule matching the supplied userID. If there is a userID
-and/or rule specified; the usual password and access checks will
-be applied and a failure will give an Authorization Required reply.
-
-So if a userID appears in the database of more than one module; or -if a valid require directive applies to more than one module; then -the first module will verify the credentials; and no access is -passed on; regardless of the AuthAuthoritative setting.
-
-A common use for this is in conjunction with one of the basic auth
-modules; such as mod_auth.c.
-Whereas this DB module supplies the bulk of the user credential
-checking; a few (administrator) related accesses fall through to
-a lower level with a well protected .htpasswd file.
- -Default: By default; control is not passed on; and an unknown -userID or rule will result in an Authorization Required reply. Not -setting it thus keeps the system secure; and forces an NSCA compliant -behaviour.
-Security: Do consider the implications of allowing a user to allow -fall-through in his .htaccess file; and verify that this is really -what you want; Generally it is easier to just secure a single -.htpasswd file, than it is to secure a database which might have -more access interfaces. - -
-See also AuthName, -AuthType and -AuthDBGroupFile.
- - - - - diff --git a/docs/manual/mod/mod_auth_dbm.html b/docs/manual/mod/mod_auth_dbm.html deleted file mode 100644 index 42e0b649853..00000000000 --- a/docs/manual/mod/mod_auth_dbm.html +++ /dev/null @@ -1,162 +0,0 @@ - - -
-Module mod_auth_dbm
- -This module is contained in themod_auth_dbm.c file, and
-is not compiled in by default. It provides for user authentication using
-DBM files.
-
-
-
-- - -
AuthDbmGroupFile
- -Syntax: AuthDBMGroupFile filename-Context: directory, .htaccess
-Override: AuthConfig
-Status: Extension
-Module: mod_auth_dbm
- -The AuthDBMGroupFile directive sets the name of a DBM file containing the list -of user groups for user authentication. Filename is the absolute path -to the group file.
- -The group file is keyed on the username. The value for a user is a -comma-separated list of the groups to which the users belongs. There must -be no whitespace within the value, and it must never contain any colons.
- -Security: make sure that the AuthDBMGroupFile is stored outside the -document tree of the web-server; do not put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBMGroupFile unless otherwise protected.
- -Combining Group and Password DBM files: In some cases it is easier to -manage a single database which contains both the password and group -details for each user. This simplifies any support programs that need -to be written: they now only have to deal with writing to and locking -a single DBM file. This can be accomplished by first setting the group -and password files to point to the same DBM:
- -
-AuthDBMGroupFile /www/userbase
-AuthDBMUserFile /www/userbase
-- -
-Unix Crypt-ed Password : List of Groups [ : (ignored) ]
-- -See also AuthName, -AuthType and -AuthDBMUserFile.
- -
AuthDBMUserFile
- -Syntax: AuthDBMUserFile filename-Context: directory, .htaccess
-Override: AuthConfig
-Status: Extension
-Module: mod_auth_dbm
- -The AuthDBMUserFile directive sets the name of a DBM file containing the list -of users and passwords for user authentication. Filename is the -absolute path to the user file.
- -The user file is keyed on the username. The value for a user is the -crypt() encrypted password, optionally followed by a colon and -arbitrary data. The colon and the data following it will be ignored -by the server.
- -Security: make sure that the AuthDBMUserFile is stored outside the -document tree of the web-server; do not put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBMUserFile.
- -Important compatibility note: The implementation of "dbmopen" in the -apache modules reads the string length of the hashed values from the -DBM data structures, rather than relying upon the string being -NULL-appended. Some applications, such as the Netscape web server, -rely upon the string being NULL-appended, so if you are having trouble -using DBM files interchangeably between applications this may be a -part of the problem.
- -See also AuthName, -AuthType and -AuthDBMGroupFile.
- -
-
AuthDBMAuthoritative
- -Syntax: AuthDBMAuthoritative < on(default) | off >-Context: directory, .htaccess
-Override: AuthConfig
-Status: Base
-Module: mod_auth
-
-Setting the AuthDBMAuthoritative directive explicitly to 'off'
-allows for both authentication and authorization to be passed on
-to lower level modules (as defined in the Configuration
-and modules.c file if there is no userID or
-rule matching the supplied userID. If there is a userID
-and/or rule specified; the usual password and access checks will
-be applied and a failure will give an Authorization Required reply.
-
-So if a userID appears in the database of more than one module; or -if a valid require directive applies to more than one module; then -the first module will verify the credentials; and no access is -passed on; regardless of the AuthAuthoritative setting.
-
-A common use for this is in conjunction with one of the basic auth
-modules; such as mod_auth.c.
-Whereas this DBM module supplies the bulk of the user credential
-checking; a few (administrator) related accesses fall through to
-a lower level with a well protected .htpasswd file.
- -Default: By default; control is not passed on; and an unknown -userID or rule will result in an Authorization Required reply. Not -setting it thus keeps the system secure; and forces an NSCA compliant -behaviour.
- -Security: Do consider the implications of allowing a user to allow -fall-through in his .htaccess file; and verify that this is really -what you want; Generally it is easier to just secure a single -.htpasswd file, than it is to secure a database which might have -more access interfaces. - -
-See also AuthName, -AuthType and -AuthDBMGroupFile.
- - - - - diff --git a/docs/manual/mod/mod_cern_meta.html b/docs/manual/mod/mod_cern_meta.html deleted file mode 100644 index 98a7410f401..00000000000 --- a/docs/manual/mod/mod_cern_meta.html +++ /dev/null @@ -1,81 +0,0 @@ - - -
-Apache module mod_cern_meta
- -This module is contained in themod_cern_meta.c file, and
-is not compiled in by default. It provides for CERN httpd metafile
-semantics. It is only available in Apache 1.1 and later.
-
-Summary
- -Emulate the CERN HTTPD Meta file semantics. Meta files are HTTP -headers that can be output in addition to the normal range of headers -for each file accessed. They appear rather like the Apache -.asis files, and are able to provide a crude way of influencing -the Expires: header, as well as providing other curiosities. -There are many ways to manage meta information, this one was -chosen because there is already a large number of CERN users -who can exploit this module. - -More information on the -CERN metafile semantics is available. - -
Directives
--
-
- MetaDir -
- MetaSuffix -
- -
MetaDir
-Syntax: MetaDir directory name-Default:
MetaDir .web-Context: server config
-Status: Base
-Module: mod_cern_meta
-Compatibility: MetaDir is only available in Apache 1.1 -and later.
-
-Specifies the name of the directory in which Apache can find
-meta information files. The directory is usually a 'hidden'
-subdirectory of the directory that contains the file being
-accessed. Set to "." to look in the same directory as the
-file.
-
-
MetaSuffix
-Syntax: MetaSuffix suffix-Default:
MetaSuffix .meta-Context: server config
-Status: Base
-Module: mod_cern_meta
-Compatibility: MetaSuffix is only available in Apache 1.1 -and later.
-
-Specifies the file name suffix for the file containing the
-meta information. For example, the default values for the two
-directives will cause a request to
-DOCUMENT_ROOT/somedir/index.html to look in
-DOCUMENT_ROOT/somedir/.web/index.html.meta and will use
-its contents to generate additional MIME header information.
-
-
- - - - - diff --git a/docs/manual/mod/mod_cgi.html b/docs/manual/mod/mod_cgi.html deleted file mode 100644 index fc06cf5c27b..00000000000 --- a/docs/manual/mod/mod_cgi.html +++ /dev/null @@ -1,174 +0,0 @@ - - -
-Module mod_cgi
- -This module is contained in themod_cgi.c file, and
-is compiled in by default. It provides for execution of CGI scripts.
-Any file with mime type application/x-httpd-cgi will be
-processed by this module.
-
-
-
-Summary
-Any file that has the mime typeapplication/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 ending in 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.
-
-
CGI Environment variables
-The server will set the CGI environment variables as described in the CGI -specification, with the following provisions: --
-
- REMOTE_HOST -
- This will only be set if the server has not been compiled with
-
MINIMAL_DNS. - - REMOTE_IDENT -
- This will only be set if
-IdentityCheck is set to
on. - - 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). - -
- -
Directives
- -ScriptLog
- -Syntax: ScriptLog filename-Default: none
-Context: resource 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 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
- -Syntax: ScriptLogLength size-Default: 10385760
-Context: resource 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 size-Default: 1024
-Context: resource config
-Status: mod_cgi -
- -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. - - - - - diff --git a/docs/manual/mod/mod_dir.html b/docs/manual/mod/mod_dir.html deleted file mode 100644 index aebd31a5bb8..00000000000 --- a/docs/manual/mod/mod_dir.html +++ /dev/null @@ -1,367 +0,0 @@ - - -
-Module mod_dir
- -This module is contained in themod_dir.c file, and
-is compiled in by default. It provides for directory indexing.
-
-Summary
-This module controls the directory indexing. The index of a directory -can come from one of two sources: --
-
- A file written by the user, typically called
index.html. -The DirectoryIndex directive sets the name -of this file. - - Otherwise, a listing generated by the server. The other directives -control the format of this listing. The AddIcon, -AddIconByEncoding and -AddIconByType are used to set a list of -icons to display for various file types; for each file listed, the -first icon listed that matches the file is displayed. -
Directives
- - -- -
AddAlt
- -Syntax: AddAlt string file file...-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
-
-This sets the alternate text to display for a file, instead of an icon, for
-FancyIndexing. File is a file
-extension, partial filename, wild-card expression or full filename for files
-to describe. String is enclosed in double quotes
-("). This alternate text is displayed if the client is
-image-incapable or has image loading disabled.
-
-
-
AddAltByEncoding
- -Syntax: AddAltByEncoding string MIME-encoding - MIME-encoding...-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
-
-This sets the alternate text to display for a file, instead of an icon, for
-FancyIndexing. MIME-encoding is a
-valid content-encoding, such as x-compress.
-String is enclosed in double quotes
-("). This alternate text is displayed if the client is
-image-incapable or has image loading disabled.
-
-
-
AddAltByType
- -Syntax: AddAltByType string MIME-type MIME-type...-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
-
-This sets the alternate text to display for a file, instead of an icon, for
-FancyIndexing. MIME-type is a
-valid content-type, such as text/html.
-String is enclosed in double quotes
-("). This alternate text is displayed if the client is
-image-incapable or has image loading disabled.
-
-
- -
AddDescription
- -Syntax: AddDescription string file file...-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
-
-This sets the description to display for a file, for
-FancyIndexing. File is a file
-extension, partial filename, wild-card expression or full filename for files
-to describe. String is enclosed in double quotes
-("). Example:
-
AddDescription "The planet Mars" /web/pics/mars.gif
-- -
AddIcon
- -Syntax: AddIcon icon name name ...-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
- -This sets the icon to display next to a file ending in name for -FancyIndexing. Icon is either a -(%-escaped) relative URL to the icon, or of the format -(alttext,url) where alttext is the text tag given -for an icon for non-graphical browsers.
- -Name is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for -blank lines (to format the list correctly), a file extension, a wildcard -expression, a partial filename or a complete filename. Examples: -
-AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm
-AddIcon /icons/dir.xbm ^^DIRECTORY^^
-AddIcon /icons/backup.xbm *~
-- -
AddIconByEncoding
- -Syntax: AddIconByEncoding icon mime-encoding mime-encoding -...-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
- -This sets the icon to display next to files with -mime-encoding for FancyIndexing. -Icon is either a (%-escaped) relative URL to the icon, or of the -format (alttext,url) where alttext is the text tag -given for an icon for non-graphical browsers.
- -Mime-encoding is a wildcard expression matching required the -content-encoding. Examples: -
-AddIconByEncoding /icons/compress.xbm x-compress
-- -
AddIconByType
- -Syntax: AddIconByType icon mime-type mime-type ...-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
- -This sets the icon to display next to files of type mime-type for -FancyIndexing. Icon is either a -(%-escaped) relative URL to the icon, or of the format -(alttext,url) where alttext is the text tag given -for an icon for non-graphical browsers.
-Mime-type is a wildcard expression matching required the mime types. -Examples: -
-AddIconByType (IMG,/icons/image.xbm) image/*
-- -
DefaultIcon
- -Syntax: DefaultIcon url-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
- -The DefaultIcon directive sets the icon to display for files when no -specific icon is known, for FancyIndexing. -Url is a (%-escaped) relative URL to the icon. Examples: -
-DefaultIcon /icon/unknown.xbm
-- -
DirectoryIndex
- -Syntax: DirectoryIndex local-url local-url ...-Default:
DirectoryIndex index.html-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
-
-The DirectoryIndex directive sets the list of resources to look for,
-when the client requests an index of the directory by specifying a /
-at the end of the a directory name. Local-url is the
-(%-encoded) URL of a document on the server relative to the requested
-directory; it is usually the name of a file in the directory. Several
-URLs may be given, in which case the server will return the first one
-that it finds. If none of the resources exist and the
-Indexes option is set, the server will generate its own
-listing of the directory.
-
- -Example: -
-DirectoryIndex index.html
-http://myserver/docs/ would return
-http://myserver/docs/index.html if it exists, or would list
-the directory if it did not. - -Note that the documents do not need to be relative to the directory; -
-DirectoryIndex index.html index.txt /cgi-bin/index.pl/cgi-bin/index.pl to be executed
-if neither index.html or index.txt existed in
-a directory.- -
FancyIndexing
- -Syntax: FancyIndexing boolean-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
-
-The FancyIndexing directive sets the FancyIndexing option for a directory.
-Boolean can be on or off. The
-IndexOptions directive should be used in
-preference.
- -
HeaderName
- -Syntax: HeaderName filename-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
-
-The HeaderName directive sets the name of the file that will be inserted
-at the top of the index listing. Filename is the name of the file
-to include, and is taken to be relative to the directory being indexed.
-The server first attempts to include filename.html
-as an HTML document, otherwise it will include filename as plain
-text. Example:
-
HeaderName HEADER/web, the server will first look for
-the HTML file /web/HEADER.html and include it if found, otherwise
-it will include the plain text file /web/HEADER, if it exists.
-
-See also ReadmeName.
- -
IndexIgnore
- -Syntax: IndexIgnore file file ...-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
-
-The IndexIgnore directive adds to the list of files to hide when listing
-a directory. File is a file extension, partial filename,
-wildcard expression or full filename for files to ignore. Multiple
-IndexIgnore directives add to the list, rather than the replacing the list
-of ignored files. By default, the list contains `.'. Example:
-
-IndexIgnore README .htaccess *~
-- -
IndexOptions
- -Syntax: IndexOptions option option ...-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
- -The IndexOptions directive specifies the behavior of the directory indexing. -Option can be one of -
-
-
- FancyIndexing -
- -This turns on fancy indexing of directories. -
- IconsAreLinks -
- - -This makes the icons part of the anchor for the filename, for -fancy indexing. -
- ScanHTMLTitles -
- -This enables the extraction of the title from HTML documents for fancy -indexing. If the file does not have a description given by -AddDescription then httpd will read the -document for the value of the TITLE tag. This is CPU and disk intensive. -
- SuppressLastModified -
- - -This will suppress the display of the last modification date, in fancy -indexing listings. -
- SuppressSize -
- - -This will suppress the file size in fancy indexing listings. -
- SuppressDescription -
- - -This will suppress the file description in fancy indexing listings. -
-<Directory /web/docs>
-IndexOptions FancyIndexing
-</Directory>
-<Directory /web/docs/spec>
-IndexOptions ScanHTMLTitles
-</Directory>
-ScanHTMLTitles will be set for the /web/docs/spec
-directory.- -
ReadmeName
- -Syntax: ReadmeName filename-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Status: Base
-Module: mod_dir
-
-The ReadmeName directive sets the name of the file that will be appended
-to the end of the index listing. Filename is the name of the file
-to include, and is taken to be relative to the directory being indexed.
-The server first attempts to include filename.html
-as an HTML document, otherwise it will include filename as plain
-text. Example:
-
ReadmeName README/web, the server will first look for
-the HTML file /web/README.html and include it if found, otherwise
-it will include the plain text file /web/README, if it exists.
-
-See also HeaderName.
- - - - - - diff --git a/docs/manual/mod/mod_env.html b/docs/manual/mod/mod_env.html deleted file mode 100644 index 0ee71931b39..00000000000 --- a/docs/manual/mod/mod_env.html +++ /dev/null @@ -1,92 +0,0 @@ - - -
-Apache module mod_env
- -This module is contained in themod_env.c file, and
-is not compiled in by default. It provides for
-passing environment variables to CGI/SSI scripts. Is is only available
-in Apache 1.1 and later.
-
-Summary
- -This module allows Apache's CGI and SSI environment to inherit -environment variables from the shell which invoked the httpd process. -CERN web-servers are able to do this, so this module is especially -useful to web-admins who wish to migrate from CERN to Apache without -rewriting all their scripts - -Directives
- - -- -
PassEnv
-Syntax: PassEnv variable variable ...-Context: server config, virtual host
-Status: Base
-Module: mod_env
-Compatibility: PassEnv is only available in -Apache 1.1 and later.
- -Specifies one or more environment variables to pass to CGI scripts -from the server's own environment. Example: -
- PassEnv LD_LIBRARY_PATH -- -
- -
SetEnv
-Syntax: SetEnv variable value-Context: server config, virtual host
-Status: Base
-Module: mod_env
-Compatibility: SetEnv is only available in -Apache 1.1 and later.
- -Sets an environment variable, which is then passed on to CGI -scripts. Example: -
- SetEnv SPECIAL_PATH /foo/bin -- -
- -
UnsetEnv
-Syntax: UnsetEnv variable variable ...-Context: server config, virtual host
-Status: Base
-Module: mod_env
-Compatibility: UnsetEnv is only available in -Apache 1.1 and later.
- -Removes one or more environment variables from those passed on to -CGI scripts. Example: -
- UnsetEnv LD_LIBRARY_PATH -- - - -
- - - - diff --git a/docs/manual/mod/mod_example.html b/docs/manual/mod/mod_example.html deleted file mode 100644 index 5ac54af3278..00000000000 --- a/docs/manual/mod/mod_example.html +++ /dev/null @@ -1,140 +0,0 @@ - - -
-Module mod_example
-
- This module is contained in the modules/mod_example.c file, and
- is not compiled in by default. It illustrates many of
- the aspects of the
- Apache 1.2 API
- and, when used, demonstrates the manner in which module callbacks are
- triggered by the server.
-
Summary
-
- The files in the src/modules/example directory under the
- Apache distribution directory tree are provided as an example to those
- that wish to write modules that use the Apache API.
-
- The main file is mod_example.c, which illustrates all
- the different callback mechanisms and call syntaces. By no means does
- an add-on module need to include routines for all of the callbacks -
- quite the contrary!
-
- The example module is an actual working module. If you link it into - your server, enable the "example-handler" handler for a location, and - then browse to that location, you will see a display of - some of the tracing the example module did as the various callbacks - were made. -
-- To include the example module in your server, follow the steps below: -
--
-
- Uncomment the "Module example_module" line near the bottom of
- the
src/Configurationfile. If there isn't one, add - it; it should look like this: -- Module example_module modules/example/mod_example.o -
-
- - Run the
src/Configurescript - ("cd src; ./Configure"). This will - build the Makefile for the server itself, and update the -src/modules/Makefilefor any additional modules you - have requested from beneath that subdirectory. -
- - Make the server (run "make" in the
src- directory). -
-
- To add another module of your own: -
--
-
- mkdir src/modules/mymodule - -
- cp src/modules/example/* src/modules/mymodule - -
- Modify the files in the new directory. - -
- Follow steps [1] through [3] above, with appropriate changes. - -
- Using the mod_example Module -
-- To activate the example module, include a block similar to the - following in your srm.conf file: -
-- <Location /example-info> - SetHandler example-handler - </Location> --
- As an alternative, you can put the following into a - .htaccess - file and then request the file "test.example" from that - location: -
-- AddHandler example-handler .example --
- After reloading/restarting your server, you should be able to browse - to this location and see the brief display mentioned earlier. -
-Directives
--
-
-
- Example - -
-
- Example -
-
- Syntax: Example
-
- Default: None
-
- Context: server config, virtual host, directory, .htaccess
-
- Override: Options
-
- Status: Extension
-
- Module: mod_example
-
- The Example directive activates the example module's content handler - for a particular location or file type. It takes no arguments. If - you browse to an URL to which the example content-handler applies, you - will get a display of the routines within the module and how and in - what order they were called to service the document request. -
- - - diff --git a/docs/manual/mod/mod_expires.html b/docs/manual/mod/mod_expires.html deleted file mode 100644 index 3ec53d1156b..00000000000 --- a/docs/manual/mod/mod_expires.html +++ /dev/null @@ -1,185 +0,0 @@ - - - -Module mod_expires
-
- This module is contained in the mod_expires.c file, and
- is not compiled in by default. It provides for the
- generation of Expires headers according to user-specified
- criteria.
-
Summary
-
- This module controls the setting of the Expires HTTP
- header in server responses. The expiration date can set to be
- relative to either the time the source file was last modified, or to
- the time of the client access.
-
- The Expires HTTP header is an instruction to the client
- about the document's validity and persistence. If cached, the document
- may be fetched from the cache rather than from the source until this
- time has passed. After that, the cache copy is considered
- "expired" and invalid, and a new copy must be obtained from
- the source.
-
Directives
--
--
- ExpiresActive directive -
- -
- Syntax: ExpiresActive boolean
-
- Context: server config, virtual host, directory, .htaccess
-
- Override: Indexes
-
- Status: Extension
-
- Module: mod_expires
-
- This directive enables or disables the generation of the
- Expires header for the document realm in question. (That
- is, if found in an .htaccess file, for instance, it
- applies only to documents generated from that directory.) If set to
- Off, no Expires header will be
- generated for any document in the realm (unless overridden at a lower
- level, such as an .htaccess file overriding a server
- config file). If set to On, the header will be
- added to served documents according to the criteria defined by the
- ExpiresByType
- and
- ExpiresDefault
- directives (q.v.).
-
- Note that this directive does not guarantee that an
- Expires header will be generated. If the criteria aren't
- met, no header will be sent, and the effect will be as though this
- directive wasn't even specified.
-
-
- ExpiresByType directive -
- -
- Syntax: ExpiresByType mime-type <code>seconds
-
- Context: server config, virtual host, directory, .htaccess
-
- Override: Indexes
-
- Status: Extension
-
- Module: mod_expires
-
- This directive defines the value of the Expires header
- generated for documents of the specified type (e.g.,
- text/html). The second argument sets the number of
- seconds that will be added to a base time to construct the expiration
- date.
-
- The base time is either the last modification time of the file, or the
- time of the client's access to the document. Which should be used is
- specified by the <code> field;
- M means that the file's last modification time should
- be used as the base time, and A means the client's
- access time should be used.
-
- The difference in effect is subtle. If M is used, all current - copies of the document in all caches will expire at the same time, - which can be good for something like a weekly notice that's always - found at the same URL. If A is used, the date of expiration - is different for each client; this can be good for image files that - don't change very often, particularly for a set of related documents - that all refer to the same images (i.e., the images will be - accessed repeatedly within a relatively short timespan). -
-- Example: -
--
- ExpiresActive On # enable expirations - ExpiresByType image/gif A2592000 # expire GIF images after a month - # in the client's cache - ExpiresByType text/html M604800 # HTML documents are good for a - # week from the time they were - # changed, period -- -
- Note that this directive only has effect if ExpiresActive
- On has been specified. It overrides, for the specified MIME
- type only, any expiration date set by the
- ExpiresDefault
- directive.
-
-
- ExpiresDefault directive -
- -
- Syntax: ExpiresDefault <code>seconds
-
- Context: server config, virtual host, directory, .htaccess
-
- Override: Indexes
-
- Status: Extension
-
- Module: mod_expires
-
- This directive sets the default algorithm for calculating the - expiration time for all documents in the affected realm. It can be - overridden on a type-by-type basis by the - ExpiresByType - directive. See the description of that directive for details about - the syntax of the argument. -
- - - diff --git a/docs/manual/mod/mod_headers.html b/docs/manual/mod/mod_headers.html deleted file mode 100644 index aed34f04db9..00000000000 --- a/docs/manual/mod/mod_headers.html +++ /dev/null @@ -1,104 +0,0 @@ - - - -Headers Module
- -The optional headers module allows for the customization of HTTP -response headers. Headers can be merged, replaced or removed. The -directives described in this document are only available if Apache is -compiled with mod_headers.c. - -- -
Directive
--
-
- Header -
- -
Header
-Syntax: Header [ set | append | add ] header value-Syntax: Header unset header
-Context: server config, virtual host, access.conf, .htaccess
-Status: optional
-Module: mod_header
- -This directive can replace, merge or remove HTTP response headers. The -action it performs is determined by the first argument. This can be one -of the following values: - -
-
-
- set
- The response header is set, replacing any previous header with this name - - - append
- The response header is appended to any existing header of the same - name. When a new value is merged onto an existing header it is - separated from the existing header with a comma. This is the HTTP standard - way of giving a header multiple values. - - - add
- The response header is added to the existing set of headers, even if - this header already exists. This can result in two (or more) headers - having the same name. This can lead to unforeseen consequences, and in - general "append" should be used instead. - - - unset
- The response header of this name is removed, if it exists. If there are - multiple headers of the same name, only the first one set will be removed. -
Order of Processing
- -The Header directive can occur almost anywhere within the server -configuration. It is valid in the main server config and virtual host -sections, inside <Directory>, <Location> and <Files> -sections, and within .htaccess files. --The Header directives are processed in the following order: -
-
-
- main server -
- virtual host -
- <Directory> sections and .htaccess -
- <Location> -
- <Files> -
-Header append Author "John P. Doe" -Header unset Author -- -This way round, the Author header is not set. If reversed, the Author -header is set to "John P. Doe". -
- -The Header directives are processed just before the response is sent -by its handler. These means that some headers that are added just -before the response is sent cannot be unset or overridden. This -includes headers such as "Date" and "Server". -
- - - - diff --git a/docs/manual/mod/mod_imap.html b/docs/manual/mod/mod_imap.html deleted file mode 100644 index 718f3fb683b..00000000000 --- a/docs/manual/mod/mod_imap.html +++ /dev/null @@ -1,284 +0,0 @@ - - -
-Module mod_imap
- -This module is contained in themod_imap.c file, and is
-compiled in by default. It provides for .map files,
-replacing the functionality of the imagemap CGI
-program. Any directory or document type configured to use the handler
-imap-file (using either AddHandler or SetHandler) will be
-processed by this module.
-
-Summary
- -This module is in the default Apache distribution. The following directive will -activate files ending with.map as imagemap files:
-
-AddHandler imap-file mapAddType application/x-httpd-imap mapNew Features
-The imagemap module adds some new features that were not -possible with previously distributed imagemap programs.- -
-
-
- URL references relative to the Referer: information. -
- Default <BASE> assignment through a new map directive
-
base. - - No need for
imagemap.conffile. - - Point references. -
- Configurable generation of imagemap menus. -
- -
Configuration Directives
--
-
- ImapMenu -
- ImapDefault -
- ImapBase -
- -
ImapMenu
-Syntax: ImapMenu{none, formatted, semi-formatted,
- unformatted}-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Module: mod_imap.c
-Compatibility: ImapMenu is only available in Apache -1.1 and later.
- -The ImapMenu directive determines the action taken if an imagemap file -is called without valid coordinates. -
-
-
none-- If ImapMenu is
-
none, no menu is generated, and thedefault- action is performed. - formatted-- A
formattedmenu is the simplest menu. Comments - in the imagemap file are ignored. A level one header is - printed, then an hrule, then the links each on a separate line. - The menu has a consistent, plain look close to that of - a directory listing. - semiformatted-- In the
semiformattedmenu, comments are printed - where they occur in the imagemap file. Blank lines are turned - into HTML breaks. No header or hrule is printed, but otherwise - the menu is the same as aformattedmenu. - unformatted-- Comments are printed, blank lines are ignored. Nothing is - printed that does not appear in the imagemap file. All breaks - and headers must be included as comments in the imagemap file. - This gives you the most flexibility over the appearance of your - menus, but requires you to treat your map files as HTML instead - of plaintext. -
- -
ImapDefault
-Syntax: ImapDefault{error, nocontent,
- map, referer, URL}-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Module: mod_imap.c
-Compatibility: ImapDefault is only available in Apache -1.1 and later.
-
-
-The ImapDefault directive sets the default default used in
-the imagemap files. It's value is overridden by a default
-directive within the imagemap file. If not present, the
-default action is nocontent, which means
-that a 204 No Content is sent to the client. In this
-case, the client should continue to display the original page.
-
-
- -
ImapBase
-Syntax: ImapBase{map, referer, URL}-Context: server config, virtual host, directory, .htaccess
-Override: Indexes
-Module: mod_imap.c
-Compatibility: ImapBase is only available in Apache -1.1 and later.
-
-The ImapBase directive sets the default base used in
-the imagemap files. It's value is overridden by a base
-directive within the imagemap file. If not present, the
-base defaults to http://servername/.
-
-
-
- -
Imagemap File
-The lines in the imagemap files can have one of several formats: ---The directive is one ofdirective value [x,y ...]
-directive value "Menu text" [x,y ...]
-directive value x,y ... "Menu text"
-
base, default,
-poly, circle, rect, or
-point. The value is an absolute or relative URL, or one
-of the special values listed below. The coordinates are
-x,y pairs separated by whitespace. The quoted text is
-used as the text of the link if a imagemap menu is generated. Lines
-beginning with '#' are comments.
-
-Imagemap File Directives
-There are six directives allowed in the imagemap file. The directives -can come in any order, but are processed in the order they are found -in the imagemap file. --
-
baseDirective -- Has the effect of
<BASE href="value">. The - non-absolute URLs of the map-file are taken relative to this value. - Thebasedirective overrides ImapBase as set in a - .htaccess file or in the server configuration files. In the absence - of an ImapBase configuration directive,basedefaults to -http://server_name/.
-base_uriis synonymous withbase. Note that - a trailing slash on the URL is significant. --
defaultDirective -- The action taken if the coordinates given do not fit any of the
-
poly,circleorrect- directives, and there are nopointdirectives. Defaults - tonocontentin the absence of an ImapDefault - configuration setting, causing a status code of204 No - Contentto be returned. The client should keep the same - page displayed. --
polyDirective -- Takes three to one-hundred points, and is obeyed if the user selected
- coordinates fall within the polygon defined by these points.
-
-
circle-- Takes the center coordinates of a circle and a point on the circle. Is
- obeyed if the user selected point is with the circle.
-
-
rectDirective -- Takes the coordinates of two opposing corners of a rectangle. Obeyed
- if the point selected is within this rectangle.
-
-
pointDirective -- Takes a single point. The point directive closest to the user
- selected point is obeyed if no other directives are satisfied.
- Note that
defaultwill not be followed if a -pointdirective is present and valid coordinates are - given. -
Values
-The values for each of the directives can any of the following: --
-
- a URL -
- The URL can be relative or absolute URL. Relative URLs can
- contain '..' syntax and will be resolved relative to the
-
basevalue.
-baseitself will not resolved according to the current - value. A statementbase mailto:will work properly, though. --
map-- Equivalent to the URL of the imagemap file itself. No
- coordinates are sent with this, so a menu will be generated
- unless ImapMenu is set to 'none'.
-
-
menu-- Synonymous with
map. --
referer-- Equivalent to the URL of the referring document.
- Defaults to
http://servername/if no Referer: - header was present. --
nocontent-- Sends a status code of
204 No Content, - telling the client to keep the same page displayed. Valid for - all butbase. --
error-- Fails with a
500 Server Error. Valid for all but -base, but sort of silly for anything but -default. -
Coordinates
--
-
0,0 200,200-- A coordinate consists of an x and a y value
- separated by a comma. The coordinates are separated from each other
- by whitespace. To accommodate the way Lynx handles imagemaps, should a
- user select the coordinate
0,0, it is as if - no coordinate had been selected. -
Quoted Text
--
-
"Menu Text"-- After the value or after the coordinates, the line optionally may
- contain text within double quotes. This string is used as the
- text for the link if a menu is generated:
-<a href="http://foo.com/">Menu text</a>
- If no quoted text is present, the name of the link will be used - as the text:
-<a href="http://foo.com/">http://foo.com</a>
- It is impossible to escape double quotes within this text. -
- -
Example Mapfile
-
-#Comments are printed in a 'formatted' or 'semiformatted' menu.
-#And can contain html tags. <hr>
-base referer
-poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0
-rect .. 0,0 77,27 "the directory of the referer"
-circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27
-rect another_file "in same directory as referer" 306,0 419,27
-point http://www.zyzzyva.com/ 100,100
-point http://www.tripod.com/ 200,200
-rect mailto:nate@tripod.com 100,150 200,0 "Bugs?"
-- -
Referencing your mapfile
-
-<A HREF="/maps/imagmap1.map">
-<IMG ISMAP SRC="/images/imagemap1.gif">
-</A>
-- - - - - - diff --git a/docs/manual/mod/mod_include.html b/docs/manual/mod/mod_include.html deleted file mode 100644 index 6f511309989..00000000000 --- a/docs/manual/mod/mod_include.html +++ /dev/null @@ -1,385 +0,0 @@ - - -
-Module mod_include
- -This module is contained in themod_include.c file, and
-is compiled in by default. It provides for server-parsed html
-documents. Several directives beyond the original NCSA definition have been
-included in Apache 1.2 - these are flagged below with the phrase
-"Apache 1.2 and above". Of particular significance are the new flow
-control directives documented at the bottom.
-
-Enabling Server-Side Includes
- -Any document with handler of "server-parsed" will be parsed by this -module, if theIncludes option is set. If documents
-containing server-side include directives are given the extension
-.shtml, the following directives will make Apache parse them and
-assign the resulting document the mime type of text/html:
-
--AddType text/html .shtml -AddHandler server-parsed .shtml -- -The following directive must be given for the directories containing -the shtml files (typically in a
<Directory> section,
-but this directive is also valid .htaccess files if AllowOverride
-Options is set):
-
--Options +Includes -- -Alternatively the
XBitHack
-directive can be used to parse normal (text/html) files,
-based on file permissions.
-
-For backwards compatibility, documents with mime type
-text/x-server-parsed-html or
-text/x-server-parsed-html3 will also be parsed
-(and the resulting output given the mime type text/html).
-
-
Basic Elements
- -The document is parsed as an HTML document, with special commands embedded -as SGML comments. A command has the syntax: - -- -The value will often be enclosed in double quotes; many commands only allow -a single attribute-value pair. Note that the comment terminator -(-->) should be preceded by whitespace to ensure that it -isn't considered part of an SSI token. --<!--#element attribute=value attribute=value ... ---> -
-The allowed elements are:
- -
-
-
-
- config -
-
-This command controls various aspects of the parsing. The valid attributes
-are:
-
-
-
- errmsg -
- The value is a message that is sent back to the client if an error occurs -whilst parsing the document. -
- sizefmt -
- The value sets the format to be used which displaying the size of a file.
-Valid values are
bytesfor a count in bytes, or -abbrevfor a count in Kb or Mb as appropriate. - - timefmt -
- The value is a string to be used by the
strftime(3)library -routine when printing dates. -
- echo -
-
-This command prints one of the include variables, defined below.
-If the variable is unset, it is printed as
(none). -Any dates printed are subject to the currently configuredtimefmt. -Attributes: --
-
- var -
- The value is the name of the variable to print. -
- exec -
-
-The exec command executes a given shell command or CGI script.
-The IncludesNOEXEC Option disables this command
-completely. The valid attributes are:
-
-
-
- cgi -
-
-The value specifies a (%-encoded) URL relative path to the CGI script.
-If the path does not begin with a (/), then it is taken to be relative to
-the current document. The document referenced by this path is invoked
-as a CGI script, even if the server would not normally recognize it as
-such. However, the directory containing the script must be enabled for
-CGI scripts (with ScriptAlias
-or the ExecCGI Option).
-The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the -original request from the client; these cannot be specified in the URL path. -The include variables will be available to the script in addition to the -standard CGI environment.
-If the script returns a Location: header instead of output, then this -will be translated into an HTML anchor.
-The
include virtualelement should be used in preference to -exec cgi. - - cmd -
- The server will execute the given string using
/bin/sh. -The include variables are available to the command. -
- fsize -
-
-This command prints the size of the specified file, subject to the
-
sizefmtformat specification. Attributes: --
-
- file -
- The value is a path relative to the directory containing the current -document being parsed. -
- virtual -
- The value is a (%-encoded) URL-path relative to the current document being -parsed. If it does not begin with a slash (/) then it is taken to be relative -to the current document. -
- flastmod -
-
-This command prints the last modification date of the specified file,
-subject to the
timefmtformat specification. The attributes are -the same as for thefsizecommand. - - - include -
-
-This command inserts the text of another document or file into the parsed
-file. Any included file is subject to the usual access control. If the
-directory containing the parsed file has the
-Option
-IncludesNOEXEC set, and the including the document would cause a program
-to be executed, then it will not be included; this prevents the execution of
-CGI scripts. Otherwise CGI scripts are invoked as normal using the complete
-URL given in the command, including any query string.
-
-
- -An attribute defines the location of the document; the inclusion is done for -each attribute given to the include command. The valid attributes are: -
-
-
- file -
- The value is a path relative to the directory containing the current
-document being parsed. It cannot contain
../, nor can it be an -absolute path. Thevirtualattribute should always be used -in preference to this one. - - virtual -
- The value is a (%-encoded) URL relative to the current document being -parsed. The URL cannot contain a scheme or hostname, only a path and -an optional query string. If it does not begin with a slash (/) then it -is taken to be relative to the current document. -
- printenv -
- This prints out a listing of all existing variables and their values.
- No attributes.
-
- For example:
<!--#printenv -->-- Apache 1.2 and above. - -
- For example:
- set -
- This sets the value of a variable. Attributes:
-
-
-
- var -
- The name of the variable to set. -
- value -
- The value to give a variable. -
<!--#set var="category" value="help" -->-- Apache 1.2 and above. - -
Include Variables
- -In addition to the variables in the standard CGI environment, these are -available for theecho command, for if and
-elif, and to any program invoked by the document.
-
--
-
- DATE_GMT -
- The current date in Greenwich Mean Time. -
- DATE_LOCAL -
- The current date in the local time zone. -
- DOCUMENT_NAME -
- The filename (excluding directories) of the document requested by the -user. -
- DOCUMENT_URI -
- The (%-decoded) URL path of the document requested by the user. Note that -in the case of nested include files, this is not then URL for the -current document. -
- LAST_MODIFIED -
- The last modification date of the document requested by the user. -
- -
Variable Substitution
-Variable substitution is done within quoted strings in most cases - where they may reasonably occur as an argument to an SSI directive. - This includes the - config, - exec, - flastmod, - fsize, - include, and - set - directives, as well as the arguments to conditional operators. - You can insert a literal dollar sign into the string using backslash - quoting: - -
- <!--#if expr="$a = \$test" --> -- -
If a variable reference needs to be substituted in the middle of a - character sequence that might otherwise be considered a valid - identifier in its own right, it can be disambiguated by enclosing - the reference in braces, à la shell substitution: - -
- <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->
-
-
-This will result in the Zed variable being set to - "X_Y" if REMOTE_HOST is - "X" and REQUEST_METHOD is - "Y". - -
EXAMPLE: the below example will print "in foo" if the DOCUMENT_URI is -/foo/file.html, "in bar" if it is /bar/file.html and "in neither" -otherwise: -
- <!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" --> - in foo - <!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" --> - in bar - <!--#else --> - in neither - <!--#endif --> -- -
Flow Control Elements
- -These are available in Apache 1.2 and above. The basic flow control -elements are: - -- <!--#if expr="test_condition" --> - <!--#elif expr="test_condition" --> - <!--#else --> - <!--#endif --> -- -
The if element works like an
- if statement in a programming language. The test condition
- is evaluated and if the result is true, then the text until
- the next elif, else.
- or endif element is included in the
- output stream.
-
-
The elif or else
- statements are be used the put text into the output stream
- if the original test_condition was false. These elements
- are optional.
-
-
The endif element ends the
- if element and is required.
-
-
test_condition is one of the following: - -
-
-
-
- string
- true if string is not empty - -
- string1 = string2
- string1 != string2 - - - Compare string1 with string 2. If string2 has the form /string/ - than it is compared as a regular expression. - Regular expressions have the same syntax as those found in the - Unix egrep command. - -
- ( test_condition ) -
- true if test_condition is true -
- ! test_condition -
- true if test_condition is false -
- test_condition1 && test_condition2 -
- true if both test_condition1 and - test_condition2 are true -
- test_condition1 || test_condition2 -
- true if either test_condition1 or - test_condition2 is true -
"=" and "!=" bind more tightly than "&&" and - "||". - "!" binds most tightly. Thus, the following are equivalent: - -
- <!--#if expr="$a = test1 && $b = test2" --> - <!--#if expr="($a = test1) && ($b = test2)" --> -- -
Anything that's not recognized as a variable or an operator is - treated as a string. Strings can also be quoted: 'string'. - Unquoted strings can't contain whitespace (blanks and tabs) - because it is used to separate tokens such as variables. If - multiple strings are found in a row, they are concatenated using - blanks. So, - -
- string1 string2 results in string1 string2 - 'string1 string2' results in string1 string2 -- -
-
Directives
--
-
- XBitHack -
- - -
XBitHack
- -Syntax: XBitHack status-Default:
XBitHack off-Context: server config, virtual host, directory, .htaccess
-Override: Options
-Status: Base
-Module: mod_include
-
-The XBitHack directives controls the parsing of ordinary html documents.
-This directive only affects files associated with the MIME type
-text/html.
-Status can have the following values:
-
-
-
- off -
- No special treatment of executable files. -
- on -
- Any file that has the user-execute bit set will be treated as a -server-parsed html document. -
- full -
- As for
onbut also test the group-execute bit. If it -is set, then set the Last-modified date of the returned file to be the -last modified time of the file. If it is not set, then no last-modified date -is sent. Setting this bit allows clients and proxies to cache the result of -the request. -Note: you would not want to use this, for example, when you -
#includea CGI that produces different output on each hit -(or potentially depends on the hit). -
- - - - diff --git a/docs/manual/mod/mod_info.html b/docs/manual/mod/mod_info.html deleted file mode 100644 index dd753499906..00000000000 --- a/docs/manual/mod/mod_info.html +++ /dev/null @@ -1,73 +0,0 @@ - - -
-Module mod_info
- -This module is contained in themod_info.c file. It
-provides a comprehensive overview of the server configuration
-including all installed modules and directives in the configuration
-files. This module is not compiled into the
-server by default. It is only available in Apache 1.1 and later. To
-enable it, add the following line to the server build Configuration
-file, and rebuild the server:
-
--Module info_module mod_info.o -- -
-
-To configure it, add the following to your access.conf file.
-
-
-<Location /server-info> -SetHandler server-info -</Location> -- -You may wish to add a -<Limit> -clause inside the -location -directive to limit access to your server configuration information.
-Once configured, the server information is obtained by accessing -http://your.host.dom/server-info
-
- - Note that the configuration files are read by the module at run-time, - and therefore the display may not reflect the running - server's active configuration if the files have been changed since the - server was last reloaded. Also, the configuration files must be - readable by the user as which the server is running (see the - User - directive), or else the directive settings will not be listed. -- - - diff --git a/docs/manual/mod/mod_log_agent.html b/docs/manual/mod/mod_log_agent.html deleted file mode 100644 index 9e8fa50855c..00000000000 --- a/docs/manual/mod/mod_log_agent.html +++ /dev/null @@ -1,61 +0,0 @@ - - - -- It should also be noted that if mod_info is compiled into - the server, its handler capability is available in all - configuration files, including per-directory files - (e.g., .htaccess). This may have - security-related ramifications for your site. -
- -
Module mod_log_agent
- -This module is contained in themod_log_agent.c file, and is not
-compiled in by default. It provides for logging of the client user agents.
-
-
--
-
- AgentLog -
- - -
AgentLog
- -Syntax: AgentLog file-pipe-Default:
AgentLog logs/agent_log-Context: server config, virtual host
-Status: Extension
-Module: mod_log_agent
- -The AgentLog directive sets the name of the file to which the server will -log the UserAgent header of incoming requests. File-pipe is one -of -
- A filename -
- A filename relative to the ServerRoot. -
- `|' followed by a command -
- A program to receive the agent log information on its standard input. -Note the a new program will not be started for a VirtualHost if it inherits -the AgentLog from the main server. -
- -Security: See the security tips document for -details on why your security could be compromised if the directory -where logfiles are stored is writable by anyone other than the user -that starts the server.
- -This directive is provided for compatibility with NCSA 1.4.
- - - - - diff --git a/docs/manual/mod/mod_log_config.html b/docs/manual/mod/mod_log_config.html deleted file mode 100644 index 8ffc86c5cb9..00000000000 --- a/docs/manual/mod/mod_log_config.html +++ /dev/null @@ -1,263 +0,0 @@ - - -
-Module mod_log_config
- -This module is contained in themod_log_config.c file,
-and is compiled in by default in Apache 1.2. mod_log_config replaces
-mod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was
-an optional module. It provides for logging of the requests made to
-the server, using the Common Log Format or a user-specified format.
-
-Summary
- -Three directives are provided by this module:TransferLog
-to create a log file, LogFormat to set a custom format,
-and CustomLog to define a log file and format in one go.
-The TransferLog and CustomLog directives can
-be used multiple times in each server to cause each request to be
-logged to multiple files.
-- -
Compatibility notes
- --
-
- This module is based on mod_log_config distributed with -previous Apache releases, now updated to handle multiple logs. -There is now no need to re-configure Apache to use configuration log -formats. - -
- The module also implements the
CookieLogdirective, -used to log user-tracking information created by mod_usertrack. The use of -CookieLogis deprecated, and aCustomLog-should be defined to log user-tracking information instead. - -
Log File Formats
- -Unless told otherwise with LogFormat the log files created by -TransferLog will be in standard "Common Log Format" -(CLF). The contents of each line in a CLF file are explained -below. Alternatively, the log file can be customized (and if multiple -log files are used, each can have a different format). Custom formats -are set withLogFormat and CustomLog.
-
-Common Log Format
- -The Common Log Format (CLF) file contains a separate line for each -request. A line is composed of several tokens separated by spaces: - --host ident authuser date request status bytes --If a token does not have a value then it is represented by a hyphen (-). -The meanings and values of these tokens are as follows: -
-
-
- host -
- The fully-qualified domain name of the client, or its IP number if the -name is not available. -
- ident -
- If IdentityCheck is enabled and the -client machine runs identd, then this is the identity information reported -by the client. -
- authuser -
- If the request was for an password protected document, then this is -the userid used in the request. -
- date -
- The date and time of the request, in the following format:
-
date = [day/month/year:hour:minute:second zone]
-day = 2*digit
-month = 3*letter
-year = 4*digit
-hour = 2*digit
-minute = 2*digit
-second = 2*digit
-zone = (`+' | `-') 4*digit
- request -
- The request line from the client, enclosed in double quotes
-(
"). - - status -
- The three digit status code returned to the client. -
- bytes -
- The number of bytes in the object returned to the client, not including -any headers. -
Custom Log Formats
- -The format argument to theLogFormat and
-CustomLog is a string. This string is logged to the log
-file for each request. It can contain literal characters copied into
-the log files, and `%' directives which are replaced in the log file
-by the values as follows:
-
-
-%...b: Bytes sent, excluding HTTP headers.
-%...f: Filename
-%...{FOOBAR}e: The contents of the environment variable FOOBAR
-%...h: Remote host
-%...{Foobar}i: The contents of Foobar: header line(s) in the request
- sent to the server.
-%...l: Remote logname (from identd, if supplied)
-%...{Foobar}n: The contents of note "Foobar" from another module.
-%...{Foobar}o: The contents of Foobar: header line(s) in the reply.
-%...p: The port the request was served to
-%...P: The process ID of the child that serviced the request.
-%...r: First line of request
-%...s: Status. For requests that got internally redirected, this
- is status of the *original* request --- %...>s for the last.
-%...t: Time, in common log format time format
-%...{format}t: The time, in the form given by format, which should
- be in strftime(3) format.
-%...T: The time taken to serve the request, in seconds.
-%...u: Remote user (from auth; may be bogus if return status (%s) is 401)
-%...U: The URL path requested.
-%...v: The name of the server (i.e. which virtual host?)
-
-
-The `...' can be nothing at all (e.g. "%h %u %r %s %b"), or it can
-indicate conditions for inclusion of the item (which will cause it
-to be replaced with `-' if the condition is not met). Note that
-there is no escaping performed on the strings from %r, %...i and
-%...o; some with long memories may remember that I thought this was
-a bad idea, once upon a time, and I'm still not comfortable with
-it, but it is difficult to see how to `do the right thing' with all
-of `%..i', unless we URL-escape everything and break with CLF.
-
-- -The forms of condition are a list of HTTP status codes, which may -or may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs -User-agent: on 400 errors and 501 errors (Bad Request, Not -Implemented) only; `%!200,304,302{Referer}i' logs Referer: on all -requests which did not return some sort of normal status. - -
-
-Note that the common log format is defined by the string "%h %l
-%u %t \"%r\" %s %b", which can be used as the basis for
-extending for format if desired (e.g. to add extra fields at the end).
-NCSA's extended/combined log format would be "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\"".
-
-
Using Multiple Log Files
- -TheTransferLog and CustomLog directives can
-be given more than once to log requests to multiple log files. Each
-request will be logged to all the log files defined by either of these
-directives.
-
-Use with Virtual Hosts
- -If a <VirtualHost> section does not contain any -TransferLog or CustomLog directives, the -logs defined for the main server will be used. If it does -contain one or more of these directives, requests serviced by -this virtual host will only be logged in the log files defined -within its definition, not in any of the main server's log files. -See the examples below. -- -
Security Considerations
- -See the security tips document -for details on why your security could be compromised if the directory -where logfiles are stored is writable by anyone other than the user -that starts the server. --
Directives
- - -- - -
CookieLog
- -Syntax: CookieLog filename-Context: server config, virtual host
-Module: mod_cookies
-Compatibility: Only available in Apache 1.2 and above
- -The CookieLog directive sets the filename for logging of cookies. -The filename is relative to the ServerRoot. This directive is included -only for compatibility with mod_cookies, and is deprecated. -
- -
CustomLog
-Syntax: CustomLog file-pipe format-Context: server config, virtual host
-Status: Base
-Module: mod_log_config
- -The first argument is the filename to log to. This is used -exactly like the argument to TransferLog, that is, -it is either a full path, or relative to the current -server root.
- -The format argument specifies a format for each line of the log file. -The options available for the format are exactly the same as for -the argument of the LogFormat directive. If the format -includes any spaces (which it will do in almost all cases) it -should be enclosed in double quotes. - -
LogFormat
- -Syntax: LogFormat string-Default:
LogFormat "%h %l %u %t \"%r\"
-%s %b"-Context: server config, virtual host
-Status: Base
-Module: mod_log_config
- -This sets the format of the logfile. See -Custom Log Formats for details on the format arguments.
- - -
TransferLog
- -Syntax: TransferLog file-pipe-Default: none
-Context: server config, virtual host
-Status: Base
-Module: mod_log_config
- -The TransferLog directive adds a log file in Common Log Format. -File-pipe is one -of -
- A filename -
- A filename relative to the ServerRoot. -
- `|' followed by a command -
- A program to receive the agent log information on its standard input. -Note the a new program will not be started for a VirtualHost if it inherits -the TransferLog from the main server. -
- - - - - - - diff --git a/docs/manual/mod/mod_log_referer.html b/docs/manual/mod/mod_log_referer.html deleted file mode 100644 index 8a5146491a6..00000000000 --- a/docs/manual/mod/mod_log_referer.html +++ /dev/null @@ -1,88 +0,0 @@ - - -
-Module mod_log_referer
- -This module is contained in themod_log_referer.c file, and is not
-compiled in by default. It provides for logging of the documents which
-reference documents on the server.
-
-Log file format
-The log file contains a separate line for each refer. Each line has the -format -uri -> document
-where uri is the (%-escaped) URI for the document that references
-the one requested by the client, and document is the (%-decoded)
-local URL to the document being referred to.
-
-
-Directives
- -- - -
RefererIgnore
- -Syntax: RefererIgnore string string ...-Context: server config, virtual host
-Status: Extension
-Module: mod_log_referer
- -The RefererIgnore directive adds to the list of strings to ignore in -Referer headers. If any of the strings in the list is contained in -the Referer header, then no referrer information will be logged for the -request. Example: -
RefererIgnore www.ncsa.uiuc.edu- - -
RefererLog
- -Syntax: RefererLog file-pipe-Default:
RefererLog logs/referer_log-Context: server config, virtual host
-Status: Extension
-Module: mod_log_referer
- -The RefererLog directive sets the name of the file to which the server will -log the Referer header of incoming requests. File-pipe is one -of -
- A filename -
- A filename relative to the ServerRoot. -
- `|' followed by a command -
- A program to receive the referrer log information on its standard input. -Note the a new program will not be started for a VirtualHost if it inherits -the RefererLog from the main server. -
- -Security: See the security tips document for -details on why your security could be compromised if the directory -where logfiles are stored is writable by anyone other than the user -that starts the server.
- -This directive is provided for compatibility with NCSA 1.4.
- - - - - diff --git a/docs/manual/mod/mod_mime.html b/docs/manual/mod/mod_mime.html deleted file mode 100644 index fa150c88e05..00000000000 --- a/docs/manual/mod/mod_mime.html +++ /dev/null @@ -1,212 +0,0 @@ - - -
-Module mod_mime
- -This module is contained in themod_mime.c file, and is
-compiled in by default. It provides for determining the types of files
-from the filename.
-
-Summary
-This module is used to determine the mime types of documents. Some mime -types indicate special processing to be performed by the server, otherwise -the type is returned to the client so that the browser can deal with -the document appropriately.- -The filename of a document is treated as being composed of a basename followed -by some extensions, in the following order: -
base.type.language.enc-The type extension sets the type of the document; types are defined -in the TypesConfig file and by the -AddType directive. The language extension -sets the language of the document, as defined by the -AddLanguage directive. Finally, the -enc directive sets the encoding of the document, as defined by -the AddEncoding directive. - - -
Directives
- -- - -
AddEncoding
- -Syntax: AddEncoding mime-enc extension extension...-Context: server config, virtual host, directory, .htaccess
-Override: FileInfo
-Status: Base
-Module: mod_mime
- -The AddEncoding directive adds to the list of filename extensions which -filenames may end in for the specified encoding type. Mime-enc -is the mime encoding to use for documents ending in extension. -Example: -
-AddEncoding x-gzip gz
-AddEncoding x-compress Z
-- -
AddHandler
- -Syntax: <AddHandler handler-name extension>-Context: server config, virtual host, directory, .htaccess
-Status: Base
-Module: mod_mime
-Compatibility: AddHandler is only available in Apache -1.1 and later
- -
AddHandler maps the filename extension extension to the
-handler
-handler-name. For example, to activate CGI scripts
-with the file extension ".cgi", you might use:
-
- AddHandler cgi-script cgi -- -
Once that has been put into your srm.conf or httpd.conf file, any
-file ending with ".cgi" will be treated as a CGI
-program.
- -
AddLanguage
- -Syntax: AddLanguage mime-lang extension extension...-Context: server config, virtual host, directory, .htaccess
-Override: FileInfo
-Status: Base
-Module: mod_mime
- -The AddLanguage directive adds to the list of filename extensions which -filenames may end in for the specified content language. Mime-lang -is the mime language of files with names ending extension, -after any content encoding extensions have been removed. Example: -
-AddEncoding x-compress Z
-AddLanguage en .en
-AddLanguage fr .fr
-xxxx.en.Z will be treated as being a compressed
-English document. Although the content language is reported to the client,
-the browser is unlikely to use this information. The AddLanguage directive
-is more useful for content negotiation, where the server returns one
-from several documents based on the client's language preference.- -
AddType
- -Syntax: AddType mime-type extension extension...-Context: server config, virtual host, directory, .htaccess
-Override: FileInfo
-Status: Base
-Module: mod_mime
- -The AddType directive adds to the list of filename extensions which -filenames may end in for the specified content type. Mime-enc -is the mime type to use for documents ending in extension. -after content-encoding and language extensions have been removed. Example: -
-AddType image/gif GIF
--Note that, unlike the NCSA httpd, this directive cannot be used to set the -type of particular files.
- -
ForceType
- -Syntax: <ForceType media type>-Context: directory, .htaccess
-Status: Base
-Module: mod_mime
-Compatibility: ForceType is only available in Apache -1.1 and later.
- -
When placed into an .htaccess file or a
-<Directory> or <Location> section,
-this directive forces all matching files to be served
-as the content type given by media type. For example, if you
-had a directory full of GIF files, but did not want to label them all with
-".gif", you might want to use:
-
- ForceType image/gif --
Note that this will override any filename extensions that might -media type.
- -SetHandler
- -Syntax: <SetHandler handler-name>-Context: directory, .htaccess
-Status: Base
-Module: mod_mime
-Compatibility: SetHandler is only available in Apache -1.1 and later.
- -
When placed into an .htaccess file or a
-<Directory> or <Location> section,
-this directive forces all matching files to be parsed through the
-handler
-given by handler-name. For example, if you had a
-directory you wanted to be parsed entirely as imagemap rule files,
-regardless of extension, you might put the following into an
-.htaccess file in that directory:
-
- SetHandler imap-file -- -
Another example: if you wanted to have the server display a status
-report whenever a URL of http://servername/status was
-called, you might put the following into access.conf:
-
- <Location /status> - SetHandler server-status - </Location> --
- -
TypesConfig
- -Syntax: TypesConfig filename-Default:
TypesConfig conf/mime.types-Context: server config
-Status: Base
-Module: mod_mime
- -The TypesConfig directive sets the location of the mime types configuration -file. Filename is relative to the -ServerRoot. This file sets the default list of -mappings from filename extensions to content types; changing this file is not -recommended. Use the AddType directive instead. The -file contains lines in the format of the arguments to an AddType command: -
mime-type extension extension ...-The extensions are lower-cased. Blank lines, and lines beginning with a hash -character (`#') are ignored.
- - - - - diff --git a/docs/manual/mod/mod_negotiation.html b/docs/manual/mod/mod_negotiation.html deleted file mode 100644 index 141b74bfe63..00000000000 --- a/docs/manual/mod/mod_negotiation.html +++ /dev/null @@ -1,147 +0,0 @@ - - -
-Module mod_negotiation
- -This module is contained in themod_negotiation.c file,
-and is compiled in by default. It provides for content negotiation.
-
-Summary
-Content negotiation, or more accurately content selection, is the -selection of the document that best matches the clients -capabilities, from one of several available documents. -There are two implementations of this. --
-
- A type map (a file with the handler
type-map) -which explicitly lists the files containing the variants. - - A MultiViews search (enabled by the MultiViews -Option, where the server does an implicit -filename pattern match, and choose from amongst the results. -
Type maps
-A type map has the same format as RFC822 mail headers. It contains document -descriptions separated by blank lines, with lines beginning with a hash -character ('#') treated as comments. A document description consists of -several header records; records may be continued on multiple lines if the -continuation lines start with spaces. The leading space will be deleted -and the lines concatenated. A header record consists of a keyword -name, which always ends in a colon, followed by a value. Whitespace is allowed -between the header name and value, and between the tokens of value. - -The headers allowed are: - --
-
- Content-Encoding: -
- The encoding of the file. Currently only two encodings are recognized
-by http;
x-compressfor compressed files, andx-gzip-for gzipped files. - - Content-Language: -
- The language of the variant, as an Internet standard language code, such
-as
en. - - Content-Length: -
- The length of the file, in bytes. If this header is not present, then -the actual length of the file is used. -
- Content-Type: -
- The MIME media type of the document, with optional parameters.
-parameters are separated from the media type and from one another by
-semi-colons. Parameter syntax is name=value; allowed parameters are:
-
-
-
- level -
- the value is an integer, which specifies the version of the media type.
-For
text/htmlthis defaults to 2, otherwise 0. - - qs -
- the value is a floating-point number with value between 0. and 1. -It indications the 'quality' of this variant. -
-Content-Type: image/jpeg; qs=0.8 - URI: -
- The path to the file containing this variant, relative to the map file. -
MultiViews
-A MultiViews search is enabled by the MultiViews -Option. -If the server receives a request for/some/dir/foo and
-/some/dir/foo does not exist, then the server reads the
-directory looking for all files named foo.*, and effectively
-fakes up a type map which names all those files, assigning them the same media
-types and content-encodings it would have if the client had asked for
-one of them by name. It then chooses the best match to the client's
-requirements, and returns that document.- - - -
Directives
- -- - -
CacheNegotiatedDocs
-Syntax: CacheNegotiatedDocs-Context: server config
-Status: Base
-Module: mod_negotiation
-Compatibility: CacheNegotiatedDocs is only available -in Apache 1.1 and later.
- -
If set, this directive allows content-negotiated documents to be -cached by proxy servers. This could mean that clients behind those -proxys could retrieve versions of the documents that are not the best -match for their abilities, but it will make caching more -efficient. -
- -This directive only applies to requests which come from HTTP/1.0 browsers. -HTTP/1.1 provides much better control over the caching of negotiated -documents, and this directive has no effect in responses to -HTTP/1.1 requests. - - - -
LanguagePriority
- -Syntax: LanguagePriority mime-lang mime-lang...-Context: server config, virtual host, directory, .htaccess
-Override: FileInfo
-Status: Base
-Module: mod_negotiation
- -The LanguagePriority sets the precedence of language variants for the case -where the client does not express a preference, when handling a -MultiViews request. The list of mime-lang are in order of decreasing -preference. Example: - -
LanguagePriority en fr defoo.html, where foo.html.fr
-and foo.html.de both existed, but the browser did not express
-a language preference, then foo.html.fr would be returned.- -
- -Note that this directive only has an effect if a 'best' language -cannot be determined by other any other means. Correctly implemented -HTTP/1.1 requests will mean this directive has no effect. - - - - - diff --git a/docs/manual/mod/mod_proxy.html b/docs/manual/mod/mod_proxy.html deleted file mode 100644 index e0aef688460..00000000000 --- a/docs/manual/mod/mod_proxy.html +++ /dev/null @@ -1,366 +0,0 @@ - - -
-Apache module mod_proxy
- -This module is contained in themod_proxy.c file for Apache 1.1.x,
-or the modules/proxy subdirectory for Apache 1.2, and
-is not compiled in by default. It provides for an HTTP 1.0 caching proxy
-server. It is only available in Apache 1.1 and later. Common configuration
-questions are addressed here.
-
-Note:
-This module was experimental in Apache 1.1.x. As of Apache 1.2, mod_proxy -stability is greatly improved.
- -
Summary
- -This module implements a proxy/cache for Apache. It implements -proxying capability for -FTP,
-CONNECT (for SSL),
-HTTP/0.9, and
-HTTP/1.0.
-The module can be configured to connect to other proxy modules for these
-and other protocols.
-
-Directives
--
-
- ProxyRequests -
- ProxyRemote -
- ProxyPass -
- ProxyBlock -
- CacheRoot -
- CacheSize -
- CacheMaxExpire -
- CacheDefaultExpire -
- CacheLastModifiedFactor -
- CacheGcInterval -
- CacheDirLevels -
- CacheDirLength -
- NoCache -
- -
ProxyRequests
-Syntax: ProxyRequests on/off-Default:
ProxyRequests Off-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: ProxyRequest is only available in -Apache 1.1 and later.
-
-This allows or prevents Apache from functioning as a proxy
-server. Setting ProxyRequests to 'off' does not disable use of the ProxyPass directive.
-
-ProxyRemote
-Syntax: ProxyRemote <match> <remote-server>
-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: ProxyRemote is only available in
-Apache 1.1 and later.
- -This defines remote proxies to this proxy. <match> is either the -name of a URL-scheme that the remote server supports, or a partial URL -for which the remote server should be used, or '*' to indicate the -server should be contacted for all requests. <remote-server> is a -partial URL for the remote server. Syntax: - -
- <remote-server> = <protocol>://<hostname>[:port] -- -<protocol> is the protocol that should be used to communicate -with the remote server; only "http" is supported by this module. - -Example: -
- ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000 - ProxyRemote * http://cleversite.com - ProxyRemote ftp http://ftpproxy.mydomain.com:8080 -- -In the last example, the proxy will forward FTP requests, encapsulated -as yet another HTTP proxy request, to another proxy which can handle -them. - -
ProxyPass
-Syntax: ProxyPass <path> <url>-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: ProxyPass is only available in -Apache 1.1 and later.
- -This directive allows remote servers to be mapped into the space of the local -server; the local server does not act as a proxy in the conventional sense, -but appears to be a mirror of the remote server. <path> is the name of -a local virtual path; <url> is a partial URL for the remote server. - -Suppose the local server has address http://wibble.org; then -
- ProxyPass /mirror/foo http://foo.com --Will cause a local request for the http://wibble.org/mirror/foo/bar to be -internally converted into a proxy request to http://foo.com/bar - -
ProxyBlock
-Syntax: ProxyBlock <word/host/domain list>-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: ProxyBlock is only available in -Apache 1.2 and later.
- -The ProxyBlock directive specifies a list of words, hosts and/or domains, -separated by spaces. HTTP, HTTPS, and FTP document requests to matched words, -hosts or domains are blocked by the proxy server. The proxy module -will also attempt to determine IP addresses of list items which may be -hostnames during startup, and cache them for match test as well. Example: - -
- ProxyBlock joes_garage.com some_host.co.uk rocky.wotsamattau.edu -- -'rocky.wotsamattau.edu' would also be matched if referenced by IP address.
- -Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.
- -Note also that - -
-ProxyBlock * -- -blocks connections to all sites. - -
CacheRoot
-Syntax: CacheRoot <directory>-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: CacheRoot is only available in -Apache 1.1 and later.
-
-Sets the name of the directory to contain cache files; this must be
-writable
-by the httpd server.
-
-CacheSize
-Syntax: CacheSize <size>
-Default: CacheSize 5
-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: CacheSize is only available in
-Apache 1.1 and later.
-
-Sets the desired space usage of the cache, in Kb (1024 byte units). Although
-usage may grow above this setting, the garbage collection will delete files
-until the usage is at or below this setting.
-
-CacheGcInterval
-Syntax: CacheGcInterval <time>
-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: CacheGcinterval is only available in
-Apache 1.1 and later.
-
-Check the cache every <time> hours, and delete files if the space
-usage is greater than that set by CacheSize.
-
-CacheMaxExpire
-Syntax: CacheMaxExpire <time>
-Default: CacheMaxExpire 24
-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: CacheMaxExpire is only available in
-Apache 1.1 and later.
-
-Cachable HTTP documents will be retained for at most <time> hours without
-checking the origin server. Thus documents can be at most <time>
-hours out of date. This restriction is enforced even if an expiry date
-was supplied with the document.
-
-CacheLastModifiedFactor
-Syntax: CacheLastModifiedFactor <factor>
-Default: CacheLastModifiedFactor 0.1
-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: CacheLastModifiedFactor is only available in
-Apache 1.1 and later.
- -If the origin HTTP server did not supply an expiry date for the -document, then estimate one using the formula -
- expiry-period = time-since-last-modification * <factor> --For example, if the document was last modified 10 hours ago, and -<factor> is 0.1, then the expiry period will be set to 10*0.1 = 1 hour. - -
If the expiry-period would be longer than that set by CacheMaxExpire,
-then the latter takes precedence.
-
-CacheDirLevels
-Syntax: CacheDirLevels <levels>
-Default: CacheDirLevels 3
-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: CacheDirLevels is only available in
-Apache 1.1 and later.
-
-CacheDirLevels sets the number of levels of subdirectories in the cache.
-Cached data will be saved this many directory levels below CacheRoot.
-
-CacheDirLength
-Syntax: CacheDirLength <length>
-Default: CacheDirLength 1
-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: CacheDirLength is only available in
-Apache 1.1 and later.
-
-CacheDirLength sets the number of characters in proxy cache subdirectory names.
-
-CacheDefaultExpire
-Syntax: CacheDefaultExpire <time>
-Default: CacheDefaultExpire 1
-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: CacheDefaultExpire is only available in
-Apache 1.1 and later.
-
-If the document is fetched via a protocol that does not support expiry times,
-then use <time> hours as the expiry time.
-CacheMaxExpire does not
-override.
-
-NoCache
-Syntax: NoCache <word/host/domain list>
-Context: server config
-Status: Base
-Module: mod_proxy
-Compatibility: NoCache is only available in
-Apache 1.1 and later.
- -The NoCache directive specifies a list of words, hosts and/or domains, separated -by spaces. HTTP and non-passworded FTP documents from matched words, hosts or -domains are not cached by the proxy server. The proxy module will -also attempt to determine IP addresses of list items which may be hostnames -during startup, and cache them for match test as well. Example: - -
- NoCache joes_garage.com some_host.co.uk bullwinkle.wotsamattau.edu -- -'bullwinkle.wotsamattau.edu' would also be matched if referenced by IP -address.
- -Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.
- -Note also that - -
-NoCache * -- -disables caching completely.
- -
- -
Common configuration topics
- --
-
- Controlling access to your proxy -
- Using Netscape hostname shortcuts -
- Why doesn't file type xxx download via FTP? -
- Why does Apache start more slowly when using the - proxy module? -
- Can I use the Apache proxy module with my SOCKS proxy? -
Controlling access to your proxy
- -You can control who can access your proxy via the normal <Directory> -control block using the following example:- -
-<Directory proxy:*> -<Limit GET PUT POST DELETE CONNECT OPTIONS> -order deny,allow -deny from [machines you'd like *not* to allow by IP address or name] -allow from [machines you'd like to allow by IP address or name] -</Limit> -</Directory> -
- -A <Files> block will also work, and is the only method known to work -for all possible URLs in Apache versions earlier than 1.2b10.
- -
Using Netscape hostname shortcuts
- -There is an optional patch to the proxy module to allow Netscape-like -hostname shortcuts to be used. It's available - -here.- -
Why doesn't file type xxx download via FTP?
- -You probably don't have that particular file type defined as -application/octet-stream in your proxy's mime.types configuration -file. A useful line can be- -
-application/octet-stream bin dms lha lzh exe class tgz taz -- -
Why does Apache start more slowly when using the - proxy module?
- -If you're using theProxyBlock or NoCache
-directives, hostnames' IP addresses are looked up and cached during
-startup for later match test. This may take a few seconds (or more)
-depending on the speed with which the hostname lookups occur.- -
Can I use the Apache proxy module with my SOCKS proxy?
- -Yes. Just build Apache with the ruleSOCKS4=yes in your
-Configuration file, and follow the instructions there. SOCKS5
-capability can be added in a similar way (there's no SOCKS5
-rule yet), so use the EXTRA_LFLAGS definition, or build Apache
-normally and run it with the runsocks wrapper provided with SOCKS5,
-if your OS supports dynamically linked libraries.- -Some users have reported problems when using SOCKS version 4.2 on Solaris. -The problem was solved by upgrading to SOCKS 4.3.
- -Remember that you'll also have to grant access to your Apache proxy machine by -permitting connections on the appropriate ports in your SOCKS daemon's -configuration.
- - - - - diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html deleted file mode 100644 index 03eaa5801f7..00000000000 --- a/docs/manual/mod/mod_rewrite.html +++ /dev/null @@ -1,1161 +0,0 @@ - - - - - -
-Module mod_rewrite (Version 3.0)
- -This module is contained in themod_rewrite.c file, with Apache
-1.2 and later. It provides a rule-based rewriting engine to rewrite requested
-URLs on the fly. mod_rewrite is not compiled into the server by
-default. To use mod_rewrite you have to enable the following line
-in the server build Configuration file:
-- Module rewrite_module mod_rewrite.o -- -
Summary
- -This module uses a rule-based rewriting engine (based on a -regular-expression parser) to rewrite requested URLs on the fly. - --It supports an unlimited number of additional rule conditions (which can -operate on a lot of variables, including HTTP headers) for granular -matching and external database lookups (either via plain text -tables, DBM hash files or external processes) for advanced URL -substitution. - -
-It operates on the full URLs (including the PATH_INFO part) both in -per-server context (httpd.conf) and per-dir context (.htaccess) and even -can generate QUERY_STRING parts on result. The rewritten result can lead to internal sub-processing, external request redirection or to internal proxy throughput. - - -
-The latest version can be found on
-
-http://www.engelschall.com/sw/mod_rewrite/
-
-
-Copyright © 1996,1997 The Apache Group, All rights reserved.
-Copyright © 1996,1997 Ralf S. Engelschall, All rights reserved.
-
-Written for The Apache Group by -
- Ralf S. Engelschall- - -
- rse@engelschall.com
- www.engelschall.com -
- - -
-
Directives
- --
-
- RewriteEngine -
- RewriteOptions -
- RewriteLog -
- RewriteLogLevel -
- RewriteMap -
- RewriteBase -
- RewriteCond -
- RewriteRule -
- - - -
Configuration Directives
- -RewriteEngine
-Syntax:RewriteEngine {on,off}-Default:
RewriteEngine off-Context: server config, virtual host, per-directory config
-
-
-The RewriteEngine directive enables or disables the
-runtime rewriting engine. If it is set to off this module does
-no runtime processing at all. It does not even update the SCRIPT_URx
-environment variables.
-
-
-Use this directive to disable the module instead of commenting out -all RewriteRule directives! - -
-
-
-
-RewriteOptions
-Syntax: RewriteOptions Option ...
-Default: -None-
-Context: server config, virtual host, per-directory config
-
- -The RewriteOption directive sets some special options for the -current per-server or per-directory configuration. The Option -strings can be one of the following: - -
-
-
- '
inherit'
- This forces the current configuration to inherit the configuration of the - parent. In per-virtual-server context this means that the maps, - conditions and rules of the main server gets inherited. In per-directory - context this means that conditions and rules of the parent directory's - .htaccess configuration gets inherited. --
-
-
-
-RewriteLog
-Syntax: RewriteLog Filename
-Default: -None-
-Context: server config, virtual host
-
- -The RewriteLog directive sets the name of the file to which the -server logs any rewriting actions it performs. If the name does not begin -with a slash ('/') then it is assumed to be relative to the -Server Root. The directive should occur only once per server -config. - -
-
-To disable the logging of rewriting actions it is not recommended
-to set Filename
-to /dev/null, because although the rewriting engine does
-not create output to a logfile it still creates the logfile
-output internally. This will slow down the server with no advantage to the
-administrator!
-To disable logging either remove or comment out the
-RewriteLog directive or use RewriteLogLevel 0!
- |
-
| -SECURITY: See the Apache Security -Tips document for details on why your security could be compromised if the -directory where logfiles are stored is writable by anyone other than the user -that starts the server. - |
-Example: -
-- --RewriteLog "/usr/local/var/apache/logs/rewrite.log" --
-
-
-
-RewriteLogLevel
-Syntax: RewriteLogLevel Level
-Default: RewriteLogLevel 0
-Context: server config, virtual host
-
- -The RewriteLogLevel directive set the verbosity level of the rewriting -logfile. The default level 0 means no logging, while 9 or more means -that practically all actions are logged. - -
-To disable the logging of rewriting actions simply set Level to 0. -This disables all rewrite action logs. - -
-
| -Notice: Using a high value for Level will slow down your Apache -server dramatically! Use the rewriting logfile only for debugging or at least -at Level not greater than 2! - |
-Example: -
-- --RewriteLogLevel 3 --
-
-
-
-RewriteMap
-Syntax: RewriteMap Mapname {txt,dbm,prg}:Filename
-Default: not used per default
-Context: server config, virtual host
-
- -The RewriteMap directive defines an external Rewriting Map -which can be used inside rule substitution strings by the mapping-functions -to insert/substitute fields through a key lookup. -
- -The Mapname is the name of the map and will -be used to specify a mapping-function for the substitution strings of a -rewriting rule via - -
-- -When such a directive occurs the map Mapname -is consulted and the key LookupKey is looked-up. If the key is -found, the map-function directive is substituted by SubstValue. If -the key is not found then it is substituted by DefaultValue. - -${Mapname:LookupKey -|DefaultValue}-
-The Filename must be a valid Unix filepath, containing one -of the following formats: - -
-
-
- Plain Text Format
-
- This is a ASCII file which contains either blank lines, comment lines - (starting with a '#' character) or - -
- MatchingKey SubstValue -
- - pairs - one per line. You can create such files either manually, - using your favorite editor, or by using the programs - mapcollect and mapmerge from the support - directory of the mod_rewrite distribution. -- To declare such a map prefix, Filename with a
txt:- string as in the following example: - --
-
- --# -# map.real-to-user -- maps realnames to usernames -# - -Ralf.S.Engelschall rse # Bastard Operator From Hell -Dr.Fred.Klabuster fred # Mr. DAU -
-
-
- --RewriteMap real-to-host txt:/path/to/file/map.real-to-user -
-
- DBM Hashfile Format
-
- This is a binary NDBM format file containing the - same contents as the Plain Text Format files. You can create - such a file with any NDBM tool or with the dbmmanage program - from the support directory of the Apache distribution. -
- To declare such a map prefix Filename with a
dbm:- string. --
- Program Format -
- This is a Unix executable, not a lookup file. To create it you can use - the language of your choice, but the result has to be a run-able Unix - binary (i.e. either object-code or a script with the - magic cookie trick '#!/path/to/interpreter' as the first line). -
- This program gets started once at startup of the Apache servers and then - communicates with the rewriting engine over its stdin and - stdout file-handles. For each map-function lookup it will - receive the key to lookup as a newline-terminated string on - stdin. It then has to give back the looked-up value as a - newline-terminated string on stdout or the four-character string - ``NULL'' if it fails (i.e. there is no corresponding value - for the given key). A trivial program which will implement a 1:1 map - (i.e. key == value) could be: -
-
-
--#!/usr/bin/perl -$| = 1; -while (<STDIN>) { - # ...here any transformations - # or lookups should occur... - print $_; -} -- But be very careful:
--
-
- ``Keep the program simple, stupid'' (KISS), because - if this program hangs it will lead to a hang of the Apache server - when the rule occurs. -
- Avoid one common mistake: never do buffered I/O on stdout! - This will cause a deadloop! Hence the ``$|=1'' in the above - example... -
- To declare such a map prefix Filename with a
prg:- string. - - Program Format -
-
| -For plain text and DBM format files the looked-up keys are cached in-core -until the mtime of the mapfile changes or the server does a -restart. This way you can have map-functions in rules which are used -for every request. This is no problem, because the external lookup -only happens once! - |
-
-
-
-RewriteBase
-Syntax: RewriteBase BaseURL
-Default: default is the physical directory path
-Context: per-directory config
-
- -The RewriteBase directive explicitly sets the base URL for -per-directory rewrites. As you will see below, RewriteRule can be -used in per-directory config files (.htaccess). There it will act -locally, i.e. the local directory prefix is stripped at this stage of -processing and your rewriting rules act only on the remainder. At the end -it is automatically added. - -
-When a substitution occurs for a new URL, this module has to -re-inject the URL into the server processing. To be able to do this it needs -to know what the corresponding URL-prefix or URL-base is. By default this -prefix is the corresponding filepath itself. But at most websites URLs are -NOT directly related to physical filename paths, so this assumption -will be usually be wrong! There you have to use the RewriteBase -directive to specify the correct URL-prefix. - -
-
| -So, if your webserver's URLs are not directly -related to physical file paths, you have to use RewriteBase in every -.htaccess files where you want to use RewriteRule -directives. - |
-Example: - -
- Assume the following per-directory config file: - -- - --
-
- -- -In the above example, a request to /xyz/oldstuff.html gets correctly -rewritten to the physical file /abc/def/newstuff.html. - -
-
-
- -- - -For the Apache hackers:
-The following list gives detailed information about the internal -processing steps: - --
-Request: - /xyz/oldstuff.html - -Internal Processing: - /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias) - /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule) - /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase) - /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias) - -Result: - /abc/def/newstuff.html -- -This seems very complicated but is the correct Apache internal processing, -because the per-directory rewriting comes too late in the process. So, -when it occurs the (rewritten) request has to be re-injected into the Apache -kernel! BUT: While this seems like a serious overhead, it really isn't, because -this re-injection happens fully internal to the Apache server and the same -procedure is used by many other operations inside Apache. So, you can be -sure the design and implementation is correct. - -
-
-
-
-RewriteCond
-Syntax: RewriteCond TestString CondPattern
-Default: -None-
-Context: server config, virtual host, per-directory config
-
-
-The RewriteCond directive defines a rule condition. Precede a
-RewriteRule directive with one or more
-TestString is a string which contains server-variables of the form
-
-
-
-
-HTTP_USER_AGENT
-
-REMOTE_ADDR
-
-DOCUMENT_ROOT
-
-TIME_YEAR
-
-API_VERSION
-
-Special Notes:
-
-
-
-
-
-CondPattern is the condition pattern, i.e. a regular expression
-which gets applied to the current instance of the TestString, i.e.
-TestString gets evaluated and then matched against
-CondPattern.
-
-
-Remember: CondPattern is a standard
-Extended Regular Expression with some additions:
-
-
-
-
-
-
-
-
-
-Notice: All of these tests can also be prefixed by a not ('!') character
-to negate their meaning.
-
-Additionally you can set special flags for CondPattern by appending
-
-
-
-
-
-Example:
-
-
-
-
-
-
-The RewriteRule directive is the real rewriting workhorse. The
-directive can occur more than once. Each directive then defines one single
-rewriting rule. The definition order of these rules is
-important, because this order is used when applying the rules at
-run-time.
-
-
-Pattern can be (for Apache 1.1.x a System
-V8 and for Apache 1.2.x a POSIX) regular expression
-which gets applied to the current URL. Here ``current'' means the value of the
-URL when this rule gets applied. This may not be the original requested
-URL, because there could be any number of rules before which already matched
-and made alterations to it.
-
-
-Some hints about the syntax of regular expressions:
-
-
-
-Additionally the NOT character ('!') is a possible pattern
-prefix. This gives you the ability to negate a pattern; to say, for instance: ``if
-the current URL does NOT match to this pattern''. This can be used
-for special cases where it is better to match the negative pattern or as a
-last default rule.
-
-
-
-Substitution of a rewriting rule is the string
-which is substituted for (or replaces) the original URL for which
-Pattern matched. Beside plain text you can use
-
-
-As already mentioned above, all the rewriting rules are applied to the
-Substitution (in the order of definition in the config file). The
-URL is completely replaced by the Substitution and the
-rewriting process goes on until there are no more rules (unless explicitly
-terminated by a
-There is a special substitution string named '-' which means:
-NO substitution! Sounds silly? No, it is useful to provide rewriting
-rules which only match some URLs but do no substitution, e.g. in
-conjunction with the C (chain) flag to be able to have more than one
-pattern to be applied before a substitution occurs.
-
-
-
-Remember: An unconditional external redirect to your own server will
-not work with the prefix http://thishost because of this feature.
-To achieve such a self-redirect, you have to use the R-flag (see
-below).
-
-Additionally you can set special flags for Substitution by appending
-
-
- Notice: When you use this flag, make sure that the
- substitution field is a valid URL! If not, you are redirecting to an
- invalid location! And remember that this flag itself only prefixes the
- URL with
-
-
-
- Notice: You really have to put ProxyRequests On into your
- server configuration to prevent proxy requests from leading to core-dumps
- inside the Apache kernel. If you have not compiled in the proxy module,
- then there is no core-dump problem, because mod_rewrite checks for
- existence of the proxy module and if lost forbids proxy URLs.
-
-
-
-
-
-
- Use the following rule for your decision: whenever you prefix some URLs
- with CGI-scripts to force them to be processed by the CGI-script, the
- chance is high that you will run into problems (or even overhead) on sub-requests.
- In these cases, use this flag.
-
-
- Notice: You have to use this flag if you want to intermix directives
- of different modules which contain URL-to-filename translators. The
- typical example is the use of mod_alias and
- mod_rewrite..
-
-
-
-
-
-There is one exception: If a substitution string starts with
-``http://'' then the directory prefix will be not added and a
-external redirect or proxy throughput (if flag P is used!) is forced!
-
-
-Here are all possible substitution combinations and their meanings:
-
-
-Inside per-server configuration (httpd.conf)
-
-Inside per-directory configuration for /somepath
-
-Example:
-
-
-We take the rewrite mapfile from above and save it under
-
-
-
-The details given are:
-
-You can now access server statistics by using a Web browser to access the
-page
-Note that mod_status will only work when you are running Apache in
-standalone mode and not
-inetd mode.
-
-
-
-Do this by adding the following to the AUX_CFLAGS line in the
-"Configuration" file and then recompiling as usual.
-
-
-The UserDir directive sets the real directory in a user's home directory
-to use when a request for a document for a user is received.
-Directory is either
-
-Be careful when using this directive; for instance, "UserDir
-./" would map "/~root" to
-"/" - which is probably undesirable. See also
-the
-<Directory>
-directive and the
-Security Tips
-page for more information.
-
-
-
-When used, this directive sets an expiry time on the cookie generated
-by the usertrack module. The expiry-period can be given either
-as a number of seconds, or in the format such as "2 weeks 3 days 7
-hours". Valid denominations are: years, months, weeks, hours, minutes
-and seconds.
-
- If this directive is not used, cookies last only for the current
-browser session.
-
-When the user track module is compiled in, and "CookieTracking on" is
-set, Apache will start sending a user-tracking cookie for all new
-requests. This directive can be used to turn this behavior on or off
-on a per-server or per-directory basis. By default, compiling
-mod_usertrack will not activate cookies.
-
-
-
-
-
diff --git a/docs/manual/platform/perf-dec.html b/docs/manual/platform/perf-dec.html
deleted file mode 100644
index 7cc8bb13081..00000000000
--- a/docs/manual/platform/perf-dec.html
+++ /dev/null
@@ -1,279 +0,0 @@
-
-
-
-
-In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not
-defined by Apache autoconfiguration). To reduce instances of connections
-in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2
-only).
-
-
-
-NOTE: Unixware 2.1.2 and later already have patch ptf3123 included
-
-In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not
-defined by Apache autoconfiguration). To reduce instances of connections
-in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2
-only).
-
-Thanks to Joe Doupnik <JRD@cc.usu.edu> and Rich Vaughn
-<rvaughn@aad.com> for additional info for UnixWare builds.
-
-
-
-
diff --git a/docs/manual/process-model.html b/docs/manual/process-model.html
deleted file mode 100644
index c130decffa7..00000000000
--- a/docs/manual/process-model.html
+++ /dev/null
@@ -1,68 +0,0 @@
-
-
-We found that many people were using values for "MaxServers" either
-too high or too low, and were hanging themselves on it. The model we
-adopted is still based on long-lived minimal-forking processes, but
-instead of specifying one number of persistent processes, the
-web-master specifies a maximum and minimum number of processes to be
-"spare" - every couple of seconds the parent checks the actual number
-of spare servers and adjusts accordingly. This should keep the number
-of servers concurrently running relatively low while still ensuring
-minimal forking.
-
-
-
-We renamed the current StartServers to MinSpareServers, created
-separate StartServers parameter which means what it says, and renamed
-MaxServers to MaxSpareServers (though the old name still works, for
-NCSA 1.4 back-compatibility). The old names were generally regarded
-as too confusing.
-
-
-
-The defaults for each variable are:
-
-
-
-In versions before 1.2, HARD_SERVER_LIMIT defaulted to 150.
-
-We do not recommend changing either of these values unless:
-
-
- This script performs a very simple search across the Apache
- documentation for any single case-insensitive word. No combinations,
- wildcards, regular expressions, word-stubbing, or other fancy options
- are supported; this is just to help you find topics quickly. Only
- those pages which include the exact word you type will be
- listed.
-
- Documents containing the search word are not listed in any
- sort of priority order.
- \n Sorry, no matches found.\n Total of %d match", scalar (@files));
- #
- # Be smart about plurals.
- #
- if (scalar (@files) != 1) {
- printf ("es") ;
- }
- printf (" found.\n You will notice many To send a signal to the parent you should issue a command such as:
- Sending the Sending the Users of the
-status module
-will notice that the server statistics are
-set to zero when a Note: If your configuration file has errors in it when you issue a
-restart then your parent will not restart, it will exit with an error.
-See below for a method of avoiding this.
-
- Note: prior to release 1.2b9 this code is quite unstable and
-shouldn't be used at all.
-
- The This code is designed to always respect the
-MaxClients,
-MinSpareServers,
-and MaxSpareServers settings.
-Furthermore, it respects StartServers
-in the following manner: if after one second at least StartServers new
-children have not been created, then create enough to pick up the slack.
-This is to say that the code tries to maintain both the number of children
-appropriate for the current load on the server, and respect your wishes
-with the StartServers parameter.
-
- Users of the
-status module
-will notice that the server statistics
-are not set to zero when a The status module will also use a At present there is no way for a log rotation script using
- Note: If your configuration file has errors in it when you issue a
-restart then your parent will not restart, it will exit with an error.
-In the case of graceful
-restarts it will also leave children running when it exits. (These are
-the children which are "gracefully exiting" by handling their last request.)
-This will cause problems if you attempt to restart the server -- it will
-not be able to bind to its listening ports. At present the only work
-around is to check the syntax of your files before doing a restart. The
-easiest way is to just run httpd as a non-root user. If there are no
-errors it will attempt to open its sockets and logs and fail because it's
-not root (or because the currently running httpd already has those ports
-bound). If it fails for any other reason then it's probably a config file
-error and the error should be fixed before issuing the graceful restart.
-
- Prior to Apache 1.2b9 there were several race conditions
-involving the restart and die signals (a simple description of race
-condition is: a time-sensitive problem, as in if something happens at just
-the wrong time it won't behave as expected). For those architectures that
-have the "right" feature set we have eliminated as many as we can.
-But it should be noted that there still do exist race conditions on
-certain architectures.
-
- Architectures that use an on disk
-ScoreBoardFile
-have the potential to corrupt their scoreboards. This can result in
-the "bind: Address already in use" (after All architectures have a small race condition in each child involving
-the second and subsequent requests on a persistent HTTP connection
-(KeepAlive). It may exit after reading the request line but before
-reading any of the request headers. There is a fix that was discovered
-too late to make 1.2. In theory this isn't an issue because the KeepAlive
-client has to expect these events because of network latencies and
-server timeouts. In practice it doesn't seem to affect anything either
--- in a test case the server was restarted twenty times per second and
-clients successfully browsed the site without getting broken images or
-empty documents.
-
-
-
-
diff --git a/docs/manual/stopping.html.en b/docs/manual/stopping.html.en
deleted file mode 100644
index 373590a3119..00000000000
--- a/docs/manual/stopping.html.en
+++ /dev/null
@@ -1,166 +0,0 @@
-
-
- You will notice many To send a signal to the parent you should issue a command such as:
- Sending the Sending the Users of the
-status module
-will notice that the server statistics are
-set to zero when a Note: If your configuration file has errors in it when you issue a
-restart then your parent will not restart, it will exit with an error.
-See below for a method of avoiding this.
-
- Note: prior to release 1.2b9 this code is quite unstable and
-shouldn't be used at all.
-
- The This code is designed to always respect the
-MaxClients,
-MinSpareServers,
-and MaxSpareServers settings.
-Furthermore, it respects StartServers
-in the following manner: if after one second at least StartServers new
-children have not been created, then create enough to pick up the slack.
-This is to say that the code tries to maintain both the number of children
-appropriate for the current load on the server, and respect your wishes
-with the StartServers parameter.
-
- Users of the
-status module
-will notice that the server statistics
-are not set to zero when a The status module will also use a At present there is no way for a log rotation script using
- Note: If your configuration file has errors in it when you issue a
-restart then your parent will not restart, it will exit with an error.
-In the case of graceful
-restarts it will also leave children running when it exits. (These are
-the children which are "gracefully exiting" by handling their last request.)
-This will cause problems if you attempt to restart the server -- it will
-not be able to bind to its listening ports. At present the only work
-around is to check the syntax of your files before doing a restart. The
-easiest way is to just run httpd as a non-root user. If there are no
-errors it will attempt to open its sockets and logs and fail because it's
-not root (or because the currently running httpd already has those ports
-bound). If it fails for any other reason then it's probably a config file
-error and the error should be fixed before issuing the graceful restart.
-
- Prior to Apache 1.2b9 there were several race conditions
-involving the restart and die signals (a simple description of race
-condition is: a time-sensitive problem, as in if something happens at just
-the wrong time it won't behave as expected). For those architectures that
-have the "right" feature set we have eliminated as many as we can.
-But it should be noted that there still do exist race conditions on
-certain architectures.
-
- Architectures that use an on disk
-ScoreBoardFile
-have the potential to corrupt their scoreboards. This can result in
-the "bind: Address already in use" (after All architectures have a small race condition in each child involving
-the second and subsequent requests on a persistent HTTP connection
-(KeepAlive). It may exit after reading the request line but before
-reading any of the request headers. There is a fix that was discovered
-too late to make 1.2. In theory this isn't an issue because the KeepAlive
-client has to expect these events because of network latencies and
-server timeouts. In practice it doesn't seem to affect anything either
--- in a test case the server was restarted twenty times per second and
-clients successfully browsed the site without getting broken images or
-empty documents.
-
-
-
-
diff --git a/docs/manual/suexec.html b/docs/manual/suexec.html
deleted file mode 100644
index 2b32aa950d6..00000000000
--- a/docs/manual/suexec.html
+++ /dev/null
@@ -1,190 +0,0 @@
-
-
-
-
-
-
-Edit the
-From support/suexec.h
-
-This should create the suexec wrapper executable.
-
-
-From src/httpd.h
-
-If your installation requires location of the wrapper program in a different
-directory, edit src/httpd.h and recompile your Apache server.
-See Compiling and Installing Apache for more
-info on this process.
-
-
-In order for the wrapper to set the user ID for execution requests it
-must me installed as owner root and must have
-the setuserid execution bit set for file modes.
-If you are not running a root user shell, do
-so now and execute the following commands.
-
-
-
-
-Change the path to the suEXEC wrapper to match your system
-installation.
-
-
-
-
-
-If you don't see this message at server startup, the server is most
-likely not finding the wrapper program where it expects it, or the
-executable is not installed setuid root. Check
-your installation and try again.
-
-One way to use suEXEC is through the
-User and
-Group directives in
-VirtualHost
-definitions. By setting these directives to values different from the
-main server user ID, all requests for CGI resources will be executed as
-the User and Group defined for that
-<VirtualHost>. If only one or
-neither of these directives are specified for a
-<VirtualHost> then the main
-server userid is assumed.
-
-suEXEC can also be used to to execute CGI programs as
-the user to which the request is being directed. This is accomplished by
-using the ~ character prefixing the user ID for whom
-execution is desired.
-The only requirement needed for this feature to work is for CGI
-execution to be enabled for the user and that the script must meet the
-scrutiny of the security checks above.
-
-
-
-
-
-
-Edit the
-From support/suexec.h
-
-This should create the suexec wrapper executable.
-
-
-From src/httpd.h
-
-If your installation requires location of the wrapper program in a different
-directory, edit src/httpd.h and recompile your Apache server.
-See Compiling and Installing Apache for more
-info on this process.
-
-
-In order for the wrapper to set the user ID for execution requests it
-must me installed as owner root and must have
-the setuserid execution bit set for file modes.
-If you are not running a root user shell, do
-so now and execute the following commands.
-
-
-
-
-Change the path to the suEXEC wrapper to match your system
-installation.
-
-
-
-
-
-If you don't see this message at server startup, the server is most
-likely not finding the wrapper program where it expects it, or the
-executable is not installed setuid root. Check
-your installation and try again.
-
-One way to use suEXEC is through the
-User and
-Group directives in
-VirtualHost
-definitions. By setting these directives to values different from the
-main server user ID, all requests for CGI resources will be executed as
-the User and Group defined for that
-<VirtualHost>. If only one or
-neither of these directives are specified for a
-<VirtualHost> then the main
-server userid is assumed.
-
-suEXEC can also be used to to execute CGI programs as
-the user to which the request is being directed. This is accomplished by
-using the ~ character prefixing the user ID for whom
-execution is desired.
-The only requirement needed for this feature to work is for CGI
-execution to be enabled for the user and that the script must meet the
-scrutiny of the security checks above.
-
-
-%{ NAME_OF_VARIABLE }
-
-
-where NAME_OF_VARIABLE can be a string
-of the following list:
-
-
-
-
-
-
-
-
-HTTP headers:
-
-
-HTTP_REFERER
-HTTP_COOKIE
-HTTP_FORWARDED
-HTTP_HOST
-HTTP_PROXY_CONNECTION
-HTTP_ACCEPT
-
-
-connection & request:
-
-
-REMOTE_HOST
-REMOTE_USER
-REMOTE_IDENT
-REQUEST_METHOD
-SCRIPT_FILENAME
-PATH_INFO
-QUERY_STRING
-AUTH_TYPE
-
-
-
-
-
-server internals:
-
-
-SERVER_ADMIN
-SERVER_NAME
-SERVER_PORT
-SERVER_PROTOCOL
-SERVER_SOFTWARE
-SERVER_VERSION
-
-
-system stuff:
-
-
-TIME_MON
-TIME_DAY
-TIME_HOUR
-TIME_MIN
-TIME_SEC
-TIME_WDAY
-
-
-specials:
-
-THE_REQUEST
-REQUEST_URI
-REQUEST_FILENAME
-IS_SUBREQ
-
-
-
-
-
-These variables all correspond to the similar named HTTP MIME-headers, C
-variables of the Apache server or struct tm fields of the Unix
-system.
-
-
-
-
-
-
-
-
-
-Treats the TestString as a pathname and
-tests if it exists and is a directory.
-
-Treats the TestString as a pathname and
-tests if it exists and is a regular file.
-
-Treats the TestString as a pathname and
-tests if it exists and is a regular file with size greater then zero.
-
-Treats the TestString as a pathname and
-tests if it exists and is a symbolic link.
-
-Checks if TestString is a valid file and accessible via all the
-server's currently-configured access controls for that path. This uses an
-internal subrequest to determine the check, so use it with care because it
-decreases your servers performance!
-
-Checks if TestString is a valid URL and accessible via all the server's
-currently-configured access controls for that path. This uses an internal
-subrequest to determine the check, so use it with care because it decreases
-your servers performance!
-
-
-
-as the third argument to the RewriteCond directive. Flags
-is a comma-separated list of the following flags:
-
-[flags]
-
-
-
-nocase|NC' (no case)
- This makes the condition test case-insensitive, i.e. there is
- no difference between 'A-Z' and 'a-z' both in the expanded
- TestString and the CondPattern.
-ornext|OR' (or next condition)
- Use this to combine rule conditions with a local OR instead of the
- implicit AND. Typical example:
-
- Without this flag you had to write down the cond/rule three times.
-
-RewriteCond %{REMOTE_HOST} ^host1.* [OR]
-RewriteCond %{REMOTE_HOST} ^host2.* [OR]
-RewriteCond %{REMOTE_HOST} ^host3.*
-RewriteRule ...some special stuff for any of these hosts...
-
-
-To rewrite the Homepage of a site according to the ``User-Agent:''
-header of the request, you can use the following:
-
-
-
-
-Interpretation: If you use Netscape Navigator as your browser (which identifies
-itself as 'Mozilla'), then you get the max homepage, which includes
-Frames, etc. If you use the Lynx browser (which is Terminal-based), then you
-get the min homepage, which contains no images, no tables, etc. If you
-use any other browser you get the standard homepage.
-
-RewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
-RewriteRule ^/$ /homepage.max.html [L]
-
-RewriteCond %{HTTP_USER_AGENT} ^Lynx.*
-RewriteRule ^/$ /homepage.min.html [L]
-
-RewriteRule ^/$ /homepage.std.html [L]
-
-RewriteRule
-Syntax: RewriteRule Pattern Substitution
-Default: -None-
-Context: server config, virtual host, per-directory config
-
-
-
-
-
-
-
-
-
-
-^ Start of line
-$ End of line
-. Any single character
-[chars] One of chars
-[^chars] None of chars
-
-? 0 or 1 of the preceding char
-* 0 or N of the preceding char
-+ 1 or N of the preceding char
-
-\char escape that specific char
- (e.g. for specifying the chars ".[]()" etc.)
-
-(string) Grouping of chars (the Nth group can be used on the RHS with $N)
-
-
-
-
-Notice! When using the NOT character to negate a pattern you cannot
-have grouped wildcard parts in the pattern. This is impossible because when
-the pattern does NOT match, there are no contents for the groups. In
-consequence, if negated patterns are used, you cannot use $N in the
-substitution string!
-
-
-
-Back-references are $N)
-%{VARNAME})
-${mapname:key|default})
-$N (N=1..9) identifiers which
-will be replaced by the contents of the Nth group of the matched
-Pattern. The server-variables are the same as for the
-TestString of a RewriteCond directive. The
-mapping-functions come from the RewriteMap directive and are
-explained there. These three types of variables are expanded in the order of
-the above list.
-
-L flag - see below).
-
-
-
-
-
-Notice: There is a special feature. When you prefix a substitution
-field with http://thishost[:thisport] then
-mod_rewrite automatically strips it out. This auto-reduction on
-implicit external redirect URLs is a useful and important feature when
-used in combination with a mapping-function which generates the hostname
-part. Have a look at the first example in the example section below to
-understand this.
-
-
-
-as the third argument to the RewriteRule directive. Flags is a
-comma-separated list of the following flags:
-
-[flags]
-
-
-
-redirect|R[=code]' (force redirect)
- Prefix Substitution
- with http://thishost[:thisport]/ (which makes the new URL a URI) to
- force a external redirection. If no code is given a HTTP response
- of 302 (MOVED TEMPORARILY) is used. If you want to use other response
- codes in the range 300-400 just specify them as a number or use
- one of the following symbolic names: temp (default), permanent,
- seeother.
- Use it for rules which should
- canonicalize the URL and gives it back to the client, e.g. translate
- ``/~'' into ``/u/'' or always append a slash to
- /u/user, etc.
- http://thishost[:thisport]/, but rewriting goes on.
- Usually you also want to stop and do the redirection immediately. To stop
- the rewriting you also have to provide the 'L' flag.
-forbidden|F' (force URL to be forbidden)
- This forces the current URL to be forbidden, i.e. it immediately sends
- back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with
- appropriate RewriteConds to conditionally block some URLs.
-gone|G' (force URL to be gone)
- This forces the current URL to be gone, i.e. it immediately sends back a
- HTTP response of 410 (GONE). Use this flag to mark no longer existing
- pages as gone.
-proxy|P' (force proxy)
- This flag forces the substitution part to be internally forced as a proxy
- request and immediately (i.e. rewriting rule processing stops here) put
- through the proxy module. You have to make sure that the substitution
- string is a valid URI (e.g. typically http://) which can
- be handled by the Apache proxy module. If not you get an error from
- the proxy module. Use this flag to achieve a more powerful implementation
- of the mod_proxy directive ProxyPass, to map
- some remote stuff into the namespace of the local server.
- last|L' (last rule)
- Stop the rewriting process here and
- don't apply any more rewriting rules. This corresponds to the Perl
- last command or the break command from the C
- language. Use this flag to prevent the currently rewritten URL from being
- rewritten further by following rules which may be wrong. For
- example, use it to rewrite the root-path URL ('/') to a real
- one, e.g. '/e/www/'.
-next|N' (next round)
- Re-run the rewriting process (starting again with the first rewriting
- rule). Here the URL to match is again not the original URL but the URL
- from the last rewriting rule. This corresponds to the Perl
- next command or the continue command from the C
- language. Use this flag to restart the rewriting process, i.e. to
- immediately go to the top of the loop.
- But be careful not to create a deadloop!
-chain|C' (chained with next rule)
- This flag chains the current rule with the next rule (which itself can
- also be chained with its following rule, etc.). This has the following
- effect: if a rule matches, then processing continues as usual, i.e. the
- flag has no effect. If the rule does not match, then all following
- chained rules are skipped. For instance, use it to remove the
- ``.www'' part inside a per-directory rule set when you let an
- external redirect happen (where the ``.www'' part should not to
- occur!).
-type|T=mime-type' (force MIME type)
- Force the MIME-type of the target file to be mime-type. For
- instance, this can be used to simulate the old mod_alias
- directive ScriptAlias which internally forces all files inside
- the mapped directory to have a MIME type of
- ``application/x-httpd-cgi''.
-nosubreq|NS' (used only if no internal sub-request)
- This flag forces the rewriting engine to skip a rewriting rule if the
- current request is an internal sub-request. For instance, sub-requests
- occur internally in Apache when mod_include tries to find out
- information about possible directory default files (index.xxx).
- On sub-requests it is not always useful and even sometimes causes a failure to
- if the complete set of rules are applied. Use this flag to exclude some rules.
- passthrough|PT' (pass through to next handler)
- This flag forces the rewriting engine to set the uri field
- of the internal request_rec structure to the value
- of the filename field. This flag is just a hack to be able
- to post-process the output of RewriteRule directives by
- Alias, ScriptAlias, Redirect, etc. directives
- from other URI-to-filename translators. A trivial example to show the
- semantics:
- If you want to rewrite /abc to /def via the rewriting
- engine of mod_rewrite and then /def to /ghi
- with mod_alias:
-
- RewriteRule ^/abc(.*) /def$1 [PT]
- Alias /def /ghi
-
- If you omit the PT flag then mod_rewrite
- will do its job fine, i.e. it rewrites uri=/abc/... to
- filename=/def/... as a full API-compliant URI-to-filename
- translator should do. Then mod_alias comes and tries to do a
- URI-to-filename transition which will not work.
-
-
-
-
- For the Apache hackers:
- If the current Apache API had a
- filename-to-filename hook additionally to the URI-to-filename hook then
- we wouldn't need this flag! But without such a hook this flag is the
- only solution. The Apache Group has discussed this problem and will
- add such hooks into Apache version 2.0.
-
-skip|S=num' (skip next rule(s))
- This flag forces the rewriting engine to skip the next num rules
- in sequence when the current rule matches. Use this to make pseudo
- if-then-else constructs: The last rule of the then-clause becomes
- a skip=N where N is the number of rules in the else-clause.
- (This is not the same as the 'chain|C' flag!)
-env|E=VAR:VAL' (set environment variable)
- This forces an environment variable named VAR to be set to the value
- VAL, where VAL can contain regexp backreferences $N
- which will be expanded. You can use this flag more than once to set more
- than one variable. The variables can be later dereferenced at a lot of
- situations, but the usual location will be from within XSSI (via
- <!--#echo var="VAR"-->) or CGI (e.g. $ENV{'VAR'}).
- But additionally you can also dereference it in a following RewriteCond
- pattern via %{ENV:VAR}. Use this to strip but remember
- information from URLs.
-
-
-
-
-Remember: Never forget that Pattern gets applied to a complete URL
-in per-server configuration files. But in per-directory configuration
-files, the per-directory prefix (which always is the same for a specific
-directory!) gets automatically removed for the pattern matching and
-automatically added after the substitution has been done. This feature is
-essential for many sorts of rewriting, because without this prefix stripping
-you have to match the parent directory which is not always possible.
-
-
-
-
-Notice! To enable the rewriting engine for per-directory configuration files
-you need to set ``RewriteEngine On'' in these files and
-``Option FollowSymLinks'' enabled. If your administrator has
-disabled override of FollowSymLinks for a user's directory, then
-you cannot use the rewriting engine. This restriction is needed for
-security reasons.
-
-for request ``GET /somepath/pathinfo'':
-
-
-
-
-
-
-
-
-
-Given Rule Resulting Substitution
----------------------------------------------- ----------------------------------
-^/somepath(.*) otherpath$1 not supported, because invalid!
-
-^/somepath(.*) otherpath$1 [R] not supported, because invalid!
-
-^/somepath(.*) otherpath$1 [P] not supported, because invalid!
----------------------------------------------- ----------------------------------
-^/somepath(.*) /otherpath$1 /otherpath/pathinfo
-
-^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
- via external redirection
-
-^/somepath(.*) /otherpath$1 [P] not supported, because silly!
----------------------------------------------- ----------------------------------
-^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
-
-^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
- via external redirection
-
-^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly!
----------------------------------------------- ----------------------------------
-^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
- via external redirection
-
-^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
- via external redirection
- (the [R] flag is redundant)
-
-^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
- via internal proxy
-
-
-(i.e. file .htaccess in dir /physical/path/to/somepath containing
-RewriteBase /somepath)
for
-request ``GET /somepath/localpath/pathinfo'':
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Given Rule Resulting Substitution
----------------------------------------------- ----------------------------------
-^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo
-
-^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo
- via external redirection
-
-^localpath(.*) otherpath$1 [P] not supported, because silly!
----------------------------------------------- ----------------------------------
-^localpath(.*) /otherpath$1 /otherpath/pathinfo
-
-^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
- via external redirection
-
-^localpath(.*) /otherpath$1 [P] not supported, because silly!
----------------------------------------------- ----------------------------------
-^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
-
-^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
- via external redirection
-
-^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly!
----------------------------------------------- ----------------------------------
-^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
- via external redirection
-
-^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
- via external redirection
- (the [R] flag is redundant)
-
-^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
- via internal proxy
-
-
-We want to rewrite URLs of the form
-
-
-
-
-
-
-
diff --git a/docs/manual/mod/mod_status.html b/docs/manual/mod/mod_status.html
deleted file mode 100644
index f5a55fa397c..00000000000
--- a/docs/manual/mod/mod_status.html
+++ /dev/null
@@ -1,107 +0,0 @@
-
-
-
-
-into
-/ Language
-/~ Realname
-/.../ File
-
-
-/u/ Username
-/.../ File
-. Language
-/anywhere/map.real-to-user. Then we only have to add the
-following lines to the Apache server configuration file:
-
-
-
-
-RewriteLog /anywhere/rewrite.log
-RewriteMap real-to-user txt:/anywhere/map.real-to-host
-RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1
-
-Module mod_status
-
-The Status Module is only available in Apache 1.1 and later.Function
-
-The Status module allows a server administrator to find out how well
-their server is performing. A HTML page is presented that gives
-the current server statistics in an easily readable form. If required
-this page can be made to automatically refresh (given a compatible
-browser). Another page gives a simple machine-readable list of the current
-server state.
-
-
-
-A compile-time option must be used to display the details marked "(*)" as
-the instrumentation required for obtaining these statistics does not
-exist within standard Apache.
-
-Enabling Status Support
-
-To enable status reports only for browsers from the foo.com
-domain add this code to your access.conf configuration file
-
- <Location /server-status>
- SetHandler server-status
-
- order deny,allow
- deny from all
- allow from .foo.com
- </Location>
-
-http://your.server.name/server-status
-Automatic Updates
-You can get the status page to update itself automatically if you have
-a browser that supports "refresh". Access the page
-http://your.server.name/server-status?refresh=N to refresh the page
-every N seconds.
-Machine Readable Status File
-A machine-readable version of the status file is available by accessing the
-page http://your.server.name/server-status?auto. This is useful
-when automatically run, see the Perl program in the /support
-directory of Apache, log_server_status.
-
-Full Instrumentation
-
-To obtain full statistics you must compile Apache with a special
-directive. On some machines there may be a small performance loss
-if you do this. Try full statistics and see if you notice any
-difference. If you do please contact
-mark@ukweb.com and tell me your configuration.
-
-
- AUX_CFLAGS= (something) -DSTATUS
-
-
-
-
- It should be noted that if mod_status is compiled into
- the server, its handler capability is available in all
- configuration files, including per-directory files
- (e.g., .htaccess). This may have
- security-related ramifications for your site.
-
-
-
-
-
diff --git a/docs/manual/mod/mod_userdir.html b/docs/manual/mod/mod_userdir.html
deleted file mode 100644
index cca87f5020e..00000000000
--- a/docs/manual/mod/mod_userdir.html
+++ /dev/null
@@ -1,76 +0,0 @@
-
-
-
-Module mod_userdir
-
-This module is contained in the mod_userdir.c file, and
-is compiled in by default. It provides for user-specific directories.
-
-
-
-
-
-
-
-UserDir
-
-Syntax: UserDir directory/filename
-Default: UserDir public_html
-Context: server config, virtual host
-Status: Base
-Module: mod_userdir
-Compatibility: All forms except the UserDir
-public_html form are only available in Apache 1.1 or above.disabled, to disable this feature,
- or the name of a directory, following one of the following
-patterns. If not disabled, then a request for
-http://www.foo.com/~bob/one/two.html will be translated to:
-
-UserDir public_html -> ~bob/public_html/one/two.html
-UserDir /usr/web -> /usr/web/bob/one/two.html
-UserDir /home/*/www -> /home/bob/www/one/two.html
-
-The following directives will send redirects to the client:
-
-UserDir http://www.foo.com/users -> http//www.foo.com/users/bob/one/two.html
-UserDir http://www.foo.com/*/usr -> http://www.foo.com/bob/usr/one/two.html
-UserDir http://www.foo.com/~*/ -> http://www.foo.com/~bob/one/two.html
-
-
-Module mod_usertrack
-
-Previous releases of Apache have included a module which generates a
-'clickstream' log of user activity on a site using cookies. This was
-called the "cookies" module, mod_cookies. In Apache 1.2 and later this
-module has been renamed the "user tracking" module,
-mod_usertrack. This module has been simplified and new directives
-added.
-
-
-
-Logging
-
-Previously, the cookies module (now the user tracking module) did its
-own logging, using the CookieLog directive. In this release,
-this module does no logging at all. Instead, a configurable log
-format file should be used to log user click-streams. This is possible
-because the logging module now allows multiple log files. The cookie itself is
-logged by using the text %{cookie}n
-
-in the log file format. For example:
-
-CustomLog logs/clickstream "%{cookie}n %r %t"
-
-
-For backward compatibility the configurable log module implements the
-old CookieLog directive, but this should be upgraded to the
-above CustomLog directive.
-
-Directives
-
-
-
-
-
-CookieExpires
-Syntax: CookieExpires expiry-period
-Context: server config, virtual host
-Status: optional
-Module: mod_usertrackCookieTracking
-Syntax: CookieTracking on | off
-Context: server config, virtual host, directory,
-.htaccess
-Override: FileInfo
-Status: optional
-Module: mod_usertrackPerformance Tuning Tips for Digital Unix
-
-Below is a set of newsgroup posts made by an engineer from DEC in
-response to queries about how to modify DEC's Digital Unix OS for more
-heavily loaded web sites. Copied with permission.
-
-
-
-Update
-From: Jeffrey Mogul <mogul@pa.dec.com>
-Date: Fri, 28 Jun 96 16:07:56 MDT
-
-
-
-
- Patch ID OSF350-195 for V3.2C
- Patch IDs for V3.2E and V3.2F should be available soon.
- There is no known reason why the Patch ID OSF360-350195
- won't work on these releases, but such use is not officially
- supported by Digital. This patch kit will not be needed for
- V3.2G when it is released.
-
- Patch ID OSF360-350195 for V3.2D
-
-
-
-
-From mogul@pa.dec.com (Jeffrey Mogul)
-Organization DEC Western Research
-Date 30 May 1996 00:50:25 GMT
-Newsgroups comp.unix.osf.osf1
-Message-ID <4oirch$bc8@usenet.pa.dec.com>
-Subject Re: Web Site Performance
-References 1
-
-
-
-In article <skoogDs54BH.9pF@netcom.com> skoog@netcom.com (Jim Skoog) writes:
->Where are the performance bottlenecks for Alpha AXP running the
->Netscape Commerce Server 1.12 with high volume internet traffic?
->We are evaluating network performance for a variety of Alpha AXP
->runing DEC UNIX 3.2C, which run DEC's seal firewall and behind
->that Alpha 1000 and 2100 webservers.
-
-Our experience (running such Web servers as altavista.digital.com
-and www.digital.com) is that there is one important kernel tuning
-knob to adjust in order to get good performance on V3.2C. You
-need to patch the kernel global variable "somaxconn" (use dbx -k
-to do this) from its default value of 8 to something much larger.
-
-How much larger? Well, no larger than 32767 (decimal). And
-probably no less than about 2048, if you have a really high volume
-(millions of hits per day), like AltaVista does.
-
-This change allows the system to maintain more than 8 TCP
-connections in the SYN_RCVD state for the HTTP server. (You
-can use "netstat -An |grep SYN_RCVD" to see how many such
-connections exist at any given instant).
-
-If you don't make this change, you might find that as the load gets
-high, some connection attempts take a very long time. And if a lot
-of your clients disconnect from the Internet during the process of
-TCP connection establishment (this happens a lot with dialup
-users), these "embryonic" connections might tie up your somaxconn
-quota of SYN_RCVD-state connections. Until the kernel times out
-these embryonic connections, no other connections will be accepted,
-and it will appear as if the server has died.
-
-The default value for somaxconn in Digital UNIX V4.0 will be quite
-a bit larger than it has been in previous versions (we inherited
-this default from 4.3BSD).
-
-Digital UNIX V4.0 includes some other performance-related changes
-that significantly improve its maximum HTTP connection rate. However,
-we've been using V3.2C systems to front-end for altavista.digital.com
-with no obvious performance bottlenecks at the millions-of-hits-per-day
-level.
-
-We have some Webstone performance results available at
- http://www.digital.com/info/alphaserver/news/webff.html
-I'm not sure if these were done using V4.0 or an earlier version
-of Digital UNIX, although I suspect they were done using a test
-version of V4.0.
-
--Jeff
-
-
-
-
-
diff --git a/docs/manual/platform/perf.html b/docs/manual/platform/perf.html
deleted file mode 100644
index 96c48ea1992..00000000000
--- a/docs/manual/platform/perf.html
+++ /dev/null
@@ -1,146 +0,0 @@
-
-
-
-
-
-----------------------------------------------------------------------------
-
-From mogul@pa.dec.com (Jeffrey Mogul)
-Organization DEC Western Research
-Date 31 May 1996 21:01:01 GMT
-Newsgroups comp.unix.osf.osf1
-Message-ID <4onmmd$mmd@usenet.pa.dec.com>
-Subject Digital UNIX V3.2C Internet tuning patch info
-
-----------------------------------------------------------------------------
-
-Something that probably few people are aware of is that Digital
-has a patch kit available for Digital UNIX V3.2C that may improve
-Internet performance, especially for busy web servers.
-
-This patch kit is one way to increase the value of somaxconn,
-which I discussed in a message here a day or two ago.
-
-I've included in this message the revised README file for this
-patch kit below. Note that the original README file in the patch
-kit itself may be an earlier version; I'm told that the version
-below is the right one.
-
-Sorry, this patch kit is NOT available for other versions of Digital
-UNIX. Most (but not quite all) of these changes also made it into V4.0,
-so the description of the various tuning parameters in this README
-file might be useful to people running V4.0 systems.
-
-This patch kit does not appear to be available (yet?) from
- http://www.service.digital.com/html/patch_service.html
-so I guess you'll have to call Digital's Customer Support to get it.
-
--Jeff
-
-DESCRIPTION: Digital UNIX Network tuning patch
-
- Patch ID: OSF350-146
-
- SUPERSEDED PATCHES: OSF350-151, OSF350-158
-
- This set of files improves the performance of the network
- subsystem on a system being used as a web server. There are
- additional tunable parameters included here, to be used
- cautiously by an informed system administrator.
-
-TUNING
-
- To tune the web server, the number of simultaneous socket
- connection requests are limited by:
-
- somaxconn Sets the maximum number of pending requests
- allowed to wait on a listening socket. The
- default value in Digital UNIX V3.2 is 8.
- This patch kit increases the default to 1024,
- which matches the value in Digital UNIX V4.0.
-
- sominconn Sets the minimum number of pending connections
- allowed on a listening socket. When a user
- process calls listen with a backlog less
- than sominconn, the backlog will be set to
- sominconn. sominconn overrides somaxconn.
- The default value is 1.
-
- The effectiveness of tuning these parameters can be monitored by
- the sobacklog variables available in the kernel:
-
- sobacklog_hiwat Tracks the maximum pending requests to any
- socket. The initial value is 0.
-
- sobacklog_drops Tracks the number of drops exceeding the
- socket set backlog limit. The initial
- value is 0.
-
- somaxconn_drops Tracks the number of drops exceeding the
- somaxconn limit. When sominconn is larger
- than somaxconn, tracks the number of drops
- exceeding sominconn. The initial value is 0.
-
- TCP timer parameters also affect performance. Tuning the following
- require some knowledge of the characteristics of the network.
-
- tcp_msl Sets the tcp maximum segment lifetime.
- This is the maximum lifetime in half
- seconds that a packet can be in transit
- on the network. This value, when doubled,
- is the length of time a connection remains
- in the TIME_WAIT state after a incoming
- close request is processed. The unit is
- specified in 1/2 seconds, the initial
- value is 60.
-
- tcp_rexmit_interval_min
- Sets the minimum TCP retransmit interval.
- For some WAN networks the default value may
- be too short, causing unnecessary duplicate
- packets to be sent. The unit is specified
- in 1/2 seconds, the initial value is 1.
-
- tcp_keepinit This is the amount of time a partially
- established connection will sit on the listen
- queue before timing out (e.g. if a client
- sends a SYN but never answers our SYN/ACK).
- Partially established connections tie up slots
- on the listen queue. If the queue starts to
- fill with connections in SYN_RCVD state,
- tcp_keepinit can be decreased to make those
- partial connects time out sooner. This should
- be used with caution, since there might be
- legitimate clients that are taking a while
- to respond to SYN/ACK. The unit is specified
- in 1/2 seconds, the default value is 150
- (ie. 75 seconds).
-
- The hashlist size for the TCP inpcb lookup table is regulated by:
-
- tcbhashsize The number of hash buckets used for the
- TCP connection table used in the kernel.
- The initial value is 32. For best results,
- should be specified as a power of 2. For
- busy Web servers, set this to 2048 or more.
-
- The hashlist size for the interface alias table is regulated by:
-
- inifaddr_hsize The number of hash buckets used for the
- interface alias table used in the kernel.
- The initial value is 32. For best results,
- should be specified as a power of 2.
-
- ipport_userreserved The maximum number of concurrent non-reserved,
- dynamically allocated ports. Default range
- is 1025-5000. The maximum value is 65535.
- This limits the numer of times you can
- simultaneously telnet or ftp out to connect
- to other systems.
-
- tcpnodelack Don't delay acknowledging TCP data; this
- can sometimes improve performance of locally
- run CAD packages. Default is value is 0,
- the enabled value is 1.
-
- Digital UNIX version:
-
- V3.2C
-Feature V3.2C patch V4.0
- ======= ===== ===== ====
-somaxconn X X X
-sominconn - X X
-sobacklog_hiwat - X -
-sobacklog_drops - X -
-somaxconn_drops - X -
-tcpnodelack X X X
-tcp_keepidle X X X
-tcp_keepintvl X X X
-tcp_keepcnt - X X
-tcp_keepinit - X X
-TCP keepalive per-socket - - X
-tcp_msl - X -
-tcp_rexmit_interval_min - X -
-TCP inpcb hashing - X X
-tcbhashsize - X X
-interface alias hashing - X X
-inifaddr_hsize - X X
-ipport_userreserved - X -
-sysconfig -q inet - - X
-sysconfig -q socket - - X
-
-Hints on Running a High-Performance Web Server
-
-Running Apache on a heavily loaded web server, one often encounters
-problems related to the machine and OS configuration. "Heavy" is
-relative, of course - but if you are seeing more than a couple hits
-per second on a sustained basis you should consult the pointers on
-this page. In general the suggestions involve how to tune your kernel
-for the heavier TCP load, hardware/software conflicts that arise, etc.
-
-
-
-
-
-
-
-A/UX (Apple's UNIX)
-
-
-If you are running Apache on A/UX, a page that gives some helpful
-performance hints (concerning the listen() queue and using
-virtual hosts)
-can be found here
-
-
-
-
-BSD-based (BSDI, FreeBSD, etc)
-
-
-Quick and
-detailed
-performance tuning hints for BSD-derived systems.
-
-
-
-
-Digital UNIX
-
-
-
-
-
-
-
-
-Hewlett-Packard
-
-
-Some documentation on tuning HP machines can be found at http://www.software.hp.com/internet/perf/tuning.html.
-
-
-
-
-Linux
-
-
-The most common problem on Linux shows up on heavily-loaded systems
-where the whole server will appear to freeze for a couple of minutes
-at a time, and then come back to life. This has been traced to a
-listen() queue overload - certain Linux implementations have a low
-value set for the incoming connection queue which can cause problems.
-Please see our Using Apache on
-Linux page for more info on how to fix this.
-
-
-
-
-SGI
-
-
-
-
-
-
-
-Solaris 2.4
-
-
-The Solaris 2.4 TCP implementation has a few inherent limitations that
-only became apparent under heavy loads. This has been fixed to some
-extent in 2.5 (and completely revamped in 2.6), but for now consult
-the following URL for tips on how to expand the capabilities if you
-are finding slowdowns and lags are hurting performance.
-
-
-
-
-
-
-
-
-SunOS 4.x
-
-
-More information on tuning SOMAXCONN on SunOS can be found at
-
-http://www.islandnet.com/~mark/somaxconn.html.
-
-
-
-More welcome!
-
-If you have tips to contribute, send mail to brian@organic.com
-
-
-
-
diff --git a/docs/manual/platform/unixware.html b/docs/manual/platform/unixware.html
deleted file mode 100644
index eb8adbe2fe8..00000000000
--- a/docs/manual/platform/unixware.html
+++ /dev/null
@@ -1,61 +0,0 @@
-
-
-
-Compiling Apache under UnixWare
-
-To compile a working copy of Apache under UnixWare, there are several other
-steps you may need to take. These prevent such problems as zombie processes,
-bind errors, and accept errors, to name a few.
-
-UnixWare 1.x
-
-Make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not
-defined by Apache autoconfiguration). If using the UnixWare cc
-compiler, and you still see accept() errors, don't use compiler optimization,
-or get gcc.
-
-UnixWare 2.0.x
-
-SCO patch tf2163 is required
-in order for Apache to work correctly on UnixWare 2.0.x. See
-http://www.sco.com
-for UnixWare patch information.UnixWare 2.1.x
-
-SCO patch ptf3123 is required
-in order for Apache to work correctly on UnixWare 2.1.x. See
-http://www.sco.com
-for UnixWare patch information.Server Pool Management
-
-
-
-MinSpareServers 5
-MaxSpareServers 10
-StartServers 5
-
-
-There is an absolute maximum number of simultaneous children defined
-by a compile-time limit which defaults to 256 and a "MaxClients"
-directive which specifies the number of simultaneous children that
-will be allowed. MaxClients can be adjusted up to the compile-time
-limit (HARD_SERVER_LIMIT, defined in httpd.h). If you need more
-than 256 simultaneous children, you need to modify both HARD_SERVER_LIMIT
-and MaxClients.
-
-
-
-
-
-
diff --git a/docs/manual/search/manual-index.cgi b/docs/manual/search/manual-index.cgi
deleted file mode 100644
index 8d06e8a1158..00000000000
--- a/docs/manual/search/manual-index.cgi
+++ /dev/null
@@ -1,239 +0,0 @@
-#!/usr/local/bin/perl5 -w
-# ====================================================================
-# Copyright (c) 1995-1997 The Apache Group. All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions
-# are met:
-#
-# 1. Redistributions of source code must retain the above copyright
-# notice, this list of conditions and the following disclaimer.
-#
-# 2. Redistributions in binary form must reproduce the above copyright
-# notice, this list of conditions and the following disclaimer in
-# the documentation and/or other materials provided with the
-# distribution.
-#
-# 3. All advertising materials mentioning features or use of this
-# software must display the following acknowledgment:
-# "This product includes software developed by the Apache Group
-# for use in the Apache HTTP server project (http://www.apache.org/)."
-#
-# 4. The names "Apache Server" and "Apache Group" must not be used to
-# endorse or promote products derived from this software without
-# prior written permission.
-#
-# 5. Redistributions of any form whatsoever must retain the following
-# acknowledgment:
-# "This product includes software developed by the Apache Group
-# for use in the Apache HTTP server project (http://www.apache.org/)."
-#
-# THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY
-# EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR
-# ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
-# OF THE POSSIBILITY OF SUCH DAMAGE.
-# ====================================================================
-#
-# manual-index.cgi script
-# originally written by Ken Coar 
-
- Apache Documentation Search
-
-
- Results of Search for $word
-
-EOHT
-
-#
-# We enblock the next section so problems can drop out to the common
-# closure code.
-#
-QUERY:
- {
- if ($word) {
- #
- # Try and open the index file; complain bitterly if we can't.
- #
- if (! open (INDEX, "<$INDEX")) {
- printf ("Can't find documentation index!");
- last QUERY;
- }
- #
- # Got it; display the search-results header.
- #
- printf ($HTML);
- #
- # Read the entire index in and turn it into an hash for the
- # lookup.
- #
- @index = \n");
- foreach (@files) {
- printf ("
\n");
- #
- # C'est tout!
- #
- }
- }
-
-#
-# Back to common code - the exit path. Display the page trailer.
-#
-$HTML = <
-
-
-
-EOHT
-
-printf ($HTML);
-exit (0);
diff --git a/docs/manual/stopping.html b/docs/manual/stopping.html
deleted file mode 100644
index 373590a3119..00000000000
--- a/docs/manual/stopping.html
+++ /dev/null
@@ -1,166 +0,0 @@
-
-
-
-Stopping and Restarting Apache
-
-httpd executables running on your system,
-but you should not send signals to any of them except the parent, whose
-pid is in the PidFile. That is to
-say you shouldn't ever need to send signals to any process except the
-parent. There are three signals that you can send the parent:
-TERM, HUP, and USR1, which will
-be described in a moment.
-
-
-
-You can read about its progress by issuing:
-
-
- kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid`
-
-
-Modify those examples to match your
-ServerRoot and
-PidFile settings.
-
-
- tail -f /usr/local/etc/httpd/logs/error_log
-
TERM Signal: stop now
-
-TERM signal to the parent causes it to
-immediately attempt to kill off all of its children. It may take it
-several seconds to complete killing off its children. Then the
-parent itself exits. Any requests in progress are terminated, and no
-further requests are served.
-
-HUP Signal: restart now
-
-HUP signal to the parent causes it to kill off
-its children like in TERM but the parent doesn't exit. It
-re-reads its configuration files, and re-opens any log files.
-Then it spawns a new set of children and continues
-serving hits.
-
-HUP is sent.
-
-USR1 Signal: graceful restart
-
-USR1 signal causes the parent process to advise
-the children to exit after their current request (or to exit immediately
-if they're not serving anything). The parent re-reads its configuration
-files and re-opens its log files. As each child dies off the parent
-replaces it with a child from the new generation of the
-configuration, which begins serving new requests immediately.
-
-USR1 is sent. The code
-was written to both minimize the time in which the server is unable to serve
-new requests (they will be queued up by the operating system, so they're
-not lost in any event) and to respect your tuning parameters. In order
-to do this it has to keep the scoreboard used to keep track
-of all children across generations.
-
-G to indicate those
-children which are still serving requests started before the graceful
-restart was given.
-
-USR1 to know for certain that all children writing the
-pre-restart log have finished. We suggest that you use a suitable delay
-after sending the USR1 signal before you do anything with the
-old log. For example if most of your hits take less than 10 minutes to
-complete for users on low bandwidth links then you could wait 15 minutes
-before doing anything with the old log.
-
-Appendix: signals and race conditions
-
-HUP) or
-"long lost child came home!" (after USR1). The former is
-a fatal error, while the latter just causes the server to lose a scoreboard
-slot. So it might be advisable to use graceful restarts, with
-an occasional hard restart. These problems are very difficult to work
-around, but fortunately most architectures do not require a scoreboard file.
-See the ScoreBoardFile documentation for a method to determine if your
-architecture uses it.
-
-NEXT and MACHTEN (68k only) have small race
-conditions
-which can cause a restart/die signal to be lost, but should not cause the
-server to do anything otherwise problematic.
-
-
-Stopping and Restarting Apache
-
-httpd executables running on your system,
-but you should not send signals to any of them except the parent, whose
-pid is in the PidFile. That is to
-say you shouldn't ever need to send signals to any process except the
-parent. There are three signals that you can send the parent:
-TERM, HUP, and USR1, which will
-be described in a moment.
-
-
-
-You can read about its progress by issuing:
-
-
- kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid`
-
-
-Modify those examples to match your
-ServerRoot and
-PidFile settings.
-
-
- tail -f /usr/local/etc/httpd/logs/error_log
-
TERM Signal: stop now
-
-TERM signal to the parent causes it to
-immediately attempt to kill off all of its children. It may take it
-several seconds to complete killing off its children. Then the
-parent itself exits. Any requests in progress are terminated, and no
-further requests are served.
-
-HUP Signal: restart now
-
-HUP signal to the parent causes it to kill off
-its children like in TERM but the parent doesn't exit. It
-re-reads its configuration files, and re-opens any log files.
-Then it spawns a new set of children and continues
-serving hits.
-
-HUP is sent.
-
-USR1 Signal: graceful restart
-
-USR1 signal causes the parent process to advise
-the children to exit after their current request (or to exit immediately
-if they're not serving anything). The parent re-reads its configuration
-files and re-opens its log files. As each child dies off the parent
-replaces it with a child from the new generation of the
-configuration, which begins serving new requests immediately.
-
-USR1 is sent. The code
-was written to both minimize the time in which the server is unable to serve
-new requests (they will be queued up by the operating system, so they're
-not lost in any event) and to respect your tuning parameters. In order
-to do this it has to keep the scoreboard used to keep track
-of all children across generations.
-
-G to indicate those
-children which are still serving requests started before the graceful
-restart was given.
-
-USR1 to know for certain that all children writing the
-pre-restart log have finished. We suggest that you use a suitable delay
-after sending the USR1 signal before you do anything with the
-old log. For example if most of your hits take less than 10 minutes to
-complete for users on low bandwidth links then you could wait 15 minutes
-before doing anything with the old log.
-
-Appendix: signals and race conditions
-
-HUP) or
-"long lost child came home!" (after USR1). The former is
-a fatal error, while the latter just causes the server to lose a scoreboard
-slot. So it might be advisable to use graceful restarts, with
-an occasional hard restart. These problems are very difficult to work
-around, but fortunately most architectures do not require a scoreboard file.
-See the ScoreBoardFile documentation for a method to determine if your
-architecture uses it.
-
-NEXT and MACHTEN (68k only) have small race
-conditions
-which can cause a restart/die signal to be lost, but should not cause the
-server to do anything otherwise problematic.
-
-
-Apache suEXEC Support
-
-
-
-What is suEXEC?
-The suEXEC feature, introduced in Apache 1.2 provides
-the ability to run CGI programs under user IDs
-different from the user ID of the calling web-server. Used properly,
-this feature can reduce considerably the insecurity of allowing users to
-run CGI programs. At the same time, improperly configured, this facility
-can crash your computer, burn your house down and steal all the money
-from your retirement fund. :-) If you aren't familiar
-with managing setuid root programs and the security issues they
-present, we highly recommend that you not consider using this feature.
-
-Enabling suEXEC Support
-Having said all that, enabling this feature is purposefully difficult with
-the intent that it will only be installed by users determined to use it and
-is not part of the normal install/compile process.Configuring the suEXEC wrapper
-From the top-level of the Apache source tree,
-type: cd support [ENTER]suexec.h file and change the following macros to
-match your local Apache installation.
-/*
- * HTTPD_USER -- Define as the username under which Apache normally
- * runs. This is the only user allowed to execute
- * this program.
- */
-#define HTTPD_USER "www"
-
-/*
- * LOG_EXEC -- Define this as a filename if you want all suEXEC
- * transactions and errors logged for auditing and
- * debugging purposes.
- */
-#define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log"
-
-/*
- * DOC_ROOT -- Define as the DocumentRoot set for Apache. This
- * will be the only hierarchy (aside from UserDirs)
- * that can be used for suEXEC behavior.
- */
-#define DOC_ROOT "/usr/local/etc/httpd/htdocs"
-
-/*
- * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
- *
- */
-#define SAFE_PATH "/usr/local/bin:/usr/bin:/bin"
-
-
-Compiling the suEXEC wrapper
-At the shell command prompt, type: cc suexec.c
--o suexec [ENTER].Compiling Apache for suEXEC support
-By default, Apache is compiled to look for the suEXEC wrapper in the following
-location.
-/* The path to the suEXEC wrapper */
-#ifndef SUEXEC_BIN
-#define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
-#endif
-
-Installing the suEXEC wrapper
-Copy the suexec executable created in the
-exercise above to the defined location for SUEXEC_BIN.chown root /usr/local/etc/httpd/sbin/suexec [ENTER]chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]
-
-Security Model of suEXEC
-The suEXEC wrapper supplied with Apache performs the
-following security checks before it will execute any program passed to
-it for execution.
-
-
-If any of these issues are too restrictive, or do not seem restrictive
-enough, you are welcome to install your own version of the wrapper.
-We've given you the rope, now go have fun with it. :-)
-
-
-
-Using suEXEC
-After properly installing the suexec wrapper
-executable, you must kill and restart the Apache server. A simple
-kill -1 `cat httpd.pid` will not be enough.
-Upon startup of the web-server, if Apache finds a properly configured
-suexec wrapper, it will print the following message to
-the console:Configuring Apache for use with suexec wrapper.
-
-Debugging suEXEC
-The suEXEC wrapper will write log information to the location defined in
-the suexec.h as indicated above. If you feel you have
-configured and installed the wrapper properly,
-have a look at this log and the error_log for the server to see where
-you may have gone astray.
-
-
-
-
diff --git a/docs/manual/suexec.html.en b/docs/manual/suexec.html.en
deleted file mode 100644
index 2b32aa950d6..00000000000
--- a/docs/manual/suexec.html.en
+++ /dev/null
@@ -1,190 +0,0 @@
-
-
-Apache suEXEC Support
-
-
-
-What is suEXEC?
-The suEXEC feature, introduced in Apache 1.2 provides
-the ability to run CGI programs under user IDs
-different from the user ID of the calling web-server. Used properly,
-this feature can reduce considerably the insecurity of allowing users to
-run CGI programs. At the same time, improperly configured, this facility
-can crash your computer, burn your house down and steal all the money
-from your retirement fund. :-) If you aren't familiar
-with managing setuid root programs and the security issues they
-present, we highly recommend that you not consider using this feature.
-
-Enabling suEXEC Support
-Having said all that, enabling this feature is purposefully difficult with
-the intent that it will only be installed by users determined to use it and
-is not part of the normal install/compile process.Configuring the suEXEC wrapper
-From the top-level of the Apache source tree,
-type: cd support [ENTER]suexec.h file and change the following macros to
-match your local Apache installation.
-/*
- * HTTPD_USER -- Define as the username under which Apache normally
- * runs. This is the only user allowed to execute
- * this program.
- */
-#define HTTPD_USER "www"
-
-/*
- * LOG_EXEC -- Define this as a filename if you want all suEXEC
- * transactions and errors logged for auditing and
- * debugging purposes.
- */
-#define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log"
-
-/*
- * DOC_ROOT -- Define as the DocumentRoot set for Apache. This
- * will be the only hierarchy (aside from UserDirs)
- * that can be used for suEXEC behavior.
- */
-#define DOC_ROOT "/usr/local/etc/httpd/htdocs"
-
-/*
- * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
- *
- */
-#define SAFE_PATH "/usr/local/bin:/usr/bin:/bin"
-
-
-Compiling the suEXEC wrapper
-At the shell command prompt, type: cc suexec.c
--o suexec [ENTER].Compiling Apache for suEXEC support
-By default, Apache is compiled to look for the suEXEC wrapper in the following
-location.
-/* The path to the suEXEC wrapper */
-#ifndef SUEXEC_BIN
-#define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
-#endif
-
-Installing the suEXEC wrapper
-Copy the suexec executable created in the
-exercise above to the defined location for SUEXEC_BIN.chown root /usr/local/etc/httpd/sbin/suexec [ENTER]chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]
-
-Security Model of suEXEC
-The suEXEC wrapper supplied with Apache performs the
-following security checks before it will execute any program passed to
-it for execution.
-
-
-If any of these issues are too restrictive, or do not seem restrictive
-enough, you are welcome to install your own version of the wrapper.
-We've given you the rope, now go have fun with it. :-)
-
-
-
-Using suEXEC
-After properly installing the suexec wrapper
-executable, you must kill and restart the Apache server. A simple
-kill -1 `cat httpd.pid` will not be enough.
-Upon startup of the web-server, if Apache finds a properly configured
-suexec wrapper, it will print the following message to
-the console:Configuring Apache for use with suexec wrapper.
-
-Debugging suEXEC
-The suEXEC wrapper will write log information to the location defined in
-the suexec.h as indicated above. If you feel you have
-configured and installed the wrapper properly,
-have a look at this log and the error_log for the server to see where
-you may have gone astray.
-
-
-
-