From 4b50c27ec5ec786ab4022e61f94c0e58e969c883 Mon Sep 17 00:00:00 2001 From: Jason McIntyre Date: Fri, 29 Jul 2005 23:55:41 +0000 Subject: from tamas tevesz: ==> de-multiviewification complete. (rename *.html.html -> *.html) --- usr.sbin/httpd/htdocs/manual/configuring.html | 265 ++ usr.sbin/httpd/htdocs/manual/configuring.html.html | 265 -- .../httpd/htdocs/manual/content-negotiation.html | 678 ++++ .../htdocs/manual/content-negotiation.html.html | 678 ---- usr.sbin/httpd/htdocs/manual/custom-error.html | 196 + .../httpd/htdocs/manual/custom-error.html.html | 196 - usr.sbin/httpd/htdocs/manual/dns-caveats.html | 231 ++ usr.sbin/httpd/htdocs/manual/dns-caveats.html.html | 231 -- usr.sbin/httpd/htdocs/manual/env.html | 361 ++ usr.sbin/httpd/htdocs/manual/env.html.html | 361 -- usr.sbin/httpd/htdocs/manual/handler.html | 179 + usr.sbin/httpd/htdocs/manual/handler.html.html | 179 - usr.sbin/httpd/htdocs/manual/howto/cgi.html | 567 +++ usr.sbin/httpd/htdocs/manual/howto/cgi.html.html | 567 --- usr.sbin/httpd/htdocs/manual/howto/ssi.html | 558 +++ usr.sbin/httpd/htdocs/manual/howto/ssi.html.html | 558 --- usr.sbin/httpd/htdocs/manual/index.html | 286 ++ usr.sbin/httpd/htdocs/manual/index.html.html | 286 -- usr.sbin/httpd/htdocs/manual/invoking.html | 148 + usr.sbin/httpd/htdocs/manual/invoking.html.html | 148 - usr.sbin/httpd/htdocs/manual/keepalive.html | 107 + usr.sbin/httpd/htdocs/manual/keepalive.html.html | 107 - usr.sbin/httpd/htdocs/manual/mod/core.html | 4140 ++++++++++++++++++++ usr.sbin/httpd/htdocs/manual/mod/core.html.html | 4140 -------------------- .../httpd/htdocs/manual/mod/directive-dict.html | 318 ++ .../htdocs/manual/mod/directive-dict.html.html | 318 -- usr.sbin/httpd/htdocs/manual/mod/directives.html | 591 +++ .../httpd/htdocs/manual/mod/directives.html.html | 591 --- usr.sbin/httpd/htdocs/manual/mod/index-bytype.html | 289 ++ .../httpd/htdocs/manual/mod/index-bytype.html.html | 289 -- usr.sbin/httpd/htdocs/manual/mod/index.html | 243 ++ usr.sbin/httpd/htdocs/manual/mod/index.html.html | 243 -- usr.sbin/httpd/htdocs/manual/mod/mod_access.html | 354 ++ .../httpd/htdocs/manual/mod/mod_access.html.html | 354 -- usr.sbin/httpd/htdocs/manual/mod/mod_actions.html | 167 + .../httpd/htdocs/manual/mod/mod_actions.html.html | 167 - usr.sbin/httpd/htdocs/manual/mod/mod_alias.html | 399 ++ .../httpd/htdocs/manual/mod/mod_alias.html.html | 399 -- usr.sbin/httpd/htdocs/manual/mod/mod_asis.html | 107 + .../httpd/htdocs/manual/mod/mod_asis.html.html | 107 - usr.sbin/httpd/htdocs/manual/mod/mod_auth.html | 326 ++ .../httpd/htdocs/manual/mod/mod_auth.html.html | 326 -- usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html | 232 ++ usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html.html | 232 -- usr.sbin/httpd/htdocs/manual/mod/mod_dir.html | 129 + usr.sbin/httpd/htdocs/manual/mod/mod_dir.html.html | 129 - usr.sbin/httpd/htdocs/manual/mod/mod_env.html | 146 + usr.sbin/httpd/htdocs/manual/mod/mod_env.html.html | 146 - usr.sbin/httpd/htdocs/manual/mod/mod_info.html | 125 + .../httpd/htdocs/manual/mod/mod_info.html.html | 125 - .../httpd/htdocs/manual/mod/mod_log_config.html | 421 ++ .../htdocs/manual/mod/mod_log_config.html.html | 421 -- usr.sbin/httpd/htdocs/manual/mod/mod_mime.html | 691 ++++ .../httpd/htdocs/manual/mod/mod_mime.html.html | 691 ---- .../httpd/htdocs/manual/mod/mod_negotiation.html | 234 ++ .../htdocs/manual/mod/mod_negotiation.html.html | 234 -- usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html | 2107 ++++++++++ .../httpd/htdocs/manual/mod/mod_rewrite.html.html | 2107 ---------- usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html | 341 ++ .../httpd/htdocs/manual/mod/mod_setenvif.html.html | 341 -- usr.sbin/httpd/htdocs/manual/mod/mod_so.html | 205 + usr.sbin/httpd/htdocs/manual/mod/mod_so.html.html | 205 - usr.sbin/httpd/htdocs/manual/mod/mod_speling.html | 137 + .../httpd/htdocs/manual/mod/mod_speling.html.html | 137 - .../httpd/htdocs/manual/mod/mod_unique_id.html | 220 ++ .../htdocs/manual/mod/mod_unique_id.html.html | 220 -- usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html | 154 + .../httpd/htdocs/manual/mod/mod_userdir.html.html | 154 - usr.sbin/httpd/htdocs/manual/mod/module-dict.html | 129 + .../httpd/htdocs/manual/mod/module-dict.html.html | 129 - usr.sbin/httpd/htdocs/manual/process-model.html | 81 + .../httpd/htdocs/manual/process-model.html.html | 81 - .../httpd/htdocs/manual/programs/apachectl.html | 110 + .../htdocs/manual/programs/apachectl.html.html | 110 - .../httpd/htdocs/manual/programs/htpasswd.html | 189 + .../htdocs/manual/programs/htpasswd.html.html | 189 - usr.sbin/httpd/htdocs/manual/programs/httpd.html | 145 + .../httpd/htdocs/manual/programs/httpd.html.html | 145 - usr.sbin/httpd/htdocs/manual/programs/index.html | 86 + .../httpd/htdocs/manual/programs/index.html.html | 86 - usr.sbin/httpd/htdocs/manual/programs/suexec.html | 56 + .../httpd/htdocs/manual/programs/suexec.html.html | 56 - usr.sbin/httpd/htdocs/manual/sections.html | 169 + usr.sbin/httpd/htdocs/manual/sections.html.html | 169 - usr.sbin/httpd/htdocs/manual/server-wide.html | 283 ++ usr.sbin/httpd/htdocs/manual/server-wide.html.html | 283 -- usr.sbin/httpd/htdocs/manual/stopping.html | 207 + usr.sbin/httpd/htdocs/manual/stopping.html.html | 207 - usr.sbin/httpd/htdocs/manual/suexec.html | 613 +++ usr.sbin/httpd/htdocs/manual/suexec.html.html | 613 --- usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html | 87 + .../httpd/htdocs/manual/vhosts/fd-limits.html.html | 87 - usr.sbin/httpd/htdocs/manual/vhosts/index.html | 98 + .../httpd/htdocs/manual/vhosts/index.html.html | 98 - .../httpd/htdocs/manual/vhosts/name-based.html | 254 ++ .../htdocs/manual/vhosts/name-based.html.html | 254 -- 96 files changed, 18159 insertions(+), 18159 deletions(-) create mode 100644 usr.sbin/httpd/htdocs/manual/configuring.html delete mode 100644 usr.sbin/httpd/htdocs/manual/configuring.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/content-negotiation.html delete mode 100644 usr.sbin/httpd/htdocs/manual/content-negotiation.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/custom-error.html delete mode 100644 usr.sbin/httpd/htdocs/manual/custom-error.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/dns-caveats.html delete mode 100644 usr.sbin/httpd/htdocs/manual/dns-caveats.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/env.html delete mode 100644 usr.sbin/httpd/htdocs/manual/env.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/handler.html delete mode 100644 usr.sbin/httpd/htdocs/manual/handler.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/howto/cgi.html delete mode 100644 usr.sbin/httpd/htdocs/manual/howto/cgi.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/howto/ssi.html delete mode 100644 usr.sbin/httpd/htdocs/manual/howto/ssi.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/index.html delete mode 100644 usr.sbin/httpd/htdocs/manual/index.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/invoking.html delete mode 100644 usr.sbin/httpd/htdocs/manual/invoking.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/keepalive.html delete mode 100644 usr.sbin/httpd/htdocs/manual/keepalive.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/core.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/core.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/directive-dict.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/directive-dict.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/directives.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/directives.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/index-bytype.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/index-bytype.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/index.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/index.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_access.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_access.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_actions.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_actions.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_alias.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_alias.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_asis.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_asis.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_auth.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_auth.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_dir.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_dir.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_env.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_env.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_info.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_info.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_mime.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_mime.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_so.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_so.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_speling.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_speling.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/mod/module-dict.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/module-dict.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/process-model.html delete mode 100644 usr.sbin/httpd/htdocs/manual/process-model.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/programs/apachectl.html delete mode 100644 usr.sbin/httpd/htdocs/manual/programs/apachectl.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/programs/htpasswd.html delete mode 100644 usr.sbin/httpd/htdocs/manual/programs/htpasswd.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/programs/httpd.html delete mode 100644 usr.sbin/httpd/htdocs/manual/programs/httpd.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/programs/index.html delete mode 100644 usr.sbin/httpd/htdocs/manual/programs/index.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/programs/suexec.html delete mode 100644 usr.sbin/httpd/htdocs/manual/programs/suexec.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/sections.html delete mode 100644 usr.sbin/httpd/htdocs/manual/sections.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/server-wide.html delete mode 100644 usr.sbin/httpd/htdocs/manual/server-wide.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/stopping.html delete mode 100644 usr.sbin/httpd/htdocs/manual/stopping.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/suexec.html delete mode 100644 usr.sbin/httpd/htdocs/manual/suexec.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html delete mode 100644 usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/vhosts/index.html delete mode 100644 usr.sbin/httpd/htdocs/manual/vhosts/index.html.html create mode 100644 usr.sbin/httpd/htdocs/manual/vhosts/name-based.html delete mode 100644 usr.sbin/httpd/htdocs/manual/vhosts/name-based.html.html (limited to 'usr.sbin/httpd/htdocs') diff --git a/usr.sbin/httpd/htdocs/manual/configuring.html b/usr.sbin/httpd/htdocs/manual/configuring.html new file mode 100644 index 00000000000..f0c65648fcc --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/configuring.html @@ -0,0 +1,265 @@ + + + + + + + + Configuration Files + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Configuration Files

+ + +
+ +

Main Configuration Files

+ + + + + + + +
Related Modules
+
+ mod_mime
+ 		Related Directives
+
+ AccessConfig
+ <IfDefine>
+ Include
+ ResourceConfig
+ TypesConfig
+
+ +

Apache is configured by placing directives in plain text + configuration files. The main configuration file is usually + called httpd.conf. The location of this file is + set at compile-time, but may be overridden with the + -f command line flag. Some sites also have + srm.conf and access.conf files for historical + reasons. In addition, other configuration files may be + added using the Include directive. Any + directive may be placed in any of these configuration files. + Changes to the main configuration files are only recognized by + Apache when it is started or restarted.

+ +

New with Apache 1.3.13 is a feature where if any + configuration file is actually a directory, Apache will enter + that directory and parse any files (and subdirectories) found + there as configuration files. One possible use for this would + be to add VirtualHosts by creating small configuration files + for each host, and placing them in such a configuration + directory. Thus, you can add or remove VirtualHosts without + editing any files at all, simply adding or deleting them. This + makes automating such processes much easier.

+ +

The server also reads a file containing mime document types; + the filename is set by the TypesConfig directive, + and is mime.types by default.

+
+ +

Syntax of the Configuration + Files

+ +

Apache configuration files contain one directive per line. + The back-slash "\" may be used as the last character on a line + to indicate that the directive continues onto the next line. + There must be no other characters or white space between the + back-slash and the end of the line.

+ +

Directives in the configuration files are case-insensitive, + but arguments to directives are often case sensitive. Lines + which begin with the hash character "#" are considered + comments, and are ignored. Comments may not be + included on a line after a configuration directive. Blank lines + and white space occurring before a directive are ignored, so + you may indent directives for clarity.

+ +

You can check your configuration files for syntax errors + without starting the server by using apachectl + configtest or the -t command line + option.

+
+ +

Modules

+ + + + + + + +
Related Modules
+
+ mod_so
+ 		Related Directives
+
+ AddModule
+ ClearModuleList
+ <IfModule>
+ LoadModule
+
+ +

Apache is a modular server. This implies that only the most + basic functionality is included in the core server. Extended + features are available through modules which can be loaded + into Apache. By default, a base set of modules is + included in the server at compile-time. If the server is + compiled to use dynamically loaded + modules, then modules can be compiled separately and added at + any time using the LoadModule directive. + Otherwise, Apache must be recompiled to add or remove modules. + Configuration directives may be included conditional on a + presence of a particular module by enclosing them in an <IfModule> block.

+ +

To see which modules are currently compiled into the server, + you can use the -l command line option.

+
+ +

Scope of Directives

+ + + + + +
Related Directives
+
+ <Directory>
+ <DirectoryMatch>
+ <Files>
+ <FilesMatch>
+ <Location>
+ <LocationMatch>
+ <VirtualHost>
+
+ +

Directives placed in the main configuration files apply to + the entire server. If you wish to change the configuration for + only a part of the server, you can scope your directives by + placing them in <Directory>, <DirectoryMatch>, + <Files>, <FilesMatch>, <Location>, and + <LocationMatch> + sections. These sections limit the application of the + directives which they enclose to particular filesystem + locations or URLs. They can also be nested, allowing for very + fine grained configuration.

+ +

Apache has the capability to serve many different websites + simultaneously. This is called Virtual + Hosting. Directives can also be scoped by placing them + inside <VirtualHost> + sections, so that they will only apply to requests for a + particular website.

+ +

Although most directives can be placed in any of these + sections, some directives do not make sense in some contexts. + For example, directives controlling process creation can only + be placed in the main server context. To find which directives + can be placed in which sections, check the Context of the + directive. For further information, we provide details on How Directory, Location and Files sections + work.

+
+ +

.htaccess Files

+ + + + + +
Related Directives
+
+ AccessFileName
+ AllowOverride
+
+ +

Apache allows for decentralized management of configuration + via special files placed inside the web tree. The special files + are usually called .htaccess, but any name can be + specified in the AccessFileName + directive. Directives placed in .htaccess files + apply to the directory where you place the file, and all + sub-directories. The .htaccess files follow the + same syntax as the main configuration files. Since + .htaccess files are read on every request, changes + made in these files take immediate effect.

+ +

To find which directives can be placed in + .htaccess files, check the Context of the + directive. The server administrator further controls what + directives may be placed in .htaccess files by + configuring the AllowOverride + directive in the main configuration files.

+ +

For more information on .htaccess files, see + Ken Coar's tutorial on + Using .htaccess Files with Apache.

+
+ +

Apache HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/configuring.html.html b/usr.sbin/httpd/htdocs/manual/configuring.html.html deleted file mode 100644 index f0c65648fcc..00000000000 --- a/usr.sbin/httpd/htdocs/manual/configuring.html.html +++ /dev/null @@ -1,265 +0,0 @@ - - - - - - - - Configuration Files - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Configuration Files

- - -
- -

Main Configuration Files

- - - - - - - -
Related Modules
-
- mod_mime
- 		Related Directives
-
- AccessConfig
- <IfDefine>
- Include
- ResourceConfig
- TypesConfig
-
- -

Apache is configured by placing directives in plain text - configuration files. The main configuration file is usually - called httpd.conf. The location of this file is - set at compile-time, but may be overridden with the - -f command line flag. Some sites also have - srm.conf and access.conf files for historical - reasons. In addition, other configuration files may be - added using the Include directive. Any - directive may be placed in any of these configuration files. - Changes to the main configuration files are only recognized by - Apache when it is started or restarted.

- -

New with Apache 1.3.13 is a feature where if any - configuration file is actually a directory, Apache will enter - that directory and parse any files (and subdirectories) found - there as configuration files. One possible use for this would - be to add VirtualHosts by creating small configuration files - for each host, and placing them in such a configuration - directory. Thus, you can add or remove VirtualHosts without - editing any files at all, simply adding or deleting them. This - makes automating such processes much easier.

- -

The server also reads a file containing mime document types; - the filename is set by the TypesConfig directive, - and is mime.types by default.

-
- -

Syntax of the Configuration - Files

- -

Apache configuration files contain one directive per line. - The back-slash "\" may be used as the last character on a line - to indicate that the directive continues onto the next line. - There must be no other characters or white space between the - back-slash and the end of the line.

- -

Directives in the configuration files are case-insensitive, - but arguments to directives are often case sensitive. Lines - which begin with the hash character "#" are considered - comments, and are ignored. Comments may not be - included on a line after a configuration directive. Blank lines - and white space occurring before a directive are ignored, so - you may indent directives for clarity.

- -

You can check your configuration files for syntax errors - without starting the server by using apachectl - configtest or the -t command line - option.

-
- -

Modules

- - - - - - - -
Related Modules
-
- mod_so
- 		Related Directives
-
- AddModule
- ClearModuleList
- <IfModule>
- LoadModule
-
- -

Apache is a modular server. This implies that only the most - basic functionality is included in the core server. Extended - features are available through modules which can be loaded - into Apache. By default, a base set of modules is - included in the server at compile-time. If the server is - compiled to use dynamically loaded - modules, then modules can be compiled separately and added at - any time using the LoadModule directive. - Otherwise, Apache must be recompiled to add or remove modules. - Configuration directives may be included conditional on a - presence of a particular module by enclosing them in an <IfModule> block.

- -

To see which modules are currently compiled into the server, - you can use the -l command line option.

-
- -

Scope of Directives

- - - - - -
Related Directives
-
- <Directory>
- <DirectoryMatch>
- <Files>
- <FilesMatch>
- <Location>
- <LocationMatch>
- <VirtualHost>
-
- -

Directives placed in the main configuration files apply to - the entire server. If you wish to change the configuration for - only a part of the server, you can scope your directives by - placing them in <Directory>, <DirectoryMatch>, - <Files>, <FilesMatch>, <Location>, and - <LocationMatch> - sections. These sections limit the application of the - directives which they enclose to particular filesystem - locations or URLs. They can also be nested, allowing for very - fine grained configuration.

- -

Apache has the capability to serve many different websites - simultaneously. This is called Virtual - Hosting. Directives can also be scoped by placing them - inside <VirtualHost> - sections, so that they will only apply to requests for a - particular website.

- -

Although most directives can be placed in any of these - sections, some directives do not make sense in some contexts. - For example, directives controlling process creation can only - be placed in the main server context. To find which directives - can be placed in which sections, check the Context of the - directive. For further information, we provide details on How Directory, Location and Files sections - work.

-
- -

.htaccess Files

- - - - - -
Related Directives
-
- AccessFileName
- AllowOverride
-
- -

Apache allows for decentralized management of configuration - via special files placed inside the web tree. The special files - are usually called .htaccess, but any name can be - specified in the AccessFileName - directive. Directives placed in .htaccess files - apply to the directory where you place the file, and all - sub-directories. The .htaccess files follow the - same syntax as the main configuration files. Since - .htaccess files are read on every request, changes - made in these files take immediate effect.

- -

To find which directives can be placed in - .htaccess files, check the Context of the - directive. The server administrator further controls what - directives may be placed in .htaccess files by - configuring the AllowOverride - directive in the main configuration files.

- -

For more information on .htaccess files, see - Ken Coar's tutorial on - Using .htaccess Files with Apache.

-
- -

Apache HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/content-negotiation.html b/usr.sbin/httpd/htdocs/manual/content-negotiation.html new file mode 100644 index 00000000000..ea541120ab0 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/content-negotiation.html @@ -0,0 +1,678 @@ + + + + + + + + Apache Content Negotiation + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Content Negotiation

+ +

Apache's support for content negotiation has been updated to + meet the HTTP/1.1 specification. It can choose the best + representation of a resource based on the browser-supplied + preferences for media type, languages, character set and + encoding. It is also implements a couple of features to give + more intelligent handling of requests from browsers which send + incomplete negotiation information.

+ +

Content negotiation is provided by the mod_negotiation module, + which is compiled in by default.

+
+ +

About Content Negotiation

+ +

A resource may be available in several different + representations. For example, it might be available in + different languages or different media types, or a combination. + One way of selecting the most appropriate choice is to give the + user an index page, and let them select. However it is often + possible for the server to choose automatically. This works + because browsers can send as part of each request information + about what representations they prefer. For example, a browser + could indicate that it would like to see information in French, + if possible, else English will do. Browsers indicate their + preferences by headers in the request. To request only French + representations, the browser would send

+
+  Accept-Language: fr
+
+ +

Note that this preference will only be applied when there is + a choice of representations and they vary by language.

+ +

As an example of a more complex request, this browser has + been configured to accept French and English, but prefer + French, and to accept various media types, preferring HTML over + plain text or other text types, and preferring GIF or JPEG over + other media types, but also allowing any other media type as a + last resort:

+
+  Accept-Language: fr; q=1.0, en; q=0.5
+  Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
+        image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
+
+ Apache 1.2 supports 'server driven' content negotiation, as + defined in the HTTP/1.1 specification. It fully supports the + Accept, Accept-Language, Accept-Charset and Accept-Encoding + request headers. Apache 1.3.4 also supports 'transparent' + content negotiation, which is an experimental negotiation + protocol defined in RFC 2295 and RFC 2296. It does not offer + support for 'feature negotiation' as defined in these RFCs. + +

A resource is a conceptual entity + identified by a URI (RFC 2396). An HTTP server like Apache + provides access to representations of the + resource(s) within its namespace, with each representation in + the form of a sequence of bytes with a defined media type, + character set, encoding, etc. Each resource may be associated + with zero, one, or more than one representation at any given + time. If multiple representations are available, the resource + is referred to as negotiable and each of its + representations is termed a variant. The ways + in which the variants for a negotiable resource vary are called + the dimensions of negotiation.

+ +

Negotiation in Apache

+ +

In order to negotiate a resource, the server needs to be + given information about each of the variants. This is done in + one of two ways:

+ + + +

Using a type-map file

+ +

A type map is a document which is associated with the + handler named type-map (or, for + backwards-compatibility with older Apache configurations, the + mime type application/x-type-map). Note that to + use this feature, you must have a handler set in the + configuration that defines a file suffix as + type-map; this is best done with a

+
+  AddHandler type-map .var
+
+ in the server configuration file. See the comments in the + sample config file for more details. + +

Type map files have an entry for each available variant; + these entries consist of contiguous HTTP-format header lines. + Entries for different variants are separated by blank lines. + Blank lines are illegal within an entry. It is conventional to + begin a map file with an entry for the combined entity as a + whole (although this is not required, and if present will be + ignored). An example map file is:

+
+  URI: foo
+
+  URI: foo.en.html
+  Content-type: text/html
+  Content-language: en
+
+  URI: foo.fr.de.html
+  Content-type: text/html;charset=iso-8859-2
+  Content-language: fr, de
+
+ If the variants have different source qualities, that may be + indicated by the "qs" parameter to the media type, as in this + picture (available as jpeg, gif, or ASCII-art): +
+  URI: foo
+
+  URI: foo.jpeg
+  Content-type: image/jpeg; qs=0.8
+
+  URI: foo.gif
+  Content-type: image/gif; qs=0.5
+
+  URI: foo.txt
+  Content-type: text/plain; qs=0.01
+
+ +

qs values can vary in the range 0.000 to 1.000. Note that + any variant with a qs value of 0.000 will never be chosen. + Variants with no 'qs' parameter value are given a qs factor of + 1.0. The qs parameter indicates the relative 'quality' of this + variant compared to the other available variants, independent + of the client's capabilities. For example, a jpeg file is + usually of higher source quality than an ascii file if it is + attempting to represent a photograph. However, if the resource + being represented is an original ascii art, then an ascii + representation would have a higher source quality than a jpeg + representation. A qs value is therefore specific to a given + variant depending on the nature of the resource it + represents.

+ +

The full list of headers recognized is:

+ +
+
URI:
+ +
uri of the file containing the variant (of the given + media type, encoded with the given content encoding). These + are interpreted as URLs relative to the map file; they must + be on the same server (!), and they must refer to files to + which the client would be granted access if they were to be + requested directly.
+ +
Content-Type:
+ +
media type --- charset, level and "qs" parameters may be + given. These are often referred to as MIME types; typical + media types are image/gif, + text/plain, or + text/html; level=3.
+ +
Content-Language:
+ +
The languages of the variant, specified as an Internet + standard language tag from RFC 1766 (e.g., + en for English, kr for Korean, + etc.).
+ +
Content-Encoding:
+ +
If the file is compressed, or otherwise encoded, rather + than containing the actual raw data, this says how that was + done. Apache only recognizes encodings that are defined by an + AddEncoding + directive. This normally includes the encodings + x-compress for compress'd files, and + x-gzip for gzip'd files. The x- + prefix is ignored for encoding comparisons.
+ +
Content-Length:
+ +
The size of the file. Specifying content lengths in the + type-map allows the server to compare file sizes without + checking the actual files.
+ +
Description:
+ +
A human-readable textual description of the variant. If + Apache cannot find any appropriate variant to return, it will + return an error response which lists all available variants + instead. Such a variant list will include the human-readable + variant descriptions.
+
+ +

Multiviews

+ +

MultiViews is a per-directory option, meaning + it can be set with an Options directive within a + <Directory>, <Location> + or <Files> section in + access.conf, or (if AllowOverride is + properly set) in .htaccess files. Note that + Options All does not set MultiViews; + you have to ask for it by name.

+ +

The effect of MultiViews is as follows: if the + server receives a request for /some/dir/foo, if + /some/dir has MultiViews enabled, and + /some/dir/foo does not exist, then the + server reads the directory looking for 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.

+ +

MultiViews may also apply to searches for the + file named by the DirectoryIndex directive, if the + server is trying to index a directory. If the configuration + files specify

+
+  DirectoryIndex index
+
+ then the server will arbitrate between index.html + and index.html3 if both are present. If neither + are present, and index.cgi is there, the server + will run it. + +

If one of the files found when reading the directive is a + CGI script, it's not obvious what should happen. The code gives + that case special treatment --- if the request was a POST, or a + GET with QUERY_ARGS or PATH_INFO, the script is given an + extremely high quality rating, and generally invoked; otherwise + it is given an extremely low quality rating, which generally + causes one of the other views (if any) to be retrieved.

+ +

The Negotiation Methods

+ After Apache has obtained a list of the variants for a given + resource, either from a type-map file or from the filenames in + the directory, it invokes one of two methods to decide on the + 'best' variant to return, if any. It is not necessary to know + any of the details of how negotiation actually takes place in + order to use Apache's content negotiation features. However the + rest of this document explains the methods used for those + interested. + +

There are two negotiation methods:

+ +
    +
  1. Server driven negotiation with the Apache + algorithm is used in the normal case. The Apache + algorithm is explained in more detail below. When this + algorithm is used, Apache can sometimes 'fiddle' the quality + factor of a particular dimension to achieve a better result. + The ways Apache can fiddle quality factors is explained in + more detail below.
    2. + +
  2. Transparent content negotiation is used + when the browser specifically requests this through the + mechanism defined in RFC 2295. This negotiation method gives + the browser full control over deciding on the 'best' variant, + the result is therefore dependent on the specific algorithms + used by the browser. As part of the transparent negotiation + process, the browser can ask Apache to run the 'remote + variant selection algorithm' defined in RFC 2296.
    3. +
+ +

Dimensions of Negotiation

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DimensionNotes
Media TypeBrowser indicates preferences with the Accept header + field. Each item can have an associated quality factor. + Variant description can also have a quality factor (the + "qs" parameter).
LanguageBrowser indicates preferences with the Accept-Language + header field. Each item can have a quality factor. Variants + can be associated with none, one or more than one + language.
EncodingBrowser indicates preference with the Accept-Encoding + header field. Each item can have a quality factor.
CharsetBrowser indicates preference with the Accept-Charset + header field. Each item can have a quality factor. Variants + can indicate a charset as a parameter of the media + type.
+ +

Apache Negotiation Algorithm

+ +

Apache can use the following algorithm to select the 'best' + variant (if any) to return to the browser. This algorithm is + not further configurable. It operates as follows:

+ +
    +
  1. First, for each dimension of the negotiation, check the + appropriate Accept* header field and assign a + quality to each variant. If the Accept* header for + any dimension implies that this variant is not acceptable, + eliminate it. If no variants remain, go to step 4.
    2. + +
  2. + Select the 'best' variant by a process of elimination. Each + of the following tests is applied in order. Any variants + not selected at each test are eliminated. After each test, + if only one variant remains, select it as the best match + and proceed to step 3. If more than one variant remains, + move on to the next test. + +
      +
    1. Multiply the quality factor from the Accept header + with the quality-of-source factor for this variant's + media type, and select the variants with the highest + value.
      2. + +
    2. Select the variants with the highest language quality + factor.
      3. + +
    3. Select the variants with the best language match, + using either the order of languages in the + Accept-Language header (if present), or else the order of + languages in the LanguagePriority directive + (if present).
      4. + +
    4. Select the variants with the highest 'level' media + parameter (used to give the version of text/html media + types).
      5. + +
    5. Select variants with the best charset media + parameters, as given on the Accept-Charset header line. + Charset ISO-8859-1 is acceptable unless explicitly + excluded. Variants with a text/* media type + but not explicitly associated with a particular charset + are assumed to be in ISO-8859-1.
      6. + +
    6. Select those variants which have associated charset + media parameters that are not ISO-8859-1. If + there are no such variants, select all variants + instead.
      7. + +
    7. Select the variants with the best encoding. If there + are variants with an encoding that is acceptable to the + user-agent, select only these variants. Otherwise if + there is a mix of encoded and non-encoded variants, + select only the unencoded variants. If either all + variants are encoded or all variants are not encoded, + select all variants.
      8. + +
    8. Select the variants with the smallest content + length.
      9. + +
    9. Select the first variant of those remaining. This + will be either the first listed in the type-map file, or + when variants are read from the directory, the one whose + file name comes first when sorted using ASCII code + order.
      10. +
    +
    3. + +
  3. The algorithm has now selected one 'best' variant, so + return it as the response. The HTTP response header Vary is + set to indicate the dimensions of negotiation (browsers and + caches can use this information when caching the resource). + End.
    4. + +

  4. To get here means no variant was selected (because none + are acceptable to the browser). Return a 406 status (meaning + "No acceptable representation") with a response body + consisting of an HTML document listing the available + variants. Also set the HTTP Vary header to indicate the + dimensions of variance.

    + +

    You should be aware that the error message returned by Apache is + necessarily rather terse and might confuse some users (even though it + lists the available alternatives). If you want to avoid users seeing this + error page, you should organize your documents such that a document in a + default language (or with a default encoding etc.) is always returned if a + document is not available in any of the languages, encodings etc. the + browser asked for.

    + +

    In particular, if you want a document in a default language to + be returned if a document is not available in any of the languages + a browser asked for, you should create a document with no language + attribute set. See Variants with no + Language below for details.

    5. +
+ +

Fiddling with Quality + Values

+ +

Apache sometimes changes the quality values from what would + be expected by a strict interpretation of the Apache + negotiation algorithm above. This is to get a better result + from the algorithm for browsers which do not send full or + accurate information. Some of the most popular browsers send + Accept header information which would otherwise result in the + selection of the wrong variant in many cases. If a browser + sends full and correct information these fiddles will not be + applied.

+ +

Media Types and Wildcards

+ +

The Accept: request header indicates preferences for media + types. It can also include 'wildcard' media types, such as + "image/*" or "*/*" where the * matches any string. So a request + including:

+
+  Accept: image/*, */*
+
+ would indicate that any type starting "image/" is acceptable, + as is any other type (so the first "image/*" is redundant). + Some browsers routinely send wildcards in addition to explicit + types they can handle. For example: +
+  Accept: text/html, text/plain, image/gif, image/jpeg, */*
+
+ The intention of this is to indicate that the explicitly listed + types are preferred, but if a different representation is + available, that is ok too. However under the basic algorithm, + as given above, the */* wildcard has exactly equal preference + to all the other types, so they are not being preferred. The + browser should really have sent a request with a lower quality + (preference) value for *.*, such as: +
+  Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
+
+ The explicit types have no quality factor, so they default to a + preference of 1.0 (the highest). The wildcard */* is given a + low preference of 0.01, so other types will only be returned if + no variant matches an explicitly listed type. + +

If the Accept: header contains no q factors at all, + Apache sets the q value of "*/*", if present, to 0.01 to + emulate the desired behaviour. It also sets the q value of + wildcards of the format "type/*" to 0.02 (so these are + preferred over matches against "*/*". If any media type on the + Accept: header contains a q factor, these special values are + not applied, so requests from browsers which send the + correct information to start with work as expected.

+ +

Variants with no Language

+ +

If some of the variants for a particular resource have a + language attribute, and some do not, those variants with no + language are given a very low language quality factor of + 0.001.

+ +

The reason for setting this language quality factor for variant + with no language to a very low value is to allow for a default + variant which can be supplied if none of the other variants match + the browser's language preferences. This allows you to avoid users + seeing a "406" error page if their browser is set to only accept + languages which you do not offer for the resource that was + requested.

+ +

For example, consider the situation with Multiviews enabled and + three variants:

+ + + +

The meaning of a variant with no language is that it is always + acceptable to the browser. If the request is for foo + and the Accept-Language header includes either en or fr (or both) + one of foo.en.html or foo.fr.html will be returned. If the browser + does not list either en or fr as acceptable, foo.html will be + returned instead. If the client requests foo.html + instead, then no negotiation will occur since the exact match + will be returned. To avoid this problem, it is sometimes helpful + to name the "no language" variant foo.html.html to assure + that Multiviews and language negotiation will come into play.

+ +

Extensions to Transparent Content Negotiation

+ Apache extends the transparent content negotiation protocol + (RFC 2295) as follows. A new {encoding ..} element + is used in variant lists to label variants which are available + with a specific content-encoding only. The implementation of + the RVSA/1.0 algorithm (RFC 2296) is extended to recognize + encoded variants in the list, and to use them as candidate + variants whenever their encodings are acceptable according to + the Accept-Encoding request header. The RVSA/1.0 implementation + does not round computed quality factors to 5 decimal places + before choosing the best variant. + +

Note on hyperlinks and naming conventions

+ +

If you are using language negotiation you can choose between + different naming conventions, because files can have more than + one extension, and the order of the extensions is normally + irrelevant (see mod_mime + documentation for details).

+ +

A typical file has a MIME-type extension (e.g., + html), maybe an encoding extension (e.g., + gz), and of course a language extension + (e.g., en) when we have different + language variants of this file.

+ +

Examples:

+ + + +

Here some more examples of filenames together with valid and + invalid hyperlinks:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FilenameValid hyperlinkInvalid hyperlink
foo.html.enfoo
+ foo.html		-
foo.en.htmlfoofoo.html
foo.html.en.gzfoo
+ foo.html		foo.gz
+ foo.html.gz
foo.en.html.gzfoofoo.html
+ foo.html.gz
+ foo.gz
foo.gz.html.enfoo
+ foo.gz
+ foo.gz.html		foo.html
foo.html.gz.enfoo
+ foo.html
+ foo.html.gz		foo.gz
+ +

Looking at the table above you will notice that it is always + possible to use the name without any extensions in a hyperlink + (e.g., foo). The advantage is that you + can hide the actual type of a document rsp. file and can change + it later, e.g., from html to + shtml or cgi without changing any + hyperlink references.

+ +

If you want to continue to use a MIME-type in your + hyperlinks (e.g. foo.html) the language + extension (including an encoding extension if there is one) + must be on the right hand side of the MIME-type extension + (e.g., foo.html.en).

+ +

Note on Caching

+ +

When a cache stores a representation, it associates it with + the request URL. The next time that URL is requested, the cache + can use the stored representation. But, if the resource is + negotiable at the server, this might result in only the first + requested variant being cached and subsequent cache hits might + return the wrong response. To prevent this, Apache normally + marks all responses that are returned after content negotiation + as non-cacheable by HTTP/1.0 clients. Apache also supports the + HTTP/1.1 protocol features to allow caching of negotiated + responses.

+ +

For requests which come from a HTTP/1.0 compliant client + (either a browser or a cache), the directive + CacheNegotiatedDocs can be used to allow caching of + responses which were subject to negotiation. This directive can + be given in the server config or virtual host, and takes no + arguments. It has no effect on requests from HTTP/1.1 clients. +

+ +

Apache HTTP Server

+ Index + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/content-negotiation.html.html b/usr.sbin/httpd/htdocs/manual/content-negotiation.html.html deleted file mode 100644 index ea541120ab0..00000000000 --- a/usr.sbin/httpd/htdocs/manual/content-negotiation.html.html +++ /dev/null @@ -1,678 +0,0 @@ - - - - - - - - Apache Content Negotiation - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Content Negotiation

- -

Apache's support for content negotiation has been updated to - meet the HTTP/1.1 specification. It can choose the best - representation of a resource based on the browser-supplied - preferences for media type, languages, character set and - encoding. It is also implements a couple of features to give - more intelligent handling of requests from browsers which send - incomplete negotiation information.

- -

Content negotiation is provided by the mod_negotiation module, - which is compiled in by default.

-
- -

About Content Negotiation

- -

A resource may be available in several different - representations. For example, it might be available in - different languages or different media types, or a combination. - One way of selecting the most appropriate choice is to give the - user an index page, and let them select. However it is often - possible for the server to choose automatically. This works - because browsers can send as part of each request information - about what representations they prefer. For example, a browser - could indicate that it would like to see information in French, - if possible, else English will do. Browsers indicate their - preferences by headers in the request. To request only French - representations, the browser would send

-
-  Accept-Language: fr
-
- -

Note that this preference will only be applied when there is - a choice of representations and they vary by language.

- -

As an example of a more complex request, this browser has - been configured to accept French and English, but prefer - French, and to accept various media types, preferring HTML over - plain text or other text types, and preferring GIF or JPEG over - other media types, but also allowing any other media type as a - last resort:

-
-  Accept-Language: fr; q=1.0, en; q=0.5
-  Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
-        image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
-
- Apache 1.2 supports 'server driven' content negotiation, as - defined in the HTTP/1.1 specification. It fully supports the - Accept, Accept-Language, Accept-Charset and Accept-Encoding - request headers. Apache 1.3.4 also supports 'transparent' - content negotiation, which is an experimental negotiation - protocol defined in RFC 2295 and RFC 2296. It does not offer - support for 'feature negotiation' as defined in these RFCs. - -

A resource is a conceptual entity - identified by a URI (RFC 2396). An HTTP server like Apache - provides access to representations of the - resource(s) within its namespace, with each representation in - the form of a sequence of bytes with a defined media type, - character set, encoding, etc. Each resource may be associated - with zero, one, or more than one representation at any given - time. If multiple representations are available, the resource - is referred to as negotiable and each of its - representations is termed a variant. The ways - in which the variants for a negotiable resource vary are called - the dimensions of negotiation.

- -

Negotiation in Apache

- -

In order to negotiate a resource, the server needs to be - given information about each of the variants. This is done in - one of two ways:

- - - -

Using a type-map file

- -

A type map is a document which is associated with the - handler named type-map (or, for - backwards-compatibility with older Apache configurations, the - mime type application/x-type-map). Note that to - use this feature, you must have a handler set in the - configuration that defines a file suffix as - type-map; this is best done with a

-
-  AddHandler type-map .var
-
- in the server configuration file. See the comments in the - sample config file for more details. - -

Type map files have an entry for each available variant; - these entries consist of contiguous HTTP-format header lines. - Entries for different variants are separated by blank lines. - Blank lines are illegal within an entry. It is conventional to - begin a map file with an entry for the combined entity as a - whole (although this is not required, and if present will be - ignored). An example map file is:

-
-  URI: foo
-
-  URI: foo.en.html
-  Content-type: text/html
-  Content-language: en
-
-  URI: foo.fr.de.html
-  Content-type: text/html;charset=iso-8859-2
-  Content-language: fr, de
-
- If the variants have different source qualities, that may be - indicated by the "qs" parameter to the media type, as in this - picture (available as jpeg, gif, or ASCII-art): -
-  URI: foo
-
-  URI: foo.jpeg
-  Content-type: image/jpeg; qs=0.8
-
-  URI: foo.gif
-  Content-type: image/gif; qs=0.5
-
-  URI: foo.txt
-  Content-type: text/plain; qs=0.01
-
- -

qs values can vary in the range 0.000 to 1.000. Note that - any variant with a qs value of 0.000 will never be chosen. - Variants with no 'qs' parameter value are given a qs factor of - 1.0. The qs parameter indicates the relative 'quality' of this - variant compared to the other available variants, independent - of the client's capabilities. For example, a jpeg file is - usually of higher source quality than an ascii file if it is - attempting to represent a photograph. However, if the resource - being represented is an original ascii art, then an ascii - representation would have a higher source quality than a jpeg - representation. A qs value is therefore specific to a given - variant depending on the nature of the resource it - represents.

- -

The full list of headers recognized is:

- -
-
URI:
- -
uri of the file containing the variant (of the given - media type, encoded with the given content encoding). These - are interpreted as URLs relative to the map file; they must - be on the same server (!), and they must refer to files to - which the client would be granted access if they were to be - requested directly.
- -
Content-Type:
- -
media type --- charset, level and "qs" parameters may be - given. These are often referred to as MIME types; typical - media types are image/gif, - text/plain, or - text/html; level=3.
- -
Content-Language:
- -
The languages of the variant, specified as an Internet - standard language tag from RFC 1766 (e.g., - en for English, kr for Korean, - etc.).
- -
Content-Encoding:
- -
If the file is compressed, or otherwise encoded, rather - than containing the actual raw data, this says how that was - done. Apache only recognizes encodings that are defined by an - AddEncoding - directive. This normally includes the encodings - x-compress for compress'd files, and - x-gzip for gzip'd files. The x- - prefix is ignored for encoding comparisons.
- -
Content-Length:
- -
The size of the file. Specifying content lengths in the - type-map allows the server to compare file sizes without - checking the actual files.
- -
Description:
- -
A human-readable textual description of the variant. If - Apache cannot find any appropriate variant to return, it will - return an error response which lists all available variants - instead. Such a variant list will include the human-readable - variant descriptions.
-
- -

Multiviews

- -

MultiViews is a per-directory option, meaning - it can be set with an Options directive within a - <Directory>, <Location> - or <Files> section in - access.conf, or (if AllowOverride is - properly set) in .htaccess files. Note that - Options All does not set MultiViews; - you have to ask for it by name.

- -

The effect of MultiViews is as follows: if the - server receives a request for /some/dir/foo, if - /some/dir has MultiViews enabled, and - /some/dir/foo does not exist, then the - server reads the directory looking for 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.

- -

MultiViews may also apply to searches for the - file named by the DirectoryIndex directive, if the - server is trying to index a directory. If the configuration - files specify

-
-  DirectoryIndex index
-
- then the server will arbitrate between index.html - and index.html3 if both are present. If neither - are present, and index.cgi is there, the server - will run it. - -

If one of the files found when reading the directive is a - CGI script, it's not obvious what should happen. The code gives - that case special treatment --- if the request was a POST, or a - GET with QUERY_ARGS or PATH_INFO, the script is given an - extremely high quality rating, and generally invoked; otherwise - it is given an extremely low quality rating, which generally - causes one of the other views (if any) to be retrieved.

- -

The Negotiation Methods

- After Apache has obtained a list of the variants for a given - resource, either from a type-map file or from the filenames in - the directory, it invokes one of two methods to decide on the - 'best' variant to return, if any. It is not necessary to know - any of the details of how negotiation actually takes place in - order to use Apache's content negotiation features. However the - rest of this document explains the methods used for those - interested. - -

There are two negotiation methods:

- -
    -
  1. Server driven negotiation with the Apache - algorithm is used in the normal case. The Apache - algorithm is explained in more detail below. When this - algorithm is used, Apache can sometimes 'fiddle' the quality - factor of a particular dimension to achieve a better result. - The ways Apache can fiddle quality factors is explained in - more detail below.
    2. - -
  2. Transparent content negotiation is used - when the browser specifically requests this through the - mechanism defined in RFC 2295. This negotiation method gives - the browser full control over deciding on the 'best' variant, - the result is therefore dependent on the specific algorithms - used by the browser. As part of the transparent negotiation - process, the browser can ask Apache to run the 'remote - variant selection algorithm' defined in RFC 2296.
    3. -
- -

Dimensions of Negotiation

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
DimensionNotes
Media TypeBrowser indicates preferences with the Accept header - field. Each item can have an associated quality factor. - Variant description can also have a quality factor (the - "qs" parameter).
LanguageBrowser indicates preferences with the Accept-Language - header field. Each item can have a quality factor. Variants - can be associated with none, one or more than one - language.
EncodingBrowser indicates preference with the Accept-Encoding - header field. Each item can have a quality factor.
CharsetBrowser indicates preference with the Accept-Charset - header field. Each item can have a quality factor. Variants - can indicate a charset as a parameter of the media - type.
- -

Apache Negotiation Algorithm

- -

Apache can use the following algorithm to select the 'best' - variant (if any) to return to the browser. This algorithm is - not further configurable. It operates as follows:

- -
    -
  1. First, for each dimension of the negotiation, check the - appropriate Accept* header field and assign a - quality to each variant. If the Accept* header for - any dimension implies that this variant is not acceptable, - eliminate it. If no variants remain, go to step 4.
    2. - -
  2. - Select the 'best' variant by a process of elimination. Each - of the following tests is applied in order. Any variants - not selected at each test are eliminated. After each test, - if only one variant remains, select it as the best match - and proceed to step 3. If more than one variant remains, - move on to the next test. - -
      -
    1. Multiply the quality factor from the Accept header - with the quality-of-source factor for this variant's - media type, and select the variants with the highest - value.
      2. - -
    2. Select the variants with the highest language quality - factor.
      3. - -
    3. Select the variants with the best language match, - using either the order of languages in the - Accept-Language header (if present), or else the order of - languages in the LanguagePriority directive - (if present).
      4. - -
    4. Select the variants with the highest 'level' media - parameter (used to give the version of text/html media - types).
      5. - -
    5. Select variants with the best charset media - parameters, as given on the Accept-Charset header line. - Charset ISO-8859-1 is acceptable unless explicitly - excluded. Variants with a text/* media type - but not explicitly associated with a particular charset - are assumed to be in ISO-8859-1.
      6. - -
    6. Select those variants which have associated charset - media parameters that are not ISO-8859-1. If - there are no such variants, select all variants - instead.
      7. - -
    7. Select the variants with the best encoding. If there - are variants with an encoding that is acceptable to the - user-agent, select only these variants. Otherwise if - there is a mix of encoded and non-encoded variants, - select only the unencoded variants. If either all - variants are encoded or all variants are not encoded, - select all variants.
      8. - -
    8. Select the variants with the smallest content - length.
      9. - -
    9. Select the first variant of those remaining. This - will be either the first listed in the type-map file, or - when variants are read from the directory, the one whose - file name comes first when sorted using ASCII code - order.
      10. -
    -
    3. - -
  3. The algorithm has now selected one 'best' variant, so - return it as the response. The HTTP response header Vary is - set to indicate the dimensions of negotiation (browsers and - caches can use this information when caching the resource). - End.
    4. - -

  4. To get here means no variant was selected (because none - are acceptable to the browser). Return a 406 status (meaning - "No acceptable representation") with a response body - consisting of an HTML document listing the available - variants. Also set the HTTP Vary header to indicate the - dimensions of variance.

    - -

    You should be aware that the error message returned by Apache is - necessarily rather terse and might confuse some users (even though it - lists the available alternatives). If you want to avoid users seeing this - error page, you should organize your documents such that a document in a - default language (or with a default encoding etc.) is always returned if a - document is not available in any of the languages, encodings etc. the - browser asked for.

    - -

    In particular, if you want a document in a default language to - be returned if a document is not available in any of the languages - a browser asked for, you should create a document with no language - attribute set. See Variants with no - Language below for details.

    5. -
- -

Fiddling with Quality - Values

- -

Apache sometimes changes the quality values from what would - be expected by a strict interpretation of the Apache - negotiation algorithm above. This is to get a better result - from the algorithm for browsers which do not send full or - accurate information. Some of the most popular browsers send - Accept header information which would otherwise result in the - selection of the wrong variant in many cases. If a browser - sends full and correct information these fiddles will not be - applied.

- -

Media Types and Wildcards

- -

The Accept: request header indicates preferences for media - types. It can also include 'wildcard' media types, such as - "image/*" or "*/*" where the * matches any string. So a request - including:

-
-  Accept: image/*, */*
-
- would indicate that any type starting "image/" is acceptable, - as is any other type (so the first "image/*" is redundant). - Some browsers routinely send wildcards in addition to explicit - types they can handle. For example: -
-  Accept: text/html, text/plain, image/gif, image/jpeg, */*
-
- The intention of this is to indicate that the explicitly listed - types are preferred, but if a different representation is - available, that is ok too. However under the basic algorithm, - as given above, the */* wildcard has exactly equal preference - to all the other types, so they are not being preferred. The - browser should really have sent a request with a lower quality - (preference) value for *.*, such as: -
-  Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
-
- The explicit types have no quality factor, so they default to a - preference of 1.0 (the highest). The wildcard */* is given a - low preference of 0.01, so other types will only be returned if - no variant matches an explicitly listed type. - -

If the Accept: header contains no q factors at all, - Apache sets the q value of "*/*", if present, to 0.01 to - emulate the desired behaviour. It also sets the q value of - wildcards of the format "type/*" to 0.02 (so these are - preferred over matches against "*/*". If any media type on the - Accept: header contains a q factor, these special values are - not applied, so requests from browsers which send the - correct information to start with work as expected.

- -

Variants with no Language

- -

If some of the variants for a particular resource have a - language attribute, and some do not, those variants with no - language are given a very low language quality factor of - 0.001.

- -

The reason for setting this language quality factor for variant - with no language to a very low value is to allow for a default - variant which can be supplied if none of the other variants match - the browser's language preferences. This allows you to avoid users - seeing a "406" error page if their browser is set to only accept - languages which you do not offer for the resource that was - requested.

- -

For example, consider the situation with Multiviews enabled and - three variants:

- - - -

The meaning of a variant with no language is that it is always - acceptable to the browser. If the request is for foo - and the Accept-Language header includes either en or fr (or both) - one of foo.en.html or foo.fr.html will be returned. If the browser - does not list either en or fr as acceptable, foo.html will be - returned instead. If the client requests foo.html - instead, then no negotiation will occur since the exact match - will be returned. To avoid this problem, it is sometimes helpful - to name the "no language" variant foo.html.html to assure - that Multiviews and language negotiation will come into play.

- -

Extensions to Transparent Content Negotiation

- Apache extends the transparent content negotiation protocol - (RFC 2295) as follows. A new {encoding ..} element - is used in variant lists to label variants which are available - with a specific content-encoding only. The implementation of - the RVSA/1.0 algorithm (RFC 2296) is extended to recognize - encoded variants in the list, and to use them as candidate - variants whenever their encodings are acceptable according to - the Accept-Encoding request header. The RVSA/1.0 implementation - does not round computed quality factors to 5 decimal places - before choosing the best variant. - -

Note on hyperlinks and naming conventions

- -

If you are using language negotiation you can choose between - different naming conventions, because files can have more than - one extension, and the order of the extensions is normally - irrelevant (see mod_mime - documentation for details).

- -

A typical file has a MIME-type extension (e.g., - html), maybe an encoding extension (e.g., - gz), and of course a language extension - (e.g., en) when we have different - language variants of this file.

- -

Examples:

- - - -

Here some more examples of filenames together with valid and - invalid hyperlinks:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FilenameValid hyperlinkInvalid hyperlink
foo.html.enfoo
- foo.html		-
foo.en.htmlfoofoo.html
foo.html.en.gzfoo
- foo.html		foo.gz
- foo.html.gz
foo.en.html.gzfoofoo.html
- foo.html.gz
- foo.gz
foo.gz.html.enfoo
- foo.gz
- foo.gz.html		foo.html
foo.html.gz.enfoo
- foo.html
- foo.html.gz		foo.gz
- -

Looking at the table above you will notice that it is always - possible to use the name without any extensions in a hyperlink - (e.g., foo). The advantage is that you - can hide the actual type of a document rsp. file and can change - it later, e.g., from html to - shtml or cgi without changing any - hyperlink references.

- -

If you want to continue to use a MIME-type in your - hyperlinks (e.g. foo.html) the language - extension (including an encoding extension if there is one) - must be on the right hand side of the MIME-type extension - (e.g., foo.html.en).

- -

Note on Caching

- -

When a cache stores a representation, it associates it with - the request URL. The next time that URL is requested, the cache - can use the stored representation. But, if the resource is - negotiable at the server, this might result in only the first - requested variant being cached and subsequent cache hits might - return the wrong response. To prevent this, Apache normally - marks all responses that are returned after content negotiation - as non-cacheable by HTTP/1.0 clients. Apache also supports the - HTTP/1.1 protocol features to allow caching of negotiated - responses.

- -

For requests which come from a HTTP/1.0 compliant client - (either a browser or a cache), the directive - CacheNegotiatedDocs can be used to allow caching of - responses which were subject to negotiation. This directive can - be given in the server config or virtual host, and takes no - arguments. It has no effect on requests from HTTP/1.1 clients. -

- -

Apache HTTP Server

- Index - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/custom-error.html b/usr.sbin/httpd/htdocs/manual/custom-error.html new file mode 100644 index 00000000000..bccb11a9a20 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/custom-error.html @@ -0,0 +1,196 @@ + + + + + + + + Custom error responses + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Custom error responses

+ +
+
Purpose
+ +
+ Additional functionality. Allows webmasters to configure + the response of Apache to some error or problem. + +

Customizable responses can be defined to be activated in + the event of a server detected error or problem.

+ +

e.g. if a script crashes and produces a "500 Server + Error" response, then this response can be replaced with + either some friendlier text or by a redirection to another + URL (local or external).

+
+ +
Old behavior
+ +
NCSA httpd 1.3 would return some boring old error/problem + message which would often be meaningless to the user, and + would provide no means of logging the symptoms which caused + it.
+
+ +
New behavior
+ +
+ The server can be asked to; + +
    +
  1. Display some other text, instead of the NCSA hard + coded messages, or
    2. + +
  2. redirect to a local URL, or
    3. + +
  3. redirect to an external URL.
    4. +
+ +

Redirecting to another URL can be useful, but only if + some information can be passed which can then be used to + explain and/or log the error/problem more clearly.

+ +

To achieve this, Apache will define new CGI-like + environment variables, e.g.

+ +
+ REDIRECT_HTTP_ACCEPT=*/*, image/gif, + image/x-xbitmap, image/jpeg
+ REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX + A.09.05 9000/712)
+ REDIRECT_PATH=.:/bin:/usr/local/bin:/etc
+ REDIRECT_QUERY_STRING=
+ REDIRECT_REMOTE_ADDR=121.345.78.123
+ REDIRECT_REMOTE_HOST=ooh.ahhh.com
+ REDIRECT_SERVER_NAME=crash.bang.edu
+ REDIRECT_SERVER_PORT=80
+ REDIRECT_SERVER_SOFTWARE=Apache/0.8.15
+ REDIRECT_URL=/cgi-bin/buggy.pl
+ +
+ +

note the REDIRECT_ prefix.

+ +

At least REDIRECT_URL and + REDIRECT_QUERY_STRING will be passed to the + new URL (assuming it's a cgi-script or a cgi-include). The + other variables will exist only if they existed prior to + the error/problem. None of these will be + set if your ErrorDocument is an external redirect + (i.e., anything starting with a scheme name like + http:, even if it refers to the same host as + the server).

+
+ +
Configuration
+ +
+ Use of "ErrorDocument" is enabled for .htaccess files when + the "FileInfo" + override is allowed. + +

Here are some examples...

+ +
+ ErrorDocument 500 /cgi-bin/crash-recover
+ ErrorDocument 500 "Sorry, our script crashed. Oh + dear
+ ErrorDocument 500 http://xxx/
+ ErrorDocument 404 /Lame_excuses/not_found.html
+ ErrorDocument 401 + /Subscription/how_to_subscribe.html +
+ +

The syntax is,

+ +

ErrorDocument + <3-digit-code> action

+ +

where the action can be,

+ +
    +
  1. Text to be displayed. Prefix the text with a quote + ("). Whatever follows the quote is displayed. Note: + the (") prefix isn't displayed.
    2. + +
  2. An external URL to redirect to.
    3. + +
  3. A local URL to redirect to.
    4. +
+
+
+
+ +

Custom error responses and redirects

+ +
+
Purpose
+ +
Apache's behavior to redirected URLs has been modified so + that additional environment variables are available to a + script/server-include.
+ +
Old behavior
+ +
Standard CGI vars were made available to a script which + has been redirected to. No indication of where the + redirection came from was provided.
+ +
New behavior
+ +
A new batch of environment variables will be initialized + for use by a script which has been redirected to. Each new + variable will have the prefix REDIRECT_. + REDIRECT_ environment variables are created from + the CGI environment variables which existed prior to the + redirect, they are renamed with a REDIRECT_ + prefix, i.e., HTTP_USER_AGENT becomes + REDIRECT_HTTP_USER_AGENT. In addition to these + new variables, Apache will define REDIRECT_URL + and REDIRECT_STATUS to help the script trace its + origin. Both the original URL and the URL being redirected to + can be logged in the access log.
+
+ +

If the ErrorDocument specifies a local redirect to a CGI + script, the script should include a "Status:" + header field in its output in order to ensure the propagation + all the way back to the client of the error condition that + caused it to be invoked. For instance, a Perl ErrorDocument + script might include the following:

+
+      :
+    print  "Content-type: text/html\n";
+    printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
+      :
+
+ +

If the script is dedicated to handling a particular error + condition, such as 404 Not Found, it can + use the specific code and error text instead.

+
+ +

Apache HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/custom-error.html.html b/usr.sbin/httpd/htdocs/manual/custom-error.html.html deleted file mode 100644 index bccb11a9a20..00000000000 --- a/usr.sbin/httpd/htdocs/manual/custom-error.html.html +++ /dev/null @@ -1,196 +0,0 @@ - - - - - - - - Custom error responses - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Custom error responses

- -
-
Purpose
- -
- Additional functionality. Allows webmasters to configure - the response of Apache to some error or problem. - -

Customizable responses can be defined to be activated in - the event of a server detected error or problem.

- -

e.g. if a script crashes and produces a "500 Server - Error" response, then this response can be replaced with - either some friendlier text or by a redirection to another - URL (local or external).

-
- -
Old behavior
- -
NCSA httpd 1.3 would return some boring old error/problem - message which would often be meaningless to the user, and - would provide no means of logging the symptoms which caused - it.
-
- -
New behavior
- -
- The server can be asked to; - -
    -
  1. Display some other text, instead of the NCSA hard - coded messages, or
    2. - -
  2. redirect to a local URL, or
    3. - -
  3. redirect to an external URL.
    4. -
- -

Redirecting to another URL can be useful, but only if - some information can be passed which can then be used to - explain and/or log the error/problem more clearly.

- -

To achieve this, Apache will define new CGI-like - environment variables, e.g.

- -
- REDIRECT_HTTP_ACCEPT=*/*, image/gif, - image/x-xbitmap, image/jpeg
- REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX - A.09.05 9000/712)
- REDIRECT_PATH=.:/bin:/usr/local/bin:/etc
- REDIRECT_QUERY_STRING=
- REDIRECT_REMOTE_ADDR=121.345.78.123
- REDIRECT_REMOTE_HOST=ooh.ahhh.com
- REDIRECT_SERVER_NAME=crash.bang.edu
- REDIRECT_SERVER_PORT=80
- REDIRECT_SERVER_SOFTWARE=Apache/0.8.15
- REDIRECT_URL=/cgi-bin/buggy.pl
- -
- -

note the REDIRECT_ prefix.

- -

At least REDIRECT_URL and - REDIRECT_QUERY_STRING will be passed to the - new URL (assuming it's a cgi-script or a cgi-include). The - other variables will exist only if they existed prior to - the error/problem. None of these will be - set if your ErrorDocument is an external redirect - (i.e., anything starting with a scheme name like - http:, even if it refers to the same host as - the server).

-
- -
Configuration
- -
- Use of "ErrorDocument" is enabled for .htaccess files when - the "FileInfo" - override is allowed. - -

Here are some examples...

- -
- ErrorDocument 500 /cgi-bin/crash-recover
- ErrorDocument 500 "Sorry, our script crashed. Oh - dear
- ErrorDocument 500 http://xxx/
- ErrorDocument 404 /Lame_excuses/not_found.html
- ErrorDocument 401 - /Subscription/how_to_subscribe.html -
- -

The syntax is,

- -

ErrorDocument - <3-digit-code> action

- -

where the action can be,

- -
    -
  1. Text to be displayed. Prefix the text with a quote - ("). Whatever follows the quote is displayed. Note: - the (") prefix isn't displayed.
    2. - -
  2. An external URL to redirect to.
    3. - -
  3. A local URL to redirect to.
    4. -
-
-
-
- -

Custom error responses and redirects

- -
-
Purpose
- -
Apache's behavior to redirected URLs has been modified so - that additional environment variables are available to a - script/server-include.
- -
Old behavior
- -
Standard CGI vars were made available to a script which - has been redirected to. No indication of where the - redirection came from was provided.
- -
New behavior
- -
A new batch of environment variables will be initialized - for use by a script which has been redirected to. Each new - variable will have the prefix REDIRECT_. - REDIRECT_ environment variables are created from - the CGI environment variables which existed prior to the - redirect, they are renamed with a REDIRECT_ - prefix, i.e., HTTP_USER_AGENT becomes - REDIRECT_HTTP_USER_AGENT. In addition to these - new variables, Apache will define REDIRECT_URL - and REDIRECT_STATUS to help the script trace its - origin. Both the original URL and the URL being redirected to - can be logged in the access log.
-
- -

If the ErrorDocument specifies a local redirect to a CGI - script, the script should include a "Status:" - header field in its output in order to ensure the propagation - all the way back to the client of the error condition that - caused it to be invoked. For instance, a Perl ErrorDocument - script might include the following:

-
-      :
-    print  "Content-type: text/html\n";
-    printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
-      :
-
- -

If the script is dedicated to handling a particular error - condition, such as 404 Not Found, it can - use the specific code and error text instead.

-
- -

Apache HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/dns-caveats.html b/usr.sbin/httpd/htdocs/manual/dns-caveats.html new file mode 100644 index 00000000000..0d47f605fe0 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/dns-caveats.html @@ -0,0 +1,231 @@ + + + + + + + + Issues Regarding DNS and Apache + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Issues Regarding DNS and Apache

+ +

This page could be summarized with the statement: don't + require Apache to use DNS for any parsing of the configuration + files. If Apache has to use DNS to parse the configuration + files then your server may be subject to reliability problems + (it might not boot), or denial and theft of service attacks + (including users able to steal hits from other users).

+ +

A Simple Example

+ Consider this configuration snippet: + +
+
+    <VirtualHost www.abc.dom>
+    ServerAdmin webgirl@abc.dom
+    DocumentRoot /www/abc
+    </VirtualHost>
+
+
+ +

In order for Apache to function properly it absolutely needs + to have two pieces of information about each virtual host: the + ServerName + and at least one IP address that the server responds to. This + example does not include the IP address, so Apache must use DNS + to find the address of www.abc.dom. If for some + reason DNS is not available at the time your server is parsing + its config file, then this virtual host will not be + configured. It won't be able to respond to any hits to + this virtual host (prior to Apache version 1.2 the server would + not even boot).

+ +

Suppose that www.abc.dom has address 10.0.0.1. + Then consider this configuration snippet:

+ +
+
+    <VirtualHost 10.0.0.1>
+    ServerAdmin webgirl@abc.dom
+    DocumentRoot /www/abc
+    </VirtualHost>
+
+
+ +

Now Apache needs to use reverse DNS to find the + ServerName for this virtualhost. If that reverse + lookup fails then it will partially disable the virtualhost + (prior to Apache version 1.2 the server would not even boot). + If the virtual host is name-based then it will effectively be + totally disabled, but if it is IP-based then it will mostly + work. However if Apache should ever have to generate a full URL + for the server which includes the server name then it will fail + to generate a valid URL.

+ +

Here is a snippet that avoids both of these problems.

+ +
+
+    <VirtualHost 10.0.0.1>
+    ServerName www.abc.dom
+    ServerAdmin webgirl@abc.dom
+    DocumentRoot /www/abc
+    </VirtualHost>
+
+
+ +

Denial of Service

+ +

There are (at least) two forms that denial of service can + come in. If you are running a version of Apache prior to + version 1.2 then your server will not even boot if one of the + two DNS lookups mentioned above fails for any of your virtual + hosts. In some cases this DNS lookup may not even be under your + control. For example, if abc.dom is one of your + customers and they control their own DNS then they can force + your (pre-1.2) server to fail while booting simply by deleting + the www.abc.dom record.

+ +

Another form is far more insidious. Consider this + configuration snippet:

+ +
+
+    <VirtualHost www.abc.dom>
+    ServerAdmin webgirl@abc.dom
+    DocumentRoot /www/abc
+    </VirtualHost>
+
+
+ +
+
+    <VirtualHost www.def.dom>
+    ServerAdmin webguy@def.dom
+    DocumentRoot /www/def
+    </VirtualHost>
+
+
+ +

Suppose that you've assigned 10.0.0.1 to + www.abc.dom and 10.0.0.2 to + www.def.dom. Furthermore, suppose that + def.com has control of their own DNS. With this + config you have put def.com into a position where + they can steal all traffic destined to abc.com. To + do so, all they have to do is set www.def.dom to + 10.0.0.1. Since they control their own DNS you can't stop them + from pointing the www.def.com record wherever they + wish.

+ +

Requests coming in to 10.0.0.1 (including all those where + users typed in URLs of the form + http://www.abc.dom/whatever) will all be served by + the def.com virtual host. To better understand why + this happens requires a more in-depth discussion of how Apache + matches up incoming requests with the virtual host that will + serve it. A rough document describing this is available.

+ +

The "main server" Address

+ +

The addition of name-based + virtual host support in Apache 1.1 requires Apache to know + the IP address(es) of the host that httpd is running on. To get + this address it uses either the global ServerName + (if present) or calls the C function gethostname + (which should return the same as typing "hostname" at the + command prompt). Then it performs a DNS lookup on this address. + At present there is no way to avoid this lookup.

+ +

If you fear that this lookup might fail because your DNS + server is down then you can insert the hostname in + /etc/hosts (where you probably already have it so + that the machine can boot properly). Then ensure that your + machine is configured to use /etc/hosts in the + event that DNS fails. Depending on what OS you are using this + might be accomplished by editing /etc/resolv.conf, + or maybe /etc/nsswitch.conf.

+ +

If your server doesn't have to perform DNS for any other + reason then you might be able to get away with running Apache + with the HOSTRESORDER environment variable set to + "local". This all depends on what OS and resolver libraries you + are using. It also affects CGIs unless you use mod_env to control the + environment. It's best to consult the man pages or FAQs for + your OS.

+ +

Tips to Avoid these + problems

+ + + +

Appendix: Future Directions

+ +

The situation regarding DNS is highly undesirable. For + Apache 1.2 we've attempted to make the server at least continue + booting in the event of failed DNS, but it might not be the + best we can do. In any event requiring the use of explicit IP + addresses in configuration files is highly undesirable in + today's Internet where renumbering is a necessity.

+ +

A possible work around to the theft of service attack + described above would be to perform a reverse DNS lookup on the + IP address returned by the forward lookup and compare the two + names. In the event of a mismatch the virtualhost would be + disabled. This would require reverse DNS to be configured + properly (which is something that most admins are familiar with + because of the common use of "double-reverse" DNS lookups by + FTP servers and TCP wrappers).

+ +

In any event it doesn't seem possible to reliably boot a + virtual-hosted web server when DNS has failed unless IP + addresses are used. Partial solutions such as disabling + portions of the configuration might be worse than not booting + at all depending on what the webserver is supposed to + accomplish.

+ +

As HTTP/1.1 is deployed and browsers and proxies start + issuing the Host header it will become possible to + avoid the use of IP-based virtual hosts entirely. In this event + a webserver has no requirement to do DNS lookups during + configuration. But as of March 1997 these features have not + been deployed widely enough to be put into use on critical + webservers.

+ +

Apache HTTP Server

+ Index + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/dns-caveats.html.html b/usr.sbin/httpd/htdocs/manual/dns-caveats.html.html deleted file mode 100644 index 0d47f605fe0..00000000000 --- a/usr.sbin/httpd/htdocs/manual/dns-caveats.html.html +++ /dev/null @@ -1,231 +0,0 @@ - - - - - - - - Issues Regarding DNS and Apache - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Issues Regarding DNS and Apache

- -

This page could be summarized with the statement: don't - require Apache to use DNS for any parsing of the configuration - files. If Apache has to use DNS to parse the configuration - files then your server may be subject to reliability problems - (it might not boot), or denial and theft of service attacks - (including users able to steal hits from other users).

- -

A Simple Example

- Consider this configuration snippet: - -
-
-    <VirtualHost www.abc.dom>
-    ServerAdmin webgirl@abc.dom
-    DocumentRoot /www/abc
-    </VirtualHost>
-
-
- -

In order for Apache to function properly it absolutely needs - to have two pieces of information about each virtual host: the - ServerName - and at least one IP address that the server responds to. This - example does not include the IP address, so Apache must use DNS - to find the address of www.abc.dom. If for some - reason DNS is not available at the time your server is parsing - its config file, then this virtual host will not be - configured. It won't be able to respond to any hits to - this virtual host (prior to Apache version 1.2 the server would - not even boot).

- -

Suppose that www.abc.dom has address 10.0.0.1. - Then consider this configuration snippet:

- -
-
-    <VirtualHost 10.0.0.1>
-    ServerAdmin webgirl@abc.dom
-    DocumentRoot /www/abc
-    </VirtualHost>
-
-
- -

Now Apache needs to use reverse DNS to find the - ServerName for this virtualhost. If that reverse - lookup fails then it will partially disable the virtualhost - (prior to Apache version 1.2 the server would not even boot). - If the virtual host is name-based then it will effectively be - totally disabled, but if it is IP-based then it will mostly - work. However if Apache should ever have to generate a full URL - for the server which includes the server name then it will fail - to generate a valid URL.

- -

Here is a snippet that avoids both of these problems.

- -
-
-    <VirtualHost 10.0.0.1>
-    ServerName www.abc.dom
-    ServerAdmin webgirl@abc.dom
-    DocumentRoot /www/abc
-    </VirtualHost>
-
-
- -

Denial of Service

- -

There are (at least) two forms that denial of service can - come in. If you are running a version of Apache prior to - version 1.2 then your server will not even boot if one of the - two DNS lookups mentioned above fails for any of your virtual - hosts. In some cases this DNS lookup may not even be under your - control. For example, if abc.dom is one of your - customers and they control their own DNS then they can force - your (pre-1.2) server to fail while booting simply by deleting - the www.abc.dom record.

- -

Another form is far more insidious. Consider this - configuration snippet:

- -
-
-    <VirtualHost www.abc.dom>
-    ServerAdmin webgirl@abc.dom
-    DocumentRoot /www/abc
-    </VirtualHost>
-
-
- -
-
-    <VirtualHost www.def.dom>
-    ServerAdmin webguy@def.dom
-    DocumentRoot /www/def
-    </VirtualHost>
-
-
- -

Suppose that you've assigned 10.0.0.1 to - www.abc.dom and 10.0.0.2 to - www.def.dom. Furthermore, suppose that - def.com has control of their own DNS. With this - config you have put def.com into a position where - they can steal all traffic destined to abc.com. To - do so, all they have to do is set www.def.dom to - 10.0.0.1. Since they control their own DNS you can't stop them - from pointing the www.def.com record wherever they - wish.

- -

Requests coming in to 10.0.0.1 (including all those where - users typed in URLs of the form - http://www.abc.dom/whatever) will all be served by - the def.com virtual host. To better understand why - this happens requires a more in-depth discussion of how Apache - matches up incoming requests with the virtual host that will - serve it. A rough document describing this is available.

- -

The "main server" Address

- -

The addition of name-based - virtual host support in Apache 1.1 requires Apache to know - the IP address(es) of the host that httpd is running on. To get - this address it uses either the global ServerName - (if present) or calls the C function gethostname - (which should return the same as typing "hostname" at the - command prompt). Then it performs a DNS lookup on this address. - At present there is no way to avoid this lookup.

- -

If you fear that this lookup might fail because your DNS - server is down then you can insert the hostname in - /etc/hosts (where you probably already have it so - that the machine can boot properly). Then ensure that your - machine is configured to use /etc/hosts in the - event that DNS fails. Depending on what OS you are using this - might be accomplished by editing /etc/resolv.conf, - or maybe /etc/nsswitch.conf.

- -

If your server doesn't have to perform DNS for any other - reason then you might be able to get away with running Apache - with the HOSTRESORDER environment variable set to - "local". This all depends on what OS and resolver libraries you - are using. It also affects CGIs unless you use mod_env to control the - environment. It's best to consult the man pages or FAQs for - your OS.

- -

Tips to Avoid these - problems

- - - -

Appendix: Future Directions

- -

The situation regarding DNS is highly undesirable. For - Apache 1.2 we've attempted to make the server at least continue - booting in the event of failed DNS, but it might not be the - best we can do. In any event requiring the use of explicit IP - addresses in configuration files is highly undesirable in - today's Internet where renumbering is a necessity.

- -

A possible work around to the theft of service attack - described above would be to perform a reverse DNS lookup on the - IP address returned by the forward lookup and compare the two - names. In the event of a mismatch the virtualhost would be - disabled. This would require reverse DNS to be configured - properly (which is something that most admins are familiar with - because of the common use of "double-reverse" DNS lookups by - FTP servers and TCP wrappers).

- -

In any event it doesn't seem possible to reliably boot a - virtual-hosted web server when DNS has failed unless IP - addresses are used. Partial solutions such as disabling - portions of the configuration might be worse than not booting - at all depending on what the webserver is supposed to - accomplish.

- -

As HTTP/1.1 is deployed and browsers and proxies start - issuing the Host header it will become possible to - avoid the use of IP-based virtual hosts entirely. In this event - a webserver has no requirement to do DNS lookups during - configuration. But as of March 1997 these features have not - been deployed widely enough to be put into use on critical - webservers.

- -

Apache HTTP Server

- Index - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/env.html b/usr.sbin/httpd/htdocs/manual/env.html new file mode 100644 index 00000000000..1b79aa7c653 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/env.html @@ -0,0 +1,361 @@ + + + + + + + + Environment Variables in Apache + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Environment Variables in Apache

+ +

The Apache HTTP Server provides a mechanism for storing + information in named variables that are called environment + variables. This information can be used to control various + operations such as logging or access control. The variables are + also used as a mechanism to communicate with external programs + such as CGI scripts. This document discusses different ways to + manipulate and use these variables.

+ +

Although these variables are referred to as environment + variables, they are not the same as the environment + variables controlled by the underlying operating system. + Instead, these variables are stored and manipulated in an + internal Apache structure. They only become actual operating + system environment variables when they are provided to CGI + scripts and Server Side Include scripts. If you wish to + manipulate the operating system environment under which the + server itself runs, you must use the standard environment + manipulation mechanisms provided by your operating system + shell.

+ + +
+ +

Setting Environment + Variables

+ + + + + + + +
Related Modules
+
+ mod_env
+ mod_rewrite
+ mod_setenvif
+ mod_unique_id
+ 		Related Directives
+
+ BrowserMatch
+ BrowserMatchNoCase
+ PassEnv
+ RewriteRule
+ SetEnv
+ SetEnvIf
+ SetEnvIfNoCase
+ UnsetEnv
+
+ +

Basic Environment Manipulation

+ +

The most basic way to set an environment variable in Apache + is using the unconditional SetEnv directive. + Variables may also be passed from the environment of the shell + which started the server using the PassEnv + directive.

+ +

Conditional Per-Request Settings

+ +

For additional flexibility, the directives provided by + mod_setenvif allow environment variables to be set on a + per-request basis, conditional on characteristics of particular + requests. For example, a variable could be set only when a + specific browser (User-Agent) is making a request, or only when + a specific Referer [sic] header is found. Even more flexibility + is available through the mod_rewrite's RewriteRule + which uses the [E=...] option to set environment + variables.

+ +

Unique Identifiers

+ +

Finally, mod_unique_id sets the environment variable + UNIQUE_ID for each request to a value which is + guaranteed to be unique across "all" requests under very + specific conditions.

+ +

Standard CGI Variables

+ +

In addition to all environment variables set within the + Apache configuration and passed from the shell, CGI scripts and + SSI pages are provided with a set of environment variables + containing meta-information about the request as required by + the CGI specification.

+ +

Some Caveats

+ + +
+ +

Using Environment + Variables

+ + + + + + + +
Related Modules
+
+ mod_access
+ mod_cgi
+ mod_include
+ mod_log_config
+ mod_rewrite
+ 		Related Directives
+
+ Allow
+ CustomLog
+ Deny
+ LogFormat
+ RewriteCond
+ RewriteRule
+
+ +

CGI Scripts

+ +

One of the primary uses of environment variables is to + communicate information to CGI scripts. As discussed above, the + environment passed to CGI scripts includes standard + meta-information about the request in addition to any variables + set within the Apache configuration. For more details, see the + CGI tutorial.

+ +

SSI Pages

+ +

Server-parsed (SSI) documents processed by mod_include's + server-parsed handler can print environment + variables using the echo element, and can use + environment variables in flow control elements to makes parts + of a page conditional on characteristics of a request. Apache + also provides SSI pages with the standard CGI environment + variables as discussed above. For more details, see the SSI tutorial.

+ +

Access Control

+ +

Access to the server can be controlled based on the value of + environment variables using the allow from env= + and deny from env= directives. In combination with + SetEnvIf, this allows for flexible control of + access to the server based on characteristics of the client. + For example, you can use these directives to deny access to a + particular browser (User-Agent).

+ +

Conditional Logging

+ +

Environment variables can be logged in the access log using + the LogFormat option %e. In addition, + the decision on whether or not to log requests can be made + based on the status of environment variables using the + conditional form of the CustomLog directive. In + combination with SetEnvIf this allows for flexible + control of which requests are logged. For example, you can + choose not to log requests for filenames ending in + gif, or you can choose to only log requests from + clients which are outside your subnet.

+ +

URL Rewriting

+ +

The %{ENV:...} form of TestString in + the RewriteCond allows mod_rewrite's rewrite + engine to make decisions conditional on environment variables. + Note that the variables accessible in mod_rewrite without the + ENV: prefix are not actually environment + variables. Rather, they are variables special to mod_rewrite + which cannot be accessed from other modules.

+
+ +

Special Purpose Environment + Variables

+ +

Interoperability problems have led to the introduction of + mechanisms to modify the way Apache behaves when talking to + particular clients. To make these mechanisms as flexible as + possible, they are invoked by defining environment variables, + typically with BrowserMatch, + though SetEnv and PassEnv could also be used, + for example.

+ +

downgrade-1.0

+ +

This forces the request to be treated as a HTTP/1.0 request + even if it was in a later dialect.

+ +

force-no-vary

+ +

This causes any Vary fields to be removed from + the response header before it is sent back to the client. Some + clients don't interpret this field correctly (see the known client + problems page); setting this variable can work around this + problem. Setting this variable also implies + force-response-1.0.

+ +

force-response-1.0

+ +

This forces an HTTP/1.0 response when set. It was originally + implemented as a result of a problem with AOL's proxies. Some + clients may not behave correctly when given an HTTP/1.1 + response, and this can be used to interoperate with them.

+ +

nokeepalive

+ +

This disables KeepAlive when set.

+ +

suppress-error-charset

+

Available in versions after 1.3.26 and 2.0.40

+

When Apache issues a redirect in response to a client request, + the response includes some actual text to be displayed in case + the client can't (or doesn't) automatically follow the redirection. + Apache ordinarily labels this text according to the character set + which it uses, which is ISO-8859-1.

+

However, if the redirection is to a page that uses a different + character set, some broken browser versions will try to use the + character set from the redirection text rather than the actual page. + This can result in Greek, for instance, being incorrectly rendered.

+

Setting this environment variable causes Apache to omit the character + set for the redirection text, and these broken browsers will then correctly + use that of the destination page.

+
+ +

Examples

+ +

Changing protocol behavior with misbehaving clients

+ +

We recommend that the following lines be included in + httpd.conf to deal with known client problems.

+
+#
+# The following directives modify normal HTTP response behavior.
+# The first directive disables keepalive for Netscape 2.x and browsers that
+# spoof it. There are known problems with these browser implementations.
+# The second directive is for Microsoft Internet Explorer 4.0b2
+# which has a broken HTTP/1.1 implementation and does not properly
+# support keepalive when it is used on 301 or 302 (redirect) responses.
+#
+BrowserMatch "Mozilla/2" nokeepalive
+BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
+
+#
+# The following directive disables HTTP/1.1 responses to browsers which
+# are in violation of the HTTP/1.0 spec by not being able to grok a
+# basic 1.1 response.
+#
+BrowserMatch "RealPlayer 4\.0" force-response-1.0
+BrowserMatch "Java/1\.0" force-response-1.0
+BrowserMatch "JDK/1\.0" force-response-1.0
+
+ +

Do not log requests for images in the access log

+ +

This example keeps requests for images from appearing in the + access log. It can be easily modified to prevent logging of + particular directories, or to prevent logging of requests + coming from particular hosts.

+
+    SetEnvIf Request_URI \.gif image-request
+    SetEnvIf Request_URI \.jpg image-request
+    SetEnvIf Request_URI \.png image-request
+    CustomLog logs/access_log env=!image-request
+
+ +

Prevent "Image Theft"

+ +

This example shows how to keep people not on your server + from using images on your server as inline-images on their + pages. This is not a recommended configuration, but it can work + in limited circumstances. We assume that all your images are in + a directory called /web/images.

+
+    SetEnvIf Referer "^http://www.example.com/" local_referal
+    # Allow browsers that do not send Referer info
+    SetEnvIf Referer "^$" local_referal
+    <Directory /web/images>
+       Order Deny,Allow
+       Deny from all
+       Allow from env=local_referal
+    </Directory>
+
+ +

Note: spelling of 'referer' and 'referal' is + intentional.

+ +

For more information about this technique, see the + ApacheToday tutorial " + Keeping Your Images from Adorning Other Sites".

+
+ +

Apache HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/env.html.html b/usr.sbin/httpd/htdocs/manual/env.html.html deleted file mode 100644 index 1b79aa7c653..00000000000 --- a/usr.sbin/httpd/htdocs/manual/env.html.html +++ /dev/null @@ -1,361 +0,0 @@ - - - - - - - - Environment Variables in Apache - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Environment Variables in Apache

- -

The Apache HTTP Server provides a mechanism for storing - information in named variables that are called environment - variables. This information can be used to control various - operations such as logging or access control. The variables are - also used as a mechanism to communicate with external programs - such as CGI scripts. This document discusses different ways to - manipulate and use these variables.

- -

Although these variables are referred to as environment - variables, they are not the same as the environment - variables controlled by the underlying operating system. - Instead, these variables are stored and manipulated in an - internal Apache structure. They only become actual operating - system environment variables when they are provided to CGI - scripts and Server Side Include scripts. If you wish to - manipulate the operating system environment under which the - server itself runs, you must use the standard environment - manipulation mechanisms provided by your operating system - shell.

- - -
- -

Setting Environment - Variables

- - - - - - - -
Related Modules
-
- mod_env
- mod_rewrite
- mod_setenvif
- mod_unique_id
- 		Related Directives
-
- BrowserMatch
- BrowserMatchNoCase
- PassEnv
- RewriteRule
- SetEnv
- SetEnvIf
- SetEnvIfNoCase
- UnsetEnv
-
- -

Basic Environment Manipulation

- -

The most basic way to set an environment variable in Apache - is using the unconditional SetEnv directive. - Variables may also be passed from the environment of the shell - which started the server using the PassEnv - directive.

- -

Conditional Per-Request Settings

- -

For additional flexibility, the directives provided by - mod_setenvif allow environment variables to be set on a - per-request basis, conditional on characteristics of particular - requests. For example, a variable could be set only when a - specific browser (User-Agent) is making a request, or only when - a specific Referer [sic] header is found. Even more flexibility - is available through the mod_rewrite's RewriteRule - which uses the [E=...] option to set environment - variables.

- -

Unique Identifiers

- -

Finally, mod_unique_id sets the environment variable - UNIQUE_ID for each request to a value which is - guaranteed to be unique across "all" requests under very - specific conditions.

- -

Standard CGI Variables

- -

In addition to all environment variables set within the - Apache configuration and passed from the shell, CGI scripts and - SSI pages are provided with a set of environment variables - containing meta-information about the request as required by - the CGI specification.

- -

Some Caveats

- - -
- -

Using Environment - Variables

- - - - - - - -
Related Modules
-
- mod_access
- mod_cgi
- mod_include
- mod_log_config
- mod_rewrite
- 		Related Directives
-
- Allow
- CustomLog
- Deny
- LogFormat
- RewriteCond
- RewriteRule
-
- -

CGI Scripts

- -

One of the primary uses of environment variables is to - communicate information to CGI scripts. As discussed above, the - environment passed to CGI scripts includes standard - meta-information about the request in addition to any variables - set within the Apache configuration. For more details, see the - CGI tutorial.

- -

SSI Pages

- -

Server-parsed (SSI) documents processed by mod_include's - server-parsed handler can print environment - variables using the echo element, and can use - environment variables in flow control elements to makes parts - of a page conditional on characteristics of a request. Apache - also provides SSI pages with the standard CGI environment - variables as discussed above. For more details, see the SSI tutorial.

- -

Access Control

- -

Access to the server can be controlled based on the value of - environment variables using the allow from env= - and deny from env= directives. In combination with - SetEnvIf, this allows for flexible control of - access to the server based on characteristics of the client. - For example, you can use these directives to deny access to a - particular browser (User-Agent).

- -

Conditional Logging

- -

Environment variables can be logged in the access log using - the LogFormat option %e. In addition, - the decision on whether or not to log requests can be made - based on the status of environment variables using the - conditional form of the CustomLog directive. In - combination with SetEnvIf this allows for flexible - control of which requests are logged. For example, you can - choose not to log requests for filenames ending in - gif, or you can choose to only log requests from - clients which are outside your subnet.

- -

URL Rewriting

- -

The %{ENV:...} form of TestString in - the RewriteCond allows mod_rewrite's rewrite - engine to make decisions conditional on environment variables. - Note that the variables accessible in mod_rewrite without the - ENV: prefix are not actually environment - variables. Rather, they are variables special to mod_rewrite - which cannot be accessed from other modules.

-
- -

Special Purpose Environment - Variables

- -

Interoperability problems have led to the introduction of - mechanisms to modify the way Apache behaves when talking to - particular clients. To make these mechanisms as flexible as - possible, they are invoked by defining environment variables, - typically with BrowserMatch, - though SetEnv and PassEnv could also be used, - for example.

- -

downgrade-1.0

- -

This forces the request to be treated as a HTTP/1.0 request - even if it was in a later dialect.

- -

force-no-vary

- -

This causes any Vary fields to be removed from - the response header before it is sent back to the client. Some - clients don't interpret this field correctly (see the known client - problems page); setting this variable can work around this - problem. Setting this variable also implies - force-response-1.0.

- -

force-response-1.0

- -

This forces an HTTP/1.0 response when set. It was originally - implemented as a result of a problem with AOL's proxies. Some - clients may not behave correctly when given an HTTP/1.1 - response, and this can be used to interoperate with them.

- -

nokeepalive

- -

This disables KeepAlive when set.

- -

suppress-error-charset

-

Available in versions after 1.3.26 and 2.0.40

-

When Apache issues a redirect in response to a client request, - the response includes some actual text to be displayed in case - the client can't (or doesn't) automatically follow the redirection. - Apache ordinarily labels this text according to the character set - which it uses, which is ISO-8859-1.

-

However, if the redirection is to a page that uses a different - character set, some broken browser versions will try to use the - character set from the redirection text rather than the actual page. - This can result in Greek, for instance, being incorrectly rendered.

-

Setting this environment variable causes Apache to omit the character - set for the redirection text, and these broken browsers will then correctly - use that of the destination page.

-
- -

Examples

- -

Changing protocol behavior with misbehaving clients

- -

We recommend that the following lines be included in - httpd.conf to deal with known client problems.

-
-#
-# The following directives modify normal HTTP response behavior.
-# The first directive disables keepalive for Netscape 2.x and browsers that
-# spoof it. There are known problems with these browser implementations.
-# The second directive is for Microsoft Internet Explorer 4.0b2
-# which has a broken HTTP/1.1 implementation and does not properly
-# support keepalive when it is used on 301 or 302 (redirect) responses.
-#
-BrowserMatch "Mozilla/2" nokeepalive
-BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
-
-#
-# The following directive disables HTTP/1.1 responses to browsers which
-# are in violation of the HTTP/1.0 spec by not being able to grok a
-# basic 1.1 response.
-#
-BrowserMatch "RealPlayer 4\.0" force-response-1.0
-BrowserMatch "Java/1\.0" force-response-1.0
-BrowserMatch "JDK/1\.0" force-response-1.0
-
- -

Do not log requests for images in the access log

- -

This example keeps requests for images from appearing in the - access log. It can be easily modified to prevent logging of - particular directories, or to prevent logging of requests - coming from particular hosts.

-
-    SetEnvIf Request_URI \.gif image-request
-    SetEnvIf Request_URI \.jpg image-request
-    SetEnvIf Request_URI \.png image-request
-    CustomLog logs/access_log env=!image-request
-
- -

Prevent "Image Theft"

- -

This example shows how to keep people not on your server - from using images on your server as inline-images on their - pages. This is not a recommended configuration, but it can work - in limited circumstances. We assume that all your images are in - a directory called /web/images.

-
-    SetEnvIf Referer "^http://www.example.com/" local_referal
-    # Allow browsers that do not send Referer info
-    SetEnvIf Referer "^$" local_referal
-    <Directory /web/images>
-       Order Deny,Allow
-       Deny from all
-       Allow from env=local_referal
-    </Directory>
-
- -

Note: spelling of 'referer' and 'referal' is - intentional.

- -

For more information about this technique, see the - ApacheToday tutorial " - Keeping Your Images from Adorning Other Sites".

-
- -

Apache HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/handler.html b/usr.sbin/httpd/htdocs/manual/handler.html new file mode 100644 index 00000000000..57a87305145 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/handler.html @@ -0,0 +1,179 @@ + + + + + + + + Apache's Handler Use + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Apache's Handler Use

+ + +
+ +

What is a + Handler

+ + + + + + + +
Related Modules
+
+ mod_actions
+ mod_asis
+ mod_cgi
+ mod_imap
+ mod_info
+ mod_include
+ mod_mime
+ mod_negotiation
+ mod_status
+ 		Related Directives
+
+ Action
+ AddHandler
+ RemoveHandler
+ SetHandler
+
+ +

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 types + are "handled" separately.

+ +

Apache 1.1 adds the ability to use handlers explicitly. + Based on either filename extensions or on location, handlers + can be specified without relation to file type. This is + advantageous both because it is a more elegant solution, and + because it also allows for both a type and a + handler to be associated with a file. (See also Files with Multiple + Extensions.)

+ +

Handlers can either be built into the server or included in + a module, or they can be added with the Action directive. The + built-in handlers in the standard distribution are as + follows:

+ + +
+ +

Examples

+ +

Modifying static content using a CGI script

+ +

The following directives will cause requests for files with + the html extension to trigger the launch of the + footer.pl CGI script.

+
+     Action add-footer /cgi-bin/footer.pl
+     AddHandler add-footer .html
+
+ +

Then the CGI script is responsible for sending the + originally requested document (pointed to by the + PATH_TRANSLATED environment variable) and making + whatever modifications or additions are desired.

+ +

Files with HTTP headers

+ +

The following directives will enable the + send-as-is handler, which is used for files which + contain their own HTTP headers. All files in the + /web/htdocs/asis/ directory will be processed by + the send-as-is handler, regardless of their + filename extensions.

+
+    <Directory /web/htdocs/asis>
+    SetHandler send-as-is
+    </Directory>
+
+
+ +

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 HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/handler.html.html b/usr.sbin/httpd/htdocs/manual/handler.html.html deleted file mode 100644 index 57a87305145..00000000000 --- a/usr.sbin/httpd/htdocs/manual/handler.html.html +++ /dev/null @@ -1,179 +0,0 @@ - - - - - - - - Apache's Handler Use - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Apache's Handler Use

- - -
- -

What is a - Handler

- - - - - - - -
Related Modules
-
- mod_actions
- mod_asis
- mod_cgi
- mod_imap
- mod_info
- mod_include
- mod_mime
- mod_negotiation
- mod_status
- 		Related Directives
-
- Action
- AddHandler
- RemoveHandler
- SetHandler
-
- -

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 types - are "handled" separately.

- -

Apache 1.1 adds the ability to use handlers explicitly. - Based on either filename extensions or on location, handlers - can be specified without relation to file type. This is - advantageous both because it is a more elegant solution, and - because it also allows for both a type and a - handler to be associated with a file. (See also Files with Multiple - Extensions.)

- -

Handlers can either be built into the server or included in - a module, or they can be added with the Action directive. The - built-in handlers in the standard distribution are as - follows:

- - -
- -

Examples

- -

Modifying static content using a CGI script

- -

The following directives will cause requests for files with - the html extension to trigger the launch of the - footer.pl CGI script.

-
-     Action add-footer /cgi-bin/footer.pl
-     AddHandler add-footer .html
-
- -

Then the CGI script is responsible for sending the - originally requested document (pointed to by the - PATH_TRANSLATED environment variable) and making - whatever modifications or additions are desired.

- -

Files with HTTP headers

- -

The following directives will enable the - send-as-is handler, which is used for files which - contain their own HTTP headers. All files in the - /web/htdocs/asis/ directory will be processed by - the send-as-is handler, regardless of their - filename extensions.

-
-    <Directory /web/htdocs/asis>
-    SetHandler send-as-is
-    </Directory>
-
-
- -

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 HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/howto/cgi.html b/usr.sbin/httpd/htdocs/manual/howto/cgi.html new file mode 100644 index 00000000000..9efd6e4ce88 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/howto/cgi.html @@ -0,0 +1,567 @@ + + + + + + + + Apache Tutorial: Dynamic Content with CGI + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + + +

Dynamic Content with CGI

+ + + + + +
+ +

Dynamic Content with CGI

+ + + + + + + +
Related Modules
+
+ mod_alias
+ mod_cgi
+ 		Related Directives
+
+ AddHandler
+ Options
+ ScriptAlias
+
+ +

The CGI (Common Gateway Interface) defines a way for a web + server to interact with external content-generating programs, + which are often referred to as CGI programs or CGI scripts. It + is the simplest, and most common, way to put dynamic content on + your web site. This document will be an introduction to setting + up CGI on your Apache web server, and getting started writing + CGI programs.

+
+ +

Configuring Apache to + permit CGI

+ +

In order to get your CGI programs to work properly, you'll + need to have Apache configured to permit CGI execution. There + are several ways to do this.

+ +

ScriptAlias

+ +

The ScriptAlias directive tells Apache that a + particular directory is set aside for CGI programs. Apache will + assume that every file in this directory is a CGI program, and + will attempt to execute it, when that particular resource is + requested by a client.

+ +

The ScriptAlias directive looks like:

+
+        ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/
+
+ +

The example shown is from your default + httpd.conf configuration file, if you installed + Apache in the default location. The ScriptAlias + directive is much like the Alias directive, which + defines a URL prefix that is to mapped to a particular + directory. Alias and ScriptAlias are + usually used for directories that are outside of the + DocumentRoot directory. The difference between + Alias and ScriptAlias is that + ScriptAlias has the added meaning that everything + under that URL prefix will be considered a CGI program. So, the + example above tells Apache that any request for a resource + beginning with /cgi-bin/ should be served from the + directory /usr/local/apache/cgi-bin/, and should + be treated as a CGI program.

+ +

For example, if the URL + http://www.example.com/cgi-bin/test.pl is + requested, Apache will attempt to execute the file + /usr/local/apache/cgi-bin/test.pl and return the + output. Of course, the file will have to exist, and be + executable, and return output in a particular way, or Apache + will return an error message.

+ +

CGI outside of + ScriptAlias directories

+ +

CGI programs are often restricted to + ScriptAlias'ed directories for security reasons. + In this way, administrators can tightly control who is allowed + to use CGI programs. However, if the proper security + precautions are taken, there is no reason why CGI programs + cannot be run from arbitrary directories. For example, you may + wish to let users have web content in their home directories + with the UserDir directive. If they want to have + their own CGI programs, but don't have access to the main + cgi-bin directory, they will need to be able to + run CGI programs elsewhere.

+ +

Explicitly + using Options to permit CGI execution

+ +

You could explicitly use the Options directive, + inside your main server configuration file, to specify that CGI + execution was permitted in a particular directory:

+
+        <Directory /usr/local/apache/htdocs/somedir>
+                Options +ExecCGI
+        </Directory>
+
+ +

The above directive tells Apache to permit the execution of + CGI files. You will also need to tell the server what files are + CGI files. The following AddHandler directive + tells the server to treat all files with the cgi + or pl extension as CGI programs:

+
+     AddHandler cgi-script cgi pl
+
+ +

.htaccess + files

+ +

A .htaccess file is a way to set configuration + directives on a per-directory basis. When Apache serves a + resource, it looks in the directory from which it is serving a + file for a file called .htaccess, and, if it finds + it, it will apply directives found therein. + .htaccess files can be permitted with the + AllowOverride directive, which specifies what + types of directives can appear in these files, or if they are + not allowed at all. To permit the directive we will need for + this purpose, the following configuration will be needed in + your main server configuration:

+
+        AllowOverride Options
+
+ +

In the .htaccess file, you'll need the + following directive:

+
+        Options +ExecCGI
+
+ +

which tells Apache that execution of CGI programs is + permitted in this directory.

+
+ +

Writing a CGI program

+ +

There are two main differences between ``regular'' + programming, and CGI programming.

+ +

First, all output from your CGI program must be preceded by + a MIME-type header. This is HTTP header that tells the client + what sort of content it is receiving. Most of the time, this + will look like:

+
+        Content-type: text/html
+
+ +

Secondly, your output needs to be in HTML, or some other + format that a browser will be able to display. Most of the + time, this will be HTML, but occasionally you might write a CGI + program that outputs a gif image, or other non-HTML + content.

+ +

Apart from those two things, writing a CGI program will look + a lot like any other program that you might write.

+ +

Your + first CGI program

+ +

The following is an example CGI program that prints one line + to your browser. Type in the following, save it to a file + called first.pl, and put it in your + cgi-bin directory.

+
+        #!/usr/bin/perl
+        print "Content-type: text/html\r\n\r\n";
+        print "Hello, World.";
+
+ +

Even if you are not familiar with Perl, you should be able + to see what is happening here. The first line tells Apache (or + whatever shell you happen to be running under) that this + program can be executed by feeding the file to the interpreter + found at the location /usr/bin/perl. The second + line prints the content-type declaration we talked about, + followed by two carriage-return newline pairs. This puts a + blank line after the header, to indicate the end of the HTTP + headers, and the beginning of the body. The third line prints + the string ``Hello, World.'' And that's the end of it.

+ +

If you open your favorite browser and tell it to get the + address

+
+        http://www.example.com/cgi-bin/first.pl
+
+ +

or wherever you put your file, you will see the one line + Hello, World. appear in your browser window. It's + not very exciting, but once you get that working, you'll have a + good chance of getting just about anything working.

+
+ +

But it's still not + working!

+ +

There are four basic things that you may see in your browser + when you try to access your CGI program from the web:

+ +
+
The output of your CGI program
+ +
Great! That means everything worked fine.
+
+
+ +
The source code of your CGI program or a "POST Method Not + Allowed" message
+ +
That means that you have not properly configured Apache + to process your CGI program. Reread the section on configuring Apache + and try to find what you missed.
+
+
+ +
A message starting with "Forbidden"
+ +
That means that there is a permissions problem. Check the + Apache error log and the section + below on file + permissions.
+
+
+ +
A message saying "Internal Server Error"
+ +
If you check the Apache error + log, you will probably find that it says "Premature end + of script headers", possibly along with an error message + generated by your CGI program. In this case, you will want to + check each of the below sections to see what might be + preventing your CGI program from emitting the proper HTTP + headers.
+
+ +

File + permissions

+ +

Remember that the server does not run as you. That is, when + the server starts up, it is running with the permissions of an + unprivileged user - usually ``nobody'', or ``www'' - and so it + will need extra permissions to execute files that are owned by + you. Usually, the way to give a file sufficient permissions to + be executed by ``nobody'' is to give everyone execute + permission on the file:

+
+        chmod a+x first.pl
+
+ +

Also, if your program reads from, or writes to, any other + files, those files will need to have the correct permissions to + permit this.

+ +

The exception to this is when the server is configured to + use suexec. This program allows + CGI programs to be run under different user permissions, + depending on which virtual host or user home directory they are + located in. Suexec has very strict permission checking, and any + failure in that checking will result in your CGI programs + failing with an "Internal Server Error". In this case, you will + need to check the suexec log file to see what specific security + check is failing.

+ +

Path + information

+ +

When you run a program from your command line, you have + certain information that is passed to the shell without you + thinking about it. For example, you have a path, which tells + the shell where it can look for files that you reference.

+ +

When a program runs through the web server as a CGI program, + it does not have that path. Any programs that you invoke in + your CGI program (like 'sendmail', for example) will need to be + specified by a full path, so that the shell can find them when + it attempts to execute your CGI program.

+ +

A common manifestation of this is the path to the script + interpreter (often perl) indicated in the first + line of your CGI program, which will look something like:

+
+     #!/usr/bin/perl
+
+ +

Make sure that this is in fact the path to the + interpreter.

+ +

Syntax + errors

+ +

Most of the time when a CGI program fails, it's because of a + problem with the program itself. This is particularly true once + you get the hang of this CGI stuff, and no longer make the + above two mistakes. Always attempt to run your program from the + command line before you test if via a browser. This will + eliminate most of your problems.

+ +

Error logs

+ +

The error logs are your friend. Anything that goes wrong + generates message in the error log. You should always look + there first. If the place where you are hosting your web site + does not permit you access to the error log, you should + probably host your site somewhere else. Learn to read the error + logs, and you'll find that almost all of your problems are + quickly identified, and quickly solved.

+
+ +

What's going on behind the + scenes?

+ +

As you become more advanced in CGI programming, it will + become useful to understand more about what's happening behind + the scenes. Specifically, how the browser and server + communicate with one another. Because although it's all very + well to write a program that prints ``Hello, World.'', it's not + particularly useful.

+ +

Environment variables

+ +

Environment variables are values that float around you as + you use your computer. They are useful things like your path + (where the computer searches for a the actual file implementing + a command when you type it), your username, your terminal type, + and so on. For a full list of your normal, every day + environment variables, type env at a command + prompt.

+ +

During the CGI transaction, the server and the browser also + set environment variables, so that they can communicate with + one another. These are things like the browser type (Netscape, + IE, Lynx), the server type (Apache, IIS, WebSite), the name of + the CGI program that is being run, and so on.

+ +

These variables are available to the CGI programmer, and are + half of the story of the client-server communication. The + complete list of required variables is at http://hoohoo.ncsa.uiuc.edu/cgi/env.html

+ +

This simple Perl CGI program will display all of the + environment variables that are being passed around. Two similar + programs are included in the cgi-bin directory of + the Apache distribution. Note that some variables are required, + while others are optional, so you may see some variables listed + that were not in the official list. In addition, Apache + provides many different ways for you to add your own environment variables to + the basic ones provided by default.

+
+     #!/usr/bin/perl
+     print "Content-type: text/html\n\n";
+     foreach $key (keys %ENV) {
+          print "$key --> $ENV{$key}<br>";
+     }
+
+ +

STDIN and + STDOUT

+ +

Other communication between the server and the client + happens over standard input (STDIN) and standard + output (STDOUT). In normal everyday context, + STDIN means the keyboard, or a file that a program + is given to act on, and STDOUT usually means the + console or screen.

+ +

When you POST a web form to a CGI program, the + data in that form is bundled up into a special format and gets + delivered to your CGI program over STDIN. The + program then can process that data as though it was coming in + from the keyboard, or from a file

+ +

The ``special format'' is very simple. A field name and its + value are joined together with an equals (=) sign, and pairs of + values are joined together with an ampersand (&). + Inconvenient characters like spaces, ampersands, and equals + signs, are converted into their hex equivalent so that they + don't gum up the works. The whole data string might look + something like:

+
+     name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey
+
+ +

You'll sometimes also see this type of string appended to + the a URL. When that is done, the server puts that string into + the environment variable called QUERY_STRING. + That's called a GET request. Your HTML form + specifies whether a GET or a POST is + used to deliver the data, by setting the METHOD + attribute in the FORM tag.

+ +

Your program is then responsible for splitting that string + up into useful information. Fortunately, there are libraries + and modules available to help you process this data, as well as + handle other of the aspects of your CGI program.

+
+ +

CGI + modules/libraries

+ +

When you write CGI programs, you should consider using a + code library, or module, to do most of the grunt work for you. + This leads to fewer errors, and faster development.

+ +

If you're writing CGI programs in Perl, modules are + available on CPAN. The most + popular module for this purpose is CGI.pm. You might also + consider CGI::Lite, which implements a minimal set of + functionality, which is all you need in most programs.

+ +

If you're writing CGI programs in C, there are a variety of + options. One of these is the CGIC library, from http://www.boutell.com/cgic/

+
+ +

For + more information

+ +

There are a large number of CGI resources on the web. You + can discuss CGI problems with other users on the Usenet group + comp.infosystems.www.authoring.cgi. And the -servers mailing + list from the HTML Writers Guild is a great source of answers + to your questions. You can find out more at http://www.hwg.org/lists/hwg-servers/

+ +

And, of course, you should probably read the CGI + specification, which has all the details on the operation of + CGI programs. You can find the original version at the NCSA + and there is an updated draft at the Common Gateway Interface + RFC project.

+ +

When you post a question about a CGI problem that you're + having, whether to a mailing list, or to a newsgroup, make sure + you provide enough information about what happened, what you + expected to happen, and how what actually happened was + different, what server you're running, what language your CGI + program was in, and, if possible, the offending code. This will + make finding your problem much simpler.

+ +

Note that questions about CGI problems should + never be posted to the Apache bug database + unless you are sure you have found a problem in the Apache + source code.

+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/howto/cgi.html.html b/usr.sbin/httpd/htdocs/manual/howto/cgi.html.html deleted file mode 100644 index 9efd6e4ce88..00000000000 --- a/usr.sbin/httpd/htdocs/manual/howto/cgi.html.html +++ /dev/null @@ -1,567 +0,0 @@ - - - - - - - - Apache Tutorial: Dynamic Content with CGI - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - - -

Dynamic Content with CGI

- - - - - -
- -

Dynamic Content with CGI

- - - - - - - -
Related Modules
-
- mod_alias
- mod_cgi
- 		Related Directives
-
- AddHandler
- Options
- ScriptAlias
-
- -

The CGI (Common Gateway Interface) defines a way for a web - server to interact with external content-generating programs, - which are often referred to as CGI programs or CGI scripts. It - is the simplest, and most common, way to put dynamic content on - your web site. This document will be an introduction to setting - up CGI on your Apache web server, and getting started writing - CGI programs.

-
- -

Configuring Apache to - permit CGI

- -

In order to get your CGI programs to work properly, you'll - need to have Apache configured to permit CGI execution. There - are several ways to do this.

- -

ScriptAlias

- -

The ScriptAlias directive tells Apache that a - particular directory is set aside for CGI programs. Apache will - assume that every file in this directory is a CGI program, and - will attempt to execute it, when that particular resource is - requested by a client.

- -

The ScriptAlias directive looks like:

-
-        ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/
-
- -

The example shown is from your default - httpd.conf configuration file, if you installed - Apache in the default location. The ScriptAlias - directive is much like the Alias directive, which - defines a URL prefix that is to mapped to a particular - directory. Alias and ScriptAlias are - usually used for directories that are outside of the - DocumentRoot directory. The difference between - Alias and ScriptAlias is that - ScriptAlias has the added meaning that everything - under that URL prefix will be considered a CGI program. So, the - example above tells Apache that any request for a resource - beginning with /cgi-bin/ should be served from the - directory /usr/local/apache/cgi-bin/, and should - be treated as a CGI program.

- -

For example, if the URL - http://www.example.com/cgi-bin/test.pl is - requested, Apache will attempt to execute the file - /usr/local/apache/cgi-bin/test.pl and return the - output. Of course, the file will have to exist, and be - executable, and return output in a particular way, or Apache - will return an error message.

- -

CGI outside of - ScriptAlias directories

- -

CGI programs are often restricted to - ScriptAlias'ed directories for security reasons. - In this way, administrators can tightly control who is allowed - to use CGI programs. However, if the proper security - precautions are taken, there is no reason why CGI programs - cannot be run from arbitrary directories. For example, you may - wish to let users have web content in their home directories - with the UserDir directive. If they want to have - their own CGI programs, but don't have access to the main - cgi-bin directory, they will need to be able to - run CGI programs elsewhere.

- -

Explicitly - using Options to permit CGI execution

- -

You could explicitly use the Options directive, - inside your main server configuration file, to specify that CGI - execution was permitted in a particular directory:

-
-        <Directory /usr/local/apache/htdocs/somedir>
-                Options +ExecCGI
-        </Directory>
-
- -

The above directive tells Apache to permit the execution of - CGI files. You will also need to tell the server what files are - CGI files. The following AddHandler directive - tells the server to treat all files with the cgi - or pl extension as CGI programs:

-
-     AddHandler cgi-script cgi pl
-
- -

.htaccess - files

- -

A .htaccess file is a way to set configuration - directives on a per-directory basis. When Apache serves a - resource, it looks in the directory from which it is serving a - file for a file called .htaccess, and, if it finds - it, it will apply directives found therein. - .htaccess files can be permitted with the - AllowOverride directive, which specifies what - types of directives can appear in these files, or if they are - not allowed at all. To permit the directive we will need for - this purpose, the following configuration will be needed in - your main server configuration:

-
-        AllowOverride Options
-
- -

In the .htaccess file, you'll need the - following directive:

-
-        Options +ExecCGI
-
- -

which tells Apache that execution of CGI programs is - permitted in this directory.

-
- -

Writing a CGI program

- -

There are two main differences between ``regular'' - programming, and CGI programming.

- -

First, all output from your CGI program must be preceded by - a MIME-type header. This is HTTP header that tells the client - what sort of content it is receiving. Most of the time, this - will look like:

-
-        Content-type: text/html
-
- -

Secondly, your output needs to be in HTML, or some other - format that a browser will be able to display. Most of the - time, this will be HTML, but occasionally you might write a CGI - program that outputs a gif image, or other non-HTML - content.

- -

Apart from those two things, writing a CGI program will look - a lot like any other program that you might write.

- -

Your - first CGI program

- -

The following is an example CGI program that prints one line - to your browser. Type in the following, save it to a file - called first.pl, and put it in your - cgi-bin directory.

-
-        #!/usr/bin/perl
-        print "Content-type: text/html\r\n\r\n";
-        print "Hello, World.";
-
- -

Even if you are not familiar with Perl, you should be able - to see what is happening here. The first line tells Apache (or - whatever shell you happen to be running under) that this - program can be executed by feeding the file to the interpreter - found at the location /usr/bin/perl. The second - line prints the content-type declaration we talked about, - followed by two carriage-return newline pairs. This puts a - blank line after the header, to indicate the end of the HTTP - headers, and the beginning of the body. The third line prints - the string ``Hello, World.'' And that's the end of it.

- -

If you open your favorite browser and tell it to get the - address

-
-        http://www.example.com/cgi-bin/first.pl
-
- -

or wherever you put your file, you will see the one line - Hello, World. appear in your browser window. It's - not very exciting, but once you get that working, you'll have a - good chance of getting just about anything working.

-
- -

But it's still not - working!

- -

There are four basic things that you may see in your browser - when you try to access your CGI program from the web:

- -
-
The output of your CGI program
- -
Great! That means everything worked fine.
-
-
- -
The source code of your CGI program or a "POST Method Not - Allowed" message
- -
That means that you have not properly configured Apache - to process your CGI program. Reread the section on configuring Apache - and try to find what you missed.
-
-
- -
A message starting with "Forbidden"
- -
That means that there is a permissions problem. Check the - Apache error log and the section - below on file - permissions.
-
-
- -
A message saying "Internal Server Error"
- -
If you check the Apache error - log, you will probably find that it says "Premature end - of script headers", possibly along with an error message - generated by your CGI program. In this case, you will want to - check each of the below sections to see what might be - preventing your CGI program from emitting the proper HTTP - headers.
-
- -

File - permissions

- -

Remember that the server does not run as you. That is, when - the server starts up, it is running with the permissions of an - unprivileged user - usually ``nobody'', or ``www'' - and so it - will need extra permissions to execute files that are owned by - you. Usually, the way to give a file sufficient permissions to - be executed by ``nobody'' is to give everyone execute - permission on the file:

-
-        chmod a+x first.pl
-
- -

Also, if your program reads from, or writes to, any other - files, those files will need to have the correct permissions to - permit this.

- -

The exception to this is when the server is configured to - use suexec. This program allows - CGI programs to be run under different user permissions, - depending on which virtual host or user home directory they are - located in. Suexec has very strict permission checking, and any - failure in that checking will result in your CGI programs - failing with an "Internal Server Error". In this case, you will - need to check the suexec log file to see what specific security - check is failing.

- -

Path - information

- -

When you run a program from your command line, you have - certain information that is passed to the shell without you - thinking about it. For example, you have a path, which tells - the shell where it can look for files that you reference.

- -

When a program runs through the web server as a CGI program, - it does not have that path. Any programs that you invoke in - your CGI program (like 'sendmail', for example) will need to be - specified by a full path, so that the shell can find them when - it attempts to execute your CGI program.

- -

A common manifestation of this is the path to the script - interpreter (often perl) indicated in the first - line of your CGI program, which will look something like:

-
-     #!/usr/bin/perl
-
- -

Make sure that this is in fact the path to the - interpreter.

- -

Syntax - errors

- -

Most of the time when a CGI program fails, it's because of a - problem with the program itself. This is particularly true once - you get the hang of this CGI stuff, and no longer make the - above two mistakes. Always attempt to run your program from the - command line before you test if via a browser. This will - eliminate most of your problems.

- -

Error logs

- -

The error logs are your friend. Anything that goes wrong - generates message in the error log. You should always look - there first. If the place where you are hosting your web site - does not permit you access to the error log, you should - probably host your site somewhere else. Learn to read the error - logs, and you'll find that almost all of your problems are - quickly identified, and quickly solved.

-
- -

What's going on behind the - scenes?

- -

As you become more advanced in CGI programming, it will - become useful to understand more about what's happening behind - the scenes. Specifically, how the browser and server - communicate with one another. Because although it's all very - well to write a program that prints ``Hello, World.'', it's not - particularly useful.

- -

Environment variables

- -

Environment variables are values that float around you as - you use your computer. They are useful things like your path - (where the computer searches for a the actual file implementing - a command when you type it), your username, your terminal type, - and so on. For a full list of your normal, every day - environment variables, type env at a command - prompt.

- -

During the CGI transaction, the server and the browser also - set environment variables, so that they can communicate with - one another. These are things like the browser type (Netscape, - IE, Lynx), the server type (Apache, IIS, WebSite), the name of - the CGI program that is being run, and so on.

- -

These variables are available to the CGI programmer, and are - half of the story of the client-server communication. The - complete list of required variables is at http://hoohoo.ncsa.uiuc.edu/cgi/env.html

- -

This simple Perl CGI program will display all of the - environment variables that are being passed around. Two similar - programs are included in the cgi-bin directory of - the Apache distribution. Note that some variables are required, - while others are optional, so you may see some variables listed - that were not in the official list. In addition, Apache - provides many different ways for you to add your own environment variables to - the basic ones provided by default.

-
-     #!/usr/bin/perl
-     print "Content-type: text/html\n\n";
-     foreach $key (keys %ENV) {
-          print "$key --> $ENV{$key}<br>";
-     }
-
- -

STDIN and - STDOUT

- -

Other communication between the server and the client - happens over standard input (STDIN) and standard - output (STDOUT). In normal everyday context, - STDIN means the keyboard, or a file that a program - is given to act on, and STDOUT usually means the - console or screen.

- -

When you POST a web form to a CGI program, the - data in that form is bundled up into a special format and gets - delivered to your CGI program over STDIN. The - program then can process that data as though it was coming in - from the keyboard, or from a file

- -

The ``special format'' is very simple. A field name and its - value are joined together with an equals (=) sign, and pairs of - values are joined together with an ampersand (&). - Inconvenient characters like spaces, ampersands, and equals - signs, are converted into their hex equivalent so that they - don't gum up the works. The whole data string might look - something like:

-
-     name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey
-
- -

You'll sometimes also see this type of string appended to - the a URL. When that is done, the server puts that string into - the environment variable called QUERY_STRING. - That's called a GET request. Your HTML form - specifies whether a GET or a POST is - used to deliver the data, by setting the METHOD - attribute in the FORM tag.

- -

Your program is then responsible for splitting that string - up into useful information. Fortunately, there are libraries - and modules available to help you process this data, as well as - handle other of the aspects of your CGI program.

-
- -

CGI - modules/libraries

- -

When you write CGI programs, you should consider using a - code library, or module, to do most of the grunt work for you. - This leads to fewer errors, and faster development.

- -

If you're writing CGI programs in Perl, modules are - available on CPAN. The most - popular module for this purpose is CGI.pm. You might also - consider CGI::Lite, which implements a minimal set of - functionality, which is all you need in most programs.

- -

If you're writing CGI programs in C, there are a variety of - options. One of these is the CGIC library, from http://www.boutell.com/cgic/

-
- -

For - more information

- -

There are a large number of CGI resources on the web. You - can discuss CGI problems with other users on the Usenet group - comp.infosystems.www.authoring.cgi. And the -servers mailing - list from the HTML Writers Guild is a great source of answers - to your questions. You can find out more at http://www.hwg.org/lists/hwg-servers/

- -

And, of course, you should probably read the CGI - specification, which has all the details on the operation of - CGI programs. You can find the original version at the NCSA - and there is an updated draft at the Common Gateway Interface - RFC project.

- -

When you post a question about a CGI problem that you're - having, whether to a mailing list, or to a newsgroup, make sure - you provide enough information about what happened, what you - expected to happen, and how what actually happened was - different, what server you're running, what language your CGI - program was in, and, if possible, the offending code. This will - make finding your problem much simpler.

- -

Note that questions about CGI problems should - never be posted to the Apache bug database - unless you are sure you have found a problem in the Apache - source code.

-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/howto/ssi.html b/usr.sbin/httpd/htdocs/manual/howto/ssi.html new file mode 100644 index 00000000000..2da0dab0dfe --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/howto/ssi.html @@ -0,0 +1,558 @@ + + + + + + + + Apache Tutorial: Introduction to Server Side + Includes + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + + +

Apache Tutorial: Introduction to Server Side + Includes

+ + + + + +
+ +

Apache + Tutorial: Introduction to Server Side Includes

+ + + + + + + +
Related Modules
+
+ mod_include
+ mod_cgi
+ mod_expires
+ 		Related Directives
+
+ Options
+ XBitHack
+ AddType
+ AddHandler
+ BrowserMatchNoCase
+
+ +

This article deals with Server Side Includes, usually called + simply SSI. In this article, I'll talk about configuring your + server to permit SSI, and introduce some basic SSI techniques + for adding dynamic content to your existing HTML pages.

+ +

In the latter part of the article, we'll talk about some of + the somewhat more advanced things that can be done with SSI, + such as conditional statements in your SSI directives.

+
+ +

What are SSI?

+ +

SSI (Server Side Includes) are directives that are placed in + HTML pages, and evaluated on the server while the pages are + being served. They let you add dynamically generated content to + an existing HTML page, without having to serve the entire page + via a CGI program, or other dynamic technology.

+ +

The decision of when to use SSI, and when to have your page + entirely generated by some program, is usually a matter of how + much of the page is static, and how much needs to be + recalculated every time the page is served. SSI is a great way + to add small pieces of information, such as the current time. + But if a majority of your page is being generated at the time + that it is served, you need to look for some other + solution.

+
+ +

Configuring your server + to permit SSI

+ +

To permit SSI on your server, you must have mod_include installed and + enabled. Additionally, you must have the following + directive either in your httpd.conf file, or in a + .htaccess file:

+
+        Options +Includes
+
+ +

This tells Apache that you want to permit files to be parsed + for SSI directives. Note that most configurations contain + multiple Options directives + that can override each other. You will probably need to apply the + Options to the specific directory where you want SSI + enabled in order to assure that it gets evaluated last.

+ +

Not just any file is parsed for SSI directives. You have to + tell Apache which files should be parsed. There are two ways to + do this. You can tell Apache to parse any file with a + particular file extension, such as .shtml, with + the following directives:

+
+        AddType text/html .shtml
+        AddHandler server-parsed .shtml
+
+ +

One disadvantage to this approach is that if you wanted to + add SSI directives to an existing page, you would have to + change the name of that page, and all links to that page, in + order to give it a .shtml extension, so that those + directives would be executed.

+ +

The other method is to use the XBitHack + directive:

+
+        XBitHack on
+
+ +

XBitHack tells Apache to parse files for SSI + directives if they have the execute bit set. So, to add SSI + directives to an existing page, rather than having to change + the file name, you would just need to make the file executable + using chmod.

+
+        chmod +x pagename.html
+
+ +

A brief comment about what not to do. You'll occasionally + see people recommending that you just tell Apache to parse all + .html files for SSI, so that you don't have to + mess with .shtml file names. These folks have + perhaps not heard about XBitHack. The thing to + keep in mind is that, by doing this, you're requiring that + Apache read through every single file that it sends out to + clients, even if they don't contain any SSI directives. This + can slow things down quite a bit, and is not a good idea.

+ +

Of course, on Windows, there is no such thing as an execute + bit to set, so that limits your options a little.

+ +

In its default configuration, Apache does not send the last + modified date or content length HTTP headers on SSI pages, + because these values are difficult to calculate for dynamic + content. This can prevent your document from being cached, and + result in slower perceived client performance. There are two + ways to solve this:

+ +
    +
  1. Use the XBitHack Full configuration. This + tells Apache to determine the last modified date by looking + only at the date of the originally requested file, ignoring + the modification date of any included files.
    2. + +
  2. Use the directives provided by mod_expires to set an + explicit expiration time on your files, thereby letting + browsers and proxies know that it is acceptable to cache + them.
    3. +
+
+ +

Basic + SSI directives

+ +

SSI directives have the following syntax:

+
+        <!--#element attribute=value attribute=value ... -->
+
+ +

It is formatted like an HTML comment, so if you don't have + SSI correctly enabled, the browser will ignore it, but it will + still be visible in the HTML source. If you have SSI correctly + configured, the directive will be replaced with its + results.

+ +

The element can be one of a number of things, and we'll talk + some more about most of these in the next installment of this + series. For now, here are some examples of what you can do with + SSI

+ +

Today's + date

+
+        <!--#echo var="DATE_LOCAL" -->
+
+ +

The echo element just spits out the value of a + variable. There are a number of standard variables, which + include the whole set of environment variables that are + available to CGI programs. Also, you can define your own + variables with the set element.

+ +

If you don't like the format in which the date gets printed, + you can use the config element, with a + timefmt attribute, to modify that formatting.

+
+        <!--#config timefmt="%A %B %d, %Y" -->
+        Today is <!--#echo var="DATE_LOCAL" -->
+
+ +

Modification date of the + file

+
+        This document last modified <!--#flastmod file="index.html" -->
+
+ +

This element is also subject to timefmt format + configurations.

+ +

Including the results + of a CGI program

+ +

This is one of the more common uses of SSI - to output the + results of a CGI program, such as everybody's favorite, a ``hit + counter.''

+
+        <!--#include virtual="/cgi-bin/counter.pl" -->
+
+
+ +

Additional examples

+ +

Following are some specific examples of things you can do in + your HTML documents with SSI.

+
+ +

When was this document + modified?

+ +

Earlier, we mentioned that you could use SSI to inform the + user when the document was most recently modified. However, the + actual method for doing that was left somewhat in question. The + following code, placed in your HTML document, will put such a + time stamp on your page. Of course, you will have to have SSI + correctly enabled, as discussed above.

+
+        <!--#config timefmt="%A %B %d, %Y" -->
+        This file last modified <!--#flastmod file="ssi.shtml" -->
+
+ +

Of course, you will need to replace the + ssi.shtml with the actual name of the file that + you're referring to. This can be inconvenient if you're just + looking for a generic piece of code that you can paste into any + file, so you probably want to use the + LAST_MODIFIED variable instead:

+
+        <!--#config timefmt="%D" -->
+        This file last modified <!--#echo var="LAST_MODIFIED" -->
+
+ +

For more details on the timefmt format, go to + your favorite search site and look for strftime(). The + syntax is the same.

+
+ +

Including a standard + footer

+ +

If you are managing any site that is more than a few pages, + you may find that making changes to all those pages can be a + real pain, particularly if you are trying to maintain some kind + of standard look across all those pages.

+ +

Using an include file for a header and/or a footer can + reduce the burden of these updates. You just have to make one + footer file, and then include it into each page with the + include SSI command. The include + element can determine what file to include with either the + file attribute, or the virtual + attribute. The file attribute is a file path, + relative to the current directory. That means that it + cannot be an absolute file path (starting with /), nor can it + contain ../ as part of that path. The virtual + attribute is probably more useful, and should specify a URL + relative to the document being served. It can start with a /, + but must be on the same server as the file being served.

+
+        <!--#include virtual="/footer.html" -->
+
+ +

I'll frequently combine the last two things, putting a + LAST_MODIFIED directive inside a footer file to be + included. SSI directives can be contained in the included file, + and includes can be nested - that is, the included file can + include another file, and so on.

+
+ +

What + else can I config?

+ +

In addition to being able to config the time + format, you can also config two other things.

+ +

Usually, when something goes wrong with your SSI directive, + you get the message

+
+        [an error occurred while processing this directive]
+
+ +

If you want to change that message to something else, you + can do so with the errmsg attribute to the + config element:

+
+        <!--#config errmsg="[It appears that you don't know how to use SSI]" -->
+
+ +

Hopefully, end users will never see this message, because + you will have resolved all the problems with your SSI + directives before your site goes live. (Right?)

+ +

And you can config the format in which file + sizes are returned with the sizefmt attribute. You + can specify bytes for a full count in bytes, or + abbrev for an abbreviated number in Kb or Mb, as + appropriate.

+
+ +

Executing commands

+ +

I expect that I'll have an article some time in the coming + months about using SSI with small CGI programs. For now, here's + something else that you can do with the exec + element. You can actually have SSI execute a command using the + shell (/bin/sh, to be precise - or the DOS shell, + if you're on Win32). The following, for example, will give you + a directory listing.

+
+        <pre>
+        <!--#exec cmd="ls" -->
+        </pre>
+
+ +

or, on Windows

+
+        <pre>
+        <!--#exec cmd="dir" -->
+        </pre>
+
+ +

You might notice some strange formatting with this directive + on Windows, because the output from dir contains + the string ``<dir>'' in it, which confuses + browsers.

+ +

Note that this feature is exceedingly dangerous, as it will + execute whatever code happens to be embedded in the + exec tag. If you have any situation where users + can edit content on your web pages, such as with a + ``guestbook'', for example, make sure that you have this + feature disabled. You can allow SSI, but not the + exec feature, with the IncludesNOEXEC + argument to the Options directive.

+
+ +

Advanced SSI techniques

+ +

In addition to spitting out content, Apache SSI gives you + the option of setting variables, and using those variables in + comparisons and conditionals.

+ +

Caveat

+ +

Most of the features discussed in this article are only + available to you if you are running Apache 1.2 or later. Of + course, if you are not running Apache 1.2 or later, you need to + upgrade immediately, if not sooner. Go on. Do it now. We'll + wait.

+
+ +

Setting + variables

+ +

Using the set directive, you can set variables + for later use. We'll need this later in the discussion, so + we'll talk about it here. The syntax of this is as follows:

+
+        <!--#set var="name" value="Rich" -->
+
+ +

In addition to merely setting values literally like that, + you can use any other variable, including, for example, + environment variables, or some of the variables we discussed in + the last article (like LAST_MODIFIED, for example) + to give values to your variables. You will specify that + something is a variable, rather than a literal string, by using + the dollar sign ($) before the name of the variable.

+
+        <!--#set var="modified" value="$LAST_MODIFIED" -->
+
+ +

To put a literal dollar sign into the value of your + variable, you need to escape the dollar sign with a + backslash.

+
+        <!--#set var="cost" value="\$100" -->
+
+ +

Finally, if you want to put a variable in the midst of a + longer string, and there's a chance that the name of the + variable will run up against some other characters, and thus be + confused with those characters, you can place the name of the + variable in braces, to remove this confusion. (It's hard to + come up with a really good example of this, but hopefully + you'll get the point.)

+
+        <!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->
+
+
+ +

Conditional expressions

+ +

Now that we have variables, and are able to set and compare + their values, we can use them to express conditionals. This + lets SSI be a tiny programming language of sorts. + mod_include provides an if, + elif, else, endif + structure for building conditional statements. This allows you + to effectively generate multiple logical pages out of one + actual page.

+ +

The structure of this conditional construct is:

+
+        <!--#if expr="test_condition" -->
+    <!--#elif expr="test_condition" -->
+    <!--#else -->
+    <!--#endif -->
+
+ +

A test_condition can be any sort of logical + comparison - either comparing values to one another, or testing + the ``truth'' of a particular value. (A given string is true if + it is nonempty.) For a full list of the comparison operators + available to you, see the mod_include + documentation. Here are some examples of how one might use this + construct.

+ +

In your configuration file, you could put the following + line:

+
+        BrowserMatchNoCase macintosh Mac
+        BrowserMatchNoCase MSIE InternetExplorer
+
+ +

This will set environment variables ``Mac'' and + ``InternetExplorer'' to true, if the client is running Internet + Explorer on a Macintosh.

+ +

Then, in your SSI-enabled document, you might do the + following:

+
+        <!--#if expr="${Mac} && ${InternetExplorer}" -->
+        Apologetic text goes here
+        <!--#else -->
+        Cool JavaScript code goes here
+        <!--#endif -->
+
+ +

Not that I have anything against IE on Macs - I just + struggled for a few hours last week trying to get some + JavaScript working on IE on a Mac, when it was working + everywhere else. The above was the interim workaround.

+ +

Any other variable (either ones that you define, or normal + environment variables) can be used in conditional statements. + With Apache's ability to set environment variables with the + SetEnvIf directives, and other related directives, + this functionality can let you do some pretty involved dynamic + stuff without ever resorting to CGI.

+
+ +

Conclusion

+ +

SSI is certainly not a replacement for CGI, or other + technologies used for generating dynamic web pages. But it is a + great way to add small amounts of dynamic content to pages, + without doing a lot of extra work.

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/howto/ssi.html.html b/usr.sbin/httpd/htdocs/manual/howto/ssi.html.html deleted file mode 100644 index 2da0dab0dfe..00000000000 --- a/usr.sbin/httpd/htdocs/manual/howto/ssi.html.html +++ /dev/null @@ -1,558 +0,0 @@ - - - - - - - - Apache Tutorial: Introduction to Server Side - Includes - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - - -

Apache Tutorial: Introduction to Server Side - Includes

- - - - - -
- -

Apache - Tutorial: Introduction to Server Side Includes

- - - - - - - -
Related Modules
-
- mod_include
- mod_cgi
- mod_expires
- 		Related Directives
-
- Options
- XBitHack
- AddType
- AddHandler
- BrowserMatchNoCase
-
- -

This article deals with Server Side Includes, usually called - simply SSI. In this article, I'll talk about configuring your - server to permit SSI, and introduce some basic SSI techniques - for adding dynamic content to your existing HTML pages.

- -

In the latter part of the article, we'll talk about some of - the somewhat more advanced things that can be done with SSI, - such as conditional statements in your SSI directives.

-
- -

What are SSI?

- -

SSI (Server Side Includes) are directives that are placed in - HTML pages, and evaluated on the server while the pages are - being served. They let you add dynamically generated content to - an existing HTML page, without having to serve the entire page - via a CGI program, or other dynamic technology.

- -

The decision of when to use SSI, and when to have your page - entirely generated by some program, is usually a matter of how - much of the page is static, and how much needs to be - recalculated every time the page is served. SSI is a great way - to add small pieces of information, such as the current time. - But if a majority of your page is being generated at the time - that it is served, you need to look for some other - solution.

-
- -

Configuring your server - to permit SSI

- -

To permit SSI on your server, you must have mod_include installed and - enabled. Additionally, you must have the following - directive either in your httpd.conf file, or in a - .htaccess file:

-
-        Options +Includes
-
- -

This tells Apache that you want to permit files to be parsed - for SSI directives. Note that most configurations contain - multiple Options directives - that can override each other. You will probably need to apply the - Options to the specific directory where you want SSI - enabled in order to assure that it gets evaluated last.

- -

Not just any file is parsed for SSI directives. You have to - tell Apache which files should be parsed. There are two ways to - do this. You can tell Apache to parse any file with a - particular file extension, such as .shtml, with - the following directives:

-
-        AddType text/html .shtml
-        AddHandler server-parsed .shtml
-
- -

One disadvantage to this approach is that if you wanted to - add SSI directives to an existing page, you would have to - change the name of that page, and all links to that page, in - order to give it a .shtml extension, so that those - directives would be executed.

- -

The other method is to use the XBitHack - directive:

-
-        XBitHack on
-
- -

XBitHack tells Apache to parse files for SSI - directives if they have the execute bit set. So, to add SSI - directives to an existing page, rather than having to change - the file name, you would just need to make the file executable - using chmod.

-
-        chmod +x pagename.html
-
- -

A brief comment about what not to do. You'll occasionally - see people recommending that you just tell Apache to parse all - .html files for SSI, so that you don't have to - mess with .shtml file names. These folks have - perhaps not heard about XBitHack. The thing to - keep in mind is that, by doing this, you're requiring that - Apache read through every single file that it sends out to - clients, even if they don't contain any SSI directives. This - can slow things down quite a bit, and is not a good idea.

- -

Of course, on Windows, there is no such thing as an execute - bit to set, so that limits your options a little.

- -

In its default configuration, Apache does not send the last - modified date or content length HTTP headers on SSI pages, - because these values are difficult to calculate for dynamic - content. This can prevent your document from being cached, and - result in slower perceived client performance. There are two - ways to solve this:

- -
    -
  1. Use the XBitHack Full configuration. This - tells Apache to determine the last modified date by looking - only at the date of the originally requested file, ignoring - the modification date of any included files.
    2. - -
  2. Use the directives provided by mod_expires to set an - explicit expiration time on your files, thereby letting - browsers and proxies know that it is acceptable to cache - them.
    3. -
-
- -

Basic - SSI directives

- -

SSI directives have the following syntax:

-
-        <!--#element attribute=value attribute=value ... -->
-
- -

It is formatted like an HTML comment, so if you don't have - SSI correctly enabled, the browser will ignore it, but it will - still be visible in the HTML source. If you have SSI correctly - configured, the directive will be replaced with its - results.

- -

The element can be one of a number of things, and we'll talk - some more about most of these in the next installment of this - series. For now, here are some examples of what you can do with - SSI

- -

Today's - date

-
-        <!--#echo var="DATE_LOCAL" -->
-
- -

The echo element just spits out the value of a - variable. There are a number of standard variables, which - include the whole set of environment variables that are - available to CGI programs. Also, you can define your own - variables with the set element.

- -

If you don't like the format in which the date gets printed, - you can use the config element, with a - timefmt attribute, to modify that formatting.

-
-        <!--#config timefmt="%A %B %d, %Y" -->
-        Today is <!--#echo var="DATE_LOCAL" -->
-
- -

Modification date of the - file

-
-        This document last modified <!--#flastmod file="index.html" -->
-
- -

This element is also subject to timefmt format - configurations.

- -

Including the results - of a CGI program

- -

This is one of the more common uses of SSI - to output the - results of a CGI program, such as everybody's favorite, a ``hit - counter.''

-
-        <!--#include virtual="/cgi-bin/counter.pl" -->
-
-
- -

Additional examples

- -

Following are some specific examples of things you can do in - your HTML documents with SSI.

-
- -

When was this document - modified?

- -

Earlier, we mentioned that you could use SSI to inform the - user when the document was most recently modified. However, the - actual method for doing that was left somewhat in question. The - following code, placed in your HTML document, will put such a - time stamp on your page. Of course, you will have to have SSI - correctly enabled, as discussed above.

-
-        <!--#config timefmt="%A %B %d, %Y" -->
-        This file last modified <!--#flastmod file="ssi.shtml" -->
-
- -

Of course, you will need to replace the - ssi.shtml with the actual name of the file that - you're referring to. This can be inconvenient if you're just - looking for a generic piece of code that you can paste into any - file, so you probably want to use the - LAST_MODIFIED variable instead:

-
-        <!--#config timefmt="%D" -->
-        This file last modified <!--#echo var="LAST_MODIFIED" -->
-
- -

For more details on the timefmt format, go to - your favorite search site and look for strftime(). The - syntax is the same.

-
- -

Including a standard - footer

- -

If you are managing any site that is more than a few pages, - you may find that making changes to all those pages can be a - real pain, particularly if you are trying to maintain some kind - of standard look across all those pages.

- -

Using an include file for a header and/or a footer can - reduce the burden of these updates. You just have to make one - footer file, and then include it into each page with the - include SSI command. The include - element can determine what file to include with either the - file attribute, or the virtual - attribute. The file attribute is a file path, - relative to the current directory. That means that it - cannot be an absolute file path (starting with /), nor can it - contain ../ as part of that path. The virtual - attribute is probably more useful, and should specify a URL - relative to the document being served. It can start with a /, - but must be on the same server as the file being served.

-
-        <!--#include virtual="/footer.html" -->
-
- -

I'll frequently combine the last two things, putting a - LAST_MODIFIED directive inside a footer file to be - included. SSI directives can be contained in the included file, - and includes can be nested - that is, the included file can - include another file, and so on.

-
- -

What - else can I config?

- -

In addition to being able to config the time - format, you can also config two other things.

- -

Usually, when something goes wrong with your SSI directive, - you get the message

-
-        [an error occurred while processing this directive]
-
- -

If you want to change that message to something else, you - can do so with the errmsg attribute to the - config element:

-
-        <!--#config errmsg="[It appears that you don't know how to use SSI]" -->
-
- -

Hopefully, end users will never see this message, because - you will have resolved all the problems with your SSI - directives before your site goes live. (Right?)

- -

And you can config the format in which file - sizes are returned with the sizefmt attribute. You - can specify bytes for a full count in bytes, or - abbrev for an abbreviated number in Kb or Mb, as - appropriate.

-
- -

Executing commands

- -

I expect that I'll have an article some time in the coming - months about using SSI with small CGI programs. For now, here's - something else that you can do with the exec - element. You can actually have SSI execute a command using the - shell (/bin/sh, to be precise - or the DOS shell, - if you're on Win32). The following, for example, will give you - a directory listing.

-
-        <pre>
-        <!--#exec cmd="ls" -->
-        </pre>
-
- -

or, on Windows

-
-        <pre>
-        <!--#exec cmd="dir" -->
-        </pre>
-
- -

You might notice some strange formatting with this directive - on Windows, because the output from dir contains - the string ``<dir>'' in it, which confuses - browsers.

- -

Note that this feature is exceedingly dangerous, as it will - execute whatever code happens to be embedded in the - exec tag. If you have any situation where users - can edit content on your web pages, such as with a - ``guestbook'', for example, make sure that you have this - feature disabled. You can allow SSI, but not the - exec feature, with the IncludesNOEXEC - argument to the Options directive.

-
- -

Advanced SSI techniques

- -

In addition to spitting out content, Apache SSI gives you - the option of setting variables, and using those variables in - comparisons and conditionals.

- -

Caveat

- -

Most of the features discussed in this article are only - available to you if you are running Apache 1.2 or later. Of - course, if you are not running Apache 1.2 or later, you need to - upgrade immediately, if not sooner. Go on. Do it now. We'll - wait.

-
- -

Setting - variables

- -

Using the set directive, you can set variables - for later use. We'll need this later in the discussion, so - we'll talk about it here. The syntax of this is as follows:

-
-        <!--#set var="name" value="Rich" -->
-
- -

In addition to merely setting values literally like that, - you can use any other variable, including, for example, - environment variables, or some of the variables we discussed in - the last article (like LAST_MODIFIED, for example) - to give values to your variables. You will specify that - something is a variable, rather than a literal string, by using - the dollar sign ($) before the name of the variable.

-
-        <!--#set var="modified" value="$LAST_MODIFIED" -->
-
- -

To put a literal dollar sign into the value of your - variable, you need to escape the dollar sign with a - backslash.

-
-        <!--#set var="cost" value="\$100" -->
-
- -

Finally, if you want to put a variable in the midst of a - longer string, and there's a chance that the name of the - variable will run up against some other characters, and thus be - confused with those characters, you can place the name of the - variable in braces, to remove this confusion. (It's hard to - come up with a really good example of this, but hopefully - you'll get the point.)

-
-        <!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->
-
-
- -

Conditional expressions

- -

Now that we have variables, and are able to set and compare - their values, we can use them to express conditionals. This - lets SSI be a tiny programming language of sorts. - mod_include provides an if, - elif, else, endif - structure for building conditional statements. This allows you - to effectively generate multiple logical pages out of one - actual page.

- -

The structure of this conditional construct is:

-
-        <!--#if expr="test_condition" -->
-    <!--#elif expr="test_condition" -->
-    <!--#else -->
-    <!--#endif -->
-
- -

A test_condition can be any sort of logical - comparison - either comparing values to one another, or testing - the ``truth'' of a particular value. (A given string is true if - it is nonempty.) For a full list of the comparison operators - available to you, see the mod_include - documentation. Here are some examples of how one might use this - construct.

- -

In your configuration file, you could put the following - line:

-
-        BrowserMatchNoCase macintosh Mac
-        BrowserMatchNoCase MSIE InternetExplorer
-
- -

This will set environment variables ``Mac'' and - ``InternetExplorer'' to true, if the client is running Internet - Explorer on a Macintosh.

- -

Then, in your SSI-enabled document, you might do the - following:

-
-        <!--#if expr="${Mac} && ${InternetExplorer}" -->
-        Apologetic text goes here
-        <!--#else -->
-        Cool JavaScript code goes here
-        <!--#endif -->
-
- -

Not that I have anything against IE on Macs - I just - struggled for a few hours last week trying to get some - JavaScript working on IE on a Mac, when it was working - everywhere else. The above was the interim workaround.

- -

Any other variable (either ones that you define, or normal - environment variables) can be used in conditional statements. - With Apache's ability to set environment variables with the - SetEnvIf directives, and other related directives, - this functionality can let you do some pretty involved dynamic - stuff without ever resorting to CGI.

-
- -

Conclusion

- -

SSI is certainly not a replacement for CGI, or other - technologies used for generating dynamic web pages. But it is a - great way to add small amounts of dynamic content to pages, - without doing a lot of extra work.

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/index.html b/usr.sbin/httpd/htdocs/manual/index.html new file mode 100644 index 00000000000..e19b0ebe715 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/index.html @@ -0,0 +1,286 @@ + + + + + + + + Apache HTTP Server Version 1.3 Documentation + + + +
+ + + + + + + + + + + + + + + + +
[Apache Documentation]
+ + + + + + + + + + + + +
FAQ SiteMapDirectives + Modules Search +
+
 
+

Apache HTTP Server Version 1.3

+
+
+ +
+ + + + +
+
+ +
+
+ + + + + + + + + +
+ + + + + + + + +
+ Miscellaneous information
Apache License
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Reference Manual
Starting
Stopping or + Restarting
Run-time + Configuration Directives
Modules: By + Type or Alphabetical
Server and Supporting + Programs
Dynamic Shared Object (DSO) + Support
The Apache API +
+ + + + + + +
+ Platform Specific Notes
+ 		+ + + + +
.
+ 		+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Using + the Apache HTTP Server
Authentication, + Authorization, and Access Control
CGI: Dynamic Content with + CGI
Configuration + Files
Content + negotiation
Environment Variables +
General + Performance hints
Handlers
Log Files
Security + tips
Server Side + Includes
Server-Wide + Configuration
suexec: Using SetUserID Execution + for CGI
URL Mapping: Mapping + URLs to the Filesystem
URL Rewriting + Guide
Virtual Hosts +
+ + + + + + + + + + + + + + + + + + + + + +
Other + Topics
Frequently Asked + Questions
SiteMap +
Tutorials +
Other Notes
+
+
+
+
+ +

Maintained by the Apache HTTP Server + Documentation Project.

+
+ +

Apache HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/index.html.html b/usr.sbin/httpd/htdocs/manual/index.html.html deleted file mode 100644 index e19b0ebe715..00000000000 --- a/usr.sbin/httpd/htdocs/manual/index.html.html +++ /dev/null @@ -1,286 +0,0 @@ - - - - - - - - Apache HTTP Server Version 1.3 Documentation - - - -
- - - - - - - - - - - - - - - - -
[Apache Documentation]
- - - - - - - - - - - - -
FAQ SiteMapDirectives - Modules Search -
-
 
-

Apache HTTP Server Version 1.3

-
-
- -
- - - - -
-
- -
-
- - - - - - - - - -
- - - - - - - - -
- Miscellaneous information
Apache License
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Reference Manual
Starting
Stopping or - Restarting
Run-time - Configuration Directives
Modules: By - Type or Alphabetical
Server and Supporting - Programs
Dynamic Shared Object (DSO) - Support
The Apache API -
- - - - - - -
- Platform Specific Notes
- 		- - - - -
.
- 		- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Using - the Apache HTTP Server
Authentication, - Authorization, and Access Control
CGI: Dynamic Content with - CGI
Configuration - Files
Content - negotiation
Environment Variables -
General - Performance hints
Handlers
Log Files
Security - tips
Server Side - Includes
Server-Wide - Configuration
suexec: Using SetUserID Execution - for CGI
URL Mapping: Mapping - URLs to the Filesystem
URL Rewriting - Guide
Virtual Hosts -
- - - - - - - - - - - - - - - - - - - - - -
Other - Topics
Frequently Asked - Questions
SiteMap -
Tutorials -
Other Notes
-
-
-
-
- -

Maintained by the Apache HTTP Server - Documentation Project.

-
- -

Apache HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/invoking.html b/usr.sbin/httpd/htdocs/manual/invoking.html new file mode 100644 index 00000000000..a8967264149 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/invoking.html @@ -0,0 +1,148 @@ + + + + + + + + Starting Apache + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Starting Apache

+ + +
+ +

Starting Apache on Unix

+ +

On Unix, the httpd program + is run as a daemon which executes continuously in the + background to handle requests. It is possible to have Apache + invoked by the Internet daemon inetd each time a + connection to the HTTP service is made using the ServerType directive, but + this is not recommended.

+ +

If the Port specified in + the configuration file is the default of 80 (or any other port + below 1024), then it is necessary to have root privileges in + order to start Apache, so that it can bind to this privileged + port. Once the server has started and completed a few + preliminary activities such as opening its log files, it will + launch several child processes which do the work of + listening for and answering requests from clients. The main + httpd process continues to run as the root user, + but the child processes run as a less privileged user. This is + controlled by Apache's process creation + directives.

+ +

The first thing that httpd does when it is + invoked is to locate and read the configuration file + httpd.conf. The location of this file is set at + compile-time, but it is possible to specify its location at run + time using the -f command-line option as in

+ +
+ /usr/local/apache/bin/httpd -f + /usr/local/apache/conf/httpd.conf +
+ +

As an alternative to invoking the httpd binary + directly, a shell script called apachectl is provided which + can be used to control the daemon process with simple commands + such as apachectl start and apachectl + stop.

+ +

If all goes well during startup, the server will detach from + the terminal and the command prompt will return almost + immediately. This indicates that the server is up and running. + You can then use your browser to connect to the server and view + the test page in the DocumentRoot directory + and the local copy of the documentation linked from that + page.

+ +

Errors During + Start-up

+ +

If Apache suffers a fatal problem during startup, it will + write a message describing the problem either to the console or + to the ErrorLog before + exiting. One of the most common error messages is "Unable + to bind to Port ...". This message is usually caused by + either:

+ + + +

For further trouble-shooting instructions, consult the + Apache FAQ.

+ +

Starting at Boot-Time

+ +

If you want your server to continue running after a system + reboot, you should add a call to httpd or + apachectl 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. The apachectl script is + designed so that it can often be linked directly as an init + script, but be sure to check the exact requirements of your + system.

+ +

Additional Information

+ +

Additional information about the command-line options of httpd and apachectl as well as other + support programs included with the server is available on the + Server and Supporting Programs page. + There is also documentation on all the modules included with the Apache distribution + and the directives that they + provide.

+
+ +

Apache HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/invoking.html.html b/usr.sbin/httpd/htdocs/manual/invoking.html.html deleted file mode 100644 index a8967264149..00000000000 --- a/usr.sbin/httpd/htdocs/manual/invoking.html.html +++ /dev/null @@ -1,148 +0,0 @@ - - - - - - - - Starting Apache - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Starting Apache

- - -
- -

Starting Apache on Unix

- -

On Unix, the httpd program - is run as a daemon which executes continuously in the - background to handle requests. It is possible to have Apache - invoked by the Internet daemon inetd each time a - connection to the HTTP service is made using the ServerType directive, but - this is not recommended.

- -

If the Port specified in - the configuration file is the default of 80 (or any other port - below 1024), then it is necessary to have root privileges in - order to start Apache, so that it can bind to this privileged - port. Once the server has started and completed a few - preliminary activities such as opening its log files, it will - launch several child processes which do the work of - listening for and answering requests from clients. The main - httpd process continues to run as the root user, - but the child processes run as a less privileged user. This is - controlled by Apache's process creation - directives.

- -

The first thing that httpd does when it is - invoked is to locate and read the configuration file - httpd.conf. The location of this file is set at - compile-time, but it is possible to specify its location at run - time using the -f command-line option as in

- -
- /usr/local/apache/bin/httpd -f - /usr/local/apache/conf/httpd.conf -
- -

As an alternative to invoking the httpd binary - directly, a shell script called apachectl is provided which - can be used to control the daemon process with simple commands - such as apachectl start and apachectl - stop.

- -

If all goes well during startup, the server will detach from - the terminal and the command prompt will return almost - immediately. This indicates that the server is up and running. - You can then use your browser to connect to the server and view - the test page in the DocumentRoot directory - and the local copy of the documentation linked from that - page.

- -

Errors During - Start-up

- -

If Apache suffers a fatal problem during startup, it will - write a message describing the problem either to the console or - to the ErrorLog before - exiting. One of the most common error messages is "Unable - to bind to Port ...". This message is usually caused by - either:

- - - -

For further trouble-shooting instructions, consult the - Apache FAQ.

- -

Starting at Boot-Time

- -

If you want your server to continue running after a system - reboot, you should add a call to httpd or - apachectl 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. The apachectl script is - designed so that it can often be linked directly as an init - script, but be sure to check the exact requirements of your - system.

- -

Additional Information

- -

Additional information about the command-line options of httpd and apachectl as well as other - support programs included with the server is available on the - Server and Supporting Programs page. - There is also documentation on all the modules included with the Apache distribution - and the directives that they - provide.

-
- -

Apache HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/keepalive.html b/usr.sbin/httpd/htdocs/manual/keepalive.html new file mode 100644 index 00000000000..c3a3018dcdb --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/keepalive.html @@ -0,0 +1,107 @@ + + + + + + + + Apache Keep-Alive Support + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Apache Keep-Alive Support

+
+ +

What is Keep-Alive?

+ The Keep-Alive extension to HTTP, as defined by the + HTTP/1.1 draft, allows persistent connections. + These long-lived HTTP sessions allow multiple requests to be + send over the same TCP connection, and in some cases have been + shown to result in an almost 50% speedup in latency times for + HTML documents with lots of images. + +

Enabling Keep-Alive Support

+ Apache 1.1 comes with Keep-Alive support on by default, however + there are some directives you can use to modify Apache's + behavior: + +

Note: Apache 1.2 uses a different syntax + for the KeepAlive + directive.

+ +

KeepAlive

+ Syntax: KeepAlive + max-requests
+ Default: KeepAlive + 5
+ Context: server config
+ Status: Core + +

This directive enables Keep-Alive support. Set + max-requests to the maximum number of requests you + want Apache to entertain per connection. A limit is imposed to + prevent a client from hogging your server resources. Set this + to 0 to disable support.

+ +

KeepAliveTimeout

+ Syntax: KeepAliveTimeout + seconds
+ Default: KeepAliveTimeout + 15
+ Context: server config
+ Status: Core + +

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.

+ +

When Keep-Alive Is Used

+ In order for Keep-Alive support to be used, first the browser + must support it. Many current browsers, including Netscape + Navigator 2.0, and Spyglass Mosaic-based browsers (including + Microsoft Internet Explorer) do. Note, however, that some + Windows 95-based browsers misbehave with Keep-Alive-supporting + servers; they may occasionally hang on a connect. This has been + observed with several Windows browsers, and occurs when + connecting to any Keep-Alive server, not just Apache. Netscape + 3.0b5 and later versions are known to work around this problem. + + +

However, Keep-Alive support only is active with files where + the length is known beforehand. This means that most CGI + scripts, server-side included files and directory listings will + not use the Keep-Alive protocol. While this should be + completely transparent to the end user, it is something the + web-master may want to keep in mind.

+
+ +

Apache HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/keepalive.html.html b/usr.sbin/httpd/htdocs/manual/keepalive.html.html deleted file mode 100644 index c3a3018dcdb..00000000000 --- a/usr.sbin/httpd/htdocs/manual/keepalive.html.html +++ /dev/null @@ -1,107 +0,0 @@ - - - - - - - - Apache Keep-Alive Support - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Apache Keep-Alive Support

-
- -

What is Keep-Alive?

- The Keep-Alive extension to HTTP, as defined by the - HTTP/1.1 draft, allows persistent connections. - These long-lived HTTP sessions allow multiple requests to be - send over the same TCP connection, and in some cases have been - shown to result in an almost 50% speedup in latency times for - HTML documents with lots of images. - -

Enabling Keep-Alive Support

- Apache 1.1 comes with Keep-Alive support on by default, however - there are some directives you can use to modify Apache's - behavior: - -

Note: Apache 1.2 uses a different syntax - for the KeepAlive - directive.

- -

KeepAlive

- Syntax: KeepAlive - max-requests
- Default: KeepAlive - 5
- Context: server config
- Status: Core - -

This directive enables Keep-Alive support. Set - max-requests to the maximum number of requests you - want Apache to entertain per connection. A limit is imposed to - prevent a client from hogging your server resources. Set this - to 0 to disable support.

- -

KeepAliveTimeout

- Syntax: KeepAliveTimeout - seconds
- Default: KeepAliveTimeout - 15
- Context: server config
- Status: Core - -

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.

- -

When Keep-Alive Is Used

- In order for Keep-Alive support to be used, first the browser - must support it. Many current browsers, including Netscape - Navigator 2.0, and Spyglass Mosaic-based browsers (including - Microsoft Internet Explorer) do. Note, however, that some - Windows 95-based browsers misbehave with Keep-Alive-supporting - servers; they may occasionally hang on a connect. This has been - observed with several Windows browsers, and occurs when - connecting to any Keep-Alive server, not just Apache. Netscape - 3.0b5 and later versions are known to work around this problem. - - -

However, Keep-Alive support only is active with files where - the length is known beforehand. This means that most CGI - scripts, server-side included files and directory listings will - not use the Keep-Alive protocol. While this should be - completely transparent to the end user, it is something the - web-master may want to keep in mind.

-
- -

Apache HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/core.html b/usr.sbin/httpd/htdocs/manual/mod/core.html new file mode 100644 index 00000000000..dcfd27616f6 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/core.html @@ -0,0 +1,4140 @@ + + + + + + + + Apache Core Features + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Apache Core Features

+ +

These configuration parameters control the core Apache + features, and are always available.

+ +

Directives

+ + +
+ +

AcceptFilter + directive

+ + Syntax: AcceptFilter + on|off
+ Default: AcceptFilter + on
+ Context: server configt
+ Status: core
+ Compatibility: AcceptFilter is + available in Apache 1.3.22 and later + +

AcceptFilter controls a BSD specific filter + optimization. It is compiled in by default - and switched on by + default if your system supports it (setsocketopt() option + SO_ACCEPTFILTER). Currently only FreeBSD supports this.

+ +

See the filter section on performance hints for more + information.

+ +

The compile time flag AP_ACCEPTFILTER_OFF can + be used to change the default to 'off'. httpd -V + and httpd -L will show compile time defaults and + whether or not SO_ACCEPTFILTER was defined during the + compile.

+ +
+ +

AcceptMutex + directive

+ + Syntax: AcceptMutex + uslock|pthread|sysvsem|fcntl|flock|os2sem|tpfcore|none|default
+ Default: AcceptMutex + default
+ Context: server config
+ Status: core
+ Compatibility: AcceptMutex is + available in Apache 1.3.21 and later. + +

AcceptMutex controls which accept() mutex + method Apache will use. Not all methods are available on all + platforms, since the suite of methods is determined at + compile-time. For a list of which methods are available for + your particular build, the httpd -V command line + option will list them out.

+ +

The compile time flags -D + HAVE_METHOD_SERIALIZED_ACCEPT can be used to add + different methods to your build, or one can edit the + include/ap_config.h file for your particular + platform.

+ +

This directive has no effect on Microsoft Windows.

+ +

See the performance tuning + guide for more information.

+ +
+ +

AccessConfig + directive

+ + Syntax: AccessConfig + file-path|directory-path|wildcard-path
+ Default: AccessConfig + conf/access.conf
+ Context: server config, virtual + host
+ Status: core
+ Compatibility: The ability to + specify a directory, rather than a file name, is only available in + Apache 1.3.13 and later. This directive will be eliminated in version + 2.0. + +

The server will read this file for more directives after + reading the ResourceConfig file. + File-path is relative to the ServerRoot. This feature can be disabled + using:

+ +
+ AccessConfig /dev/null +
+ Or, on Win32 servers, + +
+ AccessConfig nul +
+ Historically, this file only contained <Directory> sections; in fact it + can now contain any server directive allowed in the server + config context. However, since Apache version 1.3.4, + the default access.conf file which ships with + Apache contains only comments, and all directives are placed + in the main server configuration file, httpd.conf. + +

If AccessConfig points to a directory, rather than a + file, Apache will read all files in that directory, and any + subdirectory, and parse those as configuration files. +

+

Alternatively you can use a wildcard to limit the scope; i.e + to only *.conf files. +

+

Note that by default any file in the specified + directory will be loaded as a configuration file. +

+

+ So make sure that you don't have stray files in + this directory by mistake, such as temporary files created by your + editor, for example.

+ +

See also: Include and ResourceConfig.

+
+ +

AccessFileName + directive

+ + Syntax: AccessFileName + filename [filename] ...
+ Default: AccessFileName + .htaccess
+ Context: server config, virtual + host
+ Status: core
+ Compatibility: AccessFileName + can accept more than one filename only in Apache 1.3 and later + +

When returning a document to the client the server looks for + the first existing access control file from this list of names + in every directory of the path to the document, if access + control files are enabled for that directory. For example:

+ +
+ AccessFileName .acl +
+ before returning the document /usr/local/web/index.html, the + server will read /.acl, /usr/.acl, /usr/local/.acl and + /usr/local/web/.acl for directives, unless they have been + disabled with + +
+ <Directory />
+ AllowOverride None
+ </Directory> +
+ +

See Also: AllowOverride and Configuration Files

+
+ +

AddDefaultCharset directive

+ Syntax: AddDefaultCharset + On|Off|charset
+ Context: all
+ Status: core
+ Default: + AddDefaultCharset Off
+ Compatibility: + AddDefaultCharset is only available in Apache 1.3.12 and later + +

This directive specifies the name of the character set that + will be added to any response that does not have any parameter + on the content type in the HTTP headers. This will override any + character set specified in the body of the document via a + META tag. A setting of AddDefaultCharset + Off disables this functionality. AddDefaultCharset + On enables Apache's internal default charset of + iso-8859-1 as required by the directive. You can + also specify an alternate charset to be used.

+ +

For example:

+ +
+ AddDefaultCharset utf-8 +
+ +

Note: This will not have any effect on the + Content-Type and character set for default Apache-generated + status pages (such as '404 Not Found' or '301 Moved Permanently') + because those have an actual character set (that in which the + hard-coded page content is written) and don't need to have a default + applied.

+ +
+ +

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.

+ +

For example:

+ +
+ AddModule mod_include.c +
+ +

The ordering of AddModule lines is important. + Modules are listed in reverse priority order --- the ones that come + later can override the behavior of those that come earlier. This + can have visible effects; for instance, if UserDir followed Alias, + you couldn't alias out a particular user's home directory. For + more information and a recommended ordering, see + src/Configuration.tmpl in the Apache source + distribution.

+ +

See also: ClearModuleList and LoadModule

+
+ +

AllowOverride + directive

+ + Syntax: AllowOverride + All|None|directive-type [directive-type] + ...
+ 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.

+ +

Note: AllowOverride is only + valid in <Directory> sections, not in <Location> or + <Files> sections, as implied by the Context + section above.

+ +

When this directive is set to None, then + .htaccess files are completely ignored. In this case, the + server will not even attempt to read .htaccess files in the + filesystem.

+ +

When this directive is set to All, then any + directive which has the .htaccess Context is allowed in + .htaccess files.

+ +

The directive-type can be one of the following + groupings of directives.

+ +
+
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).
+
+ +

Example:

+
AllowOverride AuthConfig Indexes
+ +

See Also: AccessFileName and Configuration Files

+
+ +

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. + AuthName takes a single argument; if the realm + name contains spaces, it must be enclosed in quotation marks. + It must be accompanied by AuthType and + Require directives, and directives such + as AuthUserFile and AuthGroupFile to + work.

+ +

For example:

+ +
AuthName "Top Secret"
+ +

The string provided for the AuthName is what will + appear in the password dialog provided by most browsers.

+ +

See also: Authentication, Authorization, and + Access Control

+
+ +

AuthType + directive

+ + Syntax: AuthType + Basic|Digest
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: core + +

This directive selects the type of user authentication for a + directory. Only Basic and Digest are + currently implemented. + + It must be accompanied by AuthName and + Require directives, and directives such + as AuthUserFile and AuthGroupFile to + work.

+ +

See also: Authentication, Authorization, and + Access Control

+
+ +

BindAddress + directive

+ + Syntax: BindAddress + *|IP-address|domain-name
+ Default: BindAddress + *
+ Context: server config
+ Status: core
+ Compatibility: BindAddress is + deprecated and will be eliminated in Apache 2.0. + +

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. If the argument to this directive is *, + then the server will listen for connections on every IP + address. Otherwise, the server can listen to only a specific + IP-address or a fully-qualified Internet + domain-name.

+ +

For example:

+ + BindAddress 192.168.15.48
+ +

Only one BindAddress directive can be used.

+ +

This directive is deprecated and will be eliminated in + Apache 2.0. Equivalent functionality and more control over the + address and ports Apache listens to is available using the + Listen + directive.

+ +

BindAddress can be used as an alternative + method for supporting virtual hosts + using multiple independent servers, instead of using <VirtualHost> + sections.

+ +

See Also: DNS + Issues
+ See Also: Setting + which addresses and ports Apache uses

+
+ +

BS2000Account + directive

+ + Syntax: BS2000Account + account
+ Default: none
+ Context: server config
+ Status: core
+ Compatibility: BS2000Account is + only available for BS2000 machines, as of Apache 1.3 and later. + + +

The BS2000Account directive is available for + BS2000 hosts only. It must be used to define the account number + for the non-privileged apache server user (which was configured + using the User directive). This is required + by the BS2000 POSIX subsystem (to change the underlying BS2000 + task environment by performing a sub-LOGON) to prevent CGI + scripts from accessing resources of the privileged account + which started the server, usually SYSROOT.
+ Only one BS2000Account directive can be used.

+ +
+ +

CGICommandArgs + directive

+ + Syntax: CGICommandArgs On|Off
+ Default: CGICommandArgs On
+ Context: directory, .htaccess
+ Override: Options
+ Status: core
+ Compatibility: Available in Apache + 1.3.24 and later. + +

Way back when the internet was a safer, more naive place, it + was convenient for the server to take a query string that did not + contain an '=' sign and to parse and pass it to a CGI program as + command line args. For example, <IsIndex> + generated searches often work in this way. The default behavior + in Apache is to maintain this behavior for backwards + compatibility, although it is generally regarded as unsafe + practice today. Most CGI programs do not take command line + parameters, but among those that do, many are unaware of this + method of passing arguments and are therefore vulnerable to + malicious clients passing unsafe material in this way. Setting + CGICommandArgs Off is recommended to protect such + scripts with little loss in functionality.

+ +
+ +

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.

+ +

See also: AddModule and LoadModule

+ +
+ +

ContentDigest + directive

+ + Syntax: ContentDigest + on|off
+ Default: ContentDigest + off
+ Context: server config, virtual + host, directory, .htaccess
+ Override: Options
+ Status: experimental
+ Compatibility: ContentDigest is + only available in Apache 1.1 and later + +

This directive enables the generation of + Content-MD5 headers as defined in RFC1864 + respectively RFC2068.

+ +

MD5 is an algorithm for computing a "message digest" + (sometimes called "fingerprint") of arbitrary-length data, with + a high degree of confidence that any alterations in the data + will be reflected in alterations in the message digest.

+ +

The Content-MD5 header provides an end-to-end + message integrity check (MIC) of the entity-body. A proxy or + client may check this header for detecting accidental + modification of the entity-body in transit. Example header:

+
+   Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==
+
+ +

Note that this can cause performance problems on your server + since the message digest is computed on every request (the + values are not cached).

+ +

Content-MD5 is only sent for documents served + by the core, and not by any module. For example, SSI documents, + output from CGI scripts, and byte range responses do not have + this header.

+
+ +

CoreDumpDirectory directive

+ + Syntax: CoreDumpDirectory + directory-path
+ Default: the same location as + ServerRoot
+ Context: server config
+ Status: core + +

This controls the directory to which Apache attempts to + switch before dumping core. The default is in the ServerRoot directory, however since this + should not be writable by the user the server runs as, core + dumps won't normally get written. If you want a core dump for + debugging, you can use this directive to place it in a + different location.

+ +

For example:

+ +
+ CoreDumpDirectory /tmp +
+ +
+ +

DefaultType + directive

+ + Syntax: DefaultType + MIME-type
+ Default: DefaultType + text/plain
+ 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 +
+ would be appropriate for a directory which contained many gif + images with filenames missing the .gif extension. + +

See also: AddType and TypesConfig.

+ +
+ +

<Directory> + directive

+ + Syntax: <Directory + directory-path|proxy:url-path> + ... </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-path 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. + As of Apache 1.3, you may also use `[ ]' character ranges like + in the shell. Also as of Apache 1.3 none of the wildcards match + a `/' character, which more closely mimics the behavior of + Unix shells. 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 (non-regular expression) 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> +
+ for access to the document /home/web/dir/doc.html + the steps are: + + + +

Regular expression directory sections are handled slightly + differently by Apache 1.2 and 1.3. In Apache 1.2 they are + interspersed with the normal directory sections and applied in + the order they appear in the configuration file. They are + applied only once, and apply when the shortest match possible + occurs. In Apache 1.3 regular expressions are not considered + until after all of the normal sections have been applied. Then + all of the regular expressions are tested in the order they + appeared in the configuration file. For example, with

+ +
+ <Directory ~ abc$>
+ ... directives here ...
+ </Directory>
+ +
+ Suppose that the filename being accessed is + /home/abc/public_html/abc/index.html. The server + considers each of /, /home, + /home/abc, /home/abc/public_html, and + /home/abc/public_html/abc in that order. In Apache + 1.2, when /home/abc is considered, the regular + expression will match and be applied. In Apache 1.3 the regular + expression isn't considered at all at that point in the tree. + It won't be considered until after all normal + <Directory>s and .htaccess files have been + applied. Then the regular expression will match on + /home/abc/public_html/abc and be applied. + +

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.

+ <Directory> directives cannot nest, and cannot appear in + a <Limit> or <LimitExcept> section. + +

If you have mod_proxy enabled, you + can use the proxy: syntax to apply configuration + directives to proxied content. The syntax for this is to specify the + proxied URLs to which you wish to apply the configuration, or to + specify * to apply to all proxied content:

+ +

To apply to all proxied content:

+ + 
+   <Directory proxy:*>
+     ... directives here ...
+   </Directory>
+
+ +

To apply to just a subset of proxied content:

+ + 
+   <Directory proxy:http://www.example.com/>
+     ... directives here ...
+   </Directory>
+
+ +

See also: How + Directory, Location and Files sections work for an + explanation of how these different sections are combined when a + request is received

+

See also: DirectoryMatch

+
+ +

<DirectoryMatch>

+ Syntax: <DirectoryMatch + regex> ... </DirectoryMatch>
+ Context: server config, virtual + host
+ Status: Core.
+ Compatibility: Available in + Apache 1.3 and later + +

<DirectoryMatch> and </DirectoryMatch> are used + to enclose a group of directives which will apply only to the + named directory and sub-directories of that directory, the same + as <Directory>. However, it + takes as an argument a regular expression. For example:

+
+   <DirectoryMatch "^/www/.*/[0-9]{3}">
+
+ +

would match directories in /www/ that consisted of three + numbers.

+ +

See Also: <Directory> for a description of + how regular expressions are mixed in with normal + <Directory>s.
+ See also: How + Directory, Location and Files sections work for an + explanation of how these different sections are combined when a + request is received

+
+ +

DocumentRoot + directive

+ + Syntax: DocumentRoot + directory-path
+ Default: DocumentRoot + /usr/local/apache/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/web +
+ then an access to + http://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.

+
+ +

EBCDICConvert

+ + Syntax: EBCDICConvert + On|Off[=direction] extension + [extension] ...
+ Context: server config, virtual + host, directory, .htaccess
+ Status: core
+ Override: FileInfo
+ Compatibility: The configurable + EBCDIC conversion is only available in Apache 1.3.19 and later, + and on EBCDIC based platforms. + +

The EBCDICConvert directive maps the given filename + extensions to the specified conversion setting (On + or Off). File extensions may be specified with or + without a leading dot.

+ +

If the optional format On=direction (or + Off=direction) is used, where + direction is one of In, Out or + InOut, then the directive only applies to the + specified transfer direction (In: uploaded content + in a PUT or POST request, Out: returned content in + a GET or POST request, and InOut: conversion in + both directions).
+ Otherwise, InOut (conversion in both directions) + is implied.

+ +

Conversion configuration based on file extension is tested + prior to configuration based on MIME type, to allow for generic + MIME based rules to be overridden by a more specific file + extension (several file extensions may exist for the same MIME + type).

+ +

Example:
+ With a configuration like the following, the normal + *.html files contain HTML text in EBCDIC encoding, + while *.ahtml files contain HTML text in ASCII + encoding:

+
+    # *.html and *.ahtml contain HTML text:
+    AddType  text/html  .html .ahtml
+
+    # *.ahtml is not converted (contains ASCII text already):
+    EBCDICConvert       Off .ahtml
+
+    # All other text/html files presumably contain EBCDIC text:
+    EBCDICConvertByType On  text/html
+
+
+
+ + +

See also: EBCDICConvertByType

+
+ +

EBCDICConvertByType

+ + Syntax: EBCDICConvertByType + On|Off[=direction] mimetype + [mimetype] ...
+ Context: server config, virtual + host, directory, .htaccess
+ Status: core
+ Override: FileInfo
+ Compatibility: The configurable + EBCDIC conversion is only available in Apache 1.3.19 and later, + and on EBCDIC based platforms. + +

The EBCDICConvertByType directive maps the given MIME type + (optionally containing wildcards) to the specified conversion + setting (On or Off).

+ +

If the optional format On=direction (or + Off=direction) is used, where + direction is one of In, Out or + InOut, then the directive only applies to the + specified transfer direction (In: uploaded content + in a PUT or POST request, Out: returned content in + a GET or POST request, and InOut: conversion in + both directions).
+ Otherwise, InOut (conversion in both directions) + is implied.

+ +

Example:
+ A useful standard configuration should at least contain the + following defaults:

+
+    # All text documents are stored as EBCDIC files:
+    EBCDICConvertByType On  text/* message/* multipart/*
+    EBCDICConvertByType On  application/x-www-form-urlencoded \
+                model/vrml application/postscript
+    # All other files are assumed to be binary:
+    EBCDICConvertByType Off */*
+
+ If you serve ASCII documents only, for example from an NFS + mounted unix server, use: +
+    # All documents are ASCII already:
+    EBCDICConvertByType Off */*
+
+ +

See also: EBCDICConvert

+
+ +

EBCDICKludge

+ + Syntax: EBCDICKludge + On|Off
+ Default: EBCDICKludge + Off
+ Context: server config, virtual + host, directory, .htaccess
+ Status: core
+ Override: FileInfo
+ Compatibility: EBCDICKludge is + only available in Apache 1.3.19 and later, and on EBCDIC based + platforms. It is deprecated and will be withdrawn in a future + version.
+ + +

The EBCDICKludge is provided for the backward compatible + behavior with apache versions 1.3.0 through 1.3.18. In these + versions, all files with MIME types starting with "text/", + "message/" or "multipart/" or with type + "application/x-www-form-urlencoded" would be converted by + default, all other documents were returned unconverted. Only if + a MIME type "text/x-ascii-subtype" + was configured for a certain document, the document was assumed + to be in ASCII format already, and was not converted again. + Instead, the "x-ascii-" was removed from + the type, resulting in the MIME type + "text/subtype" being returned for the + document.

+ +

If the EBCDICKludge directive is set to On, and + if none of the file extensions configured with the EBCDICConvert directive matches in + the current context, then the server tests for a MIME type of + the format + type/x-ascii-subtype. If the + document has such a type, then the + "x-ascii-" substring is removed and the + conversion set to Off. This allows for overriding + the implicit assumption that all text files are stored in + EBCDIC format, for example when serving documents from an NFS + mounted directory with ASCII documents.
+ By using the EBCDICKludge, there is no way to force one of the + other MIME types (e.g., model/vrml) to be treated as + an EBCDIC text file. Use of the EBCDICConvertByType directive + mentioned above is the preferred way to configure such a + conversion. (Before Apache version 1.3.19, there was no way at + all to force these binary documents to be treated as EBCDIC + text files.)

+ +

See also: EBCDICConvert, EBCDICConvertByType

+
+ +

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,

+ +
    +
  1. output a simple hardcoded error message
    2. + +
  2. output a customized message
    3. + +
  3. redirect to a local URL-path to handle the + problem/error
    4. + +
  4. redirect to an external URL to handle the + problem/error
    5. +
+ +

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 + double-quote character ("), 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 the client will not + receive the original error status code, but instead will + receive a redirect status code. This in turn can confuse web + robots and other clients which try to determine if a URL is + valid using the status code. In addition, if you use a remote + URL in an ErrorDocument 401, the client will not + know to prompt the user for a password since it will not + receive the 401 status code. Therefore, if you use an + "ErrorDocument 401" directive then it must refer to a local + document.

+ +

See Also: documentation of + customizable responses. See the HTTP + specification for a complete list of the status codes and their + meanings.

+
+ +

ErrorLog + directive

+ + Syntax: ErrorLog + file-path|syslog[:facility]
+ Default: ErrorLog + logs/error_log (Unix)
+ Default: ErrorLog + logs/error.log (Windows and OS/2)
+ 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 + file-path does not begin with a slash (/) then it is + assumed to be relative to the ServerRoot. If the file-path + begins with a pipe (|) then it is assumed to be a command to + spawn to handle the error log.

+ +

Examples

+ +

ErrorLog logs/vhost1.error

+ + or + +

ErrorLog |/usr/local/bin/errorlog.pl

+ +

Apache 1.3 and above: Using + syslog instead of a filename enables logging via + syslogd(8) if the system supports it. The default is to use + syslog facility local7, but you can override this + by using the syslog:facility syntax where + facility can be one of the names usually documented in + syslog(1).

+ +

For example:

+ +

ErrorLog syslog

+ + or + +

ErrorLog syslog:user

+ +

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: LogLevel + and Apache Log Files

+
+ +

FileETag directive

+ Syntax: FileETag + component ...
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: core
+ Compatibility: only available + in Apache 1.3.23 versions and later. + +

+ The FileETag directive configures the file attributes that are + used to create the ETag (entity tag) response header field + when the document is based on a file. + (The ETag value is used in cache management to save network + bandwidth.) In Apache 1.3.22 and earlier, the ETag value was + always formed from the file's inode, size, and last-modified + time (mtime). The FileETag directive allows you to choose + which of these -- if any -- should be used. The recognized + keywords are: +

+
+
INode
+
The file's i-node number will be included in the calculation
+
MTime
+
The date and time the file was last modified will be included
+
Size
+
The number of bytes in the file will be included
+
All
+
All available fields will be used (equivalent to + 'FileETag INode MTime Size')
+
None
+
If a document is file-based, no ETag field will be included in the + response
+
+

+ The INode, MTime, and Size keywords may be prefixed with either '+' + or '-', which allow changes to be made to the default setting + inherited from a broader scope. Any keyword appearing without + such a prefix immediately and completely cancels the inherited + setting. +

+

+ If a directory's configuration includes + 'FileETag INode MTime Size', and a + subdirectory's includes 'FileETag -INode', + the setting for that subdirectory (which will be inherited by + any sub-subdirectories that don't override it) will be equivalent to + 'FileETag MTime Size'. +

+
+ +

<Files> directive

+ 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. The directives given + within this section will be applied to any object with a + basename (last component of filename) matching the specified + filename. <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. Note that + <Files> can be nested inside <Directory> sections + to restrict the portion of the filesystem they apply to.

+ +

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. In Apache + 1.3 and later, <FilesMatch> is + preferred, however. + +

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. + For example, to password protect a single file within a + particular directory, you might add the following to your + .htaccess file:

+ + 
+    <Files admin.cgi>
+    Require group admin
+    </Files>
+ +

Remember that directives apply to subdirectories as well, so this + will also protect files called admin.cgi in + subdirectories, unless specifically overridden.

+ +

(See Require for details on using the + Require directive)

+ +

See also: How + Directory, Location and Files sections work for an + explanation of how these different sections are combined when a + request is received

+
+ +

<FilesMatch>

+ Syntax: <FilesMatch + regex> ... </FilesMatch>
+ Context: server config, virtual + host, .htaccess
+ Status: core
+ Compatibility: only available + in Apache 1.3 and above. + +

The <FilesMatch> directive provides for access control + by filename, just as the <Files> + directive does. However, it accepts a regular expression. For + example:

+
+   <FilesMatch "\.(gif|jpe?g|png)$">
+
+ +

would match most common Internet graphics formats.

+ See also: How + Directory, Location and Files sections work for an + explanation of how these different sections are combined when a + request is received +
+ +

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.
+
+

It is recommended that you set up a new group specifically for + running the server. Some admins use user nobody, + but this is not always possible or desirable.

+ +

Example:

+ + Group www-group + +

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 + on|off|double
+ Default: HostnameLookups + off
+ Context: server config, virtual + host, directory
+ Status: core
+ Compatibility: + double available only in Apache 1.3 and + above.
+ Compatibility: Default was + on prior to Apache 1.3. + +

This directive enables DNS lookups so that host names can be + logged (and passed to CGIs/SSIs in REMOTE_HOST). + The value double refers to doing double-reverse + DNS. That is, after a reverse lookup is performed, a forward + lookup is then performed on that result. At least one of the ip + addresses in the forward lookup must match the original + address. (In "tcpwrappers" terminology this is called + PARANOID.)

+ +

Regardless of the setting, when mod_access is used for controlling + access by hostname, a double reverse lookup will be performed. + This is necessary for security. Note that the result of this + double-reverse isn't generally available unless you set + HostnameLookups double. For example, if only + HostnameLookups on and a request is made to an + object that is protected by hostname restrictions, regardless + of whether the double-reverse fails or not, CGIs will still be + passed the single-reverse result in + REMOTE_HOST.

+ +

The default for this directive was previously + on in versions of Apache prior to 1.3. It was + changed to off in order to save the network + traffic for those sites that don't truly need the reverse + lookups done. It is also better for the end users because they + don't have to suffer the extra latency that a lookup entails. + Heavily loaded sites should leave 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 + on|off
+ Default: IdentityCheck + off
+ Context: server config, virtual + host, directory
+ 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.

+ +

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.

+
+ +

<IfDefine> + directive

+ Syntax: <IfDefine + [!]parameter-name> ... + </IfDefine>
+ Default: None
+ Context: all
+ Status: Core
+ Compatibility: <IfDefine> + is only available in 1.3.1 and later. + +

The <IfDefine test>...</IfDefine> + section is used to mark directives that are conditional. The + directives within an IfDefine 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 <IfDefine> section directive + can be one of two forms:

+ + + +

In the former case, the directives between the start and end + markers are only processed if the parameter named + parameter-name is defined. The second format reverses + the test, and only processes the directives if + parameter-name is not defined.

+ +

The parameter-name argument is a define as given on + the httpd command line via + -Dparameter-, at the time the server was + started.

+ +

<IfDefine> sections are nest-able, which can be used + to implement simple multiple-parameter tests. Example:

+
+  $ httpd -DReverseProxy ...
+
+  # httpd.conf
+  <IfDefine ReverseProxy>
+  LoadModule rewrite_module libexec/mod_rewrite.so
+  LoadModule proxy_module   libexec/libproxy.so
+  </IfDefine>
+
+
+ +

<IfModule> + directive

+ Syntax: <IfModule + [!]module-name> ... + </IfModule>
+ Default: None
+ Context: all
+ Status: Core
+ Compatibility: IfModule 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:

+ + + +

In the former case, the directives between the start and end + markers are only processed if the module named module + name is included in Apache -- either compiled in or + dynamically loaded using LoadModule. The second format + reverses the test, and only processes the directives if module + name is not included.

+ +

The module name argument is 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.

+
+ +

Include directive

+ Syntax: Include + file-path|directory-path|wildcard-path
+ Context: server config
+ Status: Core
+ Compatibility: Include is only + available in Apache 1.3 and later. + +

This directive allows inclusion of other configuration files + from within the server configuration files.

+ +

The file path specified may be a fully qualified path (i.e. + starting with a slash), or may be relative to the + ServerRoot directory.

+ +

New in Apache 1.3.13 is the feature that if + Include points to a directory, rather than a file, + Apache will read all files in that directory, and any + subdirectory, and parse those as configuration files.

+

By using a wildcard this can be further limited to, say, + just the '*.conf' files. +

+

Examples:

+
+ Include /usr/local/apache/conf/ssl.conf
+ Include /usr/local/apache/conf/vhosts/ + +
+ +

Or, providing paths relative to your ServerRoot + directory:

+ +
+ Include conf/ssl.conf
+ Include conf/vhosts/ + +
+ +

Make sure that an included directory does not contain any stray + files, such as editor temporary files, for example, as Apache will + attempt to read them in and use the contents as configuration + directives, which may cause the server to fail on start up. + Running apachectl configtest will give you a list of + the files that are being processed during the configuration + check:

+ +
+root@host# apachectl configtest
+ Processing config directory: /usr/local/apache/conf/vhosts
+ Processing config file: /usr/local/apache/conf/vhosts/vhost1
+ Processing config file: /usr/local/apache/conf/vhosts/vhost2
+Syntax OK
+
+ +

This will help in verifying that you are getting only the files + that you intended as part of your configuration.

+ +

See also: apachectl

+ +
+ +

KeepAlive + directive

+ 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. + +

The Keep-Alive extension to HTTP/1.0 and the persistent + connection feature of HTTP/1.1 provide long-lived HTTP sessions + which allow multiple requests to be sent over the same TCP + connection. In some cases this has been shown to result in an + almost 50% speedup in latency times for HTML documents with + many images. To enable Keep-Alive connections in Apache 1.2 and + later, set KeepAlive On.

+ +

For HTTP/1.0 clients, Keep-Alive connections will only be + used if they are specifically requested by a client. In + addition, a Keep-Alive connection with an HTTP/1.0 client can + only be used when the length of the content is known in + advance. This implies that dynamic content such as CGI output, + SSI pages, and server-generated directory listings will + generally not use Keep-Alive connections to HTTP/1.0 clients. + For HTTP/1.1 clients, persistent connections are the default + unless otherwise specified. If the client requests it, chunked + encoding will be used in order to send content of unknown + length over persistent connections.

+ +

Apache 1.1 only: Set max-requests + to the maximum number of requests you want Apache to entertain + per connection. A limit is imposed to prevent a client from + hogging your server resources. Set this to 0 to + disable support. In Apache 1.2 and 1.3, this is controlled + through the MaxKeepAliveRequests directive instead.

+ +

See also MaxKeepAliveRequests.

+
+ +

KeepAliveTimeout directive

+ 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.

+ +

Setting KeepAliveTimeout to a high value may + cause performance problems in heavily loaded servers. The + higher the timeout, the more server processes will be kept + occupied waiting on connections with idle clients.

+
+ +

<Limit> directive

+ + Syntax: <Limit + method [method] ... > ... + </Limit>
+ Context: any
+ Status: core + +

Access controls are normally effective for + all access methods, and this is the usual + desired behavior. In the general case, access control + directives should not be placed within a + <limit> section.

+ +

The purpose of the <Limit> directive is to restrict + the effect of the access controls to the nominated HTTP + methods. For all other methods, the access restrictions that + are enclosed in the <Limit> bracket will have no + effect. The following example applies the access + control only to the methods POST, PUT, and DELETE, leaving all + other methods unprotected:

+ +
+ <Limit POST PUT DELETE>
+ Require valid-user
+ </Limit> +
+

The method names listed can be one or more of: GET, POST, PUT, + DELETE, CONNECT, OPTIONS, PATCH, PROPFIND, PROPPATCH, + MKCOL, COPY, MOVE, LOCK, and UNLOCK. The method name is + case-sensitive. If GET is used it will also restrict + HEAD requests. The TRACE method cannot be limited.

+ +

Warning: A <LimitExcept> section should + always be used in preference to a <Limit> section when restricting access, + since a <LimitExcept> section + provides protection against arbitrary methods.

+ +
+ +

<LimitExcept> + directive

+ + Syntax: <LimitExcept + method [method] ... > ... + </LimitExcept>
+ Context: any
+ Status: core
+ Compatibility: Available in + Apache 1.3.5 and later + +

<LimitExcept> and </LimitExcept> are used to + enclose a group of access control directives which will then + apply to any HTTP access method not listed in + the arguments; i.e., it is the opposite of a <Limit> section and can be used to + control both standard and nonstandard/unrecognized methods. See + the documentation for <Limit> for + more details.

+ +

For example:

+ + 
+    <LimitExcept POST GET>
+    Require valid-user
+    </LimitExcept>
+
+ +
+ +

LimitInternalRecursion directive

+ + Syntax: LimitInternalRecursion + number [number]
+ Default: LimitInternalRecursion + 20
+ Context: server config, virtual host
+ Status: core
+ Compatibility: LimitInternalRecursion + is only available in Apache 1.3.28 and later. + +

An internal redirect happens, for example, when using the Action directive, which internally + redirects the original request to a CGI script. A subrequest is Apache's + mechanism to find out what would happen for some URI if it were requested. + For example, mod_dir uses subrequests to look + for the files listed in the DirectoryIndex + directive.

+ +

LimitInternalRecursion prevents the server + from crashing when entering an infinite loop of internal redirects or + subrequests. Such loops are usually caused by misconfigurations.

+ +

The directive stores two different limits, which are evaluated on + per-request basis. The first number is the maximum number of + internal redirects, that may follow each other. The second number + determines, how deep subrequests may be nested. If you specify only one + number, it will be assigned to both limits. A value of + 0 means "unlimited".

+ +

Example

+ 
+    LimitInternalRecursion 5
+
+ +
+ +

LimitRequestBody directive

+ + Syntax: LimitRequestBody + bytes
+ Default: LimitRequestBody + 0
+ Context: server config, virtual + host, directory, .htaccess
+ Status: core
+ Compatibility: LimitRequestBody + is only available in Apache 1.3.2 and later. + +

This directive specifies the number of bytes from 0 + (meaning unlimited) to 2147483647 (2GB) that are allowed in a + request body.

+ +

The LimitRequestBody directive allows the user to set a + limit on the allowed size of an HTTP request message body + within the context in which the directive is given (server, + per-directory, per-file or per-location). If the client request + exceeds that limit, the server will return an error response + instead of servicing the request. The size of a normal request + message body will vary greatly depending on the nature of the + resource and the methods allowed on that resource. CGI scripts + typically use the message body for passing form information to + the server. Implementations of the PUT method will require a + value at least as large as any representation that the server + wishes to accept for that resource.

+ +

This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service + attacks.

+ +

If, for example, you are permitting file upload to a particular + location, and wich to limit the size of the uploaded file to 100K, + you might use the following directive:

+ + 
LimitRequestBody 102400
+ +
+ +

LimitRequestFields directive

+ + Syntax: LimitRequestFields + number
+ Default: + LimitRequestFields 100
+ Context: server config
+ Status: core
+ Compatibility: + LimitRequestFields is only available in Apache 1.3.2 and later. + + +

Number is an integer from 0 (meaning unlimited) to + 32767. The default value is defined by the compile-time + constant DEFAULT_LIMIT_REQUEST_FIELDS (100 as + distributed).

+ +

The LimitRequestFields directive allows the server + administrator to modify the limit on the number of request + header fields allowed in an HTTP request. A server needs this + value to be larger than the number of fields that a normal + client request might include. The number of request header + fields used by a client rarely exceeds 20, but this may vary + among different client implementations, often depending upon + the extent to which a user has configured their browser to + support detailed content negotiation. Optional HTTP extensions + are often expressed using request header fields.

+ +

This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service attacks. + The value should be increased if normal clients see an error + response from the server that indicates too many fields were + sent in the request.

+ +

For example:

+ + 
LimitRequestFields 50
+ +
+ +

LimitRequestFieldsize + directive

+ + Syntax: LimitRequestFieldsize + bytes
+ Default: + LimitRequestFieldsize 8190
+ Context: server config
+ Status: core
+ Compatibility: + LimitRequestFieldsize is only available in Apache 1.3.2 and + later. + +

This directive specifies the number of bytes from 0 + to the value of the compile-time constant + DEFAULT_LIMIT_REQUEST_FIELDSIZE (8190 as + distributed) that will be allowed in an HTTP request + header.

+ +

The LimitRequestFieldsize directive allows the server + administrator to reduce the limit on the allowed size of an + HTTP request header field below the normal input buffer size + compiled with the server. A server needs this value to be large + enough to hold any one header field from a normal client + request. The size of a normal request header field will vary + greatly among different client implementations, often depending + upon the extent to which a user has configured their browser to + support detailed content negotiation.

+ +

This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service attacks.

+ +

For example:

+ + 
LimitRequestFieldSize 16380
+ +

Under normal conditions, the value should not be changed from + the default.

+
+ +

LimitRequestLine directive

+ + Syntax: LimitRequestLine + bytes
+ Default: LimitRequestLine + 8190
+ Context: server config
+ Status: core
+ Compatibility: LimitRequestLine + is only available in Apache 1.3.2 and later. + +

This directive sets the number of bytes from 0 to + the value of the compile-time constant + DEFAULT_LIMIT_REQUEST_LINE (8190 as distributed) + that will be allowed on the HTTP request-line.

+ +

The LimitRequestLine directive allows the server + administrator to reduce the limit on the allowed size of a + client's HTTP request-line below the normal input buffer size + compiled with the server. Since the request-line consists of + the HTTP method, URI, and protocol version, the + LimitRequestLine directive places a restriction on the length + of a request-URI allowed for a request on the server. A server + needs this value to be large enough to hold any of its resource + names, including any information that might be passed in the + query part of a GET request.

+ +

This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service attacks.

+ +

For example:

+ + 
LimitRequestLine 16380
+ +

Under normal conditions, the value should not be changed from + the default.

+
+ +

Listen directive

+ Syntax: Listen + [IP-address:]port
+ 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.

+ Listen can be used instead of BindAddress and Port. It + tells the server to accept incoming requests on the specified + port or address-and-port combination. If the first format is + used, with a port number only, the server listens to the given + port on all interfaces, instead of the port given by the + Port directive. If an IP address is given as well as a + port, the server will listen on the given port and interface. + +

Note that you may still require a Port directive so + that URLs that Apache generates that point to your server still + work.

+ +

Multiple Listen directives may be used to specify a number + of addresses and ports to listen to. The server will respond to + requests from any of the listed addresses and ports.

+ +

For example, to make the server accept connections on both + port 80 and port 8000, use:

+
+   Listen 80
+   Listen 8000
+
+ To make the server accept connections on two specified + interfaces and port numbers, use +
+   Listen 192.170.2.1:80
+   Listen 192.170.2.5:8000
+
+ +

See Also: DNS + Issues
+ See Also: Setting + which addresses and ports Apache uses
+

+ +

ListenBacklog + directive

+ Syntax: ListenBacklog + backlog
+ Default: ListenBacklog + 511
+ Context: server config
+ Status: Core
+ Compatibility: ListenBacklog is + only available in Apache versions after 1.2.0. + +

The maximum length of the queue of pending connections. + Generally no tuning is needed or desired, however on some + systems it is desirable to increase this when under a TCP SYN + flood attack. See the backlog parameter to the + listen(2) system call.

+ +

This will often be limited to a smaller number by the + operating system. This varies from OS to OS. Also note that + many OSes do not use exactly what is specified as the backlog, + but use a number based on (but normally larger than) what is + set.

+
+ +

<Location> + directive

+ Syntax: <Location + URL-path|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 similar to the <Directory> directive, and starts a + subsection which is terminated with a </Location> + directive. <Location> sections are processed + in the order they appear in the configuration file, after the + <Directory> sections and .htaccess files are + read, and after the <Files> sections.

+ +

Note that URLs do not have to line up with the filesystem at + all, it should be emphasized that <Location> operates + completely outside the filesystem.

+ +

For all origin (non-proxy) requests, the URL to be matched + is of the form /path/, and you should not include + any http://servername prefix. For proxy requests, + the URL to be matched is of the form + scheme://servername/path, and you must include the + prefix.

+ +

The URL may use wildcards 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". In Apache 1.3 and above, a new directive <LocationMatch> exists which + behaves identical to the regex version of + <Location>.

+ +

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>
+
+ +

Apache 1.3 and above note about / (slash): + The slash character has special meaning depending on where in a + URL it appears. People may be used to its behavior in the + filesystem where multiple adjacent slashes are frequently + collapsed to a single slash (i.e., + /home///foo is the same as + /home/foo). In URL-space this is not necessarily + true. The <LocationMatch> directive and the + regex version of <Location> require you to + explicitly specify multiple slashes if that is your intention. + For example, <LocationMatch ^/abc> would + match the request URL /abc but not the request URL + //abc. The (non-regex) + <Location> directive behaves similarly when + used for proxy requests. But when (non-regex) + <Location> is used for non-proxy requests it + will implicitly match multiple slashes with a single slash. For + example, if you specify <Location /abc/def> + and the request is to /abc//def then it will + match.

+ +

See also: How + Directory, Location and Files sections work for an + explanation of how these different sections are combined when a + request is received

+
+ +

<LocationMatch>

+ Syntax: <LocationMatch + regex> ... </LocationMatch>
+ Context: server config, virtual + host
+ Status: core
+ Compatibility: LocationMatch is + only available in Apache 1.3 and later. + +

The <LocationMatch> directive provides for access + control by URL, in an identical manner to <Location>. However, it takes a + regular expression as an argument instead of a simple string. + For example:

+
+   <LocationMatch "/(extra|special)/data">
+
+ +

would match URLs that contained the substring "/extra/data" + or "/special/data".

+ See also: How + Directory, Location and Files sections work for an + explanation of how these different sections are combined when a + request is received +
+ +

LockFile + directive

+ Syntax: LockFile + file-path
+ Default: LockFile + logs/accept.lock
+ Context: server config
+ Status: core + +

The LockFile directive sets the path to the lockfile used + when Apache is compiled with either USE_FCNTL_SERIALIZED_ACCEPT + or USE_FLOCK_SERIALIZED_ACCEPT. This directive should normally + be left at its default value. The main reason for changing it + is if the logs directory is NFS mounted, since + the lockfile must be stored on a local disk. + The PID of the main server process is automatically appended to + the filename.

+ +

SECURITY: It is best to avoid putting this + file in a world writable directory such as + /var/tmp because someone could create a denial of + service attack and prevent the server from starting by creating + a lockfile with the same name as the one the server will try to + create.

+
+ +

LogLevel + directive

+ Syntax: LogLevel + level
+ Default: LogLevel + warn
+ Context: server config, virtual + host
+ Status: core
+ Compatibility: LogLevel is only + available in 1.3 or later. + +

LogLevel adjusts the verbosity of the messages recorded in + the error logs (see ErrorLog + directive). The following levels are available, in + order of decreasing significance:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Level Description Example
emerg Emergencies - system is unusable."Child cannot open lock file. Exiting"
alert Action must be taken immediately."getpwuid: couldn't determine user name from uid"
crit Critical Conditions."socket: Failed to get a socket, exiting child"
error Error conditions."Premature end of script headers"
warn Warning conditions."child process 1234 did not exit, sending another + SIGHUP"
notice Normal but significant condition."httpd: caught SIGBUS, attempting to dump core in + ..."
info Informational."Server seems busy, (you may need to increase + StartServers, or Min/MaxSpareServers)..."
debug Debug-level messages"Opening config file ..."
+ +

When a particular level is specified, messages from all + other levels of higher significance will be reported as well. + E.g., when LogLevel info is specified, + then messages with log levels of notice and + warn will also be posted.

+ +

Using a level of at least crit is + recommended.

+ +

For example:

+ + 
LogLevel notice
+ +

NOTE: When logging to a regular file messages + of the level notice cannot be suppressed and thus are + always logged. However, this doesn't apply when logging is done + using syslog.

+ +
+ +

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. To configure + more than 256 clients, you must edit the HARD_SERVER_LIMIT + entry in httpd.h and recompile.

+ +

Any connection attempts over the MaxClients limit will + normally be queued, up to a number based on the ListenBacklog directive. Once a child + process is freed at the end of a different request, the + connection will then be serviced.

+
+ +

MaxKeepAliveRequests + directive

+ 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. In Apache 1.1, this is controlled through + an option to the KeepAlive directive.

+ +

For example

+ + 
MaxKeepAliveRequests 500
+ +
+ +

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:

+ + + +

However, on Win32, It is recommended that this be set to 0. + If it is set to a non-zero value, when the request count is + reached, the child process exits, and is respawned, at which + time it re-reads the configuration files. This can lead to + unexpected behavior if you have modified a configuration file, + but are not expecting the changes to be applied yet. See also + ThreadsPerChild.

+ +

NOTE: For KeepAlive requests, only + the first request is counted towards this limit. In effect, it + changes the behavior to limit the number of + connections per child.

+
+ +

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.

+ +

Note that this is the maximum number of spare servers, + not the maximum total number of client requests that can be handled + at one time. If you wish to limit that number, see the MaxClients directive.

+ +

This directive has no effect when used with the Apache Web + server on a Microsoft Windows platform.

+ +

See also MinSpareServers, + StartServers, and MaxClients.

+
+ +

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.

+ +

Note that setting this directive to some value m ensures + that you will always have at least n + m httpd + processes running when you have n active client requests.

+ +

This directive has no effect on Microsoft Windows.

+ +

See also MaxSpareServers, + StartServers, and MaxClients.

+
+ +

NameVirtualHost directive

+ + Syntax: NameVirtualHost + addr[:port]
+ Context: server config
+ Status: core
+ Compatibility: NameVirtualHost + is only available in Apache 1.3 and later + +

The NameVirtualHost directive is a required directive if you + want to configure name-based virtual + hosts.

+ +

Although addr can be hostname it is recommended + that you always use an IP address or wildcard, + e.g.

+ +
+ NameVirtualHost 111.22.33.44 +
+ With the NameVirtualHost directive you specify the IP address + on which the server will receive requests for the name-based + virtual hosts. This will usually be the address to which your + name-based virtual host names resolve. In cases where a + firewall or other proxy receives the requests and forwards them + on a different IP address to the server, you must specify the + IP address of the physical interface on the machine which will + be servicing the requests. If you have multiple name-based + hosts on multiple addresses, repeat the directive for each + address. + +

Note: the "main server" and any _default_ servers will + never be served for a request to a + NameVirtualHost IP Address (unless for some reason you specify + NameVirtualHost but then don't define any VirtualHosts for that + address).

+ +

Optionally you can specify a port number on which the + name-based virtual hosts should be used, e.g.

+ +
+ NameVirtualHost 111.22.33.44:8080 +
+ In Apache 1.3.13 and greater you can specify a * + for the addr. This creates a wildcard NameVirtualHost + which will match connections to any address that isn't + configured with a more specific NameVirtualHost directive or <VirtualHost> section. This is + useful if you want only name-based virtual hosts and you don't + want to hard-code the server's IP address into the + configuration file. + +

See also: Apache + Virtual Host documentation

+
+ +

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. This is the default + setting.
+ +
ExecCGI
+ +
+ Execution of CGI scripts is permitted.
+ +
FollowSymLinks
+ +
+ + The server will follow symbolic links in this + directory.
+ Note: even though the server follows the + symlink it does not change the pathname used to + match against <Directory> sections.
+ Note: this option gets ignored if set + inside a <Location> section.
+ +
Includes
+ +
+ Server-side includes are permitted.
+ +
IncludesNOEXEC
+ +
+ + Server-side includes are permitted, but the #exec command and + #exec CGI are disabled. It is still possible to #include + virtual CGI scripts from ScriptAliase'd directories.
+ +
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.
+ Note: this option gets ignored if set + inside a <Location> section.
+
+ Normally, if multiple 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> +
+ then only 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> +
+ then the options FollowSymLinks and + Includes are set for the /web/docs/spec directory. + + +

Note: Using -IncludesNOEXEC or + -Includes disables server-side includes completely + regardless of the previous setting.

+ +

The default in the absence of any other settings is + All.

+
+ +

PidFile directive

+ + Syntax: PidFile + file-path
+ 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).

+ + + The primary behavior 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. + (See also UseCanonicalName.) + +

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.

+
+ +

ProtocolReqCheck + directive

+ + Syntax: ProtocolReqCheck + on|off
+ Default: ProtocolReqCheck + on
+ Context: server config +
+ Status: core
+ Compatibility: + ProtocolReqCheck is only available in Apache 1.3.27 and later. + +

This directive enables strict checking of the Protocol field + in the Request line. Versions of Apache prior to 1.3.26 would + silently accept bogus Protocols (such as HTTP-1.1) + and assume HTTP/1.0. Instead, now the Protocol field + must be valid. If the pre-1.3.26 behavior is desired or required, + it can be enabled via setting ProtocolReqCheck off. +

+ +
+ +

Require directive

+ + Syntax: Require + entity-name [entity-name] ...
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: core + +

This directive selects which authenticated users can access + a resource. The allowed syntaxes are:

+ + + +

Require must be accompanied by AuthName and AuthType directives, and directives such + as AuthUserFile and AuthGroupFile (to define + users and groups) in order to work correctly. Example:

+ +
+ AuthType Basic
+ AuthName "Restricted Directory"
+ AuthUserFile /web/users
+ AuthGroupFile /web/groups
+ Require group admin
+ +
+ Access controls which are applied in this way are effective for + all methods. This is what is normally + desired. If you wish to apply access controls only to + specific methods, while leaving other methods unprotected, then + place the Require statement into a <Limit> section + +

See also Satisfy and mod_access.

+
+ +

ResourceConfig + directive

+ + Syntax: ResourceConfig + file-path|directory-path|wildcard-path
+ Default: ResourceConfig + conf/srm.conf
+ Context: server config, virtual + host
+ Status: core
+ Compatibility: The ability to + specify a directory, rather than a file name, is only available in + Apache 1.3.13 and later. + +

The server will read this file for more directives after + reading the httpd.conf file. File-path is relative to + the ServerRoot. This feature can be + disabled using:

+ +
+ ResourceConfig /dev/null +
+ Or, on Win32 servers, + +
+ ResourceConfig nul +
+

Historically, this file contained most directives except for + server configuration directives and <Directory> sections; in fact it + can now contain any server directive allowed in the server + config context. However, since Apache version 1.3.4, the + default srm.conf file which ships with Apache contains + only comments, and all directives are placed in the main server + configuration file, httpd.conf.

+ +

If ResourceConfig points to a directory, rather than + a file, Apache will read all files in that directory, and any + subdirectory, and parse those as configuration files. +

+

Alternatively you can use a wildcard to limit the scope; i.e + to only *.conf files. +

+

Note that by default any file in the specified + directory will be loaded as a configuration file. +

+

So make sure that you don't have stray files in + this directory by mistake, such as temporary files created by your + editor, for example.

+ +

See also AccessConfig.

+
+ +

RLimitCPU directive

+ + Syntax: RLimitCPU + number|max [number|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.

+ +

This applies to processes forked off from Apache children + servicing requests, not the Apache children themselves. This + includes CGI scripts and SSI exec commands, but not any + processes forked off from the Apache parent such as piped + logs.

+ +

CPU resource limits are expressed in seconds per + process.

+ +

See also RLimitMEM or RLimitNPROC.

+
+ +

RLimitMEM + directive

+ + Syntax: RLimitMEM + number|max [number|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.

+ +

This applies to processes forked off from Apache children + servicing requests, not the Apache children themselves. This + includes CGI scripts and SSI exec commands, but not any + processes forked off from the Apache parent such as piped + logs.

+ +

Memory resource limits are expressed in bytes per + process.

+ +

See also RLimitCPU or RLimitNPROC.

+
+ +

RLimitNPROC + directive

+ + Syntax: RLimitNPROC + number|max [number|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.

+ +

This applies to processes forked off from Apache children + servicing requests, not the Apache children themselves. This + includes CGI scripts and SSI exec commands, but not any + processes forked off from the Apache parent such as piped + logs.

+ +

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 directive

+ + Syntax: Satisfy any|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.

+ +

See also Require and Allow.

+
+ +

ScoreBoardFile + directive

+ + Syntax: ScoreBoardFile + file-path
+ 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 + -DUSE_SHMGET_SCOREBOARD to the EXTRA_CFLAGS + in your Configuration. This might work with some + 1.x installations, but won't work with all of them. (Prior to + 1.3b4, HAVE_SHMGET would have sufficed.)

+ +

SVR4 users should consider adding -DHAVE_SHMGET + -DUSE_SHMGET_SCOREBOARD 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. (Prior + to 1.3b4, HAVE_SHMGET would have sufficed.)

+ +

See Also: Stopping and Restarting Apache

+
+ +

ScriptInterpreterSource + directive

+ + Syntax: ScriptInterpreterSource + registry|script
+ Default: + ScriptInterpreterSource script
+ Context: directory, + .htaccess
+ Status: core (Windows only) + +

This directive is used to control how Apache 1.3.5 and later + finds the interpreter used to run CGI scripts. The default + technique is to use the interpreter pointed to by the #! line + in the script. Setting ScriptInterpreterSource registry will + cause the Windows Registry to be searched using the script file + extension (e.g., .pl) as a search key.

+
+ +

SendBufferSize + directive

+ + Syntax: SendBufferSize + bytes
+ Context: server config
+ 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 +
+ as users do not always mention that they are talking about the + server! +
+ +

ServerAlias + directive

+ Syntax: ServerAlias + hostname [hostname] ...
+ 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 name-based virtual + hosts.

+ +

Example:

+ + 
+    <VirtualHost *>
+    ServerName server.domain.com
+    ServerAlias server server2.domain.com server2
+    ...
+    </VirtualHost>
+
+ +

See also: Apache + Virtual Host documentation

+
+ +

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 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.example.com +
+ would be used if the canonical (main) name of the actual + machine were simple.example.com. + +

If you are using name-based virtual hosts, + the ServerName inside a <VirtualHost> + section specifies what hostname must appear in the request's + Host: header to match this virtual host.

+ +

See Also:
+ DNS Issues
+ Apache virtual host + documentation
+ UseCanonicalName
+ NameVirtualHost
+ ServerAlias
+

+
+ +

ServerPath + directive

+ Syntax: ServerPath + directory-path
+ 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 name-based virtual + hosts.

+ +

See also: Apache + Virtual Host documentation

+
+ +

ServerRoot + directive

+ + Syntax: ServerRoot + directory-path
+ Default: ServerRoot + /usr/local/apache
+ 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.

+ +

See also the + security tips for information on how to properly set + permissions on the ServerRoot.

+
+ +

ServerSignature directive

+ + Syntax: ServerSignature + On|Off|EMail
+ Default: ServerSignature + Off
+ Context: server config, virtual + host, directory, .htaccess
+ Status: core
+ Compatibility: ServerSignature + is only available in Apache 1.3 and later. + +

The ServerSignature directive allows the configuration of a + trailing footer line under server-generated documents (error + messages, mod_proxy ftp directory listings, mod_info output, + ...). The reason why you would want to enable such a footer + line is that in a chain of proxies, the user often has no + possibility to tell which of the chained servers actually + produced a returned error message.
+ The Off setting, which is the default, suppresses + the error line (and is therefore compatible with the behavior + of Apache-1.2 and below). The On setting simply + adds a line with the server version number and ServerName of the serving virtual host, + and the EMail setting additionally creates a + "mailto:" reference to the ServerAdmin of the referenced + document.

+
+ +

ServerTokens + directive

+ + Syntax: ServerTokens + Minimal|ProductOnly|OS|Full
+ Default: ServerTokens + Full
+ Context: server config
+ Status: core
+ Compatibility: ServerTokens is + only available in Apache 1.3 and later; the + ProductOnly keyword is only available in versions + later than 1.3.12 + +

This directive controls whether Server response + header field which is sent back to clients includes a + description of the generic OS-type of the server as well as + information about compiled-in modules.

+ +
+
ServerTokens Prod[uctOnly]
+ +
Server sends (e.g.): Server: + Apache
+ +
ServerTokens Min[imal]
+ +
Server sends (e.g.): Server: + Apache/1.3.0
+ +
ServerTokens OS
+ +
Server sends (e.g.): Server: Apache/1.3.0 + (Unix)
+ +
ServerTokens Full (or not specified)
+ +
Server sends (e.g.): Server: Apache/1.3.0 + (Unix) PHP/3.0 MyMod/1.2
+
+ +

This setting applies to the entire server, and cannot be + enabled or disabled on a virtualhost-by-virtualhost basis.

+
+ +

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.local or + /etc/rc3.d/....)
+
+ Inetd is the lesser used of the two options. For each http + connection received, a new copy of the server is started from + scratch; after the connection is complete, this program exits. + There is a high price to pay per connection, but for security + reasons, some admins prefer this option. Inetd mode is no longer recommended and does not + always work properly. Avoid it if at all possible. + +

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.

+
+ +

ShmemUIDisUser + directive

+ + Syntax: ShmemUIDisUser + on|off
+ Default: ShmemUIDisUser + off
+ Context: server config
+ Status: core
+ Compatibility: + ShmemUIDisUser directive is only available in Apache 1.3.27 and later. + +

The ShmemUIDisUser directive controls whether Apache will change + the uid and gid ownership of System V shared memory + based scoreboards to the server settings of User and + Group. Releases of Apache up to 1.3.26 would do + this by default. Since the child processes are already attached to the + shared memory segment, this is not required for normal usage of Apache and + so to prevent possible abuse, Apache will no longer do that. The old + behavior may be required for special cases, however, which can be implemented + by setting this directive to on.

+ +

This directive has no effect on non-System V based scoreboards, such as + mmap. +

+ +
+ +

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.

+ +

When running under Microsoft Windows, this directive has no + effect. There is always one child which handles all requests. + Within the child requests are handled by separate threads. The + ThreadsPerChild directive + controls the maximum number of child threads handling requests, + which will have a similar effect to the setting of + StartServers on Unix.

+ +

See also MinSpareServers and + MaxSpareServers.

+
+ +

ThreadsPerChild

+ Syntax: ThreadsPerChild + number
+ Default: ThreadsPerChild + 50
+ Context: server config
+ Status: core (Windows, + NetWare)
+ Compatibility: Available only with Apache 1.3 + and later with Windows + +

This directive tells the server how many threads it should + use. This is the maximum number of connections the server can + handle at once; be sure and set this number high enough for + your site if you get a lot of hits.

+ +

This directive has no effect on Unix systems. Unix users + should look at StartServers and MaxRequestsPerChild.

+
+ +

ThreadStackSize

+ Syntax: ThreadStackSize + number
+ Default: ThreadStackSize + 65536
+ Context: server config
+ Status: core (NetWare)
+ Compatibility: Available only with Apache 1.3 + and later with NetWare + +

This directive tells the server what stack size to use for + each of the running threads. If you ever get a stack overflow + you will need to bump this number to a higher setting.

+ +

This directive has no effect on other systems.

+
+ +

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:

+ +
    +
  1. The total amount of time it takes to receive a GET + request.
    2. + +
  2. The amount of time between receipt of TCP packets on a + POST or PUT request.
    3. + +
  3. The amount of time between ACKs on transmissions of TCP + packets in responses.
    4. +
+ We plan on making these separately configurable at some point + down the road. The timer used to default to 1200 before 1.2, + but has been lowered to 300 which is still far more than + necessary in most situations. It is not set any lower by + default because there may still be odd places in the code where + the timer is not reset when a packet is sent. +
+ +

UseCanonicalName directive

+ + Syntax: UseCanonicalName + on|off|dns
+ Default: UseCanonicalName + on
+ Context: server config, virtual + host, directory
+ Override: Options
+ Compatibility: UseCanonicalName + is only available in Apache 1.3 and later + +

In many situations Apache has to construct a + self-referential URL. That is, a URL which refers back + to the same server. With UseCanonicalName on (and + in all versions prior to 1.3) Apache will use the ServerName and Port + directives to construct the canonical name for the server. This + name is used in all self-referential URLs, and for the values + of SERVER_NAME and SERVER_PORT in + CGIs.

+ +

For example, if ServerName is set to + www.example.com and Port is set to + 9090, then the canonical name of the server is + www.example.com:9090. In the event that + Port has its default value of 80, the + :80 is omitted from the canonical name.

+ +

With UseCanonicalName off Apache will form + self-referential URLs using the hostname and port supplied by + the client if any are supplied (otherwise it will use the + canonical name, as defined above). These values are the same + that are used to implement name based virtual hosts, + and are available with the same clients. The CGI variables + SERVER_NAME and SERVER_PORT will be + constructed from the client supplied values as well.

+ +

An example where this may be useful is on an intranet server + where you have users connecting to the machine using short + names such as www. You'll notice that if the users + type a shortname, and a URL which is a directory, such as + http://www/splat, without the trailing + slash then Apache will redirect them to + http://www.domain.com/splat/. If you have + authentication enabled, this will cause the user to have to + authenticate twice (once for www and once again + for www.domain.com -- see the FAQ on this subject for + more information). But if UseCanonicalName + is set off, then Apache will redirect to + http://www/splat/.

+ +

There is a third option, UseCanonicalName DNS, + which is intended for use with mass IP-based virtual hosting to + support ancient clients that do not provide a + Host: header. With this option Apache does a + reverse DNS lookup on the server IP address that the client + connected to in order to work out self-referential URLs.

+ +

Warning: if CGIs make assumptions about the + values of SERVER_NAME they may be broken by this + option. The client is essentially free to give whatever value + they want as a hostname. But if the CGI is only using + SERVER_NAME to construct self-referential URLs + then it should be just fine.

+ +

See also: ServerName, Port

+
+ +

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.
+
+ The user should have no privileges which result in it being + able to access files which are not intended to be visible to + the outside world, and similarly, the user should not be able + to execute code which is not meant for httpd requests. It is + recommended that you set up a new user and group specifically + for running the server. Some admins use user + nobody, but this is not always possible or + desirable. For example mod_proxy's cache, when enabled, must be + accessible to this user (see the CacheRoot + directive). + +

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] [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, + different port number or a different host name for the server, + in the former 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). + +

You can specify more than one IP address. This is useful if + a machine responds to the same name on two different + interfaces. For example, if you have a VirtualHost that is + available to hosts on an internal (intranet) as well as + external (internet) network. Example:

+ +
+ <VirtualHost 192.168.1.2 204.255.176.199>
+ DocumentRoot /www/docs/host.foo.com
+ ServerName host.foo.com
+ ServerAlias host
+ </VirtualHost> +
+ 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.

+ +

NOTE: The use of <VirtualHost> does + not affect what addresses Apache listens on. + You may need to ensure that Apache is listening on the correct + addresses using either BindAddress + or Listen.

+ +

See also: Apache + Virtual Host documentation
+ See also: Warnings about DNS and + Apache
+ See also: Setting + which addresses and ports Apache uses
+ See also: How + Directory, Location and Files sections work for an + explanation of how these different sections are combined when a + request is received

+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/core.html.html b/usr.sbin/httpd/htdocs/manual/mod/core.html.html deleted file mode 100644 index dcfd27616f6..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/core.html.html +++ /dev/null @@ -1,4140 +0,0 @@ - - - - - - - - Apache Core Features - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Apache Core Features

- -

These configuration parameters control the core Apache - features, and are always available.

- -

Directives

- - -
- -

AcceptFilter - directive

- - Syntax: AcceptFilter - on|off
- Default: AcceptFilter - on
- Context: server configt
- Status: core
- Compatibility: AcceptFilter is - available in Apache 1.3.22 and later - -

AcceptFilter controls a BSD specific filter - optimization. It is compiled in by default - and switched on by - default if your system supports it (setsocketopt() option - SO_ACCEPTFILTER). Currently only FreeBSD supports this.

- -

See the filter section on performance hints for more - information.

- -

The compile time flag AP_ACCEPTFILTER_OFF can - be used to change the default to 'off'. httpd -V - and httpd -L will show compile time defaults and - whether or not SO_ACCEPTFILTER was defined during the - compile.

- -
- -

AcceptMutex - directive

- - Syntax: AcceptMutex - uslock|pthread|sysvsem|fcntl|flock|os2sem|tpfcore|none|default
- Default: AcceptMutex - default
- Context: server config
- Status: core
- Compatibility: AcceptMutex is - available in Apache 1.3.21 and later. - -

AcceptMutex controls which accept() mutex - method Apache will use. Not all methods are available on all - platforms, since the suite of methods is determined at - compile-time. For a list of which methods are available for - your particular build, the httpd -V command line - option will list them out.

- -

The compile time flags -D - HAVE_METHOD_SERIALIZED_ACCEPT can be used to add - different methods to your build, or one can edit the - include/ap_config.h file for your particular - platform.

- -

This directive has no effect on Microsoft Windows.

- -

See the performance tuning - guide for more information.

- -
- -

AccessConfig - directive

- - Syntax: AccessConfig - file-path|directory-path|wildcard-path
- Default: AccessConfig - conf/access.conf
- Context: server config, virtual - host
- Status: core
- Compatibility: The ability to - specify a directory, rather than a file name, is only available in - Apache 1.3.13 and later. This directive will be eliminated in version - 2.0. - -

The server will read this file for more directives after - reading the ResourceConfig file. - File-path is relative to the ServerRoot. This feature can be disabled - using:

- -
- AccessConfig /dev/null -
- Or, on Win32 servers, - -
- AccessConfig nul -
- Historically, this file only contained <Directory> sections; in fact it - can now contain any server directive allowed in the server - config context. However, since Apache version 1.3.4, - the default access.conf file which ships with - Apache contains only comments, and all directives are placed - in the main server configuration file, httpd.conf. - -

If AccessConfig points to a directory, rather than a - file, Apache will read all files in that directory, and any - subdirectory, and parse those as configuration files. -

-

Alternatively you can use a wildcard to limit the scope; i.e - to only *.conf files. -

-

Note that by default any file in the specified - directory will be loaded as a configuration file. -

-

- So make sure that you don't have stray files in - this directory by mistake, such as temporary files created by your - editor, for example.

- -

See also: Include and ResourceConfig.

-
- -

AccessFileName - directive

- - Syntax: AccessFileName - filename [filename] ...
- Default: AccessFileName - .htaccess
- Context: server config, virtual - host
- Status: core
- Compatibility: AccessFileName - can accept more than one filename only in Apache 1.3 and later - -

When returning a document to the client the server looks for - the first existing access control file from this list of names - in every directory of the path to the document, if access - control files are enabled for that directory. For example:

- -
- AccessFileName .acl -
- before returning the document /usr/local/web/index.html, the - server will read /.acl, /usr/.acl, /usr/local/.acl and - /usr/local/web/.acl for directives, unless they have been - disabled with - -
- <Directory />
- AllowOverride None
- </Directory> -
- -

See Also: AllowOverride and Configuration Files

-
- -

AddDefaultCharset directive

- Syntax: AddDefaultCharset - On|Off|charset
- Context: all
- Status: core
- Default: - AddDefaultCharset Off
- Compatibility: - AddDefaultCharset is only available in Apache 1.3.12 and later - -

This directive specifies the name of the character set that - will be added to any response that does not have any parameter - on the content type in the HTTP headers. This will override any - character set specified in the body of the document via a - META tag. A setting of AddDefaultCharset - Off disables this functionality. AddDefaultCharset - On enables Apache's internal default charset of - iso-8859-1 as required by the directive. You can - also specify an alternate charset to be used.

- -

For example:

- -
- AddDefaultCharset utf-8 -
- -

Note: This will not have any effect on the - Content-Type and character set for default Apache-generated - status pages (such as '404 Not Found' or '301 Moved Permanently') - because those have an actual character set (that in which the - hard-coded page content is written) and don't need to have a default - applied.

- -
- -

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.

- -

For example:

- -
- AddModule mod_include.c -
- -

The ordering of AddModule lines is important. - Modules are listed in reverse priority order --- the ones that come - later can override the behavior of those that come earlier. This - can have visible effects; for instance, if UserDir followed Alias, - you couldn't alias out a particular user's home directory. For - more information and a recommended ordering, see - src/Configuration.tmpl in the Apache source - distribution.

- -

See also: ClearModuleList and LoadModule

-
- -

AllowOverride - directive

- - Syntax: AllowOverride - All|None|directive-type [directive-type] - ...
- 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.

- -

Note: AllowOverride is only - valid in <Directory> sections, not in <Location> or - <Files> sections, as implied by the Context - section above.

- -

When this directive is set to None, then - .htaccess files are completely ignored. In this case, the - server will not even attempt to read .htaccess files in the - filesystem.

- -

When this directive is set to All, then any - directive which has the .htaccess Context is allowed in - .htaccess files.

- -

The directive-type can be one of the following - groupings of directives.

- -
-
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).
-
- -

Example:

-
AllowOverride AuthConfig Indexes
- -

See Also: AccessFileName and Configuration Files

-
- -

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. - AuthName takes a single argument; if the realm - name contains spaces, it must be enclosed in quotation marks. - It must be accompanied by AuthType and - Require directives, and directives such - as AuthUserFile and AuthGroupFile to - work.

- -

For example:

- -
AuthName "Top Secret"
- -

The string provided for the AuthName is what will - appear in the password dialog provided by most browsers.

- -

See also: Authentication, Authorization, and - Access Control

-
- -

AuthType - directive

- - Syntax: AuthType - Basic|Digest
- Context: directory, - .htaccess
- Override: AuthConfig
- Status: core - -

This directive selects the type of user authentication for a - directory. Only Basic and Digest are - currently implemented. - - It must be accompanied by AuthName and - Require directives, and directives such - as AuthUserFile and AuthGroupFile to - work.

- -

See also: Authentication, Authorization, and - Access Control

-
- -

BindAddress - directive

- - Syntax: BindAddress - *|IP-address|domain-name
- Default: BindAddress - *
- Context: server config
- Status: core
- Compatibility: BindAddress is - deprecated and will be eliminated in Apache 2.0. - -

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. If the argument to this directive is *, - then the server will listen for connections on every IP - address. Otherwise, the server can listen to only a specific - IP-address or a fully-qualified Internet - domain-name.

- -

For example:

- - BindAddress 192.168.15.48
- -

Only one BindAddress directive can be used.

- -

This directive is deprecated and will be eliminated in - Apache 2.0. Equivalent functionality and more control over the - address and ports Apache listens to is available using the - Listen - directive.

- -

BindAddress can be used as an alternative - method for supporting virtual hosts - using multiple independent servers, instead of using <VirtualHost> - sections.

- -

See Also: DNS - Issues
- See Also: Setting - which addresses and ports Apache uses

-
- -

BS2000Account - directive

- - Syntax: BS2000Account - account
- Default: none
- Context: server config
- Status: core
- Compatibility: BS2000Account is - only available for BS2000 machines, as of Apache 1.3 and later. - - -

The BS2000Account directive is available for - BS2000 hosts only. It must be used to define the account number - for the non-privileged apache server user (which was configured - using the User directive). This is required - by the BS2000 POSIX subsystem (to change the underlying BS2000 - task environment by performing a sub-LOGON) to prevent CGI - scripts from accessing resources of the privileged account - which started the server, usually SYSROOT.
- Only one BS2000Account directive can be used.

- -
- -

CGICommandArgs - directive

- - Syntax: CGICommandArgs On|Off
- Default: CGICommandArgs On
- Context: directory, .htaccess
- Override: Options
- Status: core
- Compatibility: Available in Apache - 1.3.24 and later. - -

Way back when the internet was a safer, more naive place, it - was convenient for the server to take a query string that did not - contain an '=' sign and to parse and pass it to a CGI program as - command line args. For example, <IsIndex> - generated searches often work in this way. The default behavior - in Apache is to maintain this behavior for backwards - compatibility, although it is generally regarded as unsafe - practice today. Most CGI programs do not take command line - parameters, but among those that do, many are unaware of this - method of passing arguments and are therefore vulnerable to - malicious clients passing unsafe material in this way. Setting - CGICommandArgs Off is recommended to protect such - scripts with little loss in functionality.

- -
- -

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.

- -

See also: AddModule and LoadModule

- -
- -

ContentDigest - directive

- - Syntax: ContentDigest - on|off
- Default: ContentDigest - off
- Context: server config, virtual - host, directory, .htaccess
- Override: Options
- Status: experimental
- Compatibility: ContentDigest is - only available in Apache 1.1 and later - -

This directive enables the generation of - Content-MD5 headers as defined in RFC1864 - respectively RFC2068.

- -

MD5 is an algorithm for computing a "message digest" - (sometimes called "fingerprint") of arbitrary-length data, with - a high degree of confidence that any alterations in the data - will be reflected in alterations in the message digest.

- -

The Content-MD5 header provides an end-to-end - message integrity check (MIC) of the entity-body. A proxy or - client may check this header for detecting accidental - modification of the entity-body in transit. Example header:

-
-   Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==
-
- -

Note that this can cause performance problems on your server - since the message digest is computed on every request (the - values are not cached).

- -

Content-MD5 is only sent for documents served - by the core, and not by any module. For example, SSI documents, - output from CGI scripts, and byte range responses do not have - this header.

-
- -

CoreDumpDirectory directive

- - Syntax: CoreDumpDirectory - directory-path
- Default: the same location as - ServerRoot
- Context: server config
- Status: core - -

This controls the directory to which Apache attempts to - switch before dumping core. The default is in the ServerRoot directory, however since this - should not be writable by the user the server runs as, core - dumps won't normally get written. If you want a core dump for - debugging, you can use this directive to place it in a - different location.

- -

For example:

- -
- CoreDumpDirectory /tmp -
- -
- -

DefaultType - directive

- - Syntax: DefaultType - MIME-type
- Default: DefaultType - text/plain
- 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 -
- would be appropriate for a directory which contained many gif - images with filenames missing the .gif extension. - -

See also: AddType and TypesConfig.

- -
- -

<Directory> - directive

- - Syntax: <Directory - directory-path|proxy:url-path> - ... </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-path 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. - As of Apache 1.3, you may also use `[ ]' character ranges like - in the shell. Also as of Apache 1.3 none of the wildcards match - a `/' character, which more closely mimics the behavior of - Unix shells. 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 (non-regular expression) 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> -
- for access to the document /home/web/dir/doc.html - the steps are: - - - -

Regular expression directory sections are handled slightly - differently by Apache 1.2 and 1.3. In Apache 1.2 they are - interspersed with the normal directory sections and applied in - the order they appear in the configuration file. They are - applied only once, and apply when the shortest match possible - occurs. In Apache 1.3 regular expressions are not considered - until after all of the normal sections have been applied. Then - all of the regular expressions are tested in the order they - appeared in the configuration file. For example, with

- -
- <Directory ~ abc$>
- ... directives here ...
- </Directory>
- -
- Suppose that the filename being accessed is - /home/abc/public_html/abc/index.html. The server - considers each of /, /home, - /home/abc, /home/abc/public_html, and - /home/abc/public_html/abc in that order. In Apache - 1.2, when /home/abc is considered, the regular - expression will match and be applied. In Apache 1.3 the regular - expression isn't considered at all at that point in the tree. - It won't be considered until after all normal - <Directory>s and .htaccess files have been - applied. Then the regular expression will match on - /home/abc/public_html/abc and be applied. - -

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.

- <Directory> directives cannot nest, and cannot appear in - a <Limit> or <LimitExcept> section. - -

If you have mod_proxy enabled, you - can use the proxy: syntax to apply configuration - directives to proxied content. The syntax for this is to specify the - proxied URLs to which you wish to apply the configuration, or to - specify * to apply to all proxied content:

- -

To apply to all proxied content:

- - 
-   <Directory proxy:*>
-     ... directives here ...
-   </Directory>
-
- -

To apply to just a subset of proxied content:

- - 
-   <Directory proxy:http://www.example.com/>
-     ... directives here ...
-   </Directory>
-
- -

See also: How - Directory, Location and Files sections work for an - explanation of how these different sections are combined when a - request is received

-

See also: DirectoryMatch

-
- -

<DirectoryMatch>

- Syntax: <DirectoryMatch - regex> ... </DirectoryMatch>
- Context: server config, virtual - host
- Status: Core.
- Compatibility: Available in - Apache 1.3 and later - -

<DirectoryMatch> and </DirectoryMatch> are used - to enclose a group of directives which will apply only to the - named directory and sub-directories of that directory, the same - as <Directory>. However, it - takes as an argument a regular expression. For example:

-
-   <DirectoryMatch "^/www/.*/[0-9]{3}">
-
- -

would match directories in /www/ that consisted of three - numbers.

- -

See Also: <Directory> for a description of - how regular expressions are mixed in with normal - <Directory>s.
- See also: How - Directory, Location and Files sections work for an - explanation of how these different sections are combined when a - request is received

-
- -

DocumentRoot - directive

- - Syntax: DocumentRoot - directory-path
- Default: DocumentRoot - /usr/local/apache/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/web -
- then an access to - http://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.

-
- -

EBCDICConvert

- - Syntax: EBCDICConvert - On|Off[=direction] extension - [extension] ...
- Context: server config, virtual - host, directory, .htaccess
- Status: core
- Override: FileInfo
- Compatibility: The configurable - EBCDIC conversion is only available in Apache 1.3.19 and later, - and on EBCDIC based platforms. - -

The EBCDICConvert directive maps the given filename - extensions to the specified conversion setting (On - or Off). File extensions may be specified with or - without a leading dot.

- -

If the optional format On=direction (or - Off=direction) is used, where - direction is one of In, Out or - InOut, then the directive only applies to the - specified transfer direction (In: uploaded content - in a PUT or POST request, Out: returned content in - a GET or POST request, and InOut: conversion in - both directions).
- Otherwise, InOut (conversion in both directions) - is implied.

- -

Conversion configuration based on file extension is tested - prior to configuration based on MIME type, to allow for generic - MIME based rules to be overridden by a more specific file - extension (several file extensions may exist for the same MIME - type).

- -

Example:
- With a configuration like the following, the normal - *.html files contain HTML text in EBCDIC encoding, - while *.ahtml files contain HTML text in ASCII - encoding:

-
-    # *.html and *.ahtml contain HTML text:
-    AddType  text/html  .html .ahtml
-
-    # *.ahtml is not converted (contains ASCII text already):
-    EBCDICConvert       Off .ahtml
-
-    # All other text/html files presumably contain EBCDIC text:
-    EBCDICConvertByType On  text/html
-
-
-
- - -

See also: EBCDICConvertByType

-
- -

EBCDICConvertByType

- - Syntax: EBCDICConvertByType - On|Off[=direction] mimetype - [mimetype] ...
- Context: server config, virtual - host, directory, .htaccess
- Status: core
- Override: FileInfo
- Compatibility: The configurable - EBCDIC conversion is only available in Apache 1.3.19 and later, - and on EBCDIC based platforms. - -

The EBCDICConvertByType directive maps the given MIME type - (optionally containing wildcards) to the specified conversion - setting (On or Off).

- -

If the optional format On=direction (or - Off=direction) is used, where - direction is one of In, Out or - InOut, then the directive only applies to the - specified transfer direction (In: uploaded content - in a PUT or POST request, Out: returned content in - a GET or POST request, and InOut: conversion in - both directions).
- Otherwise, InOut (conversion in both directions) - is implied.

- -

Example:
- A useful standard configuration should at least contain the - following defaults:

-
-    # All text documents are stored as EBCDIC files:
-    EBCDICConvertByType On  text/* message/* multipart/*
-    EBCDICConvertByType On  application/x-www-form-urlencoded \
-                model/vrml application/postscript
-    # All other files are assumed to be binary:
-    EBCDICConvertByType Off */*
-
- If you serve ASCII documents only, for example from an NFS - mounted unix server, use: -
-    # All documents are ASCII already:
-    EBCDICConvertByType Off */*
-
- -

See also: EBCDICConvert

-
- -

EBCDICKludge

- - Syntax: EBCDICKludge - On|Off
- Default: EBCDICKludge - Off
- Context: server config, virtual - host, directory, .htaccess
- Status: core
- Override: FileInfo
- Compatibility: EBCDICKludge is - only available in Apache 1.3.19 and later, and on EBCDIC based - platforms. It is deprecated and will be withdrawn in a future - version.
- - -

The EBCDICKludge is provided for the backward compatible - behavior with apache versions 1.3.0 through 1.3.18. In these - versions, all files with MIME types starting with "text/", - "message/" or "multipart/" or with type - "application/x-www-form-urlencoded" would be converted by - default, all other documents were returned unconverted. Only if - a MIME type "text/x-ascii-subtype" - was configured for a certain document, the document was assumed - to be in ASCII format already, and was not converted again. - Instead, the "x-ascii-" was removed from - the type, resulting in the MIME type - "text/subtype" being returned for the - document.

- -

If the EBCDICKludge directive is set to On, and - if none of the file extensions configured with the EBCDICConvert directive matches in - the current context, then the server tests for a MIME type of - the format - type/x-ascii-subtype. If the - document has such a type, then the - "x-ascii-" substring is removed and the - conversion set to Off. This allows for overriding - the implicit assumption that all text files are stored in - EBCDIC format, for example when serving documents from an NFS - mounted directory with ASCII documents.
- By using the EBCDICKludge, there is no way to force one of the - other MIME types (e.g., model/vrml) to be treated as - an EBCDIC text file. Use of the EBCDICConvertByType directive - mentioned above is the preferred way to configure such a - conversion. (Before Apache version 1.3.19, there was no way at - all to force these binary documents to be treated as EBCDIC - text files.)

- -

See also: EBCDICConvert, EBCDICConvertByType

-
- -

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,

- -
    -
  1. output a simple hardcoded error message
    2. - -
  2. output a customized message
    3. - -
  3. redirect to a local URL-path to handle the - problem/error
    4. - -
  4. redirect to an external URL to handle the - problem/error
    5. -
- -

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 - double-quote character ("), 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 the client will not - receive the original error status code, but instead will - receive a redirect status code. This in turn can confuse web - robots and other clients which try to determine if a URL is - valid using the status code. In addition, if you use a remote - URL in an ErrorDocument 401, the client will not - know to prompt the user for a password since it will not - receive the 401 status code. Therefore, if you use an - "ErrorDocument 401" directive then it must refer to a local - document.

- -

See Also: documentation of - customizable responses. See the HTTP - specification for a complete list of the status codes and their - meanings.

-
- -

ErrorLog - directive

- - Syntax: ErrorLog - file-path|syslog[:facility]
- Default: ErrorLog - logs/error_log (Unix)
- Default: ErrorLog - logs/error.log (Windows and OS/2)
- 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 - file-path does not begin with a slash (/) then it is - assumed to be relative to the ServerRoot. If the file-path - begins with a pipe (|) then it is assumed to be a command to - spawn to handle the error log.

- -

Examples

- -

ErrorLog logs/vhost1.error

- - or - -

ErrorLog |/usr/local/bin/errorlog.pl

- -

Apache 1.3 and above: Using - syslog instead of a filename enables logging via - syslogd(8) if the system supports it. The default is to use - syslog facility local7, but you can override this - by using the syslog:facility syntax where - facility can be one of the names usually documented in - syslog(1).

- -

For example:

- -

ErrorLog syslog

- - or - -

ErrorLog syslog:user

- -

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: LogLevel - and Apache Log Files

-
- -

FileETag directive

- Syntax: FileETag - component ...
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: core
- Compatibility: only available - in Apache 1.3.23 versions and later. - -

- The FileETag directive configures the file attributes that are - used to create the ETag (entity tag) response header field - when the document is based on a file. - (The ETag value is used in cache management to save network - bandwidth.) In Apache 1.3.22 and earlier, the ETag value was - always formed from the file's inode, size, and last-modified - time (mtime). The FileETag directive allows you to choose - which of these -- if any -- should be used. The recognized - keywords are: -

-
-
INode
-
The file's i-node number will be included in the calculation
-
MTime
-
The date and time the file was last modified will be included
-
Size
-
The number of bytes in the file will be included
-
All
-
All available fields will be used (equivalent to - 'FileETag INode MTime Size')
-
None
-
If a document is file-based, no ETag field will be included in the - response
-
-

- The INode, MTime, and Size keywords may be prefixed with either '+' - or '-', which allow changes to be made to the default setting - inherited from a broader scope. Any keyword appearing without - such a prefix immediately and completely cancels the inherited - setting. -

-

- If a directory's configuration includes - 'FileETag INode MTime Size', and a - subdirectory's includes 'FileETag -INode', - the setting for that subdirectory (which will be inherited by - any sub-subdirectories that don't override it) will be equivalent to - 'FileETag MTime Size'. -

-
- -

<Files> directive

- 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. The directives given - within this section will be applied to any object with a - basename (last component of filename) matching the specified - filename. <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. Note that - <Files> can be nested inside <Directory> sections - to restrict the portion of the filesystem they apply to.

- -

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. In Apache - 1.3 and later, <FilesMatch> is - preferred, however. - -

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. - For example, to password protect a single file within a - particular directory, you might add the following to your - .htaccess file:

- - 
-    <Files admin.cgi>
-    Require group admin
-    </Files>
- -

Remember that directives apply to subdirectories as well, so this - will also protect files called admin.cgi in - subdirectories, unless specifically overridden.

- -

(See Require for details on using the - Require directive)

- -

See also: How - Directory, Location and Files sections work for an - explanation of how these different sections are combined when a - request is received

-
- -

<FilesMatch>

- Syntax: <FilesMatch - regex> ... </FilesMatch>
- Context: server config, virtual - host, .htaccess
- Status: core
- Compatibility: only available - in Apache 1.3 and above. - -

The <FilesMatch> directive provides for access control - by filename, just as the <Files> - directive does. However, it accepts a regular expression. For - example:

-
-   <FilesMatch "\.(gif|jpe?g|png)$">
-
- -

would match most common Internet graphics formats.

- See also: How - Directory, Location and Files sections work for an - explanation of how these different sections are combined when a - request is received -
- -

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.
-
-

It is recommended that you set up a new group specifically for - running the server. Some admins use user nobody, - but this is not always possible or desirable.

- -

Example:

- - Group www-group - -

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 - on|off|double
- Default: HostnameLookups - off
- Context: server config, virtual - host, directory
- Status: core
- Compatibility: - double available only in Apache 1.3 and - above.
- Compatibility: Default was - on prior to Apache 1.3. - -

This directive enables DNS lookups so that host names can be - logged (and passed to CGIs/SSIs in REMOTE_HOST). - The value double refers to doing double-reverse - DNS. That is, after a reverse lookup is performed, a forward - lookup is then performed on that result. At least one of the ip - addresses in the forward lookup must match the original - address. (In "tcpwrappers" terminology this is called - PARANOID.)

- -

Regardless of the setting, when mod_access is used for controlling - access by hostname, a double reverse lookup will be performed. - This is necessary for security. Note that the result of this - double-reverse isn't generally available unless you set - HostnameLookups double. For example, if only - HostnameLookups on and a request is made to an - object that is protected by hostname restrictions, regardless - of whether the double-reverse fails or not, CGIs will still be - passed the single-reverse result in - REMOTE_HOST.

- -

The default for this directive was previously - on in versions of Apache prior to 1.3. It was - changed to off in order to save the network - traffic for those sites that don't truly need the reverse - lookups done. It is also better for the end users because they - don't have to suffer the extra latency that a lookup entails. - Heavily loaded sites should leave 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 - on|off
- Default: IdentityCheck - off
- Context: server config, virtual - host, directory
- 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.

- -

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.

-
- -

<IfDefine> - directive

- Syntax: <IfDefine - [!]parameter-name> ... - </IfDefine>
- Default: None
- Context: all
- Status: Core
- Compatibility: <IfDefine> - is only available in 1.3.1 and later. - -

The <IfDefine test>...</IfDefine> - section is used to mark directives that are conditional. The - directives within an IfDefine 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 <IfDefine> section directive - can be one of two forms:

- - - -

In the former case, the directives between the start and end - markers are only processed if the parameter named - parameter-name is defined. The second format reverses - the test, and only processes the directives if - parameter-name is not defined.

- -

The parameter-name argument is a define as given on - the httpd command line via - -Dparameter-, at the time the server was - started.

- -

<IfDefine> sections are nest-able, which can be used - to implement simple multiple-parameter tests. Example:

-
-  $ httpd -DReverseProxy ...
-
-  # httpd.conf
-  <IfDefine ReverseProxy>
-  LoadModule rewrite_module libexec/mod_rewrite.so
-  LoadModule proxy_module   libexec/libproxy.so
-  </IfDefine>
-
-
- -

<IfModule> - directive

- Syntax: <IfModule - [!]module-name> ... - </IfModule>
- Default: None
- Context: all
- Status: Core
- Compatibility: IfModule 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:

- - - -

In the former case, the directives between the start and end - markers are only processed if the module named module - name is included in Apache -- either compiled in or - dynamically loaded using LoadModule. The second format - reverses the test, and only processes the directives if module - name is not included.

- -

The module name argument is 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.

-
- -

Include directive

- Syntax: Include - file-path|directory-path|wildcard-path
- Context: server config
- Status: Core
- Compatibility: Include is only - available in Apache 1.3 and later. - -

This directive allows inclusion of other configuration files - from within the server configuration files.

- -

The file path specified may be a fully qualified path (i.e. - starting with a slash), or may be relative to the - ServerRoot directory.

- -

New in Apache 1.3.13 is the feature that if - Include points to a directory, rather than a file, - Apache will read all files in that directory, and any - subdirectory, and parse those as configuration files.

-

By using a wildcard this can be further limited to, say, - just the '*.conf' files. -

-

Examples:

-
- Include /usr/local/apache/conf/ssl.conf
- Include /usr/local/apache/conf/vhosts/ - -
- -

Or, providing paths relative to your ServerRoot - directory:

- -
- Include conf/ssl.conf
- Include conf/vhosts/ - -
- -

Make sure that an included directory does not contain any stray - files, such as editor temporary files, for example, as Apache will - attempt to read them in and use the contents as configuration - directives, which may cause the server to fail on start up. - Running apachectl configtest will give you a list of - the files that are being processed during the configuration - check:

- -
-root@host# apachectl configtest
- Processing config directory: /usr/local/apache/conf/vhosts
- Processing config file: /usr/local/apache/conf/vhosts/vhost1
- Processing config file: /usr/local/apache/conf/vhosts/vhost2
-Syntax OK
-
- -

This will help in verifying that you are getting only the files - that you intended as part of your configuration.

- -

See also: apachectl

- -
- -

KeepAlive - directive

- 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. - -

The Keep-Alive extension to HTTP/1.0 and the persistent - connection feature of HTTP/1.1 provide long-lived HTTP sessions - which allow multiple requests to be sent over the same TCP - connection. In some cases this has been shown to result in an - almost 50% speedup in latency times for HTML documents with - many images. To enable Keep-Alive connections in Apache 1.2 and - later, set KeepAlive On.

- -

For HTTP/1.0 clients, Keep-Alive connections will only be - used if they are specifically requested by a client. In - addition, a Keep-Alive connection with an HTTP/1.0 client can - only be used when the length of the content is known in - advance. This implies that dynamic content such as CGI output, - SSI pages, and server-generated directory listings will - generally not use Keep-Alive connections to HTTP/1.0 clients. - For HTTP/1.1 clients, persistent connections are the default - unless otherwise specified. If the client requests it, chunked - encoding will be used in order to send content of unknown - length over persistent connections.

- -

Apache 1.1 only: Set max-requests - to the maximum number of requests you want Apache to entertain - per connection. A limit is imposed to prevent a client from - hogging your server resources. Set this to 0 to - disable support. In Apache 1.2 and 1.3, this is controlled - through the MaxKeepAliveRequests directive instead.

- -

See also MaxKeepAliveRequests.

-
- -

KeepAliveTimeout directive

- 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.

- -

Setting KeepAliveTimeout to a high value may - cause performance problems in heavily loaded servers. The - higher the timeout, the more server processes will be kept - occupied waiting on connections with idle clients.

-
- -

<Limit> directive

- - Syntax: <Limit - method [method] ... > ... - </Limit>
- Context: any
- Status: core - -

Access controls are normally effective for - all access methods, and this is the usual - desired behavior. In the general case, access control - directives should not be placed within a - <limit> section.

- -

The purpose of the <Limit> directive is to restrict - the effect of the access controls to the nominated HTTP - methods. For all other methods, the access restrictions that - are enclosed in the <Limit> bracket will have no - effect. The following example applies the access - control only to the methods POST, PUT, and DELETE, leaving all - other methods unprotected:

- -
- <Limit POST PUT DELETE>
- Require valid-user
- </Limit> -
-

The method names listed can be one or more of: GET, POST, PUT, - DELETE, CONNECT, OPTIONS, PATCH, PROPFIND, PROPPATCH, - MKCOL, COPY, MOVE, LOCK, and UNLOCK. The method name is - case-sensitive. If GET is used it will also restrict - HEAD requests. The TRACE method cannot be limited.

- -

Warning: A <LimitExcept> section should - always be used in preference to a <Limit> section when restricting access, - since a <LimitExcept> section - provides protection against arbitrary methods.

- -
- -

<LimitExcept> - directive

- - Syntax: <LimitExcept - method [method] ... > ... - </LimitExcept>
- Context: any
- Status: core
- Compatibility: Available in - Apache 1.3.5 and later - -

<LimitExcept> and </LimitExcept> are used to - enclose a group of access control directives which will then - apply to any HTTP access method not listed in - the arguments; i.e., it is the opposite of a <Limit> section and can be used to - control both standard and nonstandard/unrecognized methods. See - the documentation for <Limit> for - more details.

- -

For example:

- - 
-    <LimitExcept POST GET>
-    Require valid-user
-    </LimitExcept>
-
- -
- -

LimitInternalRecursion directive

- - Syntax: LimitInternalRecursion - number [number]
- Default: LimitInternalRecursion - 20
- Context: server config, virtual host
- Status: core
- Compatibility: LimitInternalRecursion - is only available in Apache 1.3.28 and later. - -

An internal redirect happens, for example, when using the Action directive, which internally - redirects the original request to a CGI script. A subrequest is Apache's - mechanism to find out what would happen for some URI if it were requested. - For example, mod_dir uses subrequests to look - for the files listed in the DirectoryIndex - directive.

- -

LimitInternalRecursion prevents the server - from crashing when entering an infinite loop of internal redirects or - subrequests. Such loops are usually caused by misconfigurations.

- -

The directive stores two different limits, which are evaluated on - per-request basis. The first number is the maximum number of - internal redirects, that may follow each other. The second number - determines, how deep subrequests may be nested. If you specify only one - number, it will be assigned to both limits. A value of - 0 means "unlimited".

- -

Example

- 
-    LimitInternalRecursion 5
-
- -
- -

LimitRequestBody directive

- - Syntax: LimitRequestBody - bytes
- Default: LimitRequestBody - 0
- Context: server config, virtual - host, directory, .htaccess
- Status: core
- Compatibility: LimitRequestBody - is only available in Apache 1.3.2 and later. - -

This directive specifies the number of bytes from 0 - (meaning unlimited) to 2147483647 (2GB) that are allowed in a - request body.

- -

The LimitRequestBody directive allows the user to set a - limit on the allowed size of an HTTP request message body - within the context in which the directive is given (server, - per-directory, per-file or per-location). If the client request - exceeds that limit, the server will return an error response - instead of servicing the request. The size of a normal request - message body will vary greatly depending on the nature of the - resource and the methods allowed on that resource. CGI scripts - typically use the message body for passing form information to - the server. Implementations of the PUT method will require a - value at least as large as any representation that the server - wishes to accept for that resource.

- -

This directive gives the server administrator greater - control over abnormal client request behavior, which may be - useful for avoiding some forms of denial-of-service - attacks.

- -

If, for example, you are permitting file upload to a particular - location, and wich to limit the size of the uploaded file to 100K, - you might use the following directive:

- - 
LimitRequestBody 102400
- -
- -

LimitRequestFields directive

- - Syntax: LimitRequestFields - number
- Default: - LimitRequestFields 100
- Context: server config
- Status: core
- Compatibility: - LimitRequestFields is only available in Apache 1.3.2 and later. - - -

Number is an integer from 0 (meaning unlimited) to - 32767. The default value is defined by the compile-time - constant DEFAULT_LIMIT_REQUEST_FIELDS (100 as - distributed).

- -

The LimitRequestFields directive allows the server - administrator to modify the limit on the number of request - header fields allowed in an HTTP request. A server needs this - value to be larger than the number of fields that a normal - client request might include. The number of request header - fields used by a client rarely exceeds 20, but this may vary - among different client implementations, often depending upon - the extent to which a user has configured their browser to - support detailed content negotiation. Optional HTTP extensions - are often expressed using request header fields.

- -

This directive gives the server administrator greater - control over abnormal client request behavior, which may be - useful for avoiding some forms of denial-of-service attacks. - The value should be increased if normal clients see an error - response from the server that indicates too many fields were - sent in the request.

- -

For example:

- - 
LimitRequestFields 50
- -
- -

LimitRequestFieldsize - directive

- - Syntax: LimitRequestFieldsize - bytes
- Default: - LimitRequestFieldsize 8190
- Context: server config
- Status: core
- Compatibility: - LimitRequestFieldsize is only available in Apache 1.3.2 and - later. - -

This directive specifies the number of bytes from 0 - to the value of the compile-time constant - DEFAULT_LIMIT_REQUEST_FIELDSIZE (8190 as - distributed) that will be allowed in an HTTP request - header.

- -

The LimitRequestFieldsize directive allows the server - administrator to reduce the limit on the allowed size of an - HTTP request header field below the normal input buffer size - compiled with the server. A server needs this value to be large - enough to hold any one header field from a normal client - request. The size of a normal request header field will vary - greatly among different client implementations, often depending - upon the extent to which a user has configured their browser to - support detailed content negotiation.

- -

This directive gives the server administrator greater - control over abnormal client request behavior, which may be - useful for avoiding some forms of denial-of-service attacks.

- -

For example:

- - 
LimitRequestFieldSize 16380
- -

Under normal conditions, the value should not be changed from - the default.

-
- -

LimitRequestLine directive

- - Syntax: LimitRequestLine - bytes
- Default: LimitRequestLine - 8190
- Context: server config
- Status: core
- Compatibility: LimitRequestLine - is only available in Apache 1.3.2 and later. - -

This directive sets the number of bytes from 0 to - the value of the compile-time constant - DEFAULT_LIMIT_REQUEST_LINE (8190 as distributed) - that will be allowed on the HTTP request-line.

- -

The LimitRequestLine directive allows the server - administrator to reduce the limit on the allowed size of a - client's HTTP request-line below the normal input buffer size - compiled with the server. Since the request-line consists of - the HTTP method, URI, and protocol version, the - LimitRequestLine directive places a restriction on the length - of a request-URI allowed for a request on the server. A server - needs this value to be large enough to hold any of its resource - names, including any information that might be passed in the - query part of a GET request.

- -

This directive gives the server administrator greater - control over abnormal client request behavior, which may be - useful for avoiding some forms of denial-of-service attacks.

- -

For example:

- - 
LimitRequestLine 16380
- -

Under normal conditions, the value should not be changed from - the default.

-
- -

Listen directive

- Syntax: Listen - [IP-address:]port
- 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.

- Listen can be used instead of BindAddress and Port. It - tells the server to accept incoming requests on the specified - port or address-and-port combination. If the first format is - used, with a port number only, the server listens to the given - port on all interfaces, instead of the port given by the - Port directive. If an IP address is given as well as a - port, the server will listen on the given port and interface. - -

Note that you may still require a Port directive so - that URLs that Apache generates that point to your server still - work.

- -

Multiple Listen directives may be used to specify a number - of addresses and ports to listen to. The server will respond to - requests from any of the listed addresses and ports.

- -

For example, to make the server accept connections on both - port 80 and port 8000, use:

-
-   Listen 80
-   Listen 8000
-
- To make the server accept connections on two specified - interfaces and port numbers, use -
-   Listen 192.170.2.1:80
-   Listen 192.170.2.5:8000
-
- -

See Also: DNS - Issues
- See Also: Setting - which addresses and ports Apache uses
-

- -

ListenBacklog - directive

- Syntax: ListenBacklog - backlog
- Default: ListenBacklog - 511
- Context: server config
- Status: Core
- Compatibility: ListenBacklog is - only available in Apache versions after 1.2.0. - -

The maximum length of the queue of pending connections. - Generally no tuning is needed or desired, however on some - systems it is desirable to increase this when under a TCP SYN - flood attack. See the backlog parameter to the - listen(2) system call.

- -

This will often be limited to a smaller number by the - operating system. This varies from OS to OS. Also note that - many OSes do not use exactly what is specified as the backlog, - but use a number based on (but normally larger than) what is - set.

-
- -

<Location> - directive

- Syntax: <Location - URL-path|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 similar to the <Directory> directive, and starts a - subsection which is terminated with a </Location> - directive. <Location> sections are processed - in the order they appear in the configuration file, after the - <Directory> sections and .htaccess files are - read, and after the <Files> sections.

- -

Note that URLs do not have to line up with the filesystem at - all, it should be emphasized that <Location> operates - completely outside the filesystem.

- -

For all origin (non-proxy) requests, the URL to be matched - is of the form /path/, and you should not include - any http://servername prefix. For proxy requests, - the URL to be matched is of the form - scheme://servername/path, and you must include the - prefix.

- -

The URL may use wildcards 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". In Apache 1.3 and above, a new directive <LocationMatch> exists which - behaves identical to the regex version of - <Location>.

- -

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>
-
- -

Apache 1.3 and above note about / (slash): - The slash character has special meaning depending on where in a - URL it appears. People may be used to its behavior in the - filesystem where multiple adjacent slashes are frequently - collapsed to a single slash (i.e., - /home///foo is the same as - /home/foo). In URL-space this is not necessarily - true. The <LocationMatch> directive and the - regex version of <Location> require you to - explicitly specify multiple slashes if that is your intention. - For example, <LocationMatch ^/abc> would - match the request URL /abc but not the request URL - //abc. The (non-regex) - <Location> directive behaves similarly when - used for proxy requests. But when (non-regex) - <Location> is used for non-proxy requests it - will implicitly match multiple slashes with a single slash. For - example, if you specify <Location /abc/def> - and the request is to /abc//def then it will - match.

- -

See also: How - Directory, Location and Files sections work for an - explanation of how these different sections are combined when a - request is received

-
- -

<LocationMatch>

- Syntax: <LocationMatch - regex> ... </LocationMatch>
- Context: server config, virtual - host
- Status: core
- Compatibility: LocationMatch is - only available in Apache 1.3 and later. - -

The <LocationMatch> directive provides for access - control by URL, in an identical manner to <Location>. However, it takes a - regular expression as an argument instead of a simple string. - For example:

-
-   <LocationMatch "/(extra|special)/data">
-
- -

would match URLs that contained the substring "/extra/data" - or "/special/data".

- See also: How - Directory, Location and Files sections work for an - explanation of how these different sections are combined when a - request is received -
- -

LockFile - directive

- Syntax: LockFile - file-path
- Default: LockFile - logs/accept.lock
- Context: server config
- Status: core - -

The LockFile directive sets the path to the lockfile used - when Apache is compiled with either USE_FCNTL_SERIALIZED_ACCEPT - or USE_FLOCK_SERIALIZED_ACCEPT. This directive should normally - be left at its default value. The main reason for changing it - is if the logs directory is NFS mounted, since - the lockfile must be stored on a local disk. - The PID of the main server process is automatically appended to - the filename.

- -

SECURITY: It is best to avoid putting this - file in a world writable directory such as - /var/tmp because someone could create a denial of - service attack and prevent the server from starting by creating - a lockfile with the same name as the one the server will try to - create.

-
- -

LogLevel - directive

- Syntax: LogLevel - level
- Default: LogLevel - warn
- Context: server config, virtual - host
- Status: core
- Compatibility: LogLevel is only - available in 1.3 or later. - -

LogLevel adjusts the verbosity of the messages recorded in - the error logs (see ErrorLog - directive). The following levels are available, in - order of decreasing significance:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Level Description Example
emerg Emergencies - system is unusable."Child cannot open lock file. Exiting"
alert Action must be taken immediately."getpwuid: couldn't determine user name from uid"
crit Critical Conditions."socket: Failed to get a socket, exiting child"
error Error conditions."Premature end of script headers"
warn Warning conditions."child process 1234 did not exit, sending another - SIGHUP"
notice Normal but significant condition."httpd: caught SIGBUS, attempting to dump core in - ..."
info Informational."Server seems busy, (you may need to increase - StartServers, or Min/MaxSpareServers)..."
debug Debug-level messages"Opening config file ..."
- -

When a particular level is specified, messages from all - other levels of higher significance will be reported as well. - E.g., when LogLevel info is specified, - then messages with log levels of notice and - warn will also be posted.

- -

Using a level of at least crit is - recommended.

- -

For example:

- - 
LogLevel notice
- -

NOTE: When logging to a regular file messages - of the level notice cannot be suppressed and thus are - always logged. However, this doesn't apply when logging is done - using syslog.

- -
- -

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. To configure - more than 256 clients, you must edit the HARD_SERVER_LIMIT - entry in httpd.h and recompile.

- -

Any connection attempts over the MaxClients limit will - normally be queued, up to a number based on the ListenBacklog directive. Once a child - process is freed at the end of a different request, the - connection will then be serviced.

-
- -

MaxKeepAliveRequests - directive

- 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. In Apache 1.1, this is controlled through - an option to the KeepAlive directive.

- -

For example

- - 
MaxKeepAliveRequests 500
- -
- -

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:

- - - -

However, on Win32, It is recommended that this be set to 0. - If it is set to a non-zero value, when the request count is - reached, the child process exits, and is respawned, at which - time it re-reads the configuration files. This can lead to - unexpected behavior if you have modified a configuration file, - but are not expecting the changes to be applied yet. See also - ThreadsPerChild.

- -

NOTE: For KeepAlive requests, only - the first request is counted towards this limit. In effect, it - changes the behavior to limit the number of - connections per child.

-
- -

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.

- -

Note that this is the maximum number of spare servers, - not the maximum total number of client requests that can be handled - at one time. If you wish to limit that number, see the MaxClients directive.

- -

This directive has no effect when used with the Apache Web - server on a Microsoft Windows platform.

- -

See also MinSpareServers, - StartServers, and MaxClients.

-
- -

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.

- -

Note that setting this directive to some value m ensures - that you will always have at least n + m httpd - processes running when you have n active client requests.

- -

This directive has no effect on Microsoft Windows.

- -

See also MaxSpareServers, - StartServers, and MaxClients.

-
- -

NameVirtualHost directive

- - Syntax: NameVirtualHost - addr[:port]
- Context: server config
- Status: core
- Compatibility: NameVirtualHost - is only available in Apache 1.3 and later - -

The NameVirtualHost directive is a required directive if you - want to configure name-based virtual - hosts.

- -

Although addr can be hostname it is recommended - that you always use an IP address or wildcard, - e.g.

- -
- NameVirtualHost 111.22.33.44 -
- With the NameVirtualHost directive you specify the IP address - on which the server will receive requests for the name-based - virtual hosts. This will usually be the address to which your - name-based virtual host names resolve. In cases where a - firewall or other proxy receives the requests and forwards them - on a different IP address to the server, you must specify the - IP address of the physical interface on the machine which will - be servicing the requests. If you have multiple name-based - hosts on multiple addresses, repeat the directive for each - address. - -

Note: the "main server" and any _default_ servers will - never be served for a request to a - NameVirtualHost IP Address (unless for some reason you specify - NameVirtualHost but then don't define any VirtualHosts for that - address).

- -

Optionally you can specify a port number on which the - name-based virtual hosts should be used, e.g.

- -
- NameVirtualHost 111.22.33.44:8080 -
- In Apache 1.3.13 and greater you can specify a * - for the addr. This creates a wildcard NameVirtualHost - which will match connections to any address that isn't - configured with a more specific NameVirtualHost directive or <VirtualHost> section. This is - useful if you want only name-based virtual hosts and you don't - want to hard-code the server's IP address into the - configuration file. - -

See also: Apache - Virtual Host documentation

-
- -

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. This is the default - setting.
- -
ExecCGI
- -
- Execution of CGI scripts is permitted.
- -
FollowSymLinks
- -
- - The server will follow symbolic links in this - directory.
- Note: even though the server follows the - symlink it does not change the pathname used to - match against <Directory> sections.
- Note: this option gets ignored if set - inside a <Location> section.
- -
Includes
- -
- Server-side includes are permitted.
- -
IncludesNOEXEC
- -
- - Server-side includes are permitted, but the #exec command and - #exec CGI are disabled. It is still possible to #include - virtual CGI scripts from ScriptAliase'd directories.
- -
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.
- Note: this option gets ignored if set - inside a <Location> section.
-
- Normally, if multiple 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> -
- then only 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> -
- then the options FollowSymLinks and - Includes are set for the /web/docs/spec directory. - - -

Note: Using -IncludesNOEXEC or - -Includes disables server-side includes completely - regardless of the previous setting.

- -

The default in the absence of any other settings is - All.

-
- -

PidFile directive

- - Syntax: PidFile - file-path
- 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).

- - - The primary behavior 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. - (See also UseCanonicalName.) - -

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.

-
- -

ProtocolReqCheck - directive

- - Syntax: ProtocolReqCheck - on|off
- Default: ProtocolReqCheck - on
- Context: server config -
- Status: core
- Compatibility: - ProtocolReqCheck is only available in Apache 1.3.27 and later. - -

This directive enables strict checking of the Protocol field - in the Request line. Versions of Apache prior to 1.3.26 would - silently accept bogus Protocols (such as HTTP-1.1) - and assume HTTP/1.0. Instead, now the Protocol field - must be valid. If the pre-1.3.26 behavior is desired or required, - it can be enabled via setting ProtocolReqCheck off. -

- -
- -

Require directive

- - Syntax: Require - entity-name [entity-name] ...
- Context: directory, - .htaccess
- Override: AuthConfig
- Status: core - -

This directive selects which authenticated users can access - a resource. The allowed syntaxes are:

- - - -

Require must be accompanied by AuthName and AuthType directives, and directives such - as AuthUserFile and AuthGroupFile (to define - users and groups) in order to work correctly. Example:

- -
- AuthType Basic
- AuthName "Restricted Directory"
- AuthUserFile /web/users
- AuthGroupFile /web/groups
- Require group admin
- -
- Access controls which are applied in this way are effective for - all methods. This is what is normally - desired. If you wish to apply access controls only to - specific methods, while leaving other methods unprotected, then - place the Require statement into a <Limit> section - -

See also Satisfy and mod_access.

-
- -

ResourceConfig - directive

- - Syntax: ResourceConfig - file-path|directory-path|wildcard-path
- Default: ResourceConfig - conf/srm.conf
- Context: server config, virtual - host
- Status: core
- Compatibility: The ability to - specify a directory, rather than a file name, is only available in - Apache 1.3.13 and later. - -

The server will read this file for more directives after - reading the httpd.conf file. File-path is relative to - the ServerRoot. This feature can be - disabled using:

- -
- ResourceConfig /dev/null -
- Or, on Win32 servers, - -
- ResourceConfig nul -
-

Historically, this file contained most directives except for - server configuration directives and <Directory> sections; in fact it - can now contain any server directive allowed in the server - config context. However, since Apache version 1.3.4, the - default srm.conf file which ships with Apache contains - only comments, and all directives are placed in the main server - configuration file, httpd.conf.

- -

If ResourceConfig points to a directory, rather than - a file, Apache will read all files in that directory, and any - subdirectory, and parse those as configuration files. -

-

Alternatively you can use a wildcard to limit the scope; i.e - to only *.conf files. -

-

Note that by default any file in the specified - directory will be loaded as a configuration file. -

-

So make sure that you don't have stray files in - this directory by mistake, such as temporary files created by your - editor, for example.

- -

See also AccessConfig.

-
- -

RLimitCPU directive

- - Syntax: RLimitCPU - number|max [number|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.

- -

This applies to processes forked off from Apache children - servicing requests, not the Apache children themselves. This - includes CGI scripts and SSI exec commands, but not any - processes forked off from the Apache parent such as piped - logs.

- -

CPU resource limits are expressed in seconds per - process.

- -

See also RLimitMEM or RLimitNPROC.

-
- -

RLimitMEM - directive

- - Syntax: RLimitMEM - number|max [number|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.

- -

This applies to processes forked off from Apache children - servicing requests, not the Apache children themselves. This - includes CGI scripts and SSI exec commands, but not any - processes forked off from the Apache parent such as piped - logs.

- -

Memory resource limits are expressed in bytes per - process.

- -

See also RLimitCPU or RLimitNPROC.

-
- -

RLimitNPROC - directive

- - Syntax: RLimitNPROC - number|max [number|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.

- -

This applies to processes forked off from Apache children - servicing requests, not the Apache children themselves. This - includes CGI scripts and SSI exec commands, but not any - processes forked off from the Apache parent such as piped - logs.

- -

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 directive

- - Syntax: Satisfy any|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.

- -

See also Require and Allow.

-
- -

ScoreBoardFile - directive

- - Syntax: ScoreBoardFile - file-path
- 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 - -DUSE_SHMGET_SCOREBOARD to the EXTRA_CFLAGS - in your Configuration. This might work with some - 1.x installations, but won't work with all of them. (Prior to - 1.3b4, HAVE_SHMGET would have sufficed.)

- -

SVR4 users should consider adding -DHAVE_SHMGET - -DUSE_SHMGET_SCOREBOARD 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. (Prior - to 1.3b4, HAVE_SHMGET would have sufficed.)

- -

See Also: Stopping and Restarting Apache

-
- -

ScriptInterpreterSource - directive

- - Syntax: ScriptInterpreterSource - registry|script
- Default: - ScriptInterpreterSource script
- Context: directory, - .htaccess
- Status: core (Windows only) - -

This directive is used to control how Apache 1.3.5 and later - finds the interpreter used to run CGI scripts. The default - technique is to use the interpreter pointed to by the #! line - in the script. Setting ScriptInterpreterSource registry will - cause the Windows Registry to be searched using the script file - extension (e.g., .pl) as a search key.

-
- -

SendBufferSize - directive

- - Syntax: SendBufferSize - bytes
- Context: server config
- 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 -
- as users do not always mention that they are talking about the - server! -
- -

ServerAlias - directive

- Syntax: ServerAlias - hostname [hostname] ...
- 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 name-based virtual - hosts.

- -

Example:

- - 
-    <VirtualHost *>
-    ServerName server.domain.com
-    ServerAlias server server2.domain.com server2
-    ...
-    </VirtualHost>
-
- -

See also: Apache - Virtual Host documentation

-
- -

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 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.example.com -
- would be used if the canonical (main) name of the actual - machine were simple.example.com. - -

If you are using name-based virtual hosts, - the ServerName inside a <VirtualHost> - section specifies what hostname must appear in the request's - Host: header to match this virtual host.

- -

See Also:
- DNS Issues
- Apache virtual host - documentation
- UseCanonicalName
- NameVirtualHost
- ServerAlias
-

-
- -

ServerPath - directive

- Syntax: ServerPath - directory-path
- 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 name-based virtual - hosts.

- -

See also: Apache - Virtual Host documentation

-
- -

ServerRoot - directive

- - Syntax: ServerRoot - directory-path
- Default: ServerRoot - /usr/local/apache
- 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.

- -

See also the - security tips for information on how to properly set - permissions on the ServerRoot.

-
- -

ServerSignature directive

- - Syntax: ServerSignature - On|Off|EMail
- Default: ServerSignature - Off
- Context: server config, virtual - host, directory, .htaccess
- Status: core
- Compatibility: ServerSignature - is only available in Apache 1.3 and later. - -

The ServerSignature directive allows the configuration of a - trailing footer line under server-generated documents (error - messages, mod_proxy ftp directory listings, mod_info output, - ...). The reason why you would want to enable such a footer - line is that in a chain of proxies, the user often has no - possibility to tell which of the chained servers actually - produced a returned error message.
- The Off setting, which is the default, suppresses - the error line (and is therefore compatible with the behavior - of Apache-1.2 and below). The On setting simply - adds a line with the server version number and ServerName of the serving virtual host, - and the EMail setting additionally creates a - "mailto:" reference to the ServerAdmin of the referenced - document.

-
- -

ServerTokens - directive

- - Syntax: ServerTokens - Minimal|ProductOnly|OS|Full
- Default: ServerTokens - Full
- Context: server config
- Status: core
- Compatibility: ServerTokens is - only available in Apache 1.3 and later; the - ProductOnly keyword is only available in versions - later than 1.3.12 - -

This directive controls whether Server response - header field which is sent back to clients includes a - description of the generic OS-type of the server as well as - information about compiled-in modules.

- -
-
ServerTokens Prod[uctOnly]
- -
Server sends (e.g.): Server: - Apache
- -
ServerTokens Min[imal]
- -
Server sends (e.g.): Server: - Apache/1.3.0
- -
ServerTokens OS
- -
Server sends (e.g.): Server: Apache/1.3.0 - (Unix)
- -
ServerTokens Full (or not specified)
- -
Server sends (e.g.): Server: Apache/1.3.0 - (Unix) PHP/3.0 MyMod/1.2
-
- -

This setting applies to the entire server, and cannot be - enabled or disabled on a virtualhost-by-virtualhost basis.

-
- -

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.local or - /etc/rc3.d/....)
-
- Inetd is the lesser used of the two options. For each http - connection received, a new copy of the server is started from - scratch; after the connection is complete, this program exits. - There is a high price to pay per connection, but for security - reasons, some admins prefer this option. Inetd mode is no longer recommended and does not - always work properly. Avoid it if at all possible. - -

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.

-
- -

ShmemUIDisUser - directive

- - Syntax: ShmemUIDisUser - on|off
- Default: ShmemUIDisUser - off
- Context: server config
- Status: core
- Compatibility: - ShmemUIDisUser directive is only available in Apache 1.3.27 and later. - -

The ShmemUIDisUser directive controls whether Apache will change - the uid and gid ownership of System V shared memory - based scoreboards to the server settings of User and - Group. Releases of Apache up to 1.3.26 would do - this by default. Since the child processes are already attached to the - shared memory segment, this is not required for normal usage of Apache and - so to prevent possible abuse, Apache will no longer do that. The old - behavior may be required for special cases, however, which can be implemented - by setting this directive to on.

- -

This directive has no effect on non-System V based scoreboards, such as - mmap. -

- -
- -

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.

- -

When running under Microsoft Windows, this directive has no - effect. There is always one child which handles all requests. - Within the child requests are handled by separate threads. The - ThreadsPerChild directive - controls the maximum number of child threads handling requests, - which will have a similar effect to the setting of - StartServers on Unix.

- -

See also MinSpareServers and - MaxSpareServers.

-
- -

ThreadsPerChild

- Syntax: ThreadsPerChild - number
- Default: ThreadsPerChild - 50
- Context: server config
- Status: core (Windows, - NetWare)
- Compatibility: Available only with Apache 1.3 - and later with Windows - -

This directive tells the server how many threads it should - use. This is the maximum number of connections the server can - handle at once; be sure and set this number high enough for - your site if you get a lot of hits.

- -

This directive has no effect on Unix systems. Unix users - should look at StartServers and MaxRequestsPerChild.

-
- -

ThreadStackSize

- Syntax: ThreadStackSize - number
- Default: ThreadStackSize - 65536
- Context: server config
- Status: core (NetWare)
- Compatibility: Available only with Apache 1.3 - and later with NetWare - -

This directive tells the server what stack size to use for - each of the running threads. If you ever get a stack overflow - you will need to bump this number to a higher setting.

- -

This directive has no effect on other systems.

-
- -

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:

- -
    -
  1. The total amount of time it takes to receive a GET - request.
    2. - -
  2. The amount of time between receipt of TCP packets on a - POST or PUT request.
    3. - -
  3. The amount of time between ACKs on transmissions of TCP - packets in responses.
    4. -
- We plan on making these separately configurable at some point - down the road. The timer used to default to 1200 before 1.2, - but has been lowered to 300 which is still far more than - necessary in most situations. It is not set any lower by - default because there may still be odd places in the code where - the timer is not reset when a packet is sent. -
- -

UseCanonicalName directive

- - Syntax: UseCanonicalName - on|off|dns
- Default: UseCanonicalName - on
- Context: server config, virtual - host, directory
- Override: Options
- Compatibility: UseCanonicalName - is only available in Apache 1.3 and later - -

In many situations Apache has to construct a - self-referential URL. That is, a URL which refers back - to the same server. With UseCanonicalName on (and - in all versions prior to 1.3) Apache will use the ServerName and Port - directives to construct the canonical name for the server. This - name is used in all self-referential URLs, and for the values - of SERVER_NAME and SERVER_PORT in - CGIs.

- -

For example, if ServerName is set to - www.example.com and Port is set to - 9090, then the canonical name of the server is - www.example.com:9090. In the event that - Port has its default value of 80, the - :80 is omitted from the canonical name.

- -

With UseCanonicalName off Apache will form - self-referential URLs using the hostname and port supplied by - the client if any are supplied (otherwise it will use the - canonical name, as defined above). These values are the same - that are used to implement name based virtual hosts, - and are available with the same clients. The CGI variables - SERVER_NAME and SERVER_PORT will be - constructed from the client supplied values as well.

- -

An example where this may be useful is on an intranet server - where you have users connecting to the machine using short - names such as www. You'll notice that if the users - type a shortname, and a URL which is a directory, such as - http://www/splat, without the trailing - slash then Apache will redirect them to - http://www.domain.com/splat/. If you have - authentication enabled, this will cause the user to have to - authenticate twice (once for www and once again - for www.domain.com -- see the FAQ on this subject for - more information). But if UseCanonicalName - is set off, then Apache will redirect to - http://www/splat/.

- -

There is a third option, UseCanonicalName DNS, - which is intended for use with mass IP-based virtual hosting to - support ancient clients that do not provide a - Host: header. With this option Apache does a - reverse DNS lookup on the server IP address that the client - connected to in order to work out self-referential URLs.

- -

Warning: if CGIs make assumptions about the - values of SERVER_NAME they may be broken by this - option. The client is essentially free to give whatever value - they want as a hostname. But if the CGI is only using - SERVER_NAME to construct self-referential URLs - then it should be just fine.

- -

See also: ServerName, Port

-
- -

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.
-
- The user should have no privileges which result in it being - able to access files which are not intended to be visible to - the outside world, and similarly, the user should not be able - to execute code which is not meant for httpd requests. It is - recommended that you set up a new user and group specifically - for running the server. Some admins use user - nobody, but this is not always possible or - desirable. For example mod_proxy's cache, when enabled, must be - accessible to this user (see the CacheRoot - directive). - -

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] [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, - different port number or a different host name for the server, - in the former 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). - -

You can specify more than one IP address. This is useful if - a machine responds to the same name on two different - interfaces. For example, if you have a VirtualHost that is - available to hosts on an internal (intranet) as well as - external (internet) network. Example:

- -
- <VirtualHost 192.168.1.2 204.255.176.199>
- DocumentRoot /www/docs/host.foo.com
- ServerName host.foo.com
- ServerAlias host
- </VirtualHost> -
- 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.

- -

NOTE: The use of <VirtualHost> does - not affect what addresses Apache listens on. - You may need to ensure that Apache is listening on the correct - addresses using either BindAddress - or Listen.

- -

See also: Apache - Virtual Host documentation
- See also: Warnings about DNS and - Apache
- See also: Setting - which addresses and ports Apache uses
- See also: How - Directory, Location and Files sections work for an - explanation of how these different sections are combined when a - request is received

-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/directive-dict.html b/usr.sbin/httpd/htdocs/manual/mod/directive-dict.html new file mode 100644 index 00000000000..28949b7b0d8 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/directive-dict.html @@ -0,0 +1,318 @@ + + + + + + + + Definitions of terms used to describe Apache + directives + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Terms Used to Describe Apache + Directives

+ +

Each Apache configuration directive is described using a + common format that looks like this:

+ +
+
Syntax: + directive-name some args
+ Default: + directive-name default-value
+ Context: + context-list
+ Override: + override
+ Status: + status
+ Module: + module-name
+ Compatibility: + compatibility notes
+
+ +

Each of the directive's attributes, complete with possible + values where possible, are described in this document.

+ +

Directive Terms

+ + +
+ +

Syntax

+ +

This indicates the format of the directive as it would + appear in a configuration file. This syntax is extremely + directive-specific, and is described in detail in the + directive's definition. Generally, the directive name is + followed by a series of one or more space-separated arguments. + If an argument contains a space, the argument must be enclosed + in double quotes. Optional arguments are enclosed in square + brackets. Where an argument can take on more than one possible + value, the possible values are separated by vertical bars "|". + Literal text is presented in the default font, while + argument-types for which substitution is necessary are + emphasized. Directives which can take a variable + number of arguments will end in "..." indicating that the last + argument is repeated.

+ +

Directives use a great number of different argument types. A + few common ones are defined below.

+ +
+
URL
+ +
A complete Uniform Resource Locator including a scheme, + hostname, and optional pathname as in + http://www.example.com/path/to/file.html
+ +
URL-path
+ +
The part of a url which follows the scheme and + hostname as in /path/to/file.html. The + url-path represents a web-view of a resource, as + opposed to a file-system view.
+ +
file-path
+ +
The path to a file in the local file-system beginning + with the root directory as in + /usr/local/apache/htdocs/path/to/file.html. + Unless otherwise specified, a file-path which does + not begin with a slash will be treated as relative to the ServerRoot.
+ +
directory-path
+ +
The path to a directory in the local file-system + beginning with the root directory as in + /usr/local/apache/htdocs/path/to/.
+ +
filename
+ +
The name of a file with no accompanying path information + as in file.html.
+ +
regex
+ +
A regular + expression, which is a way of describing a pattern to + match in text. The directive definition will specify what the + regex is matching against.
+ +
extension
+ +
In general, this is the part of the filename + which follows the last dot. However, Apache recognizes + multiple filename extensions, so if a filename + contains more than one dot, each dot-separated part of the + filename following the first dot is an extension. + For example, the filename file.html.en + contains two extensions: .html and + .en. For Apache directives, you may specify + extensions with or without the leading dot. In + addition, extensions are not case sensitive.
+ +
MIME-type
+ +
A method of describing the format of a file which + consists of a major format type and a minor format type, + separated by a slash as in text/html.
+ +
env-variable
+ +
The name of an environment + variable defined in the Apache configuration process. + Note this is not necessarily the same as an operating system + environment variable. See the environment variable documentation for + more details.
+
+
+ +

Default

+ +

If the directive has a default value (i.e., if you + omit it from your configuration entirely, the Apache Web server + will behave as though you set it to a particular value), it is + described here. If there is no default value, this section + should say "None". Note that the default listed here + is not necessarily the same as the value the directive takes in + the default httpd.conf distributed with the server.

+
+ +

Context

+ +

This indicates where in the server's configuration files the + directive is legal. It's a comma-separated list of one or more + of the following values:

+ +
+
server config
+ +
This means that the directive may be used in the server + configuration files (e.g., httpd.conf, + srm.conf, and access.conf), but + not within any + <VirtualHost> or <Directory> + containers. It is not allowed in .htaccess files + at all.
+ +
virtual host
+ +
This context means that the directive may appear inside + <VirtualHost> containers in the server + configuration files.
+ +
directory
+ +
A directive marked as being valid in this context may be + used inside <Directory>, + <Location>, and <Files> + containers in the server configuration files, subject to the + restrictions outlined in How + Directory, Location and Files sections work.
+ +
.htaccess
+ +
If a directive is valid in this context, it means that it + can appear inside per-directory + .htaccess files. It may not be processed, though + depending upon the overrides currently active.
+
+ +

The directive is only allowed within the designated + context; if you try to use it elsewhere, you'll get a + configuration error that will either prevent the server from + handling requests in that context correctly, or will keep the + server from operating at all -- i.e., the server won't + even start.

+ +

The valid locations for the directive are actually the + result of a Boolean OR of all of the listed contexts. In other + words, a directive that is marked as being valid in + "server config, .htaccess" can be used in the + httpd.conf file and in .htaccess + files, but not within any <Directory> or + <VirtualHost> containers.

+
+ +

Override

+ +

This directive attribute indicates which configuration + override must be active in order for the directive to be + processed when it appears in a .htaccess file. If + the directive's context + doesn't permit it to appear in .htaccess files, + this attribute should say "Not applicable".

+ +

Overrides are activated by the AllowOverride directive, and apply + to a particular scope (such as a directory) and all + descendants, unless further modified by other + AllowOverride directives at lower levels. The + documentation for that directive also lists the possible + override names available.

+
+ +

Status

+ +

This indicates how tightly bound into the Apache Web server + the directive is; in other words, you may need to recompile the + server with an enhanced set of modules in order to gain access + to the directive and its functionality. Possible values for + this attribute are:

+ +
+
Core
+ +
If a directive is listed as having "Core" status, that + means it is part of the innermost portions of the Apache Web + server, and is always available.
+ +
Base
+ +
A directive labeled as having "Base" status is supported + by one of the standard Apache modules which is compiled into + the server by default, and is therefore normally available + unless you've taken steps to remove the module from your + configuration.
+ +
Extension
+ +
A directive with "Extension" status is provided by one of + the modules included with the Apache server kit, but the + module isn't normally compiled into the server. To enable the + directive and its functionality, you will need to change the + server build configuration files and re-compile Apache.
+ +
Experimental
+ +
"Experimental" status indicates that the directive is + available as part of the Apache kit, but you're on your own + if you try to use it. The directive is being documented for + completeness, and is not necessarily supported. The module + which provides the directive may or may not be compiled in by + default; check the top of the page which describes the + directive and its module to see if it remarks on the + availability.
+
+
+ +

Module

+ +

This quite simply lists the name of the source module which + defines the directive.

+
+ +

Compatibility

+ +

If the directive wasn't part of the original Apache version + 1 distribution, the version in which it was introduced should + be listed here. If the directive has the same name as one from + the NCSA HTTPd server, any inconsistencies in behavior between + the two should also be mentioned. Otherwise, this attribute + should say "No compatibility issues."

+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/directive-dict.html.html b/usr.sbin/httpd/htdocs/manual/mod/directive-dict.html.html deleted file mode 100644 index 28949b7b0d8..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/directive-dict.html.html +++ /dev/null @@ -1,318 +0,0 @@ - - - - - - - - Definitions of terms used to describe Apache - directives - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Terms Used to Describe Apache - Directives

- -

Each Apache configuration directive is described using a - common format that looks like this:

- -
-
Syntax: - directive-name some args
- Default: - directive-name default-value
- Context: - context-list
- Override: - override
- Status: - status
- Module: - module-name
- Compatibility: - compatibility notes
-
- -

Each of the directive's attributes, complete with possible - values where possible, are described in this document.

- -

Directive Terms

- - -
- -

Syntax

- -

This indicates the format of the directive as it would - appear in a configuration file. This syntax is extremely - directive-specific, and is described in detail in the - directive's definition. Generally, the directive name is - followed by a series of one or more space-separated arguments. - If an argument contains a space, the argument must be enclosed - in double quotes. Optional arguments are enclosed in square - brackets. Where an argument can take on more than one possible - value, the possible values are separated by vertical bars "|". - Literal text is presented in the default font, while - argument-types for which substitution is necessary are - emphasized. Directives which can take a variable - number of arguments will end in "..." indicating that the last - argument is repeated.

- -

Directives use a great number of different argument types. A - few common ones are defined below.

- -
-
URL
- -
A complete Uniform Resource Locator including a scheme, - hostname, and optional pathname as in - http://www.example.com/path/to/file.html
- -
URL-path
- -
The part of a url which follows the scheme and - hostname as in /path/to/file.html. The - url-path represents a web-view of a resource, as - opposed to a file-system view.
- -
file-path
- -
The path to a file in the local file-system beginning - with the root directory as in - /usr/local/apache/htdocs/path/to/file.html. - Unless otherwise specified, a file-path which does - not begin with a slash will be treated as relative to the ServerRoot.
- -
directory-path
- -
The path to a directory in the local file-system - beginning with the root directory as in - /usr/local/apache/htdocs/path/to/.
- -
filename
- -
The name of a file with no accompanying path information - as in file.html.
- -
regex
- -
A regular - expression, which is a way of describing a pattern to - match in text. The directive definition will specify what the - regex is matching against.
- -
extension
- -
In general, this is the part of the filename - which follows the last dot. However, Apache recognizes - multiple filename extensions, so if a filename - contains more than one dot, each dot-separated part of the - filename following the first dot is an extension. - For example, the filename file.html.en - contains two extensions: .html and - .en. For Apache directives, you may specify - extensions with or without the leading dot. In - addition, extensions are not case sensitive.
- -
MIME-type
- -
A method of describing the format of a file which - consists of a major format type and a minor format type, - separated by a slash as in text/html.
- -
env-variable
- -
The name of an environment - variable defined in the Apache configuration process. - Note this is not necessarily the same as an operating system - environment variable. See the environment variable documentation for - more details.
-
-
- -

Default

- -

If the directive has a default value (i.e., if you - omit it from your configuration entirely, the Apache Web server - will behave as though you set it to a particular value), it is - described here. If there is no default value, this section - should say "None". Note that the default listed here - is not necessarily the same as the value the directive takes in - the default httpd.conf distributed with the server.

-
- -

Context

- -

This indicates where in the server's configuration files the - directive is legal. It's a comma-separated list of one or more - of the following values:

- -
-
server config
- -
This means that the directive may be used in the server - configuration files (e.g., httpd.conf, - srm.conf, and access.conf), but - not within any - <VirtualHost> or <Directory> - containers. It is not allowed in .htaccess files - at all.
- -
virtual host
- -
This context means that the directive may appear inside - <VirtualHost> containers in the server - configuration files.
- -
directory
- -
A directive marked as being valid in this context may be - used inside <Directory>, - <Location>, and <Files> - containers in the server configuration files, subject to the - restrictions outlined in How - Directory, Location and Files sections work.
- -
.htaccess
- -
If a directive is valid in this context, it means that it - can appear inside per-directory - .htaccess files. It may not be processed, though - depending upon the overrides currently active.
-
- -

The directive is only allowed within the designated - context; if you try to use it elsewhere, you'll get a - configuration error that will either prevent the server from - handling requests in that context correctly, or will keep the - server from operating at all -- i.e., the server won't - even start.

- -

The valid locations for the directive are actually the - result of a Boolean OR of all of the listed contexts. In other - words, a directive that is marked as being valid in - "server config, .htaccess" can be used in the - httpd.conf file and in .htaccess - files, but not within any <Directory> or - <VirtualHost> containers.

-
- -

Override

- -

This directive attribute indicates which configuration - override must be active in order for the directive to be - processed when it appears in a .htaccess file. If - the directive's context - doesn't permit it to appear in .htaccess files, - this attribute should say "Not applicable".

- -

Overrides are activated by the AllowOverride directive, and apply - to a particular scope (such as a directory) and all - descendants, unless further modified by other - AllowOverride directives at lower levels. The - documentation for that directive also lists the possible - override names available.

-
- -

Status

- -

This indicates how tightly bound into the Apache Web server - the directive is; in other words, you may need to recompile the - server with an enhanced set of modules in order to gain access - to the directive and its functionality. Possible values for - this attribute are:

- -
-
Core
- -
If a directive is listed as having "Core" status, that - means it is part of the innermost portions of the Apache Web - server, and is always available.
- -
Base
- -
A directive labeled as having "Base" status is supported - by one of the standard Apache modules which is compiled into - the server by default, and is therefore normally available - unless you've taken steps to remove the module from your - configuration.
- -
Extension
- -
A directive with "Extension" status is provided by one of - the modules included with the Apache server kit, but the - module isn't normally compiled into the server. To enable the - directive and its functionality, you will need to change the - server build configuration files and re-compile Apache.
- -
Experimental
- -
"Experimental" status indicates that the directive is - available as part of the Apache kit, but you're on your own - if you try to use it. The directive is being documented for - completeness, and is not necessarily supported. The module - which provides the directive may or may not be compiled in by - default; check the top of the page which describes the - directive and its module to see if it remarks on the - availability.
-
-
- -

Module

- -

This quite simply lists the name of the source module which - defines the directive.

-
- -

Compatibility

- -

If the directive wasn't part of the original Apache version - 1 distribution, the version in which it was introduced should - be listed here. If the directive has the same name as one from - the NCSA HTTPd server, any inconsistencies in behavior between - the two should also be mentioned. Otherwise, this attribute - should say "No compatibility issues."

-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/directives.html b/usr.sbin/httpd/htdocs/manual/mod/directives.html new file mode 100644 index 00000000000..8437b26c22a --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/directives.html @@ -0,0 +1,591 @@ + + + + + + + + Apache directives + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Apache Directives

+ +

Each Apache directive available in the standard Apache + distribution is listed here. They are described using a + consistent format, and there is a dictionary of the terms used in their + descriptions available.

+ + +
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/directives.html.html b/usr.sbin/httpd/htdocs/manual/mod/directives.html.html deleted file mode 100644 index 8437b26c22a..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/directives.html.html +++ /dev/null @@ -1,591 +0,0 @@ - - - - - - - - Apache directives - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Apache Directives

- -

Each Apache directive available in the standard Apache - distribution is listed here. They are described using a - consistent format, and there is a dictionary of the terms used in their - descriptions available.

- - -
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/index-bytype.html b/usr.sbin/httpd/htdocs/manual/mod/index-bytype.html new file mode 100644 index 00000000000..551f821e4b1 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/index-bytype.html @@ -0,0 +1,289 @@ + + + + + + + + Apache modules + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Apache modules

+ +

Below is a list of all of the modules that come as part of + the Apache distribution. See also the list of modules sorted alphabetically and the complete + alphabetical list of all Apache + directives. For modules that are not part of the Apache + distribution, please see http://modules.apache.org.

+ +

Core

+ +
+
Core
+ +
Core Apache features
+
+ +

Environment Creation

+ +
+
mod_env
+ +
Passing of environments to CGI scripts
+ +
mod_setenvif Apache 1.3 + and up
+ +
Set environment variables based on client + information
+ +
mod_unique_id Apache 1.3 + and up
+ +
Generate unique request identifier for every request
+
+ +

Content Type Decisions

+ +
+
mod_mime
+ +
Determining document types using file extensions
+ +
mod_mime_magic
+ +
Determining document types using "magic numbers"
+ +
mod_negotiation
+ +
Content negotiation
+
+ +

URL Mapping

+ +
+
mod_alias
+ +
Mapping different parts of the host filesystem in the + document tree, and URL redirection
+ +
mod_rewrite Apache 1.2 and + up
+ +
Powerful URI-to-filename mapping using regular + expressions
+ +
mod_userdir
+ +
User home directories
+ +
mod_speling Apache 1.3 and + up
+ +
Automatically correct minor typos in URLs
+ +
mod_vhost_alias Apache + 1.3.7 and up
+ +
Support for dynamically configured mass virtual + hosting
+
+ +

Directory Handling

+ +
+
mod_dir
+ +
Basic directory handling
+ +
mod_autoindex
+ +
Automatic directory listings
+
+ +

Access Control

+ +
+
mod_access
+ +
Access control based on client hostname or IP + address
+ +
mod_auth
+ +
User authentication using text files
+ +
mod_auth_dbm
+ +
User authentication using DBM files
+ +
mod_auth_db
+ +
User authentication using Berkeley DB files
+ +
mod_auth_anon Apache 1.1 + and up
+ +
Anonymous user access to authenticated areas
+ +
mod_auth_digest Apache + 1.3.8 and up
+ +
Experimental MD5 authentication
+ +
mod_digest Apache 1.1 and + up
+ +
MD5 authentication
+
+ +

HTTP Response

+ +
+
mod_headers Apache 1.2 and + up
+ +
Add arbitrary HTTP headers to resources
+ +
mod_cern_meta Apache 1.1 + and up
+ +
Support for HTTP header metafiles
+ +
mod_expires Apache 1.2 and + up
+ +
Apply Expires: headers to resources
+ +
mod_asis
+ +
Sending files which contain their own HTTP headers
+
+ +

Dynamic Content

+ +
+
mod_include
+ +
Server-parsed documents
+ +
mod_cgi
+ +
Invoking CGI scripts
+ +
mod_actions Apache 1.1 and + up
+ +
Executing CGI scripts based on media type or request + method
+ +
+ +

Internal Content Handlers

+ +
+
mod_status Apache 1.1 and + up
+ +
Server status display
+ +
mod_info Apache 1.1 and + up
+ +
Server configuration information
+
+ +

Logging

+ +
+
mod_log_config
+ +
User-configurable logging replacement for + mod_log_common
+ +
mod_log_agent
+ +
Logging of User Agents
+ +
mod_log_referer
+ +
Logging of document references
+ +
mod_usertrack Apache 1.2 + and up
+ +
User tracking using Cookies (replacement for + mod_cookies.c)
+
+ +

Miscellaneous

+ +
+
mod_imap Apache 1.1 and + up
+ +
The imagemap file handler
+ +
mod_proxy Apache 1.1 and + up
+ +
Caching proxy abilities
+ +
mod_so Apache 1.3 and up
+ +
Support for loading modules (DLLs on Windows) at + runtime
+ +
mod_mmap_static Apache + 1.3 and up
+ +
Experimental file caching, mapping files into memory to + improve performace
+
+ +

Obsolete

+ +
+
mod_browser Apache 1.2.* + only
+ +
Set environment variables based on User-Agent strings. + Replaced by mod_setenvif in Apache 1.3 and up
+ +
mod_cookies up to Apache + 1.1.1
+ +
Support for Netscape-like cookies. Replaced in Apache 1.2 + by mod_usertrack
+ +
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
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/index-bytype.html.html b/usr.sbin/httpd/htdocs/manual/mod/index-bytype.html.html deleted file mode 100644 index 551f821e4b1..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/index-bytype.html.html +++ /dev/null @@ -1,289 +0,0 @@ - - - - - - - - Apache modules - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Apache modules

- -

Below is a list of all of the modules that come as part of - the Apache distribution. See also the list of modules sorted alphabetically and the complete - alphabetical list of all Apache - directives. For modules that are not part of the Apache - distribution, please see http://modules.apache.org.

- -

Core

- -
-
Core
- -
Core Apache features
-
- -

Environment Creation

- -
-
mod_env
- -
Passing of environments to CGI scripts
- -
mod_setenvif Apache 1.3 - and up
- -
Set environment variables based on client - information
- -
mod_unique_id Apache 1.3 - and up
- -
Generate unique request identifier for every request
-
- -

Content Type Decisions

- -
-
mod_mime
- -
Determining document types using file extensions
- -
mod_mime_magic
- -
Determining document types using "magic numbers"
- -
mod_negotiation
- -
Content negotiation
-
- -

URL Mapping

- -
-
mod_alias
- -
Mapping different parts of the host filesystem in the - document tree, and URL redirection
- -
mod_rewrite Apache 1.2 and - up
- -
Powerful URI-to-filename mapping using regular - expressions
- -
mod_userdir
- -
User home directories
- -
mod_speling Apache 1.3 and - up
- -
Automatically correct minor typos in URLs
- -
mod_vhost_alias Apache - 1.3.7 and up
- -
Support for dynamically configured mass virtual - hosting
-
- -

Directory Handling

- -
-
mod_dir
- -
Basic directory handling
- -
mod_autoindex
- -
Automatic directory listings
-
- -

Access Control

- -
-
mod_access
- -
Access control based on client hostname or IP - address
- -
mod_auth
- -
User authentication using text files
- -
mod_auth_dbm
- -
User authentication using DBM files
- -
mod_auth_db
- -
User authentication using Berkeley DB files
- -
mod_auth_anon Apache 1.1 - and up
- -
Anonymous user access to authenticated areas
- -
mod_auth_digest Apache - 1.3.8 and up
- -
Experimental MD5 authentication
- -
mod_digest Apache 1.1 and - up
- -
MD5 authentication
-
- -

HTTP Response

- -
-
mod_headers Apache 1.2 and - up
- -
Add arbitrary HTTP headers to resources
- -
mod_cern_meta Apache 1.1 - and up
- -
Support for HTTP header metafiles
- -
mod_expires Apache 1.2 and - up
- -
Apply Expires: headers to resources
- -
mod_asis
- -
Sending files which contain their own HTTP headers
-
- -

Dynamic Content

- -
-
mod_include
- -
Server-parsed documents
- -
mod_cgi
- -
Invoking CGI scripts
- -
mod_actions Apache 1.1 and - up
- -
Executing CGI scripts based on media type or request - method
- -
- -

Internal Content Handlers

- -
-
mod_status Apache 1.1 and - up
- -
Server status display
- -
mod_info Apache 1.1 and - up
- -
Server configuration information
-
- -

Logging

- -
-
mod_log_config
- -
User-configurable logging replacement for - mod_log_common
- -
mod_log_agent
- -
Logging of User Agents
- -
mod_log_referer
- -
Logging of document references
- -
mod_usertrack Apache 1.2 - and up
- -
User tracking using Cookies (replacement for - mod_cookies.c)
-
- -

Miscellaneous

- -
-
mod_imap Apache 1.1 and - up
- -
The imagemap file handler
- -
mod_proxy Apache 1.1 and - up
- -
Caching proxy abilities
- -
mod_so Apache 1.3 and up
- -
Support for loading modules (DLLs on Windows) at - runtime
- -
mod_mmap_static Apache - 1.3 and up
- -
Experimental file caching, mapping files into memory to - improve performace
-
- -

Obsolete

- -
-
mod_browser Apache 1.2.* - only
- -
Set environment variables based on User-Agent strings. - Replaced by mod_setenvif in Apache 1.3 and up
- -
mod_cookies up to Apache - 1.1.1
- -
Support for Netscape-like cookies. Replaced in Apache 1.2 - by mod_usertrack
- -
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
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/index.html b/usr.sbin/httpd/htdocs/manual/mod/index.html new file mode 100644 index 00000000000..864795cf31b --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/index.html @@ -0,0 +1,243 @@ + + + + + + + + Apache modules + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Apache modules

+ +

Below is a list of all of the modules that come as part of + the Apache distribution. See also the list of modules sorted by type and the complete + alphabetical list of all Apache + directives. For Apache modules that are not part of the + Apache distribution, please see http://modules.apache.org

+ +
+
Core
+ +
Core Apache features
+ +
mod_access
+ +
Access control based on client hostname or IP + address
+ +
mod_actions Apache 1.1 and + up
+ +
Executing CGI scripts based on media type or request + method
+ +
mod_alias
+ +
Mapping different parts of the host filesystem in the + document tree, and URL redirection
+ +
mod_asis
+ +
Sending files which contain their own HTTP headers
+ +
mod_auth
+ +
User authentication using text files
+ +
mod_auth_anon Apache 1.1 + and up
+ +
Anonymous user access to authenticated areas
+ +
mod_auth_db Apache 1.1 and + up
+ +
User authentication using Berkeley DB files
+ +
mod_auth_dbm
+ +
User authentication using DBM files
+ +
mod_auth_digest Apache + 1.3.8 and up
+ +
MD5 authentication
+ +
mod_autoindex
+ +
Automatic directory listings
+ +
mod_browser Apache 1.2.* + only
+ +
Set environment variables based on User-Agent strings. + Replaced by mod_setenvif in Apache 1.3 and up
+ +
mod_cern_meta Apache 1.1 + and up
+ +
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 Apache 1.1 and + up
+ +
MD5 authentication (deprecated by mod_auth_digest)
+ +
mod_dir
+ +
Basic directory handling
+ +
mod_env Apache 1.1 and up
+ +
Passing of environments to CGI scripts
+ +
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 Apache 1.1 and + up
+ +
The imagemap file handler
+ +
mod_include
+ +
Server-parsed documents
+ +
mod_info Apache 1.1 and + up
+ +
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 using file extensions
+ +
mod_mime_magic
+ +
Determining document types using "magic numbers"
+ +
mod_mmap_static Apache + 1.3 and up
+ +
Experimental file caching, mapping files into memory to + improve performance
+ +
mod_negotiation
+ +
Content negotiation
+ +
mod_proxy Apache 1.1 and + up
+ +
Caching proxy abilities
+ +
mod_rewrite Apache 1.2 and + up
+ +
Powerful URI-to-filename mapping using regular + expressions
+ +
mod_setenvif Apache 1.3 + and up
+ +
Set environment variables based on client + information
+ +
mod_so Apache 1.3 and up
+ +
Support for loading modules (.so's on Unix, .dll's on + Win32) at runtime
+ +
mod_speling Apache 1.3 and + up
+ +
Automatically correct minor typos in URLs
+ +
mod_status Apache 1.1 and + up
+ +
Server status display
+ +
mod_unique_id Apache 1.3 + and up
+ +
Generate unique request identifier for every request
+ +
mod_userdir
+ +
User home directories
+ +
mod_usertrack Apache 1.2 + and up
+ +
User tracking using Cookies (replacement for + mod_cookies.c)
+ +
mod_vhost_alias Apache + 1.3.7 and up
+ +
Support for dynamically configured mass virtual + hosting
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/index.html.html b/usr.sbin/httpd/htdocs/manual/mod/index.html.html deleted file mode 100644 index 864795cf31b..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/index.html.html +++ /dev/null @@ -1,243 +0,0 @@ - - - - - - - - Apache modules - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Apache modules

- -

Below is a list of all of the modules that come as part of - the Apache distribution. See also the list of modules sorted by type and the complete - alphabetical list of all Apache - directives. For Apache modules that are not part of the - Apache distribution, please see http://modules.apache.org

- -
-
Core
- -
Core Apache features
- -
mod_access
- -
Access control based on client hostname or IP - address
- -
mod_actions Apache 1.1 and - up
- -
Executing CGI scripts based on media type or request - method
- -
mod_alias
- -
Mapping different parts of the host filesystem in the - document tree, and URL redirection
- -
mod_asis
- -
Sending files which contain their own HTTP headers
- -
mod_auth
- -
User authentication using text files
- -
mod_auth_anon Apache 1.1 - and up
- -
Anonymous user access to authenticated areas
- -
mod_auth_db Apache 1.1 and - up
- -
User authentication using Berkeley DB files
- -
mod_auth_dbm
- -
User authentication using DBM files
- -
mod_auth_digest Apache - 1.3.8 and up
- -
MD5 authentication
- -
mod_autoindex
- -
Automatic directory listings
- -
mod_browser Apache 1.2.* - only
- -
Set environment variables based on User-Agent strings. - Replaced by mod_setenvif in Apache 1.3 and up
- -
mod_cern_meta Apache 1.1 - and up
- -
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 Apache 1.1 and - up
- -
MD5 authentication (deprecated by mod_auth_digest)
- -
mod_dir
- -
Basic directory handling
- -
mod_env Apache 1.1 and up
- -
Passing of environments to CGI scripts
- -
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 Apache 1.1 and - up
- -
The imagemap file handler
- -
mod_include
- -
Server-parsed documents
- -
mod_info Apache 1.1 and - up
- -
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 using file extensions
- -
mod_mime_magic
- -
Determining document types using "magic numbers"
- -
mod_mmap_static Apache - 1.3 and up
- -
Experimental file caching, mapping files into memory to - improve performance
- -
mod_negotiation
- -
Content negotiation
- -
mod_proxy Apache 1.1 and - up
- -
Caching proxy abilities
- -
mod_rewrite Apache 1.2 and - up
- -
Powerful URI-to-filename mapping using regular - expressions
- -
mod_setenvif Apache 1.3 - and up
- -
Set environment variables based on client - information
- -
mod_so Apache 1.3 and up
- -
Support for loading modules (.so's on Unix, .dll's on - Win32) at runtime
- -
mod_speling Apache 1.3 and - up
- -
Automatically correct minor typos in URLs
- -
mod_status Apache 1.1 and - up
- -
Server status display
- -
mod_unique_id Apache 1.3 - and up
- -
Generate unique request identifier for every request
- -
mod_userdir
- -
User home directories
- -
mod_usertrack Apache 1.2 - and up
- -
User tracking using Cookies (replacement for - mod_cookies.c)
- -
mod_vhost_alias Apache - 1.3.7 and up
- -
Support for dynamically configured mass virtual - hosting
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_access.html b/usr.sbin/httpd/htdocs/manual/mod/mod_access.html new file mode 100644 index 00000000000..9a5a4eddfac --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_access.html @@ -0,0 +1,354 @@ + + + + + + + + Apache module mod_access + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_access

+ +

This module provides access control based on client + hostname, IP address, or other characteristics of the client + request.

+ +

Status: Base
+ Source File: mod_access.c
+ Module Identifier: + access_module

+ +

Summary

+ +

The directives provided by mod_access are used in <Directory>, <Files>, and <Location> sections + as well as .htaccess files to + control access to particular parts of the server. Access can be + controlled based on the client hostname, IP address, or other + characteristics of the client request, as captured in environment variables. The + Allow and Deny directives are used to + specify which clients are or are not allowed access to the + server, while the Order directive sets the default + access state, and configures how the Allow and + Deny directives interact with each other.

+ +

Both host-based access restrictions and password-based + authentication may be implemented simultaneously. In that case, + the Satisfy directive is used + to determine how the two sets of restrictions interact.

+ +

In general, access restriction directives apply to all + access methods (GET, PUT, + POST, etc). This is the desired behavior in most + cases. However, it is possible to restrict some methods, while + leaving other methods unrestricted, by enclosing the directives + in a <Limit> section.

+ +

Directives

+ + + +

See also Satisfy and Require.

+
+ +

Allow directive

+ +

+ Syntax: Allow from + all|host|env=env-variable + [host|env=env-variable] ...
+ Context: directory, + .htaccess
+ Override: Limit
+ Status: Base
+ Module: mod_access

+ +

The Allow directive affects which hosts can + access an area of the server. Access can be controlled by + hostname, IP Address, IP Address range, or by other + characteristics of the client request captured in environment + variables.

+ +

The first argument to this directive is always + from. The subsequent arguments can take three + different forms. If Allow from all is specified, + then all hosts are allowed access, subject to the configuration + of the Deny and Order directives as + discussed below. To allow only particular hosts or groups of + hosts to access the server, the host can be specified + in any of the following formats:

+ +
+
A (partial) domain-name
+ +
Example: Allow from apache.org
+ Hosts whose names match, or end in, this string are allowed + access. Only complete components are matched, so the above + example will match foo.apache.org but it will + not match fooapache.org. This configuration will + cause the server to perform a double reverse DNS lookup on the + client IP address, regardless of the setting of the HostnameLookups + directive. It will do a reverse DNS lookup on the IP address to + find the associated hostname, and then do a forward lookup on + the hostname to assure that it matches the original IP address. + Only if the forward and reverse DNS are consistent and the + hostname matches will access be allowed.
+ +
A full IP address
+ +
Example: Allow from 10.1.2.3
+ An IP address of a host allowed access
+ +
A partial IP address
+ +
Example: Allow from 10.1
+ The first 1 to 3 bytes of an IP address, for subnet + restriction.
+ +
A network/netmask pair
+ +
Example: Allow from + 10.1.0.0/255.255.0.0
+ A network a.b.c.d, and a netmask w.x.y.z. For more + fine-grained subnet restriction. (Apache 1.3 and later)
+ +
A network/nnn CIDR specification
+ +
Example: Allow from 10.1.0.0/16
+ Similar to the previous case, except the netmask consists of + nnn high-order 1 bits. (Apache 1.3 and later)
+
+ +

Note that the last three examples above match exactly the + same set of hosts.

+ +

The third format of the arguments to the Allow + directive allows access to the server to be controlled based on + the existence of an environment + variable. When Allow from + env=env-variable is specified, then the request + is allowed access if the environment variable + env-variable exists. The server provides the ability + to set environment variables in a flexible way based on + characteristics of the client request using the directives + provided by mod_setenvif. + Therefore, this directive can be used to allow access based on + such factors as the clients User-Agent (browser + type), Referer, or other HTTP request header + fields.

+ +

Example:

+ +
+
+SetEnvIf User-Agent ^KnockKnock/2.0 let_me_in
+<Directory /docroot>
+    Order Deny,Allow
+    Deny from all
+    Allow from env=let_me_in
+</Directory>
+
+
+ +

In this case, browsers with a user-agent string beginning + with KnockKnock/2.0 will be allowed access, and all + others will be denied.

+ +

See also Deny, Order and SetEnvIf.

+
+ +

Deny directive

+ +

+ Syntax: Deny from + all|host|env=env-variable + [host|env=env-variable] ...
+ Context: directory, + .htaccess
+ Override: Limit
+ Status: Base
+ Module: mod_access

+ +

This directive allows access to the server to be restricted + based on hostname, IP address, or environment variables. The + arguments for the Deny directive are identical to + the arguments for the Allow directive.

+ +

See also Allow, Order and SetEnvIf.

+
+ +

Order directive

+ +

+ Syntax: Order + ordering
+ Default: Order + Deny,Allow
+ Context: directory, + .htaccess
+ Override: Limit
+ Status: Base
+ Module: mod_access

+ +

The Order directive controls the default access + state and 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. Access is allowed by default. + Any client which does not match a Deny directive + or does match an Allow directive will be allowed + access to the server.
+ +
Allow,Deny
+ +
The Allow directives are evaluated before + the Deny directives. Access is denied by + default. Any client which does not match an + Allow directive or does match a + Deny directive will be denied access to the + server.
+ +
Mutual-failure
+ +
Only those hosts which appear on the Allow + list and do not appear on the Deny list are + granted access. This ordering has the same effect as + Order Allow,Deny and is deprecated in favor of + that configuration.
+
+ +

Keywords may only be separated by a comma; no whitespace is + allowed between them. Note that in all cases every + Allow and Deny statement is + evaluated.

+ +

In the following example, all hosts in the apache.org domain + are allowed access; all other hosts are denied access.

+ +
+ Order Deny,Allow
+ Deny from all
+ Allow from apache.org
+ +
+ +

In the next example, all hosts in the apache.org domain are + allowed access, except for the hosts which are in the + foo.apache.org subdomain, who are denied access. All hosts not + in the apache.org domain are denied access because the default + state is to deny access to the server.

+ +
+ Order Allow,Deny
+ Allow from apache.org
+ Deny from foo.apache.org
+ +
+ +

On the other hand, if the Order in the last + example is changed to Deny,Allow, all hosts will + be allowed access. This happens because, regardless of the + actual ordering of the directives in the configuration file, + the Allow from apache.org will be evaluated last + and will override the Deny from foo.apache.org. + All hosts not in the apache.org domain will also + be allowed access because the default state will change to + allow.

+ +

The presence of an Order directive can affect + access to a part of the server even in the absence of + accompanying Allow and Deny + directives because of its effect on the default access state. + For example,

+ +
+ <Directory /www>
+   Order Allow,Deny
+ </Directory> +
+ +

will deny all access to the /www directory + because the default access state will be set to + deny.

+ +

The Order directive controls the order of + access directive processing only within each phase of the + server's configuration processing. This implies, for example, + that an Allow or Deny directive + occurring in a <Location> section will always be + evaluated after an Allow or Deny + directive occurring in a <Directory> section or + .htaccess file, regardless of the setting of the + Order directive. For details on the merging of + configuration sections, see the documentation on How Directory, Location and Files + sections work.

+ +

See also: Deny and Allow.

+ +

Apache HTTP Server Version 1.3

+ Index + Home + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_access.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_access.html.html deleted file mode 100644 index 9a5a4eddfac..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_access.html.html +++ /dev/null @@ -1,354 +0,0 @@ - - - - - - - - Apache module mod_access - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_access

- -

This module provides access control based on client - hostname, IP address, or other characteristics of the client - request.

- -

Status: Base
- Source File: mod_access.c
- Module Identifier: - access_module

- -

Summary

- -

The directives provided by mod_access are used in <Directory>, <Files>, and <Location> sections - as well as .htaccess files to - control access to particular parts of the server. Access can be - controlled based on the client hostname, IP address, or other - characteristics of the client request, as captured in environment variables. The - Allow and Deny directives are used to - specify which clients are or are not allowed access to the - server, while the Order directive sets the default - access state, and configures how the Allow and - Deny directives interact with each other.

- -

Both host-based access restrictions and password-based - authentication may be implemented simultaneously. In that case, - the Satisfy directive is used - to determine how the two sets of restrictions interact.

- -

In general, access restriction directives apply to all - access methods (GET, PUT, - POST, etc). This is the desired behavior in most - cases. However, it is possible to restrict some methods, while - leaving other methods unrestricted, by enclosing the directives - in a <Limit> section.

- -

Directives

- - - -

See also Satisfy and Require.

-
- -

Allow directive

- -

- Syntax: Allow from - all|host|env=env-variable - [host|env=env-variable] ...
- Context: directory, - .htaccess
- Override: Limit
- Status: Base
- Module: mod_access

- -

The Allow directive affects which hosts can - access an area of the server. Access can be controlled by - hostname, IP Address, IP Address range, or by other - characteristics of the client request captured in environment - variables.

- -

The first argument to this directive is always - from. The subsequent arguments can take three - different forms. If Allow from all is specified, - then all hosts are allowed access, subject to the configuration - of the Deny and Order directives as - discussed below. To allow only particular hosts or groups of - hosts to access the server, the host can be specified - in any of the following formats:

- -
-
A (partial) domain-name
- -
Example: Allow from apache.org
- Hosts whose names match, or end in, this string are allowed - access. Only complete components are matched, so the above - example will match foo.apache.org but it will - not match fooapache.org. This configuration will - cause the server to perform a double reverse DNS lookup on the - client IP address, regardless of the setting of the HostnameLookups - directive. It will do a reverse DNS lookup on the IP address to - find the associated hostname, and then do a forward lookup on - the hostname to assure that it matches the original IP address. - Only if the forward and reverse DNS are consistent and the - hostname matches will access be allowed.
- -
A full IP address
- -
Example: Allow from 10.1.2.3
- An IP address of a host allowed access
- -
A partial IP address
- -
Example: Allow from 10.1
- The first 1 to 3 bytes of an IP address, for subnet - restriction.
- -
A network/netmask pair
- -
Example: Allow from - 10.1.0.0/255.255.0.0
- A network a.b.c.d, and a netmask w.x.y.z. For more - fine-grained subnet restriction. (Apache 1.3 and later)
- -
A network/nnn CIDR specification
- -
Example: Allow from 10.1.0.0/16
- Similar to the previous case, except the netmask consists of - nnn high-order 1 bits. (Apache 1.3 and later)
-
- -

Note that the last three examples above match exactly the - same set of hosts.

- -

The third format of the arguments to the Allow - directive allows access to the server to be controlled based on - the existence of an environment - variable. When Allow from - env=env-variable is specified, then the request - is allowed access if the environment variable - env-variable exists. The server provides the ability - to set environment variables in a flexible way based on - characteristics of the client request using the directives - provided by mod_setenvif. - Therefore, this directive can be used to allow access based on - such factors as the clients User-Agent (browser - type), Referer, or other HTTP request header - fields.

- -

Example:

- -
-
-SetEnvIf User-Agent ^KnockKnock/2.0 let_me_in
-<Directory /docroot>
-    Order Deny,Allow
-    Deny from all
-    Allow from env=let_me_in
-</Directory>
-
-
- -

In this case, browsers with a user-agent string beginning - with KnockKnock/2.0 will be allowed access, and all - others will be denied.

- -

See also Deny, Order and SetEnvIf.

-
- -

Deny directive

- -

- Syntax: Deny from - all|host|env=env-variable - [host|env=env-variable] ...
- Context: directory, - .htaccess
- Override: Limit
- Status: Base
- Module: mod_access

- -

This directive allows access to the server to be restricted - based on hostname, IP address, or environment variables. The - arguments for the Deny directive are identical to - the arguments for the Allow directive.

- -

See also Allow, Order and SetEnvIf.

-
- -

Order directive

- -

- Syntax: Order - ordering
- Default: Order - Deny,Allow
- Context: directory, - .htaccess
- Override: Limit
- Status: Base
- Module: mod_access

- -

The Order directive controls the default access - state and 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. Access is allowed by default. - Any client which does not match a Deny directive - or does match an Allow directive will be allowed - access to the server.
- -
Allow,Deny
- -
The Allow directives are evaluated before - the Deny directives. Access is denied by - default. Any client which does not match an - Allow directive or does match a - Deny directive will be denied access to the - server.
- -
Mutual-failure
- -
Only those hosts which appear on the Allow - list and do not appear on the Deny list are - granted access. This ordering has the same effect as - Order Allow,Deny and is deprecated in favor of - that configuration.
-
- -

Keywords may only be separated by a comma; no whitespace is - allowed between them. Note that in all cases every - Allow and Deny statement is - evaluated.

- -

In the following example, all hosts in the apache.org domain - are allowed access; all other hosts are denied access.

- -
- Order Deny,Allow
- Deny from all
- Allow from apache.org
- -
- -

In the next example, all hosts in the apache.org domain are - allowed access, except for the hosts which are in the - foo.apache.org subdomain, who are denied access. All hosts not - in the apache.org domain are denied access because the default - state is to deny access to the server.

- -
- Order Allow,Deny
- Allow from apache.org
- Deny from foo.apache.org
- -
- -

On the other hand, if the Order in the last - example is changed to Deny,Allow, all hosts will - be allowed access. This happens because, regardless of the - actual ordering of the directives in the configuration file, - the Allow from apache.org will be evaluated last - and will override the Deny from foo.apache.org. - All hosts not in the apache.org domain will also - be allowed access because the default state will change to - allow.

- -

The presence of an Order directive can affect - access to a part of the server even in the absence of - accompanying Allow and Deny - directives because of its effect on the default access state. - For example,

- -
- <Directory /www>
-   Order Allow,Deny
- </Directory> -
- -

will deny all access to the /www directory - because the default access state will be set to - deny.

- -

The Order directive controls the order of - access directive processing only within each phase of the - server's configuration processing. This implies, for example, - that an Allow or Deny directive - occurring in a <Location> section will always be - evaluated after an Allow or Deny - directive occurring in a <Directory> section or - .htaccess file, regardless of the setting of the - Order directive. For details on the merging of - configuration sections, see the documentation on How Directory, Location and Files - sections work.

- -

See also: Deny and Allow.

- -

Apache HTTP Server Version 1.3

- Index - Home - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html b/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html new file mode 100644 index 00000000000..e813007011f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html @@ -0,0 +1,167 @@ + + + + + + + + Module mod_actions + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_actions

+ +

This module provides for executing CGI scripts based on + media type or request method.

+ +

Status: Base
+ Source File: + mod_actions.c
+ Module Identifier: + action_module
+ Compatibility: Available in + Apache 1.1 and later.

+ +

Summary

+ +

This module has two directives. The Action directive lets + you run CGI scripts whenever a file of a certain type is + requested. The Script directive lets you run CGI scripts + whenever a particular method is used in a request. This makes + it much easier to execute scripts that process files.

+ +

Directives

+ + +
+ +

Action directive

+ +

Syntax: Action action-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 action-type is triggered by the + request. The cgi-script is the URL-path to a resource that + has been configured as a CGI script using ScriptAlias + or AddHandler. The action-type can be either + a handler or a MIME content type. It + sends the URL and file path of the requested document using the + standard CGI PATH_INFO and PATH_TRANSLATED environment + variables.

+ +

Examples:

+ 
+    # Requests for files of a particular type:
+    Action image/gif /cgi-bin/images.cgi
+
+    # Files of a particular file extension
+    AddHandler my-file-type .xyz
+    Action my-file-type /cgi-bin/program.cgi
+
+ +

In the first example, requests for files with a MIME content + type of image/gif will instead be handled by the + specified cgi script /cgi-bin/images.cgi.

+ +

In the second example, requests for files with a file extension of + .xyz are handled instead by the specified cgi script + /cgi-bin/program.cgi.

+ +

See also: AddHandler

+ +
+ +

Script directive

+ +

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; arbitrary method use is only + available with 1.3.10 and later

+ +

This directive adds an action, which will activate + cgi-script when a file is requested using the method of + method. The cgi-script is the URL-path to a resource + that has been configured as a CGI script using + ScriptAlias or AddHandler. The URL and + file path of the requested document is sent using the standard CGI + PATH_INFO and PATH_TRANSLATED environment variables.

+ +
+ Prior to Apache 1.3.10, method can only be one of + GET, POST, PUT, or + DELETE. As of 1.3.10, any arbitrary method name + may be used. Method names are case-sensitive, so + Script PUT and Script put + have two entirely different effects. +
+ +

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:

+
+    # For <ISINDEX>-style searching
+    Script GET /cgi-bin/search
+    # A CGI PUT handler
+    Script PUT /~bob/put.cgi
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html.html deleted file mode 100644 index e813007011f..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html.html +++ /dev/null @@ -1,167 +0,0 @@ - - - - - - - - Module mod_actions - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_actions

- -

This module provides for executing CGI scripts based on - media type or request method.

- -

Status: Base
- Source File: - mod_actions.c
- Module Identifier: - action_module
- Compatibility: Available in - Apache 1.1 and later.

- -

Summary

- -

This module has two directives. The Action directive lets - you run CGI scripts whenever a file of a certain type is - requested. The Script directive lets you run CGI scripts - whenever a particular method is used in a request. This makes - it much easier to execute scripts that process files.

- -

Directives

- - -
- -

Action directive

- -

Syntax: Action action-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 action-type is triggered by the - request. The cgi-script is the URL-path to a resource that - has been configured as a CGI script using ScriptAlias - or AddHandler. The action-type can be either - a handler or a MIME content type. It - sends the URL and file path of the requested document using the - standard CGI PATH_INFO and PATH_TRANSLATED environment - variables.

- -

Examples:

- 
-    # Requests for files of a particular type:
-    Action image/gif /cgi-bin/images.cgi
-
-    # Files of a particular file extension
-    AddHandler my-file-type .xyz
-    Action my-file-type /cgi-bin/program.cgi
-
- -

In the first example, requests for files with a MIME content - type of image/gif will instead be handled by the - specified cgi script /cgi-bin/images.cgi.

- -

In the second example, requests for files with a file extension of - .xyz are handled instead by the specified cgi script - /cgi-bin/program.cgi.

- -

See also: AddHandler

- -
- -

Script directive

- -

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; arbitrary method use is only - available with 1.3.10 and later

- -

This directive adds an action, which will activate - cgi-script when a file is requested using the method of - method. The cgi-script is the URL-path to a resource - that has been configured as a CGI script using - ScriptAlias or AddHandler. The URL and - file path of the requested document is sent using the standard CGI - PATH_INFO and PATH_TRANSLATED environment variables.

- -
- Prior to Apache 1.3.10, method can only be one of - GET, POST, PUT, or - DELETE. As of 1.3.10, any arbitrary method name - may be used. Method names are case-sensitive, so - Script PUT and Script put - have two entirely different effects. -
- -

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:

-
-    # For <ISINDEX>-style searching
-    Script GET /cgi-bin/search
-    # A CGI PUT handler
-    Script PUT /~bob/put.cgi
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html b/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html new file mode 100644 index 00000000000..93ea7d84f78 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html @@ -0,0 +1,399 @@ + + + + + + + + Apache module mod_alias + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_alias

+ +

This module provides for mapping different parts of the host + filesystem in the document tree, and for URL redirection.

+ +

Status: Base
+ Source File: mod_alias.c
+ Module Identifier: + alias_module

+ +

Summary

+ +

The directives contained in this module allow for + manipulation and control of URLs as requests arrive at the + server. The Alias and ScriptAlias + directives are used to map between URLs and filesystem paths. + This allows for content which is not directly under the DocumentRoot to + be served as part of the web document tree. The + ScriptAlias directive has the additional effect of + marking the target directory as containing only CGI + scripts.

+ +

The Redirect directives are used to instruct + clients to make a new request with a different URL. They are + often used when a resource has moved to a new location.

+ +

A more powerful and flexible set of directives for + manipulating URLs is contained in the mod_rewrite + module.

+ +

Directives

+ + +
+ +

Alias directive

+ +

+ Syntax: Alias URL-path + file-path|directory-path
+ 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 +
+ +

A request for http://myserver/image/foo.gif would cause the + server to return the file /ftp/pub/image/foo.gif.

+ +

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/apache/icons/ then the url + /icons will not be aliased.

+ +

Note that you may need to specify additional <Directory> + sections which cover the destination of aliases. + Aliasing occurs before <Directory> sections + are checked, so only the destination of aliases are affected. + (Note however <Location> + sections are run through once before aliases are performed, so + they will apply.)

+ +

See also ScriptAlias.

+
+ +

AliasMatch

+ +

Syntax: AliasMatch regex + file-path|directory-path
+ Context: server config, virtual + host
+ Status: Base
+ Module: mod_alias
+ Compatibility: Available in + Apache 1.3 and later

+ +

This directive is equivalent to Alias, + but makes use of standard regular expressions, instead of + simple prefix matching. The supplied regular expression is + matched against the URL-path, and if it matches, the server + will substitute any parenthesized matches into the given string + and use it as a filename. For example, to activate the + /icons directory, one might use:

+
+    AliasMatch ^/icons(.*) /usr/local/apache/icons$1
+
+
+ +

Redirect + directive

+ +

+ Syntax: Redirect + [status] URL-path URL
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ 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 +
+ +

If the client requests http://myserver/service/foo.txt, it + will be told to access http://foo2.bar.com/service/foo.txt + instead.

+ +

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 resource 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.
+
+ +

Other status codes can be returned by giving the numeric + status code as the value of status. If the status is + between 300 and 399, the url argument must be present, + otherwise it must be omitted. Note that the status must be + known to the Apache code (see the function + send_error_response in http_protocol.c).

+ +

Example:

+ + 
+    Redirect permanent /one http://example.com/two

+    Redirect 303 /two http://example.com/other
+
+
+ +

RedirectMatch

+ +

Syntax: RedirectMatch + [status] regex URL
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_alias
+ Compatibility: Available in + Apache 1.3 and later

+ +

This directive is equivalent to Redirect, but makes use of standard + regular expressions, instead of simple prefix matching. The + supplied regular expression is matched against the URL-path, + and if it matches, the server will substitute any parenthesized + matches into the given string and use it as a filename. For + example, to redirect all GIF files to like-named JPEG files on + another server, one might use:

+
+    RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg
+
+
+ +

RedirectTemp + directive

+ +

+ Syntax: RedirectTemp + URL-path URL
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_alias
+ Compatibility: This directive + is only available in Apache 1.2 and later

+ +

This directive makes the client know that the Redirect is + only temporary (status 302). Exactly equivalent to + Redirect temp.

+
+ +

RedirectPermanent + directive

+ +

+ Syntax: RedirectPermanent + URL-path URL
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_alias
+ Compatibility: This directive + is only available in Apache 1.2 and later

+ +

This directive makes the client know that the Redirect is + permanent (status 301). Exactly equivalent to Redirect + permanent.

+
+ +

ScriptAlias + directive

+ +

+ Syntax: ScriptAlias + URL-path file-path|directory-path
+ 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 that will be + processed by mod_cgi's cgi-script + handler. URLs with a (%-decoded) path beginning with + URL-path will be mapped to scripts beginning with the + second argument which is a full pathname in the local + filesystem.

+ +

Example:

+ +
+ ScriptAlias /cgi-bin/ /web/cgi-bin/ +
+ +

A request for http://myserver/cgi-bin/foo would cause the + server to run the script /web/cgi-bin/foo.

+
+ +

ScriptAliasMatch

+ +

Syntax: ScriptAliasMatch + regex file-path|directory-path
+ Context: server config, virtual + host
+ Status: Base
+ Module: mod_alias
+ Compatibility: Available in + Apache 1.3 and later

+ +

This directive is equivalent to ScriptAlias, but makes use of standard + regular expressions, instead of simple prefix matching. The + supplied regular expression is matched against the URL-path, + and if it matches, the server will substitute any parenthesized + matches into the given string and use it as a filename. For + example, to activate the standard /cgi-bin, one + might use:

+
+    ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html.html deleted file mode 100644 index 93ea7d84f78..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html.html +++ /dev/null @@ -1,399 +0,0 @@ - - - - - - - - Apache module mod_alias - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_alias

- -

This module provides for mapping different parts of the host - filesystem in the document tree, and for URL redirection.

- -

Status: Base
- Source File: mod_alias.c
- Module Identifier: - alias_module

- -

Summary

- -

The directives contained in this module allow for - manipulation and control of URLs as requests arrive at the - server. The Alias and ScriptAlias - directives are used to map between URLs and filesystem paths. - This allows for content which is not directly under the DocumentRoot to - be served as part of the web document tree. The - ScriptAlias directive has the additional effect of - marking the target directory as containing only CGI - scripts.

- -

The Redirect directives are used to instruct - clients to make a new request with a different URL. They are - often used when a resource has moved to a new location.

- -

A more powerful and flexible set of directives for - manipulating URLs is contained in the mod_rewrite - module.

- -

Directives

- - -
- -

Alias directive

- -

- Syntax: Alias URL-path - file-path|directory-path
- 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 -
- -

A request for http://myserver/image/foo.gif would cause the - server to return the file /ftp/pub/image/foo.gif.

- -

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/apache/icons/ then the url - /icons will not be aliased.

- -

Note that you may need to specify additional <Directory> - sections which cover the destination of aliases. - Aliasing occurs before <Directory> sections - are checked, so only the destination of aliases are affected. - (Note however <Location> - sections are run through once before aliases are performed, so - they will apply.)

- -

See also ScriptAlias.

-
- -

AliasMatch

- -

Syntax: AliasMatch regex - file-path|directory-path
- Context: server config, virtual - host
- Status: Base
- Module: mod_alias
- Compatibility: Available in - Apache 1.3 and later

- -

This directive is equivalent to Alias, - but makes use of standard regular expressions, instead of - simple prefix matching. The supplied regular expression is - matched against the URL-path, and if it matches, the server - will substitute any parenthesized matches into the given string - and use it as a filename. For example, to activate the - /icons directory, one might use:

-
-    AliasMatch ^/icons(.*) /usr/local/apache/icons$1
-
-
- -

Redirect - directive

- -

- Syntax: Redirect - [status] URL-path URL
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- 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 -
- -

If the client requests http://myserver/service/foo.txt, it - will be told to access http://foo2.bar.com/service/foo.txt - instead.

- -

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 resource 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.
-
- -

Other status codes can be returned by giving the numeric - status code as the value of status. If the status is - between 300 and 399, the url argument must be present, - otherwise it must be omitted. Note that the status must be - known to the Apache code (see the function - send_error_response in http_protocol.c).

- -

Example:

- - 
-    Redirect permanent /one http://example.com/two

-    Redirect 303 /two http://example.com/other
-
-
- -

RedirectMatch

- -

Syntax: RedirectMatch - [status] regex URL
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_alias
- Compatibility: Available in - Apache 1.3 and later

- -

This directive is equivalent to Redirect, but makes use of standard - regular expressions, instead of simple prefix matching. The - supplied regular expression is matched against the URL-path, - and if it matches, the server will substitute any parenthesized - matches into the given string and use it as a filename. For - example, to redirect all GIF files to like-named JPEG files on - another server, one might use:

-
-    RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg
-
-
- -

RedirectTemp - directive

- -

- Syntax: RedirectTemp - URL-path URL
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_alias
- Compatibility: This directive - is only available in Apache 1.2 and later

- -

This directive makes the client know that the Redirect is - only temporary (status 302). Exactly equivalent to - Redirect temp.

-
- -

RedirectPermanent - directive

- -

- Syntax: RedirectPermanent - URL-path URL
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_alias
- Compatibility: This directive - is only available in Apache 1.2 and later

- -

This directive makes the client know that the Redirect is - permanent (status 301). Exactly equivalent to Redirect - permanent.

-
- -

ScriptAlias - directive

- -

- Syntax: ScriptAlias - URL-path file-path|directory-path
- 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 that will be - processed by mod_cgi's cgi-script - handler. URLs with a (%-decoded) path beginning with - URL-path will be mapped to scripts beginning with the - second argument which is a full pathname in the local - filesystem.

- -

Example:

- -
- ScriptAlias /cgi-bin/ /web/cgi-bin/ -
- -

A request for http://myserver/cgi-bin/foo would cause the - server to run the script /web/cgi-bin/foo.

-
- -

ScriptAliasMatch

- -

Syntax: ScriptAliasMatch - regex file-path|directory-path
- Context: server config, virtual - host
- Status: Base
- Module: mod_alias
- Compatibility: Available in - Apache 1.3 and later

- -

This directive is equivalent to ScriptAlias, but makes use of standard - regular expressions, instead of simple prefix matching. The - supplied regular expression is matched against the URL-path, - and if it matches, the server will substitute any parenthesized - matches into the given string and use it as a filename. For - example, to activate the standard /cgi-bin, one - might use:

-
-    ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_asis.html b/usr.sbin/httpd/htdocs/manual/mod/mod_asis.html new file mode 100644 index 00000000000..9d93d39f157 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_asis.html @@ -0,0 +1,107 @@ + + + + + + + + Apache module mod_asis + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_asis

+ +

This module provides for sending files which contain their + own HTTP headers.

+ +

Status: Base
+ Source File: mod_asis.c
+ Module Identifier: + asis_module

+ +

Summary

+ +

This module provides the handler send-as-is + which causes Apache to send the document without adding most of + the usual 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.

+ +

For historical reasons, this module will also process any + file with the mime type httpd/send-as-is.

+ +

Directives

+ +

This module provides no directives.

+ +

Usage

+ +

In the server configuration file, associate files with the + send-as-is handler e.g.

+ +
+ AddHandler send-as-is asis +
+ 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: 301 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> +
+ +

Notes: the server always adds a Date: and Server: header to + the data returned to the client, so these should not be + included in the file. The server does not add a + Last-Modified header; it probably should. +

+ +

Apache HTTP Server Version 1.3

+ Index + Home + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_asis.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_asis.html.html deleted file mode 100644 index 9d93d39f157..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_asis.html.html +++ /dev/null @@ -1,107 +0,0 @@ - - - - - - - - Apache module mod_asis - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_asis

- -

This module provides for sending files which contain their - own HTTP headers.

- -

Status: Base
- Source File: mod_asis.c
- Module Identifier: - asis_module

- -

Summary

- -

This module provides the handler send-as-is - which causes Apache to send the document without adding most of - the usual 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.

- -

For historical reasons, this module will also process any - file with the mime type httpd/send-as-is.

- -

Directives

- -

This module provides no directives.

- -

Usage

- -

In the server configuration file, associate files with the - send-as-is handler e.g.

- -
- AddHandler send-as-is asis -
- 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: 301 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> -
- -

Notes: the server always adds a Date: and Server: header to - the data returned to the client, so these should not be - included in the file. The server does not add a - Last-Modified header; it probably should. -

- -

Apache HTTP Server Version 1.3

- Index - Home - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_auth.html b/usr.sbin/httpd/htdocs/manual/mod/mod_auth.html new file mode 100644 index 00000000000..2789d5bb5e0 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_auth.html @@ -0,0 +1,326 @@ + + + + + + + + Apache module mod_auth + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_auth

+ +

This module provides for user authentication using text + files.

+ +

Status: Base
+ Source File: mod_auth.c
+ Module Identifier: + auth_module

+ +

Summary

+ +

This module allows the use of HTTP Basic Authentication to + restrict access by looking up users in plain text password and + group files. Similar functionality and greater scalability is + provided by mod_auth_dbm and mod_auth_db. HTTP Digest + Authentication is provided by mod_auth_digest.

+ +

Note that these credential-based security mechanisms are + only as strong as your Web server's security. As a rule, they + are not as strong as the operating system's own security + system.

+ +

Directives

+ + + +

See also: require, satisfy, and mod_auth require keywords.

+
+ +

mod_auth + Require Keywords

+ +

The mod_auth module supports the following + keywords that can be given to the Require directive:

+ +
+
user username [...]
+ +
The supplied username and password must be in the AuthUserFile database, and the + username must also be one of those listed on the Require + directive.
+ +
group groupname [...]
+ +
The supplied username and password must be in the AuthUserFile database, and the + username must also be a member of one of the named groups in + the AuthGroupFile database.
+ +
valid-user
+ +
The supplied username and password must be in the AuthUserFile database. Any valid + username from that file will be allowed.
+ +
file-owner
+ +
[Available after Apache 1.3.20] The supplied username and + password must be in the AuthUserFile database, and the + username must also match the system's name for the owner of + the file being requested. That is, if the operating system + say the requested file is owned by jones, then + the username used to access it through the Web must be + jones as well.
+ +
file-group
+ +
[Available after Apache 1.3.20] The supplied username and + password must be in the AuthUserFile database, the name of + the group that owns the file must be in the AuthGroupFile database, and the + username must be a member of that group. For example, if the + operating system says the requested file is owned by group + accounts, the group accounts must + be in the AuthGroupFile database and the username used in the + request must be a member of that group.
+
+
+ +

Example of Require + file-owner

+ +

Consider a multi-user system running the Apache Web server, + with each user having his or her own files in + ~/public_html/private. Assuming that there is a + single AuthUserFile database that lists all of their usernames, + and that their Web usernames match the ones that actually own + the files on the server, then the following stanza would allow + only the user himself access to his own files. User + jones would not be allowed to access files in + /home/smith/public_html/private unless they were + owned by jones instead of smith.

+
+    <Directory /home/*/public_html/private>
+        AuthType Basic
+        AuthName MyPrivateFile
+        AuthUserFile /usr/local/apache/etc/.htpasswd-allusers
+        Satisfy All
+        Require file-owner
+    </Directory>
+
+
+ +

AuthGroupFile directive

+ Syntax: AuthGroupFile + file-path
+ 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. + File-path is the path to the group file. If it is not + absolute (i.e., if it doesn't begin with a slash), it + is treated as relative to the ServerRoot.

+ +

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 +
+ Note that searching large text files is very + inefficient; AuthDBMGroupFile + should be used instead. + +

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 + directive

+ Syntax: AuthUserFile + file-path
+ 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. File-path is the path to the user + file. If it is not absolute (i.e., if it doesn't begin + with a slash), it is treated as relative to the ServerRoot.

+ +

Each line of the user 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.

+ +

The utility htpasswd + which is installed as part of the binary distribution, or which + can be found in src/support, is used to maintain + this password file. See the man page for more + details. In short

+ +
+ htpasswd -c Filename username
+ Create a password file 'Filename' with 'username' as the + initial ID. It will prompt for the password. htpasswd + Filename username2
+ Adds or modifies in password file 'Filename' the 'username'. +
+ +

Note that searching large text files is very + 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 may be + able to download the AuthUserFile.
+ +
Also be aware that null usernames are permitted, and null + passwords as well (through Apache 1.3.20). If your + AuthUserFile includes a line containing only a colon (':'), a + 'Require valid-user' will allow access if both + the username and password in the credentials are + omitted.
+
+ See also AuthName, AuthType and AuthGroupFile. +
+ +

AuthAuthoritative directive

+ Syntax: AuthAuthoritative + on|off
+ Default: + AuthAuthoritative on
+ 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 NCSA compliant behavior.

+ +

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.

+ +

+ +

Apache HTTP Server Version 1.3

+ Index + Home + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_auth.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_auth.html.html deleted file mode 100644 index 2789d5bb5e0..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_auth.html.html +++ /dev/null @@ -1,326 +0,0 @@ - - - - - - - - Apache module mod_auth - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_auth

- -

This module provides for user authentication using text - files.

- -

Status: Base
- Source File: mod_auth.c
- Module Identifier: - auth_module

- -

Summary

- -

This module allows the use of HTTP Basic Authentication to - restrict access by looking up users in plain text password and - group files. Similar functionality and greater scalability is - provided by mod_auth_dbm and mod_auth_db. HTTP Digest - Authentication is provided by mod_auth_digest.

- -

Note that these credential-based security mechanisms are - only as strong as your Web server's security. As a rule, they - are not as strong as the operating system's own security - system.

- -

Directives

- - - -

See also: require, satisfy, and mod_auth require keywords.

-
- -

mod_auth - Require Keywords

- -

The mod_auth module supports the following - keywords that can be given to the Require directive:

- -
-
user username [...]
- -
The supplied username and password must be in the AuthUserFile database, and the - username must also be one of those listed on the Require - directive.
- -
group groupname [...]
- -
The supplied username and password must be in the AuthUserFile database, and the - username must also be a member of one of the named groups in - the AuthGroupFile database.
- -
valid-user
- -
The supplied username and password must be in the AuthUserFile database. Any valid - username from that file will be allowed.
- -
file-owner
- -
[Available after Apache 1.3.20] The supplied username and - password must be in the AuthUserFile database, and the - username must also match the system's name for the owner of - the file being requested. That is, if the operating system - say the requested file is owned by jones, then - the username used to access it through the Web must be - jones as well.
- -
file-group
- -
[Available after Apache 1.3.20] The supplied username and - password must be in the AuthUserFile database, the name of - the group that owns the file must be in the AuthGroupFile database, and the - username must be a member of that group. For example, if the - operating system says the requested file is owned by group - accounts, the group accounts must - be in the AuthGroupFile database and the username used in the - request must be a member of that group.
-
-
- -

Example of Require - file-owner

- -

Consider a multi-user system running the Apache Web server, - with each user having his or her own files in - ~/public_html/private. Assuming that there is a - single AuthUserFile database that lists all of their usernames, - and that their Web usernames match the ones that actually own - the files on the server, then the following stanza would allow - only the user himself access to his own files. User - jones would not be allowed to access files in - /home/smith/public_html/private unless they were - owned by jones instead of smith.

-
-    <Directory /home/*/public_html/private>
-        AuthType Basic
-        AuthName MyPrivateFile
-        AuthUserFile /usr/local/apache/etc/.htpasswd-allusers
-        Satisfy All
-        Require file-owner
-    </Directory>
-
-
- -

AuthGroupFile directive

- Syntax: AuthGroupFile - file-path
- 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. - File-path is the path to the group file. If it is not - absolute (i.e., if it doesn't begin with a slash), it - is treated as relative to the ServerRoot.

- -

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 -
- Note that searching large text files is very - inefficient; AuthDBMGroupFile - should be used instead. - -

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 - directive

- Syntax: AuthUserFile - file-path
- 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. File-path is the path to the user - file. If it is not absolute (i.e., if it doesn't begin - with a slash), it is treated as relative to the ServerRoot.

- -

Each line of the user 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.

- -

The utility htpasswd - which is installed as part of the binary distribution, or which - can be found in src/support, is used to maintain - this password file. See the man page for more - details. In short

- -
- htpasswd -c Filename username
- Create a password file 'Filename' with 'username' as the - initial ID. It will prompt for the password. htpasswd - Filename username2
- Adds or modifies in password file 'Filename' the 'username'. -
- -

Note that searching large text files is very - 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 may be - able to download the AuthUserFile.
- -
Also be aware that null usernames are permitted, and null - passwords as well (through Apache 1.3.20). If your - AuthUserFile includes a line containing only a colon (':'), a - 'Require valid-user' will allow access if both - the username and password in the credentials are - omitted.
-
- See also AuthName, AuthType and AuthGroupFile. -
- -

AuthAuthoritative directive

- Syntax: AuthAuthoritative - on|off
- Default: - AuthAuthoritative on
- 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 NCSA compliant behavior.

- -

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.

- -

- -

Apache HTTP Server Version 1.3

- Index - Home - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html b/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html new file mode 100644 index 00000000000..74435a72ed7 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html @@ -0,0 +1,232 @@ + + + + + + + + Apache module mod_cgi + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_cgi

+ +

This module provides for execution of CGI scripts.

+ +

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

+ +

Summary

+ + Any file that has the mime type + application/x-httpd-cgi or handler + cgi-script (Apache 1.1 or later) will be treated + as a CGI script, and run by the server, with its output being + returned to the client. Files acquire this type either by + having a name containing an extension defined by the AddType directive, or by being + in a ScriptAlias + directory. Files that are not in a ScriptAlias directory, + but which are of type application/x-httpd-cgi by + virtue of an AddType directive, will still not be + executed by the server unless Options ExecCGI is + enabled. See the Options directive for + more details. + +

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

+ +

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

+ +

Directives

+ + + +

See also: Options, ScriptAlias, AddType and AddHandler.

+ +

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 HostnameLookups + is set to on (it is off by default), and if a + reverse DNS lookup of the accessing host's address indeed + finds a host name.
+ +
REMOTE_IDENT
+ +
This will only be set if IdentityCheck is set to + on and the accessing host supports the ident + protocol. Note that the contents of this variable cannot be + relied upon because it can easily be faked, and if there is a + proxy between the client and the server, it is usually + totally useless.
+ +
REMOTE_USER
+ +
This will only be set if the CGI script is subject to + authentication.
+
+ +

CGI Debugging

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

CGI Logfile Format

+ When configured, the CGI error log logs any CGI which does not + execute properly. Each CGI script which fails to operate causes + several lines of information to be logged. The first two lines + are always of the format: +
+  %% [time] request-line
+  %% HTTP-status CGI-script-filename
+
+ If the error is that CGI script cannot be run, the log file + will contain an extra two lines: +
+  %%error
+  error-message
+
+ Alternatively, if the error is the result of the script + returning incorrect header information (often due to a bug in + the script), the following information is logged: +
+  %request
+  All HTTP request headers received
+  POST or PUT entity (if any)
+  %response
+  All headers output by the CGI script
+  %stdout
+  CGI standard output
+  %stderr
+  CGI standard error
+
+ (The %stdout and %stderr parts may be missing if the script did + not output anything on standard output or standard error). +
+ +

ScriptLog + directive

+ Syntax: ScriptLog + filename
+ Default: none
+ Context: server config
+ Status: mod_cgi + +

The ScriptLog directive sets the CGI script error + logfile. If no ScriptLog is given, no error log is created. If + given, any CGI errors are logged into the filename given as + argument. If this is a relative file or path it is taken + 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 directive

+ Syntax: ScriptLogLength + bytes
+ Default: 10385760
+ Context: server config
+ Status: mod_cgi + +

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

+
+ +

ScriptLogBuffer

+ Syntax: ScriptLogBuffer + bytes
+ Default: 1024
+ Context: server config
+ Status: mod_cgi + +

The size of any PUT or POST entity body that is logged to + 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.

+ +

Apache HTTP Server Version 1.3

+ Index + Home + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html.html deleted file mode 100644 index 74435a72ed7..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html.html +++ /dev/null @@ -1,232 +0,0 @@ - - - - - - - - Apache module mod_cgi - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_cgi

- -

This module provides for execution of CGI scripts.

- -

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

- -

Summary

- - Any file that has the mime type - application/x-httpd-cgi or handler - cgi-script (Apache 1.1 or later) will be treated - as a CGI script, and run by the server, with its output being - returned to the client. Files acquire this type either by - having a name containing an extension defined by the AddType directive, or by being - in a ScriptAlias - directory. Files that are not in a ScriptAlias directory, - but which are of type application/x-httpd-cgi by - virtue of an AddType directive, will still not be - executed by the server unless Options ExecCGI is - enabled. See the Options directive for - more details. - -

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

- -

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

- -

Directives

- - - -

See also: Options, ScriptAlias, AddType and AddHandler.

- -

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 HostnameLookups - is set to on (it is off by default), and if a - reverse DNS lookup of the accessing host's address indeed - finds a host name.
- -
REMOTE_IDENT
- -
This will only be set if IdentityCheck is set to - on and the accessing host supports the ident - protocol. Note that the contents of this variable cannot be - relied upon because it can easily be faked, and if there is a - proxy between the client and the server, it is usually - totally useless.
- -
REMOTE_USER
- -
This will only be set if the CGI script is subject to - authentication.
-
- -

CGI Debugging

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

CGI Logfile Format

- When configured, the CGI error log logs any CGI which does not - execute properly. Each CGI script which fails to operate causes - several lines of information to be logged. The first two lines - are always of the format: -
-  %% [time] request-line
-  %% HTTP-status CGI-script-filename
-
- If the error is that CGI script cannot be run, the log file - will contain an extra two lines: -
-  %%error
-  error-message
-
- Alternatively, if the error is the result of the script - returning incorrect header information (often due to a bug in - the script), the following information is logged: -
-  %request
-  All HTTP request headers received
-  POST or PUT entity (if any)
-  %response
-  All headers output by the CGI script
-  %stdout
-  CGI standard output
-  %stderr
-  CGI standard error
-
- (The %stdout and %stderr parts may be missing if the script did - not output anything on standard output or standard error). -
- -

ScriptLog - directive

- Syntax: ScriptLog - filename
- Default: none
- Context: server config
- Status: mod_cgi - -

The ScriptLog directive sets the CGI script error - logfile. If no ScriptLog is given, no error log is created. If - given, any CGI errors are logged into the filename given as - argument. If this is a relative file or path it is taken - 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 directive

- Syntax: ScriptLogLength - bytes
- Default: 10385760
- Context: server config
- Status: mod_cgi - -

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

-
- -

ScriptLogBuffer

- Syntax: ScriptLogBuffer - bytes
- Default: 1024
- Context: server config
- Status: mod_cgi - -

The size of any PUT or POST entity body that is logged to - 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.

- -

Apache HTTP Server Version 1.3

- Index - Home - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_dir.html b/usr.sbin/httpd/htdocs/manual/mod/mod_dir.html new file mode 100644 index 00000000000..6ae81e435e2 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_dir.html @@ -0,0 +1,129 @@ + + + + + + + + Apache module mod_dir + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_dir

+ +

This module provides for "trailing slash" redirects and + serving directory index files.

+ +

Status: Base
+ Source File: mod_dir.c
+ Module Identifier: + dir_module

+ +

Summary

+ The index of a directory can come from one of two sources: + + + The two functions are separated so that you can completely + remove (or replace) automatic index generation should you want + to. + +

A "trailing slash" redirect is issued when the server + receives a request for a URL + http://servername/foo/dirname where + dirname is a directory. Directories require a + trailing slash, so mod_dir issues a redirect to + http://servername/foo/dirname/.

+ +

Directives

+ + +
+ +

DirectoryIndex directive

+ + 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 +
+ then a request for 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 +
+ would cause the CGI script /cgi-bin/index.pl to be + executed if neither index.html or + index.txt existed in a directory. + +

+ +

Apache HTTP Server Version 1.3

+ Index + Home + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_dir.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_dir.html.html deleted file mode 100644 index 6ae81e435e2..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_dir.html.html +++ /dev/null @@ -1,129 +0,0 @@ - - - - - - - - Apache module mod_dir - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_dir

- -

This module provides for "trailing slash" redirects and - serving directory index files.

- -

Status: Base
- Source File: mod_dir.c
- Module Identifier: - dir_module

- -

Summary

- The index of a directory can come from one of two sources: - - - The two functions are separated so that you can completely - remove (or replace) automatic index generation should you want - to. - -

A "trailing slash" redirect is issued when the server - receives a request for a URL - http://servername/foo/dirname where - dirname is a directory. Directories require a - trailing slash, so mod_dir issues a redirect to - http://servername/foo/dirname/.

- -

Directives

- - -
- -

DirectoryIndex directive

- - 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 -
- then a request for 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 -
- would cause the CGI script /cgi-bin/index.pl to be - executed if neither index.html or - index.txt existed in a directory. - -

- -

Apache HTTP Server Version 1.3

- Index - Home - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_env.html b/usr.sbin/httpd/htdocs/manual/mod/mod_env.html new file mode 100644 index 00000000000..9e03e758c31 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_env.html @@ -0,0 +1,146 @@ + + + + + + + + Apache module mod_env + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Apache module mod_env

+ +

This module provides for modifying the environment which is + passed to CGI scripts and SSI pages.

+ +

Status: Base
+ Source File: mod_env.c
+ Module Identifier: + env_module
+ Compatibility: Available in + Apache 1.1 and later.

+ +

Summary

+ +

This module allows for control of the environment that will + be provided to CGI scripts and SSI pages. Environment variables + may be passed from the shell which invoked the httpd process. + Alternatively, environment variables may be set or unset within + the configuration process.

+ +

For additional information, we provide a document on Environment Variables in Apache.

+ +

Directives

+ + +
+ +

PassEnv directive

+ Syntax: PassEnv + env-variable [env-variable] ...
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_env
+ Compatibility: PassEnv is only + available in Apache 1.1 and later. Directory and .htaccess context + is available in Apache 1.3.7 and later. + +

Specifies one or more environment variables to pass to CGI + scripts and SSI pages from the environment of the shell which + invoked the httpd process. Example:

+
+    PassEnv LD_LIBRARY_PATH
+
+
+ +

SetEnv directive

+ Syntax: SetEnv env-variable + value
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_env
+ Compatibility: SetEnv is only + available in Apache 1.1 and later. Directory and .htaccess context + is available in Apache 1.3.7 and later. + +

Sets an environment variable, which is then passed on to CGI + scripts and SSI pages. Example:

+
+    SetEnv SPECIAL_PATH /foo/bin
+
+
+ +

UnsetEnv + directive

+ Syntax: UnsetEnv + env-variable [env-variable] ...
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_env
+ Compatibility: UnsetEnv is only + available in Apache 1.1 and later. Directory and .htaccess context + is available in Apache 1.3.7 and later. + +

Removes one or more environment variables from those passed + on to CGI scripts and SSI pages. Example:

+
+    UnsetEnv LD_LIBRARY_PATH
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_env.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_env.html.html deleted file mode 100644 index 9e03e758c31..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_env.html.html +++ /dev/null @@ -1,146 +0,0 @@ - - - - - - - - Apache module mod_env - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Apache module mod_env

- -

This module provides for modifying the environment which is - passed to CGI scripts and SSI pages.

- -

Status: Base
- Source File: mod_env.c
- Module Identifier: - env_module
- Compatibility: Available in - Apache 1.1 and later.

- -

Summary

- -

This module allows for control of the environment that will - be provided to CGI scripts and SSI pages. Environment variables - may be passed from the shell which invoked the httpd process. - Alternatively, environment variables may be set or unset within - the configuration process.

- -

For additional information, we provide a document on Environment Variables in Apache.

- -

Directives

- - -
- -

PassEnv directive

- Syntax: PassEnv - env-variable [env-variable] ...
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_env
- Compatibility: PassEnv is only - available in Apache 1.1 and later. Directory and .htaccess context - is available in Apache 1.3.7 and later. - -

Specifies one or more environment variables to pass to CGI - scripts and SSI pages from the environment of the shell which - invoked the httpd process. Example:

-
-    PassEnv LD_LIBRARY_PATH
-
-
- -

SetEnv directive

- Syntax: SetEnv env-variable - value
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_env
- Compatibility: SetEnv is only - available in Apache 1.1 and later. Directory and .htaccess context - is available in Apache 1.3.7 and later. - -

Sets an environment variable, which is then passed on to CGI - scripts and SSI pages. Example:

-
-    SetEnv SPECIAL_PATH /foo/bin
-
-
- -

UnsetEnv - directive

- Syntax: UnsetEnv - env-variable [env-variable] ...
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_env
- Compatibility: UnsetEnv is only - available in Apache 1.1 and later. Directory and .htaccess context - is available in Apache 1.3.7 and later. - -

Removes one or more environment variables from those passed - on to CGI scripts and SSI pages. Example:

-
-    UnsetEnv LD_LIBRARY_PATH
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_info.html b/usr.sbin/httpd/htdocs/manual/mod/mod_info.html new file mode 100644 index 00000000000..9175e2ed4da --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_info.html @@ -0,0 +1,125 @@ + + + + + + + + Apache module mod_info + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_info

+ +

This module provides a comprehensive overview of the server + configuration including all installed modules and directives in + the configuration files.

+ +

Status: Extension
+ Source File: mod_info.c
+ Module Identifier: + info_module
+ Compatibility: Available in + Apache 1.1 and later.

+ +

Directives

+ + + +

Using mod_info

+ +

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.

+ +

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.

+ +

In particular, this module can leak sensitive information + from the configuration directives of other Apache modules such as + system paths, usernames/passwords, database names, etc. Due to + the way this module works there is no way to block information + from it. Therefore, this module should ONLY be used in a controlled + environment and always with caution.

+ +
+
+ +

AddModuleInfo

+ Syntax: AddModuleInfo + module-name string
+ Context: server config, virtual + host
+ Status: Extension
+ Module: mod_info
+ Compatibility: Apache 1.3 and + above + +

This allows the content of string to be shown as + HTML interpreted, Additional Information for + the module module-name. Example:

+ +
+
+AddModuleInfo mod_auth.c 'See <A HREF="http://www.apache.org/docs/mod/mod_auth.html">http://www.apache.org/docs/mod/mod_auth.html</A>'
+
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_info.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_info.html.html deleted file mode 100644 index 9175e2ed4da..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_info.html.html +++ /dev/null @@ -1,125 +0,0 @@ - - - - - - - - Apache module mod_info - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_info

- -

This module provides a comprehensive overview of the server - configuration including all installed modules and directives in - the configuration files.

- -

Status: Extension
- Source File: mod_info.c
- Module Identifier: - info_module
- Compatibility: Available in - Apache 1.1 and later.

- -

Directives

- - - -

Using mod_info

- -

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.

- -

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.

- -

In particular, this module can leak sensitive information - from the configuration directives of other Apache modules such as - system paths, usernames/passwords, database names, etc. Due to - the way this module works there is no way to block information - from it. Therefore, this module should ONLY be used in a controlled - environment and always with caution.

- -
-
- -

AddModuleInfo

- Syntax: AddModuleInfo - module-name string
- Context: server config, virtual - host
- Status: Extension
- Module: mod_info
- Compatibility: Apache 1.3 and - above - -

This allows the content of string to be shown as - HTML interpreted, Additional Information for - the module module-name. Example:

- -
-
-AddModuleInfo mod_auth.c 'See <A HREF="http://www.apache.org/docs/mod/mod_auth.html">http://www.apache.org/docs/mod/mod_auth.html</A>'
-
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html b/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html new file mode 100644 index 00000000000..b3b292f3344 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html @@ -0,0 +1,421 @@ + + + + + + + + Apache module mod_log_config + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_log_config

+ +

This module provides for logging of the requests made to the + server, using the Common Log Format or a user-specified + format.

+ +

Status: Base
+ Source File: + mod_log_config.c
+ Module Identifier: + config_log_module
+ Compatibility: Was an extension + module prior to Apache 1.2.

+ +

Summary

+ +

This module provides for flexible logging of client + requests. Logs are written in a customizable format, and may be + written directly to a file, or to an external program. + Conditional logging is provided so that individual requests may + be included or excluded from the logs based on characteristics + of the request.

+ +

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 + step. The TransferLog and CustomLog + directives can be used multiple times in each server to cause + each request to be logged to multiple files.

+ +

See also: Apache Log Files.

+ +

Directives

+ + + +

Custom Log Formats

+ +

The format argument to the LogFormat and + CustomLog directives is a string. This string is + used to log each request to the log file. It can contain literal + characters copied into the log files and the C-style control + characters "\n" and "\t" to represent new-lines and tabs. + Literal quotes and back-slashes should be escaped with + back-slashes.

+ +

The characteristics of the request itself are logged by + placing "%" directives in the format string, which are + replaced in the log entry by the values as follows:

+
+%...a:          Remote IP-address
+%...A:          Local IP-address
+%...B:          Bytes sent, excluding HTTP headers.
+%...b:          Bytes sent, excluding HTTP headers. In CLF format
+        i.e. a '-' rather than a 0 when no bytes are sent.
+%...c:          Connection status when response was completed.
+                'X' = connection aborted before the response completed.
+                '+' = connection may be kept alive after the response is sent.
+                '-' = connection will be closed after the response is sent.
+%...{FOOBAR}e:  The contents of the environment variable FOOBAR
+%...f:          Filename
+%...h:          Remote host
+%...H       The request protocol
+%...{Foobar}i:  The contents of Foobar: header line(s) in the request
+                sent to the server.
+%...l:          Remote logname (from identd, if supplied)
+%...m       The request method
+%...{Foobar}n:  The contents of note "Foobar" from another module.
+%...{Foobar}o:  The contents of Foobar: header line(s) in the reply.
+%...p:          The canonical Port of the server serving the request
+%...P:          The process ID of the child that serviced the request.
+%...q       The query string (prepended with a ? if a query string exists,
+        otherwise an empty string)
+%...r:          First line of request
+%...s:          Status.  For requests that got internally redirected, this is
+                the status of the *original* request --- %...>s for the last.
+%...t:          Time, in common log format time format (standard english format)
+%...{format}t:  The time, in the form given by format, which should
+                be in strftime(3) format. (potentially localized)
+%...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, not including any query string.
+%...v:          The canonical ServerName of the server serving the request.
+%...V:          The server name according to the UseCanonicalName setting.
+
+ +

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). 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 in versions previous to 1.3.25 no escaping was performed + on the strings from %...r, %...i and + %...o. This was mainly to comply with the requirements of + the Common Log Format. This implied that clients could insert control + characters into the log, so you had to be quite careful when dealing + with raw log files.

+ +

For security reasons starting with 1.3.25 non-printable and + other special characters are escaped mostly by using + \xhh sequences, where hh stands for + the hexadecimal representation of the raw byte. Exceptions from this + rule are " and \ which are escaped by prepending + a backslash, and all whitespace characters that are written in their + C-style notation (\n, \t, etc).

+ +

Some commonly used log format strings are:

+ +
+
Common Log Format (CLF)
+ +
"%h %l %u %t \"%r\" %>s %b"
+ +
Common Log Format with Virtual Host
+ +
"%v %h %l %u %t \"%r\" %>s %b"
+ +
NCSA extended/combined log format
+ +
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" + \"%{User-agent}i\""
+ +
Referer log format
+ +
"%{Referer}i -> %U"
+ +
Agent (Browser) log format
+ +
"%{User-agent}i"
+
+ +

Note that the canonical ServerName and Port of the server serving the + request are used for %v and %p + respectively. This happens regardless of the UseCanonicalName setting + because otherwise log analysis programs would have to duplicate + the entire vhost matching algorithm in order to decide what + host really served the request.

+ +

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.

+ +

Compatibility notes

+ + +
+ +

CookieLog + directive

+ +

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 directive

+ +

Syntax: CustomLog + file|pipe format|nickname + [env=[!]environment-variable]
+ Context: server config, virtual + host
+ Status: Base
+ Compatibility: Nickname only + available in Apache 1.3 or later. Conditional logging available + in 1.3.5 or later.
+ Module: mod_log_config

+ +

The CustomLog directive is used to log requests + to the server. A log format is specified, and the logging can + optionally be made conditional on request characteristics using + environment variables.

+ +

The first argument, which specifies the location to which + the logs will be written, can take one of the following two + types of values:

+ +
+
file
+ +
A filename, relative to the ServerRoot.
+ +
pipe
+ +
The pipe character "|", followed by the path + to a program to receive the log information on its standard + input. Security: if a program is used, then + it will be run as the user who started httpd. This will be + root if the server was started by root; be sure that the + program is secure.
+
+ +

The second argument specifies what will be written to the + log file. It can specify either a nickname defined by + a previous LogFormat directive, or it + can be an explicit format string as described in the + log formats section.

+ +

For example, the following two sets of directives have + exactly the same effect:

+
+     # CustomLog with format nickname
+     LogFormat "%h %l %u %t \"%r\" %>s %b" common
+     CustomLog logs/access_log common
+
+     # CustomLog with explicit format string
+     CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"
+
+ +

The third argument is optional and controls + whether or not to log a particular request based on the + presence or absence of a particular variable in the server + environment. If the specified environment + variable is set for the request (or is not set, in the case + of a 'env=!name' clause), then the + request will be logged.

+ +

Environment variables can be set on a per-request + basis using the mod_setenvif + and/or mod_rewrite modules. For + example, if you want to record requests for all GIF + images on your server in a separate logfile but not in your main + log, you can use:

+
+    SetEnvIf Request_URI \.gif$ gif-image
+    CustomLog gif-requests.log common env=gif-image
+    CustomLog nongif-requests.log common env=!gif-image
+
+
+ +

LogFormat + directive

+ +

Syntax: LogFormat + format|nickname [nickname]
+ Default: LogFormat "%h %l + %u %t \"%r\" %>s %b"
+ Context: server config, virtual + host
+ Status: Base
+ Compatibility: Nickname only + available in Apache 1.3 or later
+ Module: mod_log_config

+ +

This directive specifies the format of the access log + file.

+ +

The LogFormat directive can take one of two + forms. In the first form, where only one argument is specified, + this directive sets the log format which will be used by logs + specified in subsequent TransferLog + directives. The single argument can specify an explicit + format as discussed in the custom log + formats section above. Alternatively, it can use a + nickname to refer to a log format defined in a + previous LogFormat directive as described + below.

+ +

The second form of the LogFormat directive + associates an explicit format with a + nickname. This nickname can then be used in + subsequent LogFormat or CustomLog directives rather than + repeating the entire format string. A LogFormat + directive which defines a nickname does nothing + else -- that is, it only defines the + nickname, it doesn't actually apply the format and make it the + default. Therefore, it will not affect subsequent TransferLog directives.

+ +

For example:

+ + LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common + +
+ +

TransferLog + directive

+ +

Syntax: TransferLog + file|pipe
+ Default: none
+ Context: server config, virtual + host
+ Status: Base
+ Module: mod_log_config

+ +

This directive has exactly the same arguments and effect as + the CustomLog directive, with the + exception that it does not allow the log format to be specified + explicitly or for conditional logging of requests. Instead, the + log format is determined by the most recently specified LogFormat directive that does not define + a nickname. Common Log Format is used if no other format has + been specified.

+ +

Example:

+
+   LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
+   TransferLog logs/access_log
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html.html deleted file mode 100644 index b3b292f3344..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html.html +++ /dev/null @@ -1,421 +0,0 @@ - - - - - - - - Apache module mod_log_config - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_log_config

- -

This module provides for logging of the requests made to the - server, using the Common Log Format or a user-specified - format.

- -

Status: Base
- Source File: - mod_log_config.c
- Module Identifier: - config_log_module
- Compatibility: Was an extension - module prior to Apache 1.2.

- -

Summary

- -

This module provides for flexible logging of client - requests. Logs are written in a customizable format, and may be - written directly to a file, or to an external program. - Conditional logging is provided so that individual requests may - be included or excluded from the logs based on characteristics - of the request.

- -

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 - step. The TransferLog and CustomLog - directives can be used multiple times in each server to cause - each request to be logged to multiple files.

- -

See also: Apache Log Files.

- -

Directives

- - - -

Custom Log Formats

- -

The format argument to the LogFormat and - CustomLog directives is a string. This string is - used to log each request to the log file. It can contain literal - characters copied into the log files and the C-style control - characters "\n" and "\t" to represent new-lines and tabs. - Literal quotes and back-slashes should be escaped with - back-slashes.

- -

The characteristics of the request itself are logged by - placing "%" directives in the format string, which are - replaced in the log entry by the values as follows:

-
-%...a:          Remote IP-address
-%...A:          Local IP-address
-%...B:          Bytes sent, excluding HTTP headers.
-%...b:          Bytes sent, excluding HTTP headers. In CLF format
-        i.e. a '-' rather than a 0 when no bytes are sent.
-%...c:          Connection status when response was completed.
-                'X' = connection aborted before the response completed.
-                '+' = connection may be kept alive after the response is sent.
-                '-' = connection will be closed after the response is sent.
-%...{FOOBAR}e:  The contents of the environment variable FOOBAR
-%...f:          Filename
-%...h:          Remote host
-%...H       The request protocol
-%...{Foobar}i:  The contents of Foobar: header line(s) in the request
-                sent to the server.
-%...l:          Remote logname (from identd, if supplied)
-%...m       The request method
-%...{Foobar}n:  The contents of note "Foobar" from another module.
-%...{Foobar}o:  The contents of Foobar: header line(s) in the reply.
-%...p:          The canonical Port of the server serving the request
-%...P:          The process ID of the child that serviced the request.
-%...q       The query string (prepended with a ? if a query string exists,
-        otherwise an empty string)
-%...r:          First line of request
-%...s:          Status.  For requests that got internally redirected, this is
-                the status of the *original* request --- %...>s for the last.
-%...t:          Time, in common log format time format (standard english format)
-%...{format}t:  The time, in the form given by format, which should
-                be in strftime(3) format. (potentially localized)
-%...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, not including any query string.
-%...v:          The canonical ServerName of the server serving the request.
-%...V:          The server name according to the UseCanonicalName setting.
-
- -

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). 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 in versions previous to 1.3.25 no escaping was performed - on the strings from %...r, %...i and - %...o. This was mainly to comply with the requirements of - the Common Log Format. This implied that clients could insert control - characters into the log, so you had to be quite careful when dealing - with raw log files.

- -

For security reasons starting with 1.3.25 non-printable and - other special characters are escaped mostly by using - \xhh sequences, where hh stands for - the hexadecimal representation of the raw byte. Exceptions from this - rule are " and \ which are escaped by prepending - a backslash, and all whitespace characters that are written in their - C-style notation (\n, \t, etc).

- -

Some commonly used log format strings are:

- -
-
Common Log Format (CLF)
- -
"%h %l %u %t \"%r\" %>s %b"
- -
Common Log Format with Virtual Host
- -
"%v %h %l %u %t \"%r\" %>s %b"
- -
NCSA extended/combined log format
- -
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" - \"%{User-agent}i\""
- -
Referer log format
- -
"%{Referer}i -> %U"
- -
Agent (Browser) log format
- -
"%{User-agent}i"
-
- -

Note that the canonical ServerName and Port of the server serving the - request are used for %v and %p - respectively. This happens regardless of the UseCanonicalName setting - because otherwise log analysis programs would have to duplicate - the entire vhost matching algorithm in order to decide what - host really served the request.

- -

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.

- -

Compatibility notes

- - -
- -

CookieLog - directive

- -

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 directive

- -

Syntax: CustomLog - file|pipe format|nickname - [env=[!]environment-variable]
- Context: server config, virtual - host
- Status: Base
- Compatibility: Nickname only - available in Apache 1.3 or later. Conditional logging available - in 1.3.5 or later.
- Module: mod_log_config

- -

The CustomLog directive is used to log requests - to the server. A log format is specified, and the logging can - optionally be made conditional on request characteristics using - environment variables.

- -

The first argument, which specifies the location to which - the logs will be written, can take one of the following two - types of values:

- -
-
file
- -
A filename, relative to the ServerRoot.
- -
pipe
- -
The pipe character "|", followed by the path - to a program to receive the log information on its standard - input. Security: if a program is used, then - it will be run as the user who started httpd. This will be - root if the server was started by root; be sure that the - program is secure.
-
- -

The second argument specifies what will be written to the - log file. It can specify either a nickname defined by - a previous LogFormat directive, or it - can be an explicit format string as described in the - log formats section.

- -

For example, the following two sets of directives have - exactly the same effect:

-
-     # CustomLog with format nickname
-     LogFormat "%h %l %u %t \"%r\" %>s %b" common
-     CustomLog logs/access_log common
-
-     # CustomLog with explicit format string
-     CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"
-
- -

The third argument is optional and controls - whether or not to log a particular request based on the - presence or absence of a particular variable in the server - environment. If the specified environment - variable is set for the request (or is not set, in the case - of a 'env=!name' clause), then the - request will be logged.

- -

Environment variables can be set on a per-request - basis using the mod_setenvif - and/or mod_rewrite modules. For - example, if you want to record requests for all GIF - images on your server in a separate logfile but not in your main - log, you can use:

-
-    SetEnvIf Request_URI \.gif$ gif-image
-    CustomLog gif-requests.log common env=gif-image
-    CustomLog nongif-requests.log common env=!gif-image
-
-
- -

LogFormat - directive

- -

Syntax: LogFormat - format|nickname [nickname]
- Default: LogFormat "%h %l - %u %t \"%r\" %>s %b"
- Context: server config, virtual - host
- Status: Base
- Compatibility: Nickname only - available in Apache 1.3 or later
- Module: mod_log_config

- -

This directive specifies the format of the access log - file.

- -

The LogFormat directive can take one of two - forms. In the first form, where only one argument is specified, - this directive sets the log format which will be used by logs - specified in subsequent TransferLog - directives. The single argument can specify an explicit - format as discussed in the custom log - formats section above. Alternatively, it can use a - nickname to refer to a log format defined in a - previous LogFormat directive as described - below.

- -

The second form of the LogFormat directive - associates an explicit format with a - nickname. This nickname can then be used in - subsequent LogFormat or CustomLog directives rather than - repeating the entire format string. A LogFormat - directive which defines a nickname does nothing - else -- that is, it only defines the - nickname, it doesn't actually apply the format and make it the - default. Therefore, it will not affect subsequent TransferLog directives.

- -

For example:

- - LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common - -
- -

TransferLog - directive

- -

Syntax: TransferLog - file|pipe
- Default: none
- Context: server config, virtual - host
- Status: Base
- Module: mod_log_config

- -

This directive has exactly the same arguments and effect as - the CustomLog directive, with the - exception that it does not allow the log format to be specified - explicitly or for conditional logging of requests. Instead, the - log format is determined by the most recently specified LogFormat directive that does not define - a nickname. Common Log Format is used if no other format has - been specified.

- -

Example:

-
-   LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
-   TransferLog logs/access_log
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html b/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html new file mode 100644 index 00000000000..810ee5d3e0f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html @@ -0,0 +1,691 @@ + + + + + + + + Apache module mod_mime + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_mime

+ +

This module provides for determining the types of files from + the filename and for association of handlers with files.

+ +

Status: Base
+ Source File: mod_mime.c
+ Module Identifier: + mime_module

+ +

Summary

+ This module is used to determine various bits of "meta + information" about documents. This information relates to the + content of the document and is returned to the browser or used + in content-negotiation within the server. In addition, a + "handler" can be set for a document, which determines how the + document will be processed within the server. + +

The directives AddCharset, AddEncoding, AddHandler, AddLanguage and AddType are all used to map file extensions + onto the meta-information for that file. Respectively they set + the character set, content-encoding, handler, content-language, + and MIME-type (content-type) of documents. The directive TypesConfig is used to specify a file + which also maps extensions onto MIME types. The directives ForceType and SetHandler are used to associated all + the files in a given location (e.g., a particular + directory) onto a particular MIME type or handler.

+ +

Note that changing the type or encoding of a file does not + change the value of the Last-Modified header. + Thus, previously cached copies may still be used by a client or + proxy, with the previous headers.

+ +

Directives

+ + + +

See also: MimeMagicFile.

+ +

Files with Multiple + Extensions

+ Files can have more than one extension, and the order of the + extensions is normally irrelevant. For example, if the + file welcome.html.fr maps onto content type + text/html and language French then the file + welcome.fr.html will map onto exactly the same + information. The only exception to this is if an extension is + given which Apache does not know how to handle. In this case it + will "forget" about any information it obtained from extensions + to the left of the unknown extension. So, for example, if the + extensions fr and html are mapped to the appropriate language + and type but extension xxx is not assigned to anything, then + the file welcome.fr.xxx.html will be associated + with content-type text/html but no language. + +

If more than one extension is given which maps onto the same + type of meta-information, then the one to the right will be + used. For example, if ".gif" maps to the MIME-type image/gif + and ".html" maps to the MIME-type text/html, then the file + welcome.gif.html will be associated with the + MIME-type "text/html".

+ +

Care should be taken when a file with multiple extensions + gets associated with both a MIME-type and a handler. This will + usually result in the request being by the module associated + with the handler. For example, if the .imap + extension is mapped to the handler "imap-file" (from mod_imap) + and the .html extension is mapped to the MIME-type + "text/html", then the file world.imap.html will be + associated with both the "imap-file" handler and "text/html" + MIME-type. When it is processed, the "imap-file" handler will + be used, and so it will be treated as a mod_imap imagemap + file.

+
+ +

AddCharset + directive

+ Syntax: AddCharset charset + extension [extension] ...
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_mime
+ Compatibility: AddCharset is + only available in Apache 1.3.10 and later + +

The AddCharset directive maps the given filename extensions + to the specified content charset. charset is the MIME + charset parameter of filenames containing extension. + This mapping is added to any already in force, overriding any + mappings that already exist for the same extension.

+ +

Example:

+
+    AddLanguage ja .ja
+    AddCharset EUC-JP .euc
+    AddCharset ISO-2022-JP .jis
+    AddCharset SHIFT_JIS .sjis
+
+ +

Then the document xxxx.ja.jis will be treated + as being a Japanese document whose charset is ISO-2022-JP (as + will the document xxxx.jis.ja). The AddCharset + directive is useful for both to inform the client about the + character encoding of the document so that the document can be + interpreted and displayed appropriately, and for content negotiation, + where the server returns one from several documents based on + the client's charset preference.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

See also: mod_negotiation

+
+ +

AddEncoding + directive

+ + Syntax: AddEncoding + MIME-enc extension [extension] ...
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_mime + +

The AddEncoding directive maps the given filename extensions + to the specified encoding type. MIME-enc is the MIME + encoding to use for documents containing the + extension. This mapping is added to any already in + force, overriding any mappings that already exist for the same + extension. Example:

+ +
+ AddEncoding x-gzip .gz
+ AddEncoding x-compress .Z +
+ This will cause filenames containing the .gz extension to be + marked as encoded using the x-gzip encoding, and filenames + containing the .Z extension to be marked as encoded with + x-compress. + +

Old clients expect x-gzip and + x-compress, however the standard dictates that + they're equivalent to gzip and + compress respectively. Apache does content + encoding comparisons by ignoring any leading x-. + When responding with an encoding Apache will use whatever form + (i.e., x-foo or foo) the + client requested. If the client didn't specifically request a + particular form Apache will use the form given by the + AddEncoding directive. To make this long story + short, you should always use x-gzip and + x-compress for these two specific encodings. More + recent encodings, such as deflate should be + specified without the x-.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

See also: Files with + multiple extensions

+
+ +

AddHandler + directive

+ Syntax: AddHandler + handler-name extension [extension] ...
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_mime
+ Compatibility: AddHandler is + only available in Apache 1.1 and later + +

AddHandler maps the filename extensions extension + to the handler + handler-name. This mapping is added to any already in + force, overriding any mappings that already exist for the same + extension. 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 containing the ".cgi" extension + will be treated as a CGI program.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

See also: Files with + multiple extensions, SetHandler

+
+ +

AddLanguage + directive

+ + Syntax: AddLanguage + MIME-lang extension [extension] ...
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_mime + +

The AddLanguage directive maps the given filename extension + to the specified content language. MIME-lang is the + MIME language of filenames containing extension. This + mapping is added to any already in force, overriding any + mappings that already exist for the same + extension.

+ +

Example:

+ +
+ AddEncoding x-compress .Z
+ AddLanguage en .en
+ AddLanguage fr .fr
+ +
+ +

Then the document xxxx.en.Z will be treated as + being a compressed English document (as will the document + xxxx.Z.en). 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.

+ +

If multiple language assignments are made for the same + extension, the last one encountered is the one that is used. + That is, for the case of:

+
+    AddLanguage en .en
+    AddLanguage en-uk .en
+    AddLanguage en-us .en
+
+ +

documents with the extension ".en" would be + treated as being "en-us".

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

See also: Files with + multiple extensions, DefaultLanguage
+ See also: mod_negotiation

+
+ +

AddType directive

+ + Syntax: AddType MIME-type + extension [extension] ...
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_mime + +

The AddType directive maps the given filename extensions + onto the specified content type. MIME-type is the MIME + type to use for filenames containing extension. This + mapping is added to any already in force, overriding any + mappings that already exist for the same extension. + This directive can be used to add mappings not listed in the + MIME types file (see the TypesConfig directive). + Example:

+ +
+ AddType image/gif .gif +
+ It is recommended that new MIME types be added using the + AddType directive rather than changing the TypesConfig file. + +

Note that, unlike the NCSA httpd, this directive cannot be + used to set the type of particular files.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

See also: Files with + multiple extensions

+
+ +

DefaultLanguage directive

+ + Syntax: DefaultLanguage + MIME-lang
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_mime
+ Compatibility: DefaultLanguage + is only available in Apache 1.3.4 and later. + +

The DefaultLanguage directive tells Apache that all files in + the directive's scope (e.g., all files covered by the + current <Directory> container) that don't + have an explicit language extension (such as .fr + or .de as configured by AddLanguage) + should be considered to be in the specified MIME-lang + language. This allows entire directories to be marked as + containing Dutch content, for instance, without having to + rename each file. Note that unlike using extensions to specify + languages, DefaultLanguage can only specify a + single language.

+ +

For example:

+ + DefaultLanguage fr + +

If no DefaultLanguage directive is in force, + and a file does not have any language extensions as configured + by AddLanguage, then that file will be considered + to have no language attribute.

+ +

See also: mod_negotiation
+ See also: Files with + multiple extensions

+
+ +

ForceType + directive

+ Syntax: ForceType + media-type|None
+ 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 determine the media type.

+ +

You can override any ForceType setting + by using the value of none:

+ +
+    # force all files to be image/gif:
+    <Location /images>
+      ForceType image/gif
+    </Location>
+
+    # but normal mime-type associations here:
+    <Location /images/mixed>
+      ForceType none
+    </Location>
+
+ +

See also: AddType

+ +
+ +

RemoveEncoding directive

+ Syntax: RemoveEncoding + extension [extension] ...
+ Context: virtual host, directory, + .htaccess
+ Status: Base
+ Module: mod_mime
+ Compatibility: RemoveEncoding + is only available in Apache 1.3.13 and later. + +

The RemoveEncoding directive removes any + encoding associations for files with the given extensions. This + allows .htaccess files in subdirectories to undo + any associations inherited from parent directories or the + server config files. An example of its use might be:

+ +
+
/foo/.htaccess:
+ +
AddEncoding x-gzip .gz
+ AddType text/plain .asc
+ <Files *.gz.asc>
+     RemoveEncoding + .gz
+ </Files>
+
+ +

This will cause foo.gz to mark as being encoded + with the gzip method, but foo.gz.asc as an + unencoded plaintext file.

+ +

Note:RemoveEncoding directives are processed + after any AddEncoding + directives, so it is possible they + may undo the effects of the latter if both occur within the + same directory configuration.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+
+ +

RemoveHandler directive

+ Syntax: RemoveHandler + extension [extension] ...
+ Context: virtual host, directory, + .htaccess
+ Status: Base
+ Module: mod_mime
+ Compatibility: RemoveHandler is + only available in Apache 1.3.4 and later. + +

The RemoveHandler directive removes any handler + associations for files with the given extensions. This allows + .htaccess files in subdirectories to undo any + associations inherited from parent directories or the server + config files. An example of its use might be:

+ +
+
/foo/.htaccess:
+ +
AddHandler server-parsed .html
+ +
/foo/bar/.htaccess:
+ +
RemoveHandler .html
+
+ +

This has the effect of returning .html files in + the /foo/bar directory to being treated as normal + files, rather than as candidates for parsing (see the mod_include + module).

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+
+ +

RemoveType + directive

+ Syntax: RemoveType + extension [extension] ...
+ Context: virtual host, directory, + .htaccess
+ Status: Base
+ Module: mod_mime
+ Compatibility: RemoveType is + only available in Apache 1.3.13 and later. + +

The RemoveType directive removes any MIME type + associations for files with the given extensions. This allows + .htaccess files in subdirectories to undo any + associations inherited from parent directories or the server + config files. An example of its use might be:

+ +
+
/foo/.htaccess:
+ +
RemoveType .cgi
+
+ +

This will remove any special handling of .cgi + files in the /foo/ directory and any beneath it, + causing the files to be treated as being of the default type.

+ +

Note:RemoveType directives are processed + after any AddType directives, so it is + possible they may undo the effects of the latter if both occur + within the same directory configuration.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+
+ +

SetHandler + directive

+ Syntax: SetHandler + handler-name|None
+ 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: (See mod_status for more details.)

+
+    <Location /status>
+    SetHandler server-status
+    </Location>
+
+ +

You can override an earlier defined SetHandler + directive by using the value None.

+ +

See also: AddHandler

+
+ +

TypesConfig + directive

+ + Syntax: TypesConfig + file-path
+ 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. + +

+ +

Apache HTTP Server Version 1.3

+ Index + Home + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html.html deleted file mode 100644 index 810ee5d3e0f..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html.html +++ /dev/null @@ -1,691 +0,0 @@ - - - - - - - - Apache module mod_mime - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_mime

- -

This module provides for determining the types of files from - the filename and for association of handlers with files.

- -

Status: Base
- Source File: mod_mime.c
- Module Identifier: - mime_module

- -

Summary

- This module is used to determine various bits of "meta - information" about documents. This information relates to the - content of the document and is returned to the browser or used - in content-negotiation within the server. In addition, a - "handler" can be set for a document, which determines how the - document will be processed within the server. - -

The directives AddCharset, AddEncoding, AddHandler, AddLanguage and AddType are all used to map file extensions - onto the meta-information for that file. Respectively they set - the character set, content-encoding, handler, content-language, - and MIME-type (content-type) of documents. The directive TypesConfig is used to specify a file - which also maps extensions onto MIME types. The directives ForceType and SetHandler are used to associated all - the files in a given location (e.g., a particular - directory) onto a particular MIME type or handler.

- -

Note that changing the type or encoding of a file does not - change the value of the Last-Modified header. - Thus, previously cached copies may still be used by a client or - proxy, with the previous headers.

- -

Directives

- - - -

See also: MimeMagicFile.

- -

Files with Multiple - Extensions

- Files can have more than one extension, and the order of the - extensions is normally irrelevant. For example, if the - file welcome.html.fr maps onto content type - text/html and language French then the file - welcome.fr.html will map onto exactly the same - information. The only exception to this is if an extension is - given which Apache does not know how to handle. In this case it - will "forget" about any information it obtained from extensions - to the left of the unknown extension. So, for example, if the - extensions fr and html are mapped to the appropriate language - and type but extension xxx is not assigned to anything, then - the file welcome.fr.xxx.html will be associated - with content-type text/html but no language. - -

If more than one extension is given which maps onto the same - type of meta-information, then the one to the right will be - used. For example, if ".gif" maps to the MIME-type image/gif - and ".html" maps to the MIME-type text/html, then the file - welcome.gif.html will be associated with the - MIME-type "text/html".

- -

Care should be taken when a file with multiple extensions - gets associated with both a MIME-type and a handler. This will - usually result in the request being by the module associated - with the handler. For example, if the .imap - extension is mapped to the handler "imap-file" (from mod_imap) - and the .html extension is mapped to the MIME-type - "text/html", then the file world.imap.html will be - associated with both the "imap-file" handler and "text/html" - MIME-type. When it is processed, the "imap-file" handler will - be used, and so it will be treated as a mod_imap imagemap - file.

-
- -

AddCharset - directive

- Syntax: AddCharset charset - extension [extension] ...
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_mime
- Compatibility: AddCharset is - only available in Apache 1.3.10 and later - -

The AddCharset directive maps the given filename extensions - to the specified content charset. charset is the MIME - charset parameter of filenames containing extension. - This mapping is added to any already in force, overriding any - mappings that already exist for the same extension.

- -

Example:

-
-    AddLanguage ja .ja
-    AddCharset EUC-JP .euc
-    AddCharset ISO-2022-JP .jis
-    AddCharset SHIFT_JIS .sjis
-
- -

Then the document xxxx.ja.jis will be treated - as being a Japanese document whose charset is ISO-2022-JP (as - will the document xxxx.jis.ja). The AddCharset - directive is useful for both to inform the client about the - character encoding of the document so that the document can be - interpreted and displayed appropriately, and for content negotiation, - where the server returns one from several documents based on - the client's charset preference.

- -

The extension argument is case-insensitive, and can - be specified with or without a leading dot.

- -

See also: mod_negotiation

-
- -

AddEncoding - directive

- - Syntax: AddEncoding - MIME-enc extension [extension] ...
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_mime - -

The AddEncoding directive maps the given filename extensions - to the specified encoding type. MIME-enc is the MIME - encoding to use for documents containing the - extension. This mapping is added to any already in - force, overriding any mappings that already exist for the same - extension. Example:

- -
- AddEncoding x-gzip .gz
- AddEncoding x-compress .Z -
- This will cause filenames containing the .gz extension to be - marked as encoded using the x-gzip encoding, and filenames - containing the .Z extension to be marked as encoded with - x-compress. - -

Old clients expect x-gzip and - x-compress, however the standard dictates that - they're equivalent to gzip and - compress respectively. Apache does content - encoding comparisons by ignoring any leading x-. - When responding with an encoding Apache will use whatever form - (i.e., x-foo or foo) the - client requested. If the client didn't specifically request a - particular form Apache will use the form given by the - AddEncoding directive. To make this long story - short, you should always use x-gzip and - x-compress for these two specific encodings. More - recent encodings, such as deflate should be - specified without the x-.

- -

The extension argument is case-insensitive, and can - be specified with or without a leading dot.

- -

See also: Files with - multiple extensions

-
- -

AddHandler - directive

- Syntax: AddHandler - handler-name extension [extension] ...
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_mime
- Compatibility: AddHandler is - only available in Apache 1.1 and later - -

AddHandler maps the filename extensions extension - to the handler - handler-name. This mapping is added to any already in - force, overriding any mappings that already exist for the same - extension. 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 containing the ".cgi" extension - will be treated as a CGI program.

- -

The extension argument is case-insensitive, and can - be specified with or without a leading dot.

- -

See also: Files with - multiple extensions, SetHandler

-
- -

AddLanguage - directive

- - Syntax: AddLanguage - MIME-lang extension [extension] ...
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_mime - -

The AddLanguage directive maps the given filename extension - to the specified content language. MIME-lang is the - MIME language of filenames containing extension. This - mapping is added to any already in force, overriding any - mappings that already exist for the same - extension.

- -

Example:

- -
- AddEncoding x-compress .Z
- AddLanguage en .en
- AddLanguage fr .fr
- -
- -

Then the document xxxx.en.Z will be treated as - being a compressed English document (as will the document - xxxx.Z.en). 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.

- -

If multiple language assignments are made for the same - extension, the last one encountered is the one that is used. - That is, for the case of:

-
-    AddLanguage en .en
-    AddLanguage en-uk .en
-    AddLanguage en-us .en
-
- -

documents with the extension ".en" would be - treated as being "en-us".

- -

The extension argument is case-insensitive, and can - be specified with or without a leading dot.

- -

See also: Files with - multiple extensions, DefaultLanguage
- See also: mod_negotiation

-
- -

AddType directive

- - Syntax: AddType MIME-type - extension [extension] ...
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_mime - -

The AddType directive maps the given filename extensions - onto the specified content type. MIME-type is the MIME - type to use for filenames containing extension. This - mapping is added to any already in force, overriding any - mappings that already exist for the same extension. - This directive can be used to add mappings not listed in the - MIME types file (see the TypesConfig directive). - Example:

- -
- AddType image/gif .gif -
- It is recommended that new MIME types be added using the - AddType directive rather than changing the TypesConfig file. - -

Note that, unlike the NCSA httpd, this directive cannot be - used to set the type of particular files.

- -

The extension argument is case-insensitive, and can - be specified with or without a leading dot.

- -

See also: Files with - multiple extensions

-
- -

DefaultLanguage directive

- - Syntax: DefaultLanguage - MIME-lang
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_mime
- Compatibility: DefaultLanguage - is only available in Apache 1.3.4 and later. - -

The DefaultLanguage directive tells Apache that all files in - the directive's scope (e.g., all files covered by the - current <Directory> container) that don't - have an explicit language extension (such as .fr - or .de as configured by AddLanguage) - should be considered to be in the specified MIME-lang - language. This allows entire directories to be marked as - containing Dutch content, for instance, without having to - rename each file. Note that unlike using extensions to specify - languages, DefaultLanguage can only specify a - single language.

- -

For example:

- - DefaultLanguage fr - -

If no DefaultLanguage directive is in force, - and a file does not have any language extensions as configured - by AddLanguage, then that file will be considered - to have no language attribute.

- -

See also: mod_negotiation
- See also: Files with - multiple extensions

-
- -

ForceType - directive

- Syntax: ForceType - media-type|None
- 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 determine the media type.

- -

You can override any ForceType setting - by using the value of none:

- -
-    # force all files to be image/gif:
-    <Location /images>
-      ForceType image/gif
-    </Location>
-
-    # but normal mime-type associations here:
-    <Location /images/mixed>
-      ForceType none
-    </Location>
-
- -

See also: AddType

- -
- -

RemoveEncoding directive

- Syntax: RemoveEncoding - extension [extension] ...
- Context: virtual host, directory, - .htaccess
- Status: Base
- Module: mod_mime
- Compatibility: RemoveEncoding - is only available in Apache 1.3.13 and later. - -

The RemoveEncoding directive removes any - encoding associations for files with the given extensions. This - allows .htaccess files in subdirectories to undo - any associations inherited from parent directories or the - server config files. An example of its use might be:

- -
-
/foo/.htaccess:
- -
AddEncoding x-gzip .gz
- AddType text/plain .asc
- <Files *.gz.asc>
-     RemoveEncoding - .gz
- </Files>
-
- -

This will cause foo.gz to mark as being encoded - with the gzip method, but foo.gz.asc as an - unencoded plaintext file.

- -

Note:RemoveEncoding directives are processed - after any AddEncoding - directives, so it is possible they - may undo the effects of the latter if both occur within the - same directory configuration.

- -

The extension argument is case-insensitive, and can - be specified with or without a leading dot.

-
- -

RemoveHandler directive

- Syntax: RemoveHandler - extension [extension] ...
- Context: virtual host, directory, - .htaccess
- Status: Base
- Module: mod_mime
- Compatibility: RemoveHandler is - only available in Apache 1.3.4 and later. - -

The RemoveHandler directive removes any handler - associations for files with the given extensions. This allows - .htaccess files in subdirectories to undo any - associations inherited from parent directories or the server - config files. An example of its use might be:

- -
-
/foo/.htaccess:
- -
AddHandler server-parsed .html
- -
/foo/bar/.htaccess:
- -
RemoveHandler .html
-
- -

This has the effect of returning .html files in - the /foo/bar directory to being treated as normal - files, rather than as candidates for parsing (see the mod_include - module).

- -

The extension argument is case-insensitive, and can - be specified with or without a leading dot.

-
- -

RemoveType - directive

- Syntax: RemoveType - extension [extension] ...
- Context: virtual host, directory, - .htaccess
- Status: Base
- Module: mod_mime
- Compatibility: RemoveType is - only available in Apache 1.3.13 and later. - -

The RemoveType directive removes any MIME type - associations for files with the given extensions. This allows - .htaccess files in subdirectories to undo any - associations inherited from parent directories or the server - config files. An example of its use might be:

- -
-
/foo/.htaccess:
- -
RemoveType .cgi
-
- -

This will remove any special handling of .cgi - files in the /foo/ directory and any beneath it, - causing the files to be treated as being of the default type.

- -

Note:RemoveType directives are processed - after any AddType directives, so it is - possible they may undo the effects of the latter if both occur - within the same directory configuration.

- -

The extension argument is case-insensitive, and can - be specified with or without a leading dot.

-
- -

SetHandler - directive

- Syntax: SetHandler - handler-name|None
- 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: (See mod_status for more details.)

-
-    <Location /status>
-    SetHandler server-status
-    </Location>
-
- -

You can override an earlier defined SetHandler - directive by using the value None.

- -

See also: AddHandler

-
- -

TypesConfig - directive

- - Syntax: TypesConfig - file-path
- 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. - -

- -

Apache HTTP Server Version 1.3

- Index - Home - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html b/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html new file mode 100644 index 00000000000..5240b12b266 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html @@ -0,0 +1,234 @@ + + + + + + + + Apache module mod_negotiation + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_negotiation

+ +

This module provides for content negotiation.

+ +

Status: Base
+ Source File: + mod_negotiation.c
+ Module Identifier: + negotiation_module

+ +

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. + + + +

Directives

+ + + See also: DefaultLanguage, AddEncoding, AddLanguage, AddType, and Options. + +

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. Apache only recognizes + encodings that are defined by an AddEncoding directive. + This normally includes the encodings x-compress + for compress'd files, and x-gzip for gzip'd + files. The x- prefix is ignored for encoding + comparisons.
+ +
Content-Language:
+ +
The language of the variant, as an Internet standard + language tag (RFC 1766). An example is en, + meaning English.
+ +
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 a semi-colon, with a syntax of + name=value. Common parameters include: + +
+
level
+ +
an integer specifying the version of the media type. + For text/html this defaults to 2, otherwise + 0.
+ +
qs
+ +
a floating-point number with a value in the range 0.0 + to 1.0, indicating the relative 'quality' of this variant + compared to the other available variants, independent of + the client's capabilities. For example, a jpeg file is + usually of higher source quality than an ascii file if it + is attempting to represent a photograph. However, if the + resource being represented is ascii art, then an ascii + file would have a higher source quality than a jpeg file. + All qs values are therefore specific to a given + resource.
+
+ Example: + +
+ 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. +
+ +

CacheNegotiatedDocs + directive

+ 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 directive

+ + 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 de +
+ For a request for foo.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 any other means. Correctly + implemented HTTP/1.1 requests will mean this directive has no + effect.

+ +

See also: DefaultLanguage and + AddLanguage +

+ +

Apache HTTP Server Version 1.3

+ Index + Home + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html.html deleted file mode 100644 index 5240b12b266..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html.html +++ /dev/null @@ -1,234 +0,0 @@ - - - - - - - - Apache module mod_negotiation - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_negotiation

- -

This module provides for content negotiation.

- -

Status: Base
- Source File: - mod_negotiation.c
- Module Identifier: - negotiation_module

- -

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. - - - -

Directives

- - - See also: DefaultLanguage, AddEncoding, AddLanguage, AddType, and Options. - -

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. Apache only recognizes - encodings that are defined by an AddEncoding directive. - This normally includes the encodings x-compress - for compress'd files, and x-gzip for gzip'd - files. The x- prefix is ignored for encoding - comparisons.
- -
Content-Language:
- -
The language of the variant, as an Internet standard - language tag (RFC 1766). An example is en, - meaning English.
- -
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 a semi-colon, with a syntax of - name=value. Common parameters include: - -
-
level
- -
an integer specifying the version of the media type. - For text/html this defaults to 2, otherwise - 0.
- -
qs
- -
a floating-point number with a value in the range 0.0 - to 1.0, indicating the relative 'quality' of this variant - compared to the other available variants, independent of - the client's capabilities. For example, a jpeg file is - usually of higher source quality than an ascii file if it - is attempting to represent a photograph. However, if the - resource being represented is ascii art, then an ascii - file would have a higher source quality than a jpeg file. - All qs values are therefore specific to a given - resource.
-
- Example: - -
- 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. -
- -

CacheNegotiatedDocs - directive

- 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 directive

- - 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 de -
- For a request for foo.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 any other means. Correctly - implemented HTTP/1.1 requests will mean this directive has no - effect.

- -

See also: DefaultLanguage and - AddLanguage -

- -

Apache HTTP Server Version 1.3

- Index - Home - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html b/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html new file mode 100644 index 00000000000..61903c9d942 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html @@ -0,0 +1,2107 @@ + + + + + + + + + + + Apache module mod_rewrite + + + + +
+ +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ +
+ + +

Module mod_rewrite
+ URL Rewriting Engine

+ +

This module provides a rule-based rewriting engine to + rewrite requested URLs on the fly.

+ +

Status: Extension
+ Source File: + mod_rewrite.c
+ Module Identifier: + rewrite_module
+ Compatibility: Available in + Apache 1.2 and later.

+
+
+ + +

Summary

+ +
+
+
+ ``The great thing about mod_rewrite is it gives you + all the configurability and flexibility of Sendmail. + The downside to mod_rewrite is that it gives you all + the configurability and flexibility of Sendmail.'' + + +
+ -- Brian Behlendorf
+ Apache Group +
+
+
+
+ +
+
+
+ `` Despite the tons of examples and docs, + mod_rewrite is voodoo. Damned cool voodoo, but still + voodoo. '' + +
+ -- Brian Moore
+ bem@news.cmc.net +
+
+
+
+ Welcome to mod_rewrite, the Swiss Army Knife of URL + manipulation! + +

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 rules and an + unlimited number of attached rule conditions for each rule to + provide a really flexible and powerful URL manipulation + mechanism. The URL manipulations can depend on various tests, + for instance server variables, environment variables, HTTP + headers, time stamps and even external database lookups in + various formats can be used to achieve a really granular URL + matching.

+ +

This module operates on the full URLs (including the + path-info part) both in per-server context + (httpd.conf) and per-directory context + (.htaccess) and can even generate query-string + parts on result. The rewritten result can lead to internal + sub-processing, external request redirection or even to an + internal proxy throughput.

+ +

But all this functionality and flexibility has its + drawback: complexity. So don't expect to understand this + entire module in just one day.

+ +

This module was invented and originally written in April + 1996
+ and gifted exclusively to the The Apache Group in July 1997 + by

+ +
+ Ralf S. + Engelschall
+ rse@engelschall.com
+ www.engelschall.com +
+
+ +

Table Of Contents

+ +

Internal Processing

+ + + +

Configuration Directives

+ + + Miscellaneous + + +
+ +
+

Internal + Processing

+
+
+ +

The internal processing of this module is very complex but + needs to be explained once even to the average user to avoid + common mistakes and to let you exploit its full + functionality.

+ +

API + Phases

+ +

First you have to understand that when Apache processes a + HTTP request it does this in phases. A hook for each of these + phases is provided by the Apache API. Mod_rewrite uses two of + these hooks: the URL-to-filename translation hook which is + used after the HTTP request has been read but before any + authorization starts and the Fixup hook which is triggered + after the authorization phases and after the per-directory + config files (.htaccess) have been read, but + before the content handler is activated.

+ +

So, after a request comes in and Apache has determined the + corresponding server (or virtual server) the rewriting engine + starts processing of all mod_rewrite directives from the + per-server configuration in the URL-to-filename phase. A few + steps later when the final data directories are found, the + per-directory configuration directives of mod_rewrite are + triggered in the Fixup phase. In both situations mod_rewrite + rewrites URLs either to new URLs or to filenames, although + there is no obvious distinction between them. This is a usage + of the API which was not intended to be this way when the API + was designed, but as of Apache 1.x this is the only way + mod_rewrite can operate. To make this point more clear + remember the following two points:

+ +
    +
  1. Although mod_rewrite rewrites URLs to URLs, URLs to + filenames and even filenames to filenames, the API + currently provides only a URL-to-filename hook. In Apache + 2.0 the two missing hooks will be added to make the + processing more clear. But this point has no drawbacks for + the user, it is just a fact which should be remembered: + Apache does more in the URL-to-filename hook than the API + intends for it.
    2. + +
  2. + Unbelievably mod_rewrite provides URL manipulations in + per-directory context, i.e., within + .htaccess files, although these are reached + a very long time after the URLs have been translated to + filenames. It has to be this way because + .htaccess files live in the filesystem, so + processing has already reached this stage. In other + words: According to the API phases at this time it is too + late for any URL manipulations. To overcome this chicken + and egg problem mod_rewrite uses a trick: When you + manipulate a URL/filename in per-directory context + mod_rewrite first rewrites the filename back to its + corresponding URL (which is usually impossible, but see + the RewriteBase directive below for the + trick to achieve this) and then initiates a new internal + sub-request with the new URL. This restarts processing of + the API phases. + +

    Again mod_rewrite tries hard to make this complicated + step totally transparent to the user, but you should + remember here: While URL manipulations in per-server + context are really fast and efficient, per-directory + rewrites are slow and inefficient due to this chicken and + egg problem. But on the other hand this is the only way + mod_rewrite can provide (locally restricted) URL + manipulations to the average user.

    +
    3. +
+ +

Don't forget these two points!

+ +

Ruleset + Processing

+ Now when mod_rewrite is triggered in these two API phases, it + reads the configured rulesets from its configuration + structure (which itself was either created on startup for + per-server context or during the directory walk of the Apache + kernel for per-directory context). Then the URL rewriting + engine is started with the contained ruleset (one or more + rules together with their conditions). The operation of the + URL rewriting engine itself is exactly the same for both + configuration contexts. Only the final result processing is + different. + +

The order of rules in the ruleset is important because the + rewriting engine processes them in a special (and not very + obvious) order. The rule is this: The rewriting engine loops + through the ruleset rule by rule (RewriteRule + directives) and when a particular rule matches it optionally + loops through existing corresponding conditions + (RewriteCond directives). For historical reasons + the conditions are given first, and so the control flow is a + little bit long-winded. See Figure 1 for more details.

+ +
+ + + + + + + + +
[Needs graphics capability to display]
Figure 1: The + control flow through the rewriting ruleset
+
+ +

As you can see, first the URL is matched against the + Pattern of each rule. When it fails mod_rewrite + immediately stops processing this rule and continues with the + next rule. If the Pattern matches, mod_rewrite looks + for corresponding rule conditions. If none are present, it + just substitutes the URL with a new value which is + constructed from the string Substitution and goes on + with its rule-looping. But if conditions exist, it starts an + inner loop for processing them in the order that they are + listed. For conditions the logic is different: we don't match + a pattern against the current URL. Instead we first create a + string TestString by expanding variables, + back-references, map lookups, etc. and then we try + to match CondPattern against it. If the pattern + doesn't match, the complete set of conditions and the + corresponding rule fails. If the pattern matches, then the + next condition is processed until no more conditions are + available. If all conditions match, processing is continued + with the substitution of the URL with + Substitution.

+ +

Quoting Special + Characters

+ +

As of Apache 1.3.20, special characters in + TestString and Substitution strings can be + escaped (that is, treated as normal characters without their + usual special meaning) by prefixing them with a slosh ('\') + character. In other words, you can include an actual + dollar-sign character in a Substitution string by + using '\$'; this keeps mod_rewrite from trying + to treat it as a backreference.

+ +

Regex + Back-Reference Availability

+ One important thing here has to be remembered: Whenever you + use parentheses in Pattern or in one of the + CondPattern, back-references are internally created + which can be used with the strings $N and + %N (see below). These are available for creating + the strings Substitution and TestString. + Figure 2 shows to which locations the back-references are + transfered for expansion. + +
+ + + + + + + + +
[Needs graphics capability to display]
Figure 2: The + back-reference flow through a rule
+
+ +

We know this was a crash course on mod_rewrite's internal + processing. But you will benefit from this knowledge when + reading the following documentation of the available + directives.

+
+ +
+

Configuration Directives

+
+
+ +

RewriteEngine

+ Syntax: RewriteEngine + on|off
+ Default: RewriteEngine + off
+ Context: server config, + virtual host, directory, .htaccess
+ Override: FileInfo
+ Status: Extension
+ Module: mod_rewrite.c
+ Compatibility: Apache + 1.2
+ + +

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 the RewriteRule + directives!

+ +

Note that, by default, rewrite configurations are not + inherited. This means that you need to have a + RewriteEngine on directive for each virtual host + in which you wish to use it.

+
+ +

RewriteOptions

+ Syntax: RewriteOptions + Option
+ Default: RewriteOptions + MaxRedirects=10
+ Context: server config, + virtual host, directory, .htaccess
+ Override: FileInfo
+ Status: Extension
+ Module: mod_rewrite.c
+ Compatibility: Apache + 1.2; MaxRedirects is available in Apache 1.3.28 and + later
+ + +

The RewriteOptions 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 are inherited. In per-directory context this means + that conditions and rules of the parent directory's + .htaccess configuration are inherited.
+ +
MaxRedirects=number
+
In order to prevent endless loops of internal redirects + issued by per-directory RewriteRules, + mod_rewrite aborts the request after reaching a + maximum number of such redirects and responds with an 500 Internal + Server Error. If you really need more internal redirects than 10 + per request, you may increase the default to the desired value.
+
+
+ +

RewriteLog

+ Syntax: RewriteLog + file-path
+ Default: None
+ Context: server config, + virtual host
+ Override: Not + applicable
+ Status: Extension
+ Module: mod_rewrite.c
+ Compatibility: Apache + 1.2
+ + +

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.

+ + + + + +
Note: To disable the logging of + rewriting actions it is not recommended to set + file-path to /dev/null, because + although the rewriting engine does not then 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
+ Override: Not + applicable
+ Status: Extension
+ Module: mod_rewrite.c
+ Compatibility: Apache + 1.2
+ + +

The RewriteLogLevel directive sets 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 at a + Level greater than 2 only for debugging!
+ +

Example:

+ +
+
+RewriteLogLevel 3
+
+
+
+ +

RewriteLock

+ Syntax: RewriteLock + file-path
+ Default: None
+ Context: server config
+ Override: Not + applicable
+ Status: Extension
+ Module: mod_rewrite.c
+ Compatibility: Apache + 1.3
+ + +

This directive sets the filename for a synchronization + lockfile which mod_rewrite needs to communicate with + RewriteMap programs. Set this lockfile + to a local path (not on a NFS-mounted device) when you want + to use a rewriting map-program. It is not required for other + types of rewriting maps.

+
+ +

RewriteMap

+ Syntax: RewriteMap + MapName MapType:MapSource
+ Default: not used per + default
+ Context: server config, + virtual host
+ Override: Not + applicable
+ Status: Extension
+ Module: mod_rewrite.c
+ Compatibility: Apache 1.2 + (partially), Apache 1.3
+ + +

The RewriteMap directive defines a + Rewriting Map which can be used inside rule + substitution strings by the mapping-functions to + insert/substitute fields through a key lookup. The source of + this lookup can be of various types.

+ +

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 one of the following constructs:

+ +
+ ${ MapName : + LookupKey }
+ ${ MapName : + LookupKey | DefaultValue + } +
+ When such a construct occurs the map MapName is + consulted and the key LookupKey is looked-up. If the + key is found, the map-function construct is substituted by + SubstValue. If the key is not found then it is + substituted by DefaultValue or by the empty string + if no DefaultValue was specified. + +

The following combinations for MapType and + MapSource can be used:

+ + + The RewriteMap directive can occur more than + once. For each mapping-function use one + RewriteMap directive to declare its rewriting + mapfile. While you cannot declare a map in + per-directory context it is of course possible to + use this map in per-directory context. + + + + + +
Note: 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 + URL-path
+ Default: default is the + physical directory path
+ Context: directory, + .htaccess
+ Override: + FileInfo
+ Status: Extension
+ Module: mod_rewrite.c
+ Compatibility: Apache + 1.2
+ + +

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 back to the + path.

+ +

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 usually be wrong! There you have to + use the RewriteBase directive to specify the + correct URL-prefix.

+ + + + + +
Notice: 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: + + + + + +
+
+#
+#  /abc/def/.htaccess -- per-dir config file for directory /abc/def
+#  Remember: /abc/def is the physical path of /xyz, i.e., the server
+#            has a 'Alias /xyz /abc/def' directive e.g.
+#
+
+RewriteEngine On
+
+#  let the server know that we were reached via /xyz and not
+#  via the physical path prefix /abc/def
+RewriteBase   /xyz
+
+#  now the rewriting rules
+RewriteRule   ^oldstuff\.html$  newstuff.html
+
+
+ +

In the above example, a request to + /xyz/oldstuff.html gets correctly rewritten to + the physical file /abc/def/newstuff.html.

+ + + + + +
+ Note - For 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 + internally 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, directory, .htaccess
+ Override: + FileInfo
+ Status: Extension
+ Module: mod_rewrite.c
+ Compatibility: Apache 1.2 + (partially), Apache 1.3
+ + +

The RewriteCond directive defines a rule + condition. Precede a RewriteRule directive with + one or more RewriteCond directives. The + following rewriting rule is only used if its pattern matches + the current state of the URI and if these + additional conditions apply too.

+ +

TestString is a string which can contains the + following expanded constructs in addition to plain text:

+ + + +

Special Notes:

+ +
    +
  1. The variables SCRIPT_FILENAME and REQUEST_FILENAME + contain the same value, i.e., the value of the + filename field of the internal + request_rec structure of the Apache server. + The first name is just the commonly known CGI variable name + while the second is the consistent counterpart to + REQUEST_URI (which contains the value of the + uri field of request_rec).
    2. + +
  2. There is the special format: + %{ENV:variable} where variable can be + any environment variable. This is looked-up via internal + Apache structures and (if not found there) via + getenv() from the Apache server process.
    3. + +
  3. There is the special format: + %{HTTP:header} where header can be + any HTTP MIME-header name. This is looked-up from the HTTP + request. Example: %{HTTP:Proxy-Connection} is + the value of the HTTP header + ``Proxy-Connection:''.
    4. + +
  4. There is the special format + %{LA-U:variable} for look-aheads which perform + an internal (URL-based) sub-request to determine the final + value of variable. Use this when you want to use a + variable for rewriting which is actually set later in an + API phase and thus is not available at the current stage. + For instance when you want to rewrite according to the + REMOTE_USER variable from within the + per-server context (httpd.conf file) you have + to use %{LA-U:REMOTE_USER} because this + variable is set by the authorization phases which come + after the URL translation phase where mod_rewrite + operates. On the other hand, because mod_rewrite implements + its per-directory context (.htaccess file) via + the Fixup phase of the API and because the authorization + phases come before this phase, you just can use + %{REMOTE_USER} there.
    5. + +
  5. There is the special format: + %{LA-F:variable} which performs an internal + (filename-based) sub-request to determine the final value + of variable. Most of the time this is the same as + LA-U above.
    6. +
+ +

CondPattern is the condition pattern, + i.e., a regular expression which is applied to the + current instance of the TestString, i.e., + TestString is evaluated and then matched against + CondPattern.

+ +

Remember: CondPattern is a + standard Extended Regular Expression with some + additions:

+ +
    +
  1. You can prefix the pattern string with a + '!' character (exclamation mark) to specify a + non-matching pattern.
    2. + +
  2. + There are some special variants of CondPatterns. + Instead of real regular expression strings you can also + use one of the following: + +
      +
    • '<CondPattern' (is lexically + lower)
      + Treats the CondPattern as a plain string and + compares it lexically to TestString. True if + TestString is lexically lower than + CondPattern.
      • + +
    • '>CondPattern' (is lexically + greater)
      + Treats the CondPattern as a plain string and + compares it lexically to TestString. True if + TestString is lexically greater than + CondPattern.
      • + +
    • '=CondPattern' (is lexically + equal)
      + Treats the CondPattern as a plain string and + compares it lexically to TestString. True if + TestString is lexically equal to + CondPattern, i.e the two strings are exactly + equal (character by character). If CondPattern + is just "" (two quotation marks) this + compares TestString to the empty string.
      • + +
    • '-d' (is + directory)
      + Treats the TestString as a pathname and tests + if it exists and is a directory.
      • + +
    • '-f' (is regular + file)
      + Treats the TestString as a pathname and tests + if it exists and is a regular file.
      • + +
    • '-s' (is regular file with + size)
      + Treats the TestString as a pathname and tests + if it exists and is a regular file with size greater + than zero.
      • + +
    • '-l' (is symbolic + link)
      + Treats the TestString as a pathname and tests + if it exists and is a symbolic link.
      • + +
    • '-F' (is existing file via + subrequest)
      + 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!
      • + +
    • '-U' (is existing URL via + subrequest)
      + 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 server's performance!
      • +
    + + + + + +
    Notice: All of these tests can + also be prefixed by an exclamation mark ('!') to + negate their meaning.
    +
    3. +
+ +

Additionally you can set special flags for + CondPattern by appending

+ +
+ [flags] +
+ as the third argument to the RewriteCond + directive. Flags is a comma-separated list of the + following flags: + + + +

Example:

+ +
+ To rewrite the Homepage of a site according to the + ``User-Agent:'' header of the request, you can + use the following: + +
+
+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]
+
+
+ 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. +
+
+ +

RewriteRule

+ Syntax: RewriteRule + Pattern Substitution
+ Default: None
+ Context: server config, + virtual host, directory, .htaccess
+ Override: + FileInfo
+ Status: Extension
+ Module: mod_rewrite.c
+ Compatibility: Apache 1.2 + (partially), Apache 1.3
+ + +

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 and + later 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 originally requested URL, + because any number of rules may already + have matched and made alterations to it.

+ +

Some hints about the syntax of regular expressions:

+ + + + + +
+
+Text:
+  .           Any single character
+  [chars]     Character class: One  of chars
+  [^chars]    Character class: None of chars
+  text1|text2 Alternative: text1 or text2
+
+Quantifiers:
+  ?           0 or 1 of the preceding text
+  *           0 or N of the preceding text (N > 0)
+  +           1 or N of the preceding text (N > 1)
+
+Grouping:
+  (text)      Grouping of text
+              (either to set the borders of an alternative or
+              for making backreferences where the Nth group can 
+              be used on the RHS of a RewriteRule with $N)
+
+Anchors:
+  ^           Start of line anchor
+  $           End   of line anchor
+
+Escaping:
+  \char       escape that particular char
+              (for instance to specify the chars ".[]()" etc.)
+
+
+ +

For more information about regular expressions either have + a look at your local regex(3) manpage or its + src/regex/regex.3 copy in the Apache 1.3 + distribution. If you are interested in more detailed + information about regular expressions and their variants + (POSIX regex, Perl regex, etc.) have a look at the + following dedicated book on this topic:

+ +
+ Mastering Regular Expressions
+ Jeffrey E.F. Friedl
+ Nutshell Handbook Series
+ O'Reilly & Associates, Inc. 1997
+ ISBN 1-56592-257-3
+
+ +

Additionally in mod_rewrite 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 this + pattern''. This can be used for exceptional cases, where + it is easier to match the negative pattern, or as a last + default rule.

+ + + + + +
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!
+ +

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

+ +
    +
  1. back-references $N to the RewriteRule + pattern
    2. + +
  2. back-references %N to the last matched + RewriteCond pattern
    3. + +
  3. server-variables as in rule condition test-strings + (%{VARNAME})
    4. + +
  4. mapping-function calls + (${mapname:key|default})
    5. +
+ Back-references are $N + (N=0..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. + +

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 + L flag - see below.

+ +

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.

+ +

One more note: You can even create URLs in the + substitution string containing a query string part. Just use + a question mark inside the substitution string to indicate + that the following stuff should be re-injected into the + QUERY_STRING. When you want to erase an existing query + string, end the substitution string with just the question + mark.

+ + + + + +
Note: 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.
+ + + + + +
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

+ +
+ [flags] +
+ as the third argument to the RewriteRule + directive. Flags is a comma-separated list of the + following flags: + + + + + + + +
+ Note: Never forget that + Pattern is 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!) is 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. + +

There is one exception: If a substitution string + starts with ``http://'' then the directory + prefix will not be added and an + external redirect or proxy throughput (if flag + P is used!) is forced!

+
+ + + + + +
Note: To enable the rewriting engine + for per-directory configuration files you need to set + ``RewriteEngine On'' in these files + and ``Options + FollowSymLinks'' must be 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.
+ +

Here are all possible substitution combinations and their + meanings:

+ +

Inside per-server configuration + (httpd.conf)
+ 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
+
+
+ +

Inside per-directory configuration for + /somepath
+ (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
+
+
+ +

Example:

+ +
+ We want to rewrite URLs of the form + +
+ / Language /~ + Realname /.../ File +
+ into + +
+ /u/ Username /.../ + File . Language +
+ +

We take the rewrite mapfile from above and save it under + /path/to/file/map.txt. Then we only have to + add the following lines to the Apache server configuration + file:

+ +
+
+RewriteLog   /path/to/file/rewrite.log
+RewriteMap   real-to-user               txt:/path/to/file/map.txt
+RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1
+
+
+
+
+ +
+

Miscellaneous

+
+
+ +

Environment + Variables

+ This module keeps track of two additional (non-standard) + CGI/SSI environment variables named SCRIPT_URL + and SCRIPT_URI. These contain the + logical Web-view to the current resource, while the + standard CGI/SSI variables SCRIPT_NAME and + SCRIPT_FILENAME contain the physical + System-view. + +

Notice: These variables hold the URI/URL as they were + initially requested, i.e., before any + rewriting. This is important because the rewriting process is + primarily used to rewrite logical URLs to physical + pathnames.

+ +

Example:

+ +
+
+SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
+SCRIPT_FILENAME=/u/rse/.www/index.html
+SCRIPT_URL=/u/rse/
+SCRIPT_URI=http://en1.engelschall.com/u/rse/
+
+
+
+ +

Practical + Solutions

+ We also have an URL + Rewriting Guide available, which provides a collection of + practical solutions for URL-based problems. There you can + find real-life rulesets and additional information about + mod_rewrite. +
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html.html deleted file mode 100644 index 61903c9d942..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html.html +++ /dev/null @@ -1,2107 +0,0 @@ - - - - - - - - - - - Apache module mod_rewrite - - - - -
- -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- -
- - -

Module mod_rewrite
- URL Rewriting Engine

- -

This module provides a rule-based rewriting engine to - rewrite requested URLs on the fly.

- -

Status: Extension
- Source File: - mod_rewrite.c
- Module Identifier: - rewrite_module
- Compatibility: Available in - Apache 1.2 and later.

-
-
- - -

Summary

- -
-
-
- ``The great thing about mod_rewrite is it gives you - all the configurability and flexibility of Sendmail. - The downside to mod_rewrite is that it gives you all - the configurability and flexibility of Sendmail.'' - - -
- -- Brian Behlendorf
- Apache Group -
-
-
-
- -
-
-
- `` Despite the tons of examples and docs, - mod_rewrite is voodoo. Damned cool voodoo, but still - voodoo. '' - -
- -- Brian Moore
- bem@news.cmc.net -
-
-
-
- Welcome to mod_rewrite, the Swiss Army Knife of URL - manipulation! - -

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 rules and an - unlimited number of attached rule conditions for each rule to - provide a really flexible and powerful URL manipulation - mechanism. The URL manipulations can depend on various tests, - for instance server variables, environment variables, HTTP - headers, time stamps and even external database lookups in - various formats can be used to achieve a really granular URL - matching.

- -

This module operates on the full URLs (including the - path-info part) both in per-server context - (httpd.conf) and per-directory context - (.htaccess) and can even generate query-string - parts on result. The rewritten result can lead to internal - sub-processing, external request redirection or even to an - internal proxy throughput.

- -

But all this functionality and flexibility has its - drawback: complexity. So don't expect to understand this - entire module in just one day.

- -

This module was invented and originally written in April - 1996
- and gifted exclusively to the The Apache Group in July 1997 - by

- -
- Ralf S. - Engelschall
- rse@engelschall.com
- www.engelschall.com -
-
- -

Table Of Contents

- -

Internal Processing

- - - -

Configuration Directives

- - - Miscellaneous - - -
- -
-

Internal - Processing

-
-
- -

The internal processing of this module is very complex but - needs to be explained once even to the average user to avoid - common mistakes and to let you exploit its full - functionality.

- -

API - Phases

- -

First you have to understand that when Apache processes a - HTTP request it does this in phases. A hook for each of these - phases is provided by the Apache API. Mod_rewrite uses two of - these hooks: the URL-to-filename translation hook which is - used after the HTTP request has been read but before any - authorization starts and the Fixup hook which is triggered - after the authorization phases and after the per-directory - config files (.htaccess) have been read, but - before the content handler is activated.

- -

So, after a request comes in and Apache has determined the - corresponding server (or virtual server) the rewriting engine - starts processing of all mod_rewrite directives from the - per-server configuration in the URL-to-filename phase. A few - steps later when the final data directories are found, the - per-directory configuration directives of mod_rewrite are - triggered in the Fixup phase. In both situations mod_rewrite - rewrites URLs either to new URLs or to filenames, although - there is no obvious distinction between them. This is a usage - of the API which was not intended to be this way when the API - was designed, but as of Apache 1.x this is the only way - mod_rewrite can operate. To make this point more clear - remember the following two points:

- -
    -
  1. Although mod_rewrite rewrites URLs to URLs, URLs to - filenames and even filenames to filenames, the API - currently provides only a URL-to-filename hook. In Apache - 2.0 the two missing hooks will be added to make the - processing more clear. But this point has no drawbacks for - the user, it is just a fact which should be remembered: - Apache does more in the URL-to-filename hook than the API - intends for it.
    2. - -
  2. - Unbelievably mod_rewrite provides URL manipulations in - per-directory context, i.e., within - .htaccess files, although these are reached - a very long time after the URLs have been translated to - filenames. It has to be this way because - .htaccess files live in the filesystem, so - processing has already reached this stage. In other - words: According to the API phases at this time it is too - late for any URL manipulations. To overcome this chicken - and egg problem mod_rewrite uses a trick: When you - manipulate a URL/filename in per-directory context - mod_rewrite first rewrites the filename back to its - corresponding URL (which is usually impossible, but see - the RewriteBase directive below for the - trick to achieve this) and then initiates a new internal - sub-request with the new URL. This restarts processing of - the API phases. - -

    Again mod_rewrite tries hard to make this complicated - step totally transparent to the user, but you should - remember here: While URL manipulations in per-server - context are really fast and efficient, per-directory - rewrites are slow and inefficient due to this chicken and - egg problem. But on the other hand this is the only way - mod_rewrite can provide (locally restricted) URL - manipulations to the average user.

    -
    3. -
- -

Don't forget these two points!

- -

Ruleset - Processing

- Now when mod_rewrite is triggered in these two API phases, it - reads the configured rulesets from its configuration - structure (which itself was either created on startup for - per-server context or during the directory walk of the Apache - kernel for per-directory context). Then the URL rewriting - engine is started with the contained ruleset (one or more - rules together with their conditions). The operation of the - URL rewriting engine itself is exactly the same for both - configuration contexts. Only the final result processing is - different. - -

The order of rules in the ruleset is important because the - rewriting engine processes them in a special (and not very - obvious) order. The rule is this: The rewriting engine loops - through the ruleset rule by rule (RewriteRule - directives) and when a particular rule matches it optionally - loops through existing corresponding conditions - (RewriteCond directives). For historical reasons - the conditions are given first, and so the control flow is a - little bit long-winded. See Figure 1 for more details.

- -
- - - - - - - - -
[Needs graphics capability to display]
Figure 1: The - control flow through the rewriting ruleset
-
- -

As you can see, first the URL is matched against the - Pattern of each rule. When it fails mod_rewrite - immediately stops processing this rule and continues with the - next rule. If the Pattern matches, mod_rewrite looks - for corresponding rule conditions. If none are present, it - just substitutes the URL with a new value which is - constructed from the string Substitution and goes on - with its rule-looping. But if conditions exist, it starts an - inner loop for processing them in the order that they are - listed. For conditions the logic is different: we don't match - a pattern against the current URL. Instead we first create a - string TestString by expanding variables, - back-references, map lookups, etc. and then we try - to match CondPattern against it. If the pattern - doesn't match, the complete set of conditions and the - corresponding rule fails. If the pattern matches, then the - next condition is processed until no more conditions are - available. If all conditions match, processing is continued - with the substitution of the URL with - Substitution.

- -

Quoting Special - Characters

- -

As of Apache 1.3.20, special characters in - TestString and Substitution strings can be - escaped (that is, treated as normal characters without their - usual special meaning) by prefixing them with a slosh ('\') - character. In other words, you can include an actual - dollar-sign character in a Substitution string by - using '\$'; this keeps mod_rewrite from trying - to treat it as a backreference.

- -

Regex - Back-Reference Availability

- One important thing here has to be remembered: Whenever you - use parentheses in Pattern or in one of the - CondPattern, back-references are internally created - which can be used with the strings $N and - %N (see below). These are available for creating - the strings Substitution and TestString. - Figure 2 shows to which locations the back-references are - transfered for expansion. - -
- - - - - - - - -
[Needs graphics capability to display]
Figure 2: The - back-reference flow through a rule
-
- -

We know this was a crash course on mod_rewrite's internal - processing. But you will benefit from this knowledge when - reading the following documentation of the available - directives.

-
- -
-

Configuration Directives

-
-
- -

RewriteEngine

- Syntax: RewriteEngine - on|off
- Default: RewriteEngine - off
- Context: server config, - virtual host, directory, .htaccess
- Override: FileInfo
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.2
- - -

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 the RewriteRule - directives!

- -

Note that, by default, rewrite configurations are not - inherited. This means that you need to have a - RewriteEngine on directive for each virtual host - in which you wish to use it.

-
- -

RewriteOptions

- Syntax: RewriteOptions - Option
- Default: RewriteOptions - MaxRedirects=10
- Context: server config, - virtual host, directory, .htaccess
- Override: FileInfo
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.2; MaxRedirects is available in Apache 1.3.28 and - later
- - -

The RewriteOptions 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 are inherited. In per-directory context this means - that conditions and rules of the parent directory's - .htaccess configuration are inherited.
- -
MaxRedirects=number
-
In order to prevent endless loops of internal redirects - issued by per-directory RewriteRules, - mod_rewrite aborts the request after reaching a - maximum number of such redirects and responds with an 500 Internal - Server Error. If you really need more internal redirects than 10 - per request, you may increase the default to the desired value.
-
-
- -

RewriteLog

- Syntax: RewriteLog - file-path
- Default: None
- Context: server config, - virtual host
- Override: Not - applicable
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.2
- - -

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.

- - - - - -
Note: To disable the logging of - rewriting actions it is not recommended to set - file-path to /dev/null, because - although the rewriting engine does not then 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
- Override: Not - applicable
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.2
- - -

The RewriteLogLevel directive sets 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 at a - Level greater than 2 only for debugging!
- -

Example:

- -
-
-RewriteLogLevel 3
-
-
-
- -

RewriteLock

- Syntax: RewriteLock - file-path
- Default: None
- Context: server config
- Override: Not - applicable
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.3
- - -

This directive sets the filename for a synchronization - lockfile which mod_rewrite needs to communicate with - RewriteMap programs. Set this lockfile - to a local path (not on a NFS-mounted device) when you want - to use a rewriting map-program. It is not required for other - types of rewriting maps.

-
- -

RewriteMap

- Syntax: RewriteMap - MapName MapType:MapSource
- Default: not used per - default
- Context: server config, - virtual host
- Override: Not - applicable
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache 1.2 - (partially), Apache 1.3
- - -

The RewriteMap directive defines a - Rewriting Map which can be used inside rule - substitution strings by the mapping-functions to - insert/substitute fields through a key lookup. The source of - this lookup can be of various types.

- -

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 one of the following constructs:

- -
- ${ MapName : - LookupKey }
- ${ MapName : - LookupKey | DefaultValue - } -
- When such a construct occurs the map MapName is - consulted and the key LookupKey is looked-up. If the - key is found, the map-function construct is substituted by - SubstValue. If the key is not found then it is - substituted by DefaultValue or by the empty string - if no DefaultValue was specified. - -

The following combinations for MapType and - MapSource can be used:

- - - The RewriteMap directive can occur more than - once. For each mapping-function use one - RewriteMap directive to declare its rewriting - mapfile. While you cannot declare a map in - per-directory context it is of course possible to - use this map in per-directory context. - - - - - -
Note: 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 - URL-path
- Default: default is the - physical directory path
- Context: directory, - .htaccess
- Override: - FileInfo
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.2
- - -

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 back to the - path.

- -

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 usually be wrong! There you have to - use the RewriteBase directive to specify the - correct URL-prefix.

- - - - - -
Notice: 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: - - - - - -
-
-#
-#  /abc/def/.htaccess -- per-dir config file for directory /abc/def
-#  Remember: /abc/def is the physical path of /xyz, i.e., the server
-#            has a 'Alias /xyz /abc/def' directive e.g.
-#
-
-RewriteEngine On
-
-#  let the server know that we were reached via /xyz and not
-#  via the physical path prefix /abc/def
-RewriteBase   /xyz
-
-#  now the rewriting rules
-RewriteRule   ^oldstuff\.html$  newstuff.html
-
-
- -

In the above example, a request to - /xyz/oldstuff.html gets correctly rewritten to - the physical file /abc/def/newstuff.html.

- - - - - -
- Note - For 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 - internally 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, directory, .htaccess
- Override: - FileInfo
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache 1.2 - (partially), Apache 1.3
- - -

The RewriteCond directive defines a rule - condition. Precede a RewriteRule directive with - one or more RewriteCond directives. The - following rewriting rule is only used if its pattern matches - the current state of the URI and if these - additional conditions apply too.

- -

TestString is a string which can contains the - following expanded constructs in addition to plain text:

- - - -

Special Notes:

- -
    -
  1. The variables SCRIPT_FILENAME and REQUEST_FILENAME - contain the same value, i.e., the value of the - filename field of the internal - request_rec structure of the Apache server. - The first name is just the commonly known CGI variable name - while the second is the consistent counterpart to - REQUEST_URI (which contains the value of the - uri field of request_rec).
    2. - -
  2. There is the special format: - %{ENV:variable} where variable can be - any environment variable. This is looked-up via internal - Apache structures and (if not found there) via - getenv() from the Apache server process.
    3. - -
  3. There is the special format: - %{HTTP:header} where header can be - any HTTP MIME-header name. This is looked-up from the HTTP - request. Example: %{HTTP:Proxy-Connection} is - the value of the HTTP header - ``Proxy-Connection:''.
    4. - -
  4. There is the special format - %{LA-U:variable} for look-aheads which perform - an internal (URL-based) sub-request to determine the final - value of variable. Use this when you want to use a - variable for rewriting which is actually set later in an - API phase and thus is not available at the current stage. - For instance when you want to rewrite according to the - REMOTE_USER variable from within the - per-server context (httpd.conf file) you have - to use %{LA-U:REMOTE_USER} because this - variable is set by the authorization phases which come - after the URL translation phase where mod_rewrite - operates. On the other hand, because mod_rewrite implements - its per-directory context (.htaccess file) via - the Fixup phase of the API and because the authorization - phases come before this phase, you just can use - %{REMOTE_USER} there.
    5. - -
  5. There is the special format: - %{LA-F:variable} which performs an internal - (filename-based) sub-request to determine the final value - of variable. Most of the time this is the same as - LA-U above.
    6. -
- -

CondPattern is the condition pattern, - i.e., a regular expression which is applied to the - current instance of the TestString, i.e., - TestString is evaluated and then matched against - CondPattern.

- -

Remember: CondPattern is a - standard Extended Regular Expression with some - additions:

- -
    -
  1. You can prefix the pattern string with a - '!' character (exclamation mark) to specify a - non-matching pattern.
    2. - -
  2. - There are some special variants of CondPatterns. - Instead of real regular expression strings you can also - use one of the following: - -
      -
    • '<CondPattern' (is lexically - lower)
      - Treats the CondPattern as a plain string and - compares it lexically to TestString. True if - TestString is lexically lower than - CondPattern.
      • - -
    • '>CondPattern' (is lexically - greater)
      - Treats the CondPattern as a plain string and - compares it lexically to TestString. True if - TestString is lexically greater than - CondPattern.
      • - -
    • '=CondPattern' (is lexically - equal)
      - Treats the CondPattern as a plain string and - compares it lexically to TestString. True if - TestString is lexically equal to - CondPattern, i.e the two strings are exactly - equal (character by character). If CondPattern - is just "" (two quotation marks) this - compares TestString to the empty string.
      • - -
    • '-d' (is - directory)
      - Treats the TestString as a pathname and tests - if it exists and is a directory.
      • - -
    • '-f' (is regular - file)
      - Treats the TestString as a pathname and tests - if it exists and is a regular file.
      • - -
    • '-s' (is regular file with - size)
      - Treats the TestString as a pathname and tests - if it exists and is a regular file with size greater - than zero.
      • - -
    • '-l' (is symbolic - link)
      - Treats the TestString as a pathname and tests - if it exists and is a symbolic link.
      • - -
    • '-F' (is existing file via - subrequest)
      - 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!
      • - -
    • '-U' (is existing URL via - subrequest)
      - 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 server's performance!
      • -
    - - - - - -
    Notice: All of these tests can - also be prefixed by an exclamation mark ('!') to - negate their meaning.
    -
    3. -
- -

Additionally you can set special flags for - CondPattern by appending

- -
- [flags] -
- as the third argument to the RewriteCond - directive. Flags is a comma-separated list of the - following flags: - - - -

Example:

- -
- To rewrite the Homepage of a site according to the - ``User-Agent:'' header of the request, you can - use the following: - -
-
-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]
-
-
- 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. -
-
- -

RewriteRule

- Syntax: RewriteRule - Pattern Substitution
- Default: None
- Context: server config, - virtual host, directory, .htaccess
- Override: - FileInfo
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache 1.2 - (partially), Apache 1.3
- - -

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 and - later 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 originally requested URL, - because any number of rules may already - have matched and made alterations to it.

- -

Some hints about the syntax of regular expressions:

- - - - - -
-
-Text:
-  .           Any single character
-  [chars]     Character class: One  of chars
-  [^chars]    Character class: None of chars
-  text1|text2 Alternative: text1 or text2
-
-Quantifiers:
-  ?           0 or 1 of the preceding text
-  *           0 or N of the preceding text (N > 0)
-  +           1 or N of the preceding text (N > 1)
-
-Grouping:
-  (text)      Grouping of text
-              (either to set the borders of an alternative or
-              for making backreferences where the Nth group can 
-              be used on the RHS of a RewriteRule with $N)
-
-Anchors:
-  ^           Start of line anchor
-  $           End   of line anchor
-
-Escaping:
-  \char       escape that particular char
-              (for instance to specify the chars ".[]()" etc.)
-
-
- -

For more information about regular expressions either have - a look at your local regex(3) manpage or its - src/regex/regex.3 copy in the Apache 1.3 - distribution. If you are interested in more detailed - information about regular expressions and their variants - (POSIX regex, Perl regex, etc.) have a look at the - following dedicated book on this topic:

- -
- Mastering Regular Expressions
- Jeffrey E.F. Friedl
- Nutshell Handbook Series
- O'Reilly & Associates, Inc. 1997
- ISBN 1-56592-257-3
-
- -

Additionally in mod_rewrite 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 this - pattern''. This can be used for exceptional cases, where - it is easier to match the negative pattern, or as a last - default rule.

- - - - - -
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!
- -

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

- -
    -
  1. back-references $N to the RewriteRule - pattern
    2. - -
  2. back-references %N to the last matched - RewriteCond pattern
    3. - -
  3. server-variables as in rule condition test-strings - (%{VARNAME})
    4. - -
  4. mapping-function calls - (${mapname:key|default})
    5. -
- Back-references are $N - (N=0..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. - -

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 - L flag - see below.

- -

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.

- -

One more note: You can even create URLs in the - substitution string containing a query string part. Just use - a question mark inside the substitution string to indicate - that the following stuff should be re-injected into the - QUERY_STRING. When you want to erase an existing query - string, end the substitution string with just the question - mark.

- - - - - -
Note: 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.
- - - - - -
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

- -
- [flags] -
- as the third argument to the RewriteRule - directive. Flags is a comma-separated list of the - following flags: - - - - - - - -
- Note: Never forget that - Pattern is 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!) is 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. - -

There is one exception: If a substitution string - starts with ``http://'' then the directory - prefix will not be added and an - external redirect or proxy throughput (if flag - P is used!) is forced!

-
- - - - - -
Note: To enable the rewriting engine - for per-directory configuration files you need to set - ``RewriteEngine On'' in these files - and ``Options - FollowSymLinks'' must be 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.
- -

Here are all possible substitution combinations and their - meanings:

- -

Inside per-server configuration - (httpd.conf)
- 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
-
-
- -

Inside per-directory configuration for - /somepath
- (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
-
-
- -

Example:

- -
- We want to rewrite URLs of the form - -
- / Language /~ - Realname /.../ File -
- into - -
- /u/ Username /.../ - File . Language -
- -

We take the rewrite mapfile from above and save it under - /path/to/file/map.txt. Then we only have to - add the following lines to the Apache server configuration - file:

- -
-
-RewriteLog   /path/to/file/rewrite.log
-RewriteMap   real-to-user               txt:/path/to/file/map.txt
-RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1
-
-
-
-
- -
-

Miscellaneous

-
-
- -

Environment - Variables

- This module keeps track of two additional (non-standard) - CGI/SSI environment variables named SCRIPT_URL - and SCRIPT_URI. These contain the - logical Web-view to the current resource, while the - standard CGI/SSI variables SCRIPT_NAME and - SCRIPT_FILENAME contain the physical - System-view. - -

Notice: These variables hold the URI/URL as they were - initially requested, i.e., before any - rewriting. This is important because the rewriting process is - primarily used to rewrite logical URLs to physical - pathnames.

- -

Example:

- -
-
-SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
-SCRIPT_FILENAME=/u/rse/.www/index.html
-SCRIPT_URL=/u/rse/
-SCRIPT_URI=http://en1.engelschall.com/u/rse/
-
-
-
- -

Practical - Solutions

- We also have an URL - Rewriting Guide available, which provides a collection of - practical solutions for URL-based problems. There you can - find real-life rulesets and additional information about - mod_rewrite. -
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html b/usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html new file mode 100644 index 00000000000..2837e4619b9 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html @@ -0,0 +1,341 @@ + + + + + + + + Apache module mod_setenvif + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_setenvif

+ +

This module provides the ability to set environment + variables based upon attributes of the request.

+ +

Status: Base
+ Source File: + mod_setenvif.c
+ Module Identifier: + setenvif_module
+ Compatibility: Available in + Apache 1.3 and later.

+ +

Summary

+ +

The mod_setenvif module allows you to set + environment variables according to whether different aspects of + the request match regular + expressions you specify. These environment variables can be + used by other parts of the server to make decisions about + actions to be taken.

+ +

The directives are considered in the order they appear in + the configuration files. So more complex sequences can be used, + such as this example, which sets netscape if the + browser is mozilla but not MSIE.

+ +
+
+  BrowserMatch ^Mozilla netscape
+  BrowserMatch MSIE !netscape
+ 
+
+
+ +

For additional information, we provide a document on Environment Variables in Apache.

+ +

Directives

+ + +
+ + +

BrowserMatch + directive

+ +

Syntax: BrowserMatch regex + env-variable[=value] + [env-variable[=value]] ...
+ Default: none
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_setenvif
+ Compatibility: Apache 1.2 and + above (in Apache 1.2 this directive was found in the + now-obsolete mod_browser module); use in .htaccess files only + supported with 1.3.13 and later

+ +

The BrowserMatch directive defines environment variables + based on the User-Agent HTTP request header field. + The first argument should be a POSIX.2 extended regular + expression (similar to an egrep-style regex). The + rest of the arguments give the names of variables to set, and + optionally values to which they should be set. These take the + form of

+ +
    +
  1. varname, or
    2. + +
  2. !varname, or
    3. + +
  3. varname=value
    4. +
+ +

In the first form, the value will be set to "1". The second + will remove the given variable if already defined, and the + third will set the variable to the value given by + value. If a User-Agent + string matches more than one entry, they will be merged. + Entries are processed in the order in which they appear, and + later entries can override earlier ones.

+ +

For example:

+
+    BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
+    BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
+    BrowserMatch MSIE !javascript
+ 
+
+ +

Note that the regular expression string is + case-sensitive. For case-INsensitive matching, + see the BrowserMatchNoCase + directive.

+ +

The BrowserMatch and + BrowserMatchNoCase directives are special cases of + the SetEnvIf and SetEnvIfNoCase + directives. The following two lines have the same effect:

+
+   BrowserMatchNoCase Robot is_a_robot
+   SetEnvIfNoCase User-Agent Robot is_a_robot
+ 
+
+
+ + +

BrowserMatchNoCase directive

+ +

Syntax: BrowserMatchNoCase + regex env-variable[=value] + [env-variable[=value]] ...
+ Default: none
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_setenvif
+ Compatibility: Apache 1.2 and + above (in Apache 1.2 this directive was found in the + now-obsolete mod_browser module)

+ +

The BrowserMatchNoCase directive is + semantically identical to the BrowserMatch directive. + However, it provides for case-insensitive matching. For + example:

+
+    BrowserMatchNoCase mac platform=macintosh
+    BrowserMatchNoCase win platform=windows
+ 
+
+ +

The BrowserMatch and + BrowserMatchNoCase directives are special cases of + the SetEnvIf and SetEnvIfNoCase + directives. The following two lines have the same effect:

+
+   BrowserMatchNoCase Robot is_a_robot
+   SetEnvIfNoCase User-Agent Robot is_a_robot
+ 
+
+
+ + +

SetEnvIf + directive

+ +

Syntax: SetEnvIf attribute + regex env-variable[=value] + [env-variable[=value]] ...
+ Default: none
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_setenvif
+ Compatibility: Apache 1.3 and + above; the Request_Protocol keyword and environment-variable + matching are only available with 1.3.7 and later; use in + .htaccess files only supported with 1.3.13 and later

+ +

The SetEnvIf directive defines environment + variables based on attributes of the request. These attributes + can be the values of various HTTP request header fields (see RFC2616 + for more information about these), or of other aspects of the + request, including the following:

+ + + +

Some of the more commonly used request header field names + include Host, User-Agent, and + Referer.

+ +

If the attribute name doesn't match any of the + special keywords, nor any of the request's header field names, + it is tested as the name of an environment variable in the list + of those associated with the request. This allows + SetEnvIf directives to test against the result of + prior matches.

+ +
+ Only those environment variables defined by earlier + SetEnvIf[NoCase] directives are available for + testing in this manner. 'Earlier' means that they were + defined at a broader scope (such as server-wide) or + previously in the current directive's scope. +
+ +

Example:

+
+   SetEnvIf Request_URI "\.gif$" object_is_image=gif
+   SetEnvIf Request_URI "\.jpg$" object_is_image=jpg
+   SetEnvIf Request_URI "\.xbm$" object_is_image=xbm
+        :
+   SetEnvIf Referer www\.mydomain\.com intra_site_referral
+        :
+   SetEnvIf object_is_image xbm XBIT_PROCESSING=1
+ 
+
+ +

The first three will set the environment variable + object_is_image if the request was for an image + file, and the fourth sets intra_site_referral if + the referring page was somewhere on the + www.mydomain.com Web site.

+
+ + +

SetEnvIfNoCase + directive

+ +

Syntax: SetEnvIfNoCase + attribute regex env-variable[=value] + [env-variable[=value]] ...
+ Default: none
+ Context: server config, virtual + host, directory, .htaccess
+ Override: FileInfo
+ Status: Base
+ Module: mod_setenvif
+ Compatibility: Apache 1.3 and + above; the Request_Protocol keyword and environment-variable + matching are only available with 1.3.7 and later; use in + .htaccess files only supported with 1.3.13 and later

+ +

The SetEnvIfNoCase is semantically identical to + the SetEnvIf directive, + and differs only in that the regular expression matching is + performed in a case-insensitive manner. For example:

+
+   SetEnvIfNoCase Host Apache\.Org site=apache
+ 
+
+ +

This will cause the site environment variable + to be set to "apache" if the HTTP request header + field Host: was included and contained + Apache.Org, apache.org, or any other + combination.

+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html.html deleted file mode 100644 index 2837e4619b9..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_setenvif.html.html +++ /dev/null @@ -1,341 +0,0 @@ - - - - - - - - Apache module mod_setenvif - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_setenvif

- -

This module provides the ability to set environment - variables based upon attributes of the request.

- -

Status: Base
- Source File: - mod_setenvif.c
- Module Identifier: - setenvif_module
- Compatibility: Available in - Apache 1.3 and later.

- -

Summary

- -

The mod_setenvif module allows you to set - environment variables according to whether different aspects of - the request match regular - expressions you specify. These environment variables can be - used by other parts of the server to make decisions about - actions to be taken.

- -

The directives are considered in the order they appear in - the configuration files. So more complex sequences can be used, - such as this example, which sets netscape if the - browser is mozilla but not MSIE.

- -
-
-  BrowserMatch ^Mozilla netscape
-  BrowserMatch MSIE !netscape
- 
-
-
- -

For additional information, we provide a document on Environment Variables in Apache.

- -

Directives

- - -
- - -

BrowserMatch - directive

- -

Syntax: BrowserMatch regex - env-variable[=value] - [env-variable[=value]] ...
- Default: none
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_setenvif
- Compatibility: Apache 1.2 and - above (in Apache 1.2 this directive was found in the - now-obsolete mod_browser module); use in .htaccess files only - supported with 1.3.13 and later

- -

The BrowserMatch directive defines environment variables - based on the User-Agent HTTP request header field. - The first argument should be a POSIX.2 extended regular - expression (similar to an egrep-style regex). The - rest of the arguments give the names of variables to set, and - optionally values to which they should be set. These take the - form of

- -
    -
  1. varname, or
    2. - -
  2. !varname, or
    3. - -
  3. varname=value
    4. -
- -

In the first form, the value will be set to "1". The second - will remove the given variable if already defined, and the - third will set the variable to the value given by - value. If a User-Agent - string matches more than one entry, they will be merged. - Entries are processed in the order in which they appear, and - later entries can override earlier ones.

- -

For example:

-
-    BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
-    BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
-    BrowserMatch MSIE !javascript
- 
-
- -

Note that the regular expression string is - case-sensitive. For case-INsensitive matching, - see the BrowserMatchNoCase - directive.

- -

The BrowserMatch and - BrowserMatchNoCase directives are special cases of - the SetEnvIf and SetEnvIfNoCase - directives. The following two lines have the same effect:

-
-   BrowserMatchNoCase Robot is_a_robot
-   SetEnvIfNoCase User-Agent Robot is_a_robot
- 
-
-
- - -

BrowserMatchNoCase directive

- -

Syntax: BrowserMatchNoCase - regex env-variable[=value] - [env-variable[=value]] ...
- Default: none
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_setenvif
- Compatibility: Apache 1.2 and - above (in Apache 1.2 this directive was found in the - now-obsolete mod_browser module)

- -

The BrowserMatchNoCase directive is - semantically identical to the BrowserMatch directive. - However, it provides for case-insensitive matching. For - example:

-
-    BrowserMatchNoCase mac platform=macintosh
-    BrowserMatchNoCase win platform=windows
- 
-
- -

The BrowserMatch and - BrowserMatchNoCase directives are special cases of - the SetEnvIf and SetEnvIfNoCase - directives. The following two lines have the same effect:

-
-   BrowserMatchNoCase Robot is_a_robot
-   SetEnvIfNoCase User-Agent Robot is_a_robot
- 
-
-
- - -

SetEnvIf - directive

- -

Syntax: SetEnvIf attribute - regex env-variable[=value] - [env-variable[=value]] ...
- Default: none
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_setenvif
- Compatibility: Apache 1.3 and - above; the Request_Protocol keyword and environment-variable - matching are only available with 1.3.7 and later; use in - .htaccess files only supported with 1.3.13 and later

- -

The SetEnvIf directive defines environment - variables based on attributes of the request. These attributes - can be the values of various HTTP request header fields (see RFC2616 - for more information about these), or of other aspects of the - request, including the following:

- - - -

Some of the more commonly used request header field names - include Host, User-Agent, and - Referer.

- -

If the attribute name doesn't match any of the - special keywords, nor any of the request's header field names, - it is tested as the name of an environment variable in the list - of those associated with the request. This allows - SetEnvIf directives to test against the result of - prior matches.

- -
- Only those environment variables defined by earlier - SetEnvIf[NoCase] directives are available for - testing in this manner. 'Earlier' means that they were - defined at a broader scope (such as server-wide) or - previously in the current directive's scope. -
- -

Example:

-
-   SetEnvIf Request_URI "\.gif$" object_is_image=gif
-   SetEnvIf Request_URI "\.jpg$" object_is_image=jpg
-   SetEnvIf Request_URI "\.xbm$" object_is_image=xbm
-        :
-   SetEnvIf Referer www\.mydomain\.com intra_site_referral
-        :
-   SetEnvIf object_is_image xbm XBIT_PROCESSING=1
- 
-
- -

The first three will set the environment variable - object_is_image if the request was for an image - file, and the fourth sets intra_site_referral if - the referring page was somewhere on the - www.mydomain.com Web site.

-
- - -

SetEnvIfNoCase - directive

- -

Syntax: SetEnvIfNoCase - attribute regex env-variable[=value] - [env-variable[=value]] ...
- Default: none
- Context: server config, virtual - host, directory, .htaccess
- Override: FileInfo
- Status: Base
- Module: mod_setenvif
- Compatibility: Apache 1.3 and - above; the Request_Protocol keyword and environment-variable - matching are only available with 1.3.7 and later; use in - .htaccess files only supported with 1.3.13 and later

- -

The SetEnvIfNoCase is semantically identical to - the SetEnvIf directive, - and differs only in that the regular expression matching is - performed in a case-insensitive manner. For example:

-
-   SetEnvIfNoCase Host Apache\.Org site=apache
- 
-
- -

This will cause the site environment variable - to be set to "apache" if the HTTP request header - field Host: was included and contained - Apache.Org, apache.org, or any other - combination.

-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_so.html b/usr.sbin/httpd/htdocs/manual/mod/mod_so.html new file mode 100644 index 00000000000..21b2835e39a --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_so.html @@ -0,0 +1,205 @@ + + + + + + + + Apache module mod_so + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_so

+ +

This module provides for loading of executable code and + modules into the server at start-up or restart time.

+ +

Status: Base (Windows); + Experimental (Unix)
+ Source File: mod_so.c
+ Module Identifier: + so_module
+ Compatibility: Available in + Apache 1.3 and later.

+ +

Summary

+ +

This is an experimental module. On selected operating + systems it can be used to load modules into Apache at runtime + via the Dynamic Shared Object (DSO) + mechanism, rather than requiring a recompilation.

+ +

On Unix, the loaded code typically comes from shared object + files (usually with .so extension), whilst on + Windows this module loads DLL files. This module + is only available in Apache 1.3 and up.

+ +

In previous releases, the functionality of this module was + provided for Unix by mod_dld, and for Windows by mod_dll. On + Windows, mod_dll was used in beta release 1.3b1 through 1.3b5. + mod_so combines these two modules into a single module for all + operating systems.

+ +

Directives

+ + + +

Creating DLL Modules for + Windows

+ +

The Apache module API is unchanged between the Unix and + Windows versions. Many modules will run on Windows with no or + little change from Unix, although others rely on aspects of the + Unix architecture which are not present in Windows, and will + not work.

+ +

When a module does work, it can be added to the server in + one of two ways. As with Unix, it can be compiled into the + server. Because Apache for Windows does not have the + Configure program of Apache for Unix, the module's + source file must be added to the ApacheCore project file, and + its symbols must be added to the + os\win32\modules.c file.

+ +

The second way is to compile the module as a DLL, a shared + library that can be loaded into the server at runtime, using + the LoadModule + directive. These module DLLs can be distributed and run on any + Apache for Windows installation, without recompilation of the + server.

+ +

To create a module DLL, a small change is necessary to the + module's source file: The module record must be exported from + the DLL (which will be created later; see below). To do this, + add the MODULE_VAR_EXPORT (defined in the Apache + header files) to your module's module record definition. For + example, if your module has:

+
+    module foo_module;
+
+ +

Replace the above with:

+
+    module MODULE_VAR_EXPORT foo_module;
+
+ +

Note that this will only be activated on Windows, so the + module can continue to be used, unchanged, with Unix if needed. + Also, if you are familiar with .DEF files, you can + export the module record with that method instead.

+ +

Now, create a DLL containing your module. You will need to + link this against the ApacheCore.lib export library that is + created when the ApacheCore.dll shared library is compiled. You + may also have to change the compiler settings to ensure that + the Apache header files are correctly located.

+ +

This should create a DLL version of your module. Now simply + place it in the modules directory of your server + root, and use the LoadModule directive to load + it.

+
+ +

LoadFile + directive

+ + Syntax: LoadFile + filename [filename] ...
+ Context: server config
+ Status: Base
+ Module: mod_so + +

The LoadFile directive links in the named object files or + libraries when the server is started or restarted; this is used + to load additional code which may be required for some module + to work. Filename is either an absolute path or + relative to ServerRoot.

+ +

For example:

+ LoadFile libexec/libxmlparse.so + +
+ +

LoadModule + directive

+ + Syntax: LoadModule module + filename
+ Context: server config
+ Status: Base
+ Module: mod_so + +

The LoadModule directive links in the object file or library + filename and adds the module structure named + module to the list of active modules. Module + is the name of the external variable of type + module in the file, and is listed as the Module Identifier + in the module documentation. Example (Unix, and for Windows as + of Apache 1.3.15):

+ +
+ LoadModule status_module modules/mod_status.so +
+ +

Example (Windows prior to Apache 1.3.15, and some 3rd party + modules):

+ +
+ LoadModule foo_module modules/ApacheModuleFoo.dll
+ +
+ +

Note that all modules bundled with the Apache Win32 + binary distribution were renamed as of Apache version + 1.3.15.

+ +

Win32 Apache modules are often distributed with the old + style names, or even a name such as libfoo.dll. Whatever the + name of the module, the LoadModule directive requires the exact + filename, no assumption is made about the filename + extension.

+ +

See also: AddModule and ClearModuleList

+ +
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_so.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_so.html.html deleted file mode 100644 index 21b2835e39a..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_so.html.html +++ /dev/null @@ -1,205 +0,0 @@ - - - - - - - - Apache module mod_so - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_so

- -

This module provides for loading of executable code and - modules into the server at start-up or restart time.

- -

Status: Base (Windows); - Experimental (Unix)
- Source File: mod_so.c
- Module Identifier: - so_module
- Compatibility: Available in - Apache 1.3 and later.

- -

Summary

- -

This is an experimental module. On selected operating - systems it can be used to load modules into Apache at runtime - via the Dynamic Shared Object (DSO) - mechanism, rather than requiring a recompilation.

- -

On Unix, the loaded code typically comes from shared object - files (usually with .so extension), whilst on - Windows this module loads DLL files. This module - is only available in Apache 1.3 and up.

- -

In previous releases, the functionality of this module was - provided for Unix by mod_dld, and for Windows by mod_dll. On - Windows, mod_dll was used in beta release 1.3b1 through 1.3b5. - mod_so combines these two modules into a single module for all - operating systems.

- -

Directives

- - - -

Creating DLL Modules for - Windows

- -

The Apache module API is unchanged between the Unix and - Windows versions. Many modules will run on Windows with no or - little change from Unix, although others rely on aspects of the - Unix architecture which are not present in Windows, and will - not work.

- -

When a module does work, it can be added to the server in - one of two ways. As with Unix, it can be compiled into the - server. Because Apache for Windows does not have the - Configure program of Apache for Unix, the module's - source file must be added to the ApacheCore project file, and - its symbols must be added to the - os\win32\modules.c file.

- -

The second way is to compile the module as a DLL, a shared - library that can be loaded into the server at runtime, using - the LoadModule - directive. These module DLLs can be distributed and run on any - Apache for Windows installation, without recompilation of the - server.

- -

To create a module DLL, a small change is necessary to the - module's source file: The module record must be exported from - the DLL (which will be created later; see below). To do this, - add the MODULE_VAR_EXPORT (defined in the Apache - header files) to your module's module record definition. For - example, if your module has:

-
-    module foo_module;
-
- -

Replace the above with:

-
-    module MODULE_VAR_EXPORT foo_module;
-
- -

Note that this will only be activated on Windows, so the - module can continue to be used, unchanged, with Unix if needed. - Also, if you are familiar with .DEF files, you can - export the module record with that method instead.

- -

Now, create a DLL containing your module. You will need to - link this against the ApacheCore.lib export library that is - created when the ApacheCore.dll shared library is compiled. You - may also have to change the compiler settings to ensure that - the Apache header files are correctly located.

- -

This should create a DLL version of your module. Now simply - place it in the modules directory of your server - root, and use the LoadModule directive to load - it.

-
- -

LoadFile - directive

- - Syntax: LoadFile - filename [filename] ...
- Context: server config
- Status: Base
- Module: mod_so - -

The LoadFile directive links in the named object files or - libraries when the server is started or restarted; this is used - to load additional code which may be required for some module - to work. Filename is either an absolute path or - relative to ServerRoot.

- -

For example:

- LoadFile libexec/libxmlparse.so - -
- -

LoadModule - directive

- - Syntax: LoadModule module - filename
- Context: server config
- Status: Base
- Module: mod_so - -

The LoadModule directive links in the object file or library - filename and adds the module structure named - module to the list of active modules. Module - is the name of the external variable of type - module in the file, and is listed as the Module Identifier - in the module documentation. Example (Unix, and for Windows as - of Apache 1.3.15):

- -
- LoadModule status_module modules/mod_status.so -
- -

Example (Windows prior to Apache 1.3.15, and some 3rd party - modules):

- -
- LoadModule foo_module modules/ApacheModuleFoo.dll
- -
- -

Note that all modules bundled with the Apache Win32 - binary distribution were renamed as of Apache version - 1.3.15.

- -

Win32 Apache modules are often distributed with the old - style names, or even a name such as libfoo.dll. Whatever the - name of the module, the LoadModule directive requires the exact - filename, no assumption is made about the filename - extension.

- -

See also: AddModule and ClearModuleList

- -
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_speling.html b/usr.sbin/httpd/htdocs/manual/mod/mod_speling.html new file mode 100644 index 00000000000..976f046b806 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_speling.html @@ -0,0 +1,137 @@ + + + + + + + + Apache module mod_speling + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_speling

+ +

This module attempts to correct misspellings of URLs that + users might have entered, by ignoring capitalization and by + allowing up to one misspelling.

+ +

Status: Extension
+ Source File: + mod_speling.c
+ Module Identifier: + speling_module
+ Compatibility: Available in + Apache 1.3 and later. Available as an External module in Apache + 1.1 and later.

+ +

Summary

+ +

Requests to documents sometimes cannot be served by the core + apache server because the request was misspelled or + miscapitalized. This module addresses this problem by trying to + find a matching document, even after all other modules gave up. + It does its work by comparing each document name in the + requested directory against the requested document name + without regard to case, and allowing + up to one misspelling (character insertion / + omission / transposition or wrong character). A list is built + with all document names which were matched using this + strategy.

+ +

If, after scanning the directory,

+ + + +

Directives

+ + +
+ + +

CheckSpelling directive

+ + Syntax: CheckSpelling + on|off
+ Default: CheckSpelling + Off
+ Context: server config, virtual + host, directory, .htaccess
+ Override: Options
+ Status: Base
+ Module: mod_speling
+ Compatibility: CheckSpelling + was available as a separately available module for Apache 1.1, + but was limited to miscapitalizations. As of Apache 1.3, it is + part of the Apache distribution. Prior to Apache 1.3.2, the + CheckSpelling directive was only available in the + "server" and "virtual host" contexts. + +

This directive enables or disables the spelling module. When + enabled, keep in mind that

+ + +
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_speling.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_speling.html.html deleted file mode 100644 index 976f046b806..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_speling.html.html +++ /dev/null @@ -1,137 +0,0 @@ - - - - - - - - Apache module mod_speling - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_speling

- -

This module attempts to correct misspellings of URLs that - users might have entered, by ignoring capitalization and by - allowing up to one misspelling.

- -

Status: Extension
- Source File: - mod_speling.c
- Module Identifier: - speling_module
- Compatibility: Available in - Apache 1.3 and later. Available as an External module in Apache - 1.1 and later.

- -

Summary

- -

Requests to documents sometimes cannot be served by the core - apache server because the request was misspelled or - miscapitalized. This module addresses this problem by trying to - find a matching document, even after all other modules gave up. - It does its work by comparing each document name in the - requested directory against the requested document name - without regard to case, and allowing - up to one misspelling (character insertion / - omission / transposition or wrong character). A list is built - with all document names which were matched using this - strategy.

- -

If, after scanning the directory,

- - - -

Directives

- - -
- - -

CheckSpelling directive

- - Syntax: CheckSpelling - on|off
- Default: CheckSpelling - Off
- Context: server config, virtual - host, directory, .htaccess
- Override: Options
- Status: Base
- Module: mod_speling
- Compatibility: CheckSpelling - was available as a separately available module for Apache 1.1, - but was limited to miscapitalizations. As of Apache 1.3, it is - part of the Apache distribution. Prior to Apache 1.3.2, the - CheckSpelling directive was only available in the - "server" and "virtual host" contexts. - -

This directive enables or disables the spelling module. When - enabled, keep in mind that

- - -
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html b/usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html new file mode 100644 index 00000000000..3f7b31a700a --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html @@ -0,0 +1,220 @@ + + + + + + + + Apache module mod_unique_id + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_unique_id

+ +

This module provides an environment variable with a unique + identifier for each request.

+ +

Status: Extension
+ Source File: + mod_unique_id.c
+ Module Identifier: + unique_id_module
+ Compatibility: Available in + Apache 1.3 and later.

+ +

Summary

+ +

This module provides a magic token for each request which is + guaranteed to be unique across "all" requests under very + specific conditions. The unique identifier is even unique + across multiple machines in a properly configured cluster of + machines. The environment variable UNIQUE_ID is + set to the identifier for each request. Unique identifiers are + useful for various reasons which are beyond the scope of this + document.

+ +

Directives

+ +

This module has no directives.

+ +

Theory

+ +

First a brief recap of how the Apache server works on Unix + machines. On Unix machines, Apache creates several children, + the children process requests one at a time. Each child can + serve multiple requests in its lifetime. For the purpose of + this discussion, the children don't share any data with each + other. We'll refer to the children as httpd processes.

+ +

Your website has one or more machines under your + administrative control, together we'll call them a cluster of + machines. Each machine can possibly run multiple instances of + Apache. All of these collectively are considered "the + universe", and with certain assumptions we'll show that in this + universe we can generate unique identifiers for each request, + without extensive communication between machines in the + cluster.

+ +

The machines in your cluster should satisfy these + requirements. (Even if you have only one machine you should + synchronize its clock with NTP.)

+ + + +

As far as operating system assumptions go, we assume that + pids (process ids) fit in 32-bits. If the operating system uses + more than 32-bits for a pid, the fix is trivial but must be + performed in the code.

+ +

Given those assumptions, at a single point in time we can + identify any httpd process on any machine in the cluster from + all other httpd processes. The machine's IP address and the pid + of the httpd process are sufficient to do this. So in order to + generate unique identifiers for requests we need only + distinguish between different points in time.

+ +

To distinguish time we will use a Unix timestamp (seconds + since January 1, 1970 UTC), and a 16-bit counter. The timestamp + has only one second granularity, so the counter is used to + represent up to 65536 values during a single second. The + quadruple ( ip_addr, pid, time_stamp, counter ) is + sufficient to enumerate 65536 requests per second per httpd + process. There are issues however with pid reuse over time, and + the counter is used to alleviate this issue.

+ +

When an httpd child is created, the counter is initialized + with ( current microseconds divided by 10 ) modulo 65536 (this + formula was chosen to eliminate some variance problems with the + low order bits of the microsecond timers on some systems). When + a unique identifier is generated, the time stamp used is the + time the request arrived at the web server. The counter is + incremented every time an identifier is generated (and allowed + to roll over).

+ +

The kernel generates a pid for each process as it forks the + process, and pids are allowed to roll over (they're 16-bits on + many Unixes, but newer systems have expanded to 32-bits). So + over time the same pid will be reused. However unless it is + reused within the same second, it does not destroy the + uniqueness of our quadruple. That is, we assume the system does + not spawn 65536 processes in a one second interval (it may even + be 32768 processes on some Unixes, but even this isn't likely + to happen).

+ +

Suppose that time repeats itself for some reason. That is, + suppose that the system's clock is screwed up and it revisits a + past time (or it is too far forward, is reset correctly, and + then revisits the future time). In this case we can easily show + that we can get pid and time stamp reuse. The choice of + initializer for the counter is intended to help defeat this. + Note that we really want a random number to initialize the + counter, but there aren't any readily available numbers on most + systems (i.e., you can't use rand() because you need + to seed the generator, and can't seed it with the time because + time, at least at one second resolution, has repeated itself). + This is not a perfect defense.

+ +

How good a defense is it? Suppose that one of your machines + serves at most 500 requests per second (which is a very + reasonable upper bound at this writing, because systems + generally do more than just shovel out static files). To do + that it will require a number of children which depends on how + many concurrent clients you have. But we'll be pessimistic and + suppose that a single child is able to serve 500 requests per + second. There are 1000 possible starting counter values such + that two sequences of 500 requests overlap. So there is a 1.5% + chance that if time (at one second resolution) repeats itself + this child will repeat a counter value, and uniqueness will be + broken. This was a very pessimistic example, and with real + world values it's even less likely to occur. If your system is + such that it's still likely to occur, then perhaps you should + make the counter 32 bits (by editing the code).

+ +

You may be concerned about the clock being "set back" during + summer daylight savings. However this isn't an issue because + the times used here are UTC, which "always" go forward. Note + that x86 based Unixes may need proper configuration for this to + be true -- they should be configured to assume that the + motherboard clock is on UTC and compensate appropriately. But + even still, if you're running NTP then your UTC time will be + correct very shortly after reboot.

+ +

The UNIQUE_ID environment variable is + constructed by encoding the 112-bit (32-bit IP address, 32 bit + pid, 32 bit time stamp, 16 bit counter) quadruple using the + alphabet [A-Za-z0-9@-] in a manner similar to MIME + base64 encoding, producing 19 characters. The MIME base64 + alphabet is actually [A-Za-z0-9+/] however + + and / need to be specially encoded + in URLs, which makes them less desirable. All values are + encoded in network byte ordering so that the encoding is + comparable across architectures of different byte ordering. The + actual ordering of the encoding is: time stamp, IP address, + pid, counter. This ordering has a purpose, but it should be + emphasized that applications should not dissect the encoding. + Applications should treat the entire encoded + UNIQUE_ID as an opaque token, which can be + compared against other UNIQUE_IDs for equality + only.

+ +

The ordering was chosen such that it's possible to change + the encoding in the future without worrying about collision + with an existing database of UNIQUE_IDs. The new + encodings should also keep the time stamp as the first element, + and can otherwise use the same alphabet and bit length. Since + the time stamps are essentially an increasing sequence, it's + sufficient to have a flag second in which all machines + in the cluster stop serving and request, and stop using the old + encoding format. Afterwards they can resume requests and begin + issuing the new encodings.

+ +

This is a relatively portable solution. It is extended to + multithreaded systems like Windows NT, which add the thread-id + to the ID, producing a 144-bit (including 32-bit tid) quadruple + that generates a 24 character UNIQUE_ID value. The identifiers + generated have essentially an infinite life-time because future + identifiers can be made longer as required. Essentially no + communication is required between machines in the cluster (only + NTP synchronization is required, which is low overhead), and no + communication between httpd processes is required (the + communication is implicit in the pid value assigned by the + kernel). In very specific situations the identifier can be + shortened, but more information needs to be assumed (for + example the 32-bit IP address is overkill for any site, but + there is no portable shorter replacement for it). This module + may be extended to include an entire IPv6 address, but that is + overkill for nearly all server configurations. +

+ +

Apache HTTP Server Version 1.3

+ Index + Home + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html.html deleted file mode 100644 index 3f7b31a700a..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_unique_id.html.html +++ /dev/null @@ -1,220 +0,0 @@ - - - - - - - - Apache module mod_unique_id - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_unique_id

- -

This module provides an environment variable with a unique - identifier for each request.

- -

Status: Extension
- Source File: - mod_unique_id.c
- Module Identifier: - unique_id_module
- Compatibility: Available in - Apache 1.3 and later.

- -

Summary

- -

This module provides a magic token for each request which is - guaranteed to be unique across "all" requests under very - specific conditions. The unique identifier is even unique - across multiple machines in a properly configured cluster of - machines. The environment variable UNIQUE_ID is - set to the identifier for each request. Unique identifiers are - useful for various reasons which are beyond the scope of this - document.

- -

Directives

- -

This module has no directives.

- -

Theory

- -

First a brief recap of how the Apache server works on Unix - machines. On Unix machines, Apache creates several children, - the children process requests one at a time. Each child can - serve multiple requests in its lifetime. For the purpose of - this discussion, the children don't share any data with each - other. We'll refer to the children as httpd processes.

- -

Your website has one or more machines under your - administrative control, together we'll call them a cluster of - machines. Each machine can possibly run multiple instances of - Apache. All of these collectively are considered "the - universe", and with certain assumptions we'll show that in this - universe we can generate unique identifiers for each request, - without extensive communication between machines in the - cluster.

- -

The machines in your cluster should satisfy these - requirements. (Even if you have only one machine you should - synchronize its clock with NTP.)

- - - -

As far as operating system assumptions go, we assume that - pids (process ids) fit in 32-bits. If the operating system uses - more than 32-bits for a pid, the fix is trivial but must be - performed in the code.

- -

Given those assumptions, at a single point in time we can - identify any httpd process on any machine in the cluster from - all other httpd processes. The machine's IP address and the pid - of the httpd process are sufficient to do this. So in order to - generate unique identifiers for requests we need only - distinguish between different points in time.

- -

To distinguish time we will use a Unix timestamp (seconds - since January 1, 1970 UTC), and a 16-bit counter. The timestamp - has only one second granularity, so the counter is used to - represent up to 65536 values during a single second. The - quadruple ( ip_addr, pid, time_stamp, counter ) is - sufficient to enumerate 65536 requests per second per httpd - process. There are issues however with pid reuse over time, and - the counter is used to alleviate this issue.

- -

When an httpd child is created, the counter is initialized - with ( current microseconds divided by 10 ) modulo 65536 (this - formula was chosen to eliminate some variance problems with the - low order bits of the microsecond timers on some systems). When - a unique identifier is generated, the time stamp used is the - time the request arrived at the web server. The counter is - incremented every time an identifier is generated (and allowed - to roll over).

- -

The kernel generates a pid for each process as it forks the - process, and pids are allowed to roll over (they're 16-bits on - many Unixes, but newer systems have expanded to 32-bits). So - over time the same pid will be reused. However unless it is - reused within the same second, it does not destroy the - uniqueness of our quadruple. That is, we assume the system does - not spawn 65536 processes in a one second interval (it may even - be 32768 processes on some Unixes, but even this isn't likely - to happen).

- -

Suppose that time repeats itself for some reason. That is, - suppose that the system's clock is screwed up and it revisits a - past time (or it is too far forward, is reset correctly, and - then revisits the future time). In this case we can easily show - that we can get pid and time stamp reuse. The choice of - initializer for the counter is intended to help defeat this. - Note that we really want a random number to initialize the - counter, but there aren't any readily available numbers on most - systems (i.e., you can't use rand() because you need - to seed the generator, and can't seed it with the time because - time, at least at one second resolution, has repeated itself). - This is not a perfect defense.

- -

How good a defense is it? Suppose that one of your machines - serves at most 500 requests per second (which is a very - reasonable upper bound at this writing, because systems - generally do more than just shovel out static files). To do - that it will require a number of children which depends on how - many concurrent clients you have. But we'll be pessimistic and - suppose that a single child is able to serve 500 requests per - second. There are 1000 possible starting counter values such - that two sequences of 500 requests overlap. So there is a 1.5% - chance that if time (at one second resolution) repeats itself - this child will repeat a counter value, and uniqueness will be - broken. This was a very pessimistic example, and with real - world values it's even less likely to occur. If your system is - such that it's still likely to occur, then perhaps you should - make the counter 32 bits (by editing the code).

- -

You may be concerned about the clock being "set back" during - summer daylight savings. However this isn't an issue because - the times used here are UTC, which "always" go forward. Note - that x86 based Unixes may need proper configuration for this to - be true -- they should be configured to assume that the - motherboard clock is on UTC and compensate appropriately. But - even still, if you're running NTP then your UTC time will be - correct very shortly after reboot.

- -

The UNIQUE_ID environment variable is - constructed by encoding the 112-bit (32-bit IP address, 32 bit - pid, 32 bit time stamp, 16 bit counter) quadruple using the - alphabet [A-Za-z0-9@-] in a manner similar to MIME - base64 encoding, producing 19 characters. The MIME base64 - alphabet is actually [A-Za-z0-9+/] however - + and / need to be specially encoded - in URLs, which makes them less desirable. All values are - encoded in network byte ordering so that the encoding is - comparable across architectures of different byte ordering. The - actual ordering of the encoding is: time stamp, IP address, - pid, counter. This ordering has a purpose, but it should be - emphasized that applications should not dissect the encoding. - Applications should treat the entire encoded - UNIQUE_ID as an opaque token, which can be - compared against other UNIQUE_IDs for equality - only.

- -

The ordering was chosen such that it's possible to change - the encoding in the future without worrying about collision - with an existing database of UNIQUE_IDs. The new - encodings should also keep the time stamp as the first element, - and can otherwise use the same alphabet and bit length. Since - the time stamps are essentially an increasing sequence, it's - sufficient to have a flag second in which all machines - in the cluster stop serving and request, and stop using the old - encoding format. Afterwards they can resume requests and begin - issuing the new encodings.

- -

This is a relatively portable solution. It is extended to - multithreaded systems like Windows NT, which add the thread-id - to the ID, producing a 144-bit (including 32-bit tid) quadruple - that generates a 24 character UNIQUE_ID value. The identifiers - generated have essentially an infinite life-time because future - identifiers can be made longer as required. Essentially no - communication is required between machines in the cluster (only - NTP synchronization is required, which is low overhead), and no - communication between httpd processes is required (the - communication is implicit in the pid value assigned by the - kernel). In very specific situations the identifier can be - shortened, but more information needs to be assumed (for - example the 32-bit IP address is overkill for any site, but - there is no portable shorter replacement for it). This module - may be extended to include an entire IPv6 address, but that is - overkill for nearly all server configurations. -

- -

Apache HTTP Server Version 1.3

- Index - Home - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html b/usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html new file mode 100644 index 00000000000..b896dffb0ef --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html @@ -0,0 +1,154 @@ + + + + + + + + Apache module mod_userdir + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Module mod_userdir

+ +

This module provides for user-specific directories.

+ +

Status: Base
+ Source File: + mod_userdir.c
+ Module Identifier: + userdir_module

+ +

Directives

+ + +
+ +

UserDir directive

+ + 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. Use of the enabled keyword, + or disabled with a list of usernames, is only + available in Apache 1.3 and above. + +

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-filename is one of the + following:

+ + + +

If neither the enabled nor the + disabled keywords appear in the + Userdir directive, the argument is treated as a + filename pattern, and is used to turn the name into a directory + specification. 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
+
+ +
+ Be careful when using this directive; for instance, + "UserDir ./" would map + "/~root" to "/" - which is probably + undesirable. If you are running Apache 1.3 or above, it is + strongly recommended that your configuration include a + "UserDir disabled root" declaration. + See also the <Directory> directive + and the Security + Tips page for more information. +
+ +

Additional examples:

+ +

To allow a few users to have UserDir directories, but +not anyone else, use the following:

+ +
+UserDir disabled
+UserDir enabled user1 user2 user3
+
+ +

To allow most users to have UserDir directories, but +deny this to a few, use the following:

+ +
+UserDir enabled
+UserDir disabled user4 user5 user6
+
+ +
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html.html b/usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html.html deleted file mode 100644 index b896dffb0ef..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html.html +++ /dev/null @@ -1,154 +0,0 @@ - - - - - - - - Apache module mod_userdir - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Module mod_userdir

- -

This module provides for user-specific directories.

- -

Status: Base
- Source File: - mod_userdir.c
- Module Identifier: - userdir_module

- -

Directives

- - -
- -

UserDir directive

- - 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. Use of the enabled keyword, - or disabled with a list of usernames, is only - available in Apache 1.3 and above. - -

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-filename is one of the - following:

- - - -

If neither the enabled nor the - disabled keywords appear in the - Userdir directive, the argument is treated as a - filename pattern, and is used to turn the name into a directory - specification. 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
-
- -
- Be careful when using this directive; for instance, - "UserDir ./" would map - "/~root" to "/" - which is probably - undesirable. If you are running Apache 1.3 or above, it is - strongly recommended that your configuration include a - "UserDir disabled root" declaration. - See also the <Directory> directive - and the Security - Tips page for more information. -
- -

Additional examples:

- -

To allow a few users to have UserDir directories, but -not anyone else, use the following:

- -
-UserDir disabled
-UserDir enabled user1 user2 user3
-
- -

To allow most users to have UserDir directories, but -deny this to a few, use the following:

- -
-UserDir enabled
-UserDir disabled user4 user5 user6
-
- -
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/module-dict.html b/usr.sbin/httpd/htdocs/manual/mod/module-dict.html new file mode 100644 index 00000000000..0d04a540cae --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/module-dict.html @@ -0,0 +1,129 @@ + + + + + + + + Definitions of terms used to describe Apache + modules + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Terms Used to Describe Apache Modules

+ +

Each Apache module is described using a common format that + looks like this:

+ +
+
Status: + status
+ Source + File: source-file
+ Module + Identifier: module-identifier
+ Compatibility: + compatibility notes
+
+ +

Each of the attributes, complete with values where possible, + are described in this document.

+ +

Module Terms

+ + +
+ +

Status

+ +

This indicates how tightly bound into the Apache Web server + the module is; in other words, you may need to recompile the + server in order to gain access to the module and its + functionality. Possible values for this attribute are:

+ +
+
Base
+ +
A module labeled as having "Base" status is compiled and + loaded into the server by default, and is therefore normally + available unless you have taken steps to remove the module + from your configuration.
+ +
Extension
+ +
A module with "Extension" status is not normally compiled + and loaded into the server. To enable the module and its + functionality, you may need to change the server build + configuration files and re-compile Apache.
+ +
Experimental
+ +
"Experimental" status indicates that the module is + available as part of the Apache kit, but you are on your own + if you try to use it. The module is being documented for + completeness, and is not necessarily supported.
+ +
External
+ +
Modules which are not included with the base Apache + distribution ("third-party modules") may use the "External" + status. We are not responsible, nor do we support such + modules.
+
+
+ +

Source File

+ +

This quite simply lists the name of the source file which + contains the code for the module. This is also the name used by + the <IfModule> + directive.

+
+ +

Module + Identifier

+ +

This is a string which identifies the module for use in the + LoadModule directive when + dynamically loading modules. In particular, it is the name of + the external variable of type module in the source file.

+
+ +

Compatibility

+ +

If the module was not part of the original Apache version 1 + distribution, the version in which it was introduced should be + listed here.

+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/module-dict.html.html b/usr.sbin/httpd/htdocs/manual/mod/module-dict.html.html deleted file mode 100644 index 0d04a540cae..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/module-dict.html.html +++ /dev/null @@ -1,129 +0,0 @@ - - - - - - - - Definitions of terms used to describe Apache - modules - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Terms Used to Describe Apache Modules

- -

Each Apache module is described using a common format that - looks like this:

- -
-
Status: - status
- Source - File: source-file
- Module - Identifier: module-identifier
- Compatibility: - compatibility notes
-
- -

Each of the attributes, complete with values where possible, - are described in this document.

- -

Module Terms

- - -
- -

Status

- -

This indicates how tightly bound into the Apache Web server - the module is; in other words, you may need to recompile the - server in order to gain access to the module and its - functionality. Possible values for this attribute are:

- -
-
Base
- -
A module labeled as having "Base" status is compiled and - loaded into the server by default, and is therefore normally - available unless you have taken steps to remove the module - from your configuration.
- -
Extension
- -
A module with "Extension" status is not normally compiled - and loaded into the server. To enable the module and its - functionality, you may need to change the server build - configuration files and re-compile Apache.
- -
Experimental
- -
"Experimental" status indicates that the module is - available as part of the Apache kit, but you are on your own - if you try to use it. The module is being documented for - completeness, and is not necessarily supported.
- -
External
- -
Modules which are not included with the base Apache - distribution ("third-party modules") may use the "External" - status. We are not responsible, nor do we support such - modules.
-
-
- -

Source File

- -

This quite simply lists the name of the source file which - contains the code for the module. This is also the name used by - the <IfModule> - directive.

-
- -

Module - Identifier

- -

This is a string which identifies the module for use in the - LoadModule directive when - dynamically loading modules. In particular, it is the name of - the external variable of type module in the source file.

-
- -

Compatibility

- -

If the module was not part of the original Apache version 1 - distribution, the version in which it was introduced should be - listed here.

-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/process-model.html b/usr.sbin/httpd/htdocs/manual/process-model.html new file mode 100644 index 00000000000..d26fe3cee9d --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/process-model.html @@ -0,0 +1,81 @@ + + + + + + + + Server Pool Management + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Server Pool Management

+
+ +

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:

+
+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. + +

In versions before 1.2, HARD_SERVER_LIMIT defaulted to + 150.

+ +

We do not recommend changing either of these values + unless:

+ +
    +
  1. You know you have the server resources to handle + more
    2. + +
  2. You use the machine for other purposes and must limit the + amount of memory Apache uses
    3. +
+
+ +

Apache HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/process-model.html.html b/usr.sbin/httpd/htdocs/manual/process-model.html.html deleted file mode 100644 index d26fe3cee9d..00000000000 --- a/usr.sbin/httpd/htdocs/manual/process-model.html.html +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - - - Server Pool Management - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Server Pool Management

-
- -

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:

-
-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. - -

In versions before 1.2, HARD_SERVER_LIMIT defaulted to - 150.

- -

We do not recommend changing either of these values - unless:

- -
    -
  1. You know you have the server resources to handle - more
    2. - -
  2. You use the machine for other purposes and must limit the - amount of memory Apache uses
    3. -
-
- -

Apache HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/programs/apachectl.html b/usr.sbin/httpd/htdocs/manual/programs/apachectl.html new file mode 100644 index 00000000000..ef67f594b81 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/programs/apachectl.html @@ -0,0 +1,110 @@ + + + + + + + + Manual Page: apachectl - Apache HTTP Server + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Manual Page: apachectl

+ +
+NAME
+     apachectl - Apache HTTP server control interface
+
+SYNOPSIS
+     apachectl command [...]
+
+DESCRIPTION
+     apachectl is a front end to the  Apache  HyperText  Transfer
+     Protocol (HTTP) server.  It is designed to help the adminis-
+     trator control the functioning of the Apache httpd daemon.
+
+     NOTE: If your Apache installation uses  non-standard  paths,
+     you  will  need  to  edit  the  apachectl  script to set the
+     appropriate paths to your PID file and  your  httpd  binary.
+     See the comments in the script for details.
+
+     The apachectl script returns a 0 exit value on success,  and
+     >0  if an error occurs.  For more details, view the comments
+     in the script.
+
+     Full   documentation   for   Apache    is    available    at
+     http://www.apache.org/
+
+OPTIONS
+     The command can be any one or more of the following options:
+
+     start       Start the Apache daemon.  Gives an error  if  it
+                 is already running.
+
+     stop        Stops the Apache daemon.
+
+     restart     Restarts the  Apache  daemon  by  sending  it  a
+                 SIGHUP.   If  the  daemon  is not running, it is
+                 started.  This command automatically checks  the
+                 configuration  files  via configtest before ini-
+                 tiating the restart to make sure Apache  doesn't
+                 die.
+
+     fullstatus  Displays a full status report  from  mod_status.
+                 For  this  to  work, you need to have mod_status
+                 enabled on your server and a text-based  browser
+                 such  as lynx available on your system.  The URL
+                 used to access the status report can be  set  by
+                 editing the STATUSURL variable in the script.
+
+     status      Displays a brief status report.  Similar to  the
+                 fullstatus  option,  except  that  the  list  of
+                 requests currently being served is omitted.
+
+     graceful    Gracefully restarts the Apache daemon by sending
+                 it  a SIGUSR1.  If the daemon is not running, it
+                 is started.  This differs from a normal  restart
+                 in  that  currently  open  connections  are  not
+                 aborted.  A side effect is that  old  log  files
+                 will not be closed immediately.  This means that
+                 if used in a log rotation script, a  substantial
+                 delay  may  be  necessary to ensure that the old
+                 log files are  closed  before  processing  them.
+                 This command automatically checks the configura-
+                 tion files via configtest before initiating  the
+                 restart to make sure Apache doesn't die.
+
+     configtest  Run a configuration file syntax test. It  parses
+                 the  configuration files and either reports Syn-
+                 tax Ok or detailed information about the partic-
+                 ular syntax error.
+
+     help        Displays a short help message.
+
+SEE ALSO
+     httpd(8)
+
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/programs/apachectl.html.html b/usr.sbin/httpd/htdocs/manual/programs/apachectl.html.html deleted file mode 100644 index ef67f594b81..00000000000 --- a/usr.sbin/httpd/htdocs/manual/programs/apachectl.html.html +++ /dev/null @@ -1,110 +0,0 @@ - - - - - - - - Manual Page: apachectl - Apache HTTP Server - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Manual Page: apachectl

- -
-NAME
-     apachectl - Apache HTTP server control interface
-
-SYNOPSIS
-     apachectl command [...]
-
-DESCRIPTION
-     apachectl is a front end to the  Apache  HyperText  Transfer
-     Protocol (HTTP) server.  It is designed to help the adminis-
-     trator control the functioning of the Apache httpd daemon.
-
-     NOTE: If your Apache installation uses  non-standard  paths,
-     you  will  need  to  edit  the  apachectl  script to set the
-     appropriate paths to your PID file and  your  httpd  binary.
-     See the comments in the script for details.
-
-     The apachectl script returns a 0 exit value on success,  and
-     >0  if an error occurs.  For more details, view the comments
-     in the script.
-
-     Full   documentation   for   Apache    is    available    at
-     http://www.apache.org/
-
-OPTIONS
-     The command can be any one or more of the following options:
-
-     start       Start the Apache daemon.  Gives an error  if  it
-                 is already running.
-
-     stop        Stops the Apache daemon.
-
-     restart     Restarts the  Apache  daemon  by  sending  it  a
-                 SIGHUP.   If  the  daemon  is not running, it is
-                 started.  This command automatically checks  the
-                 configuration  files  via configtest before ini-
-                 tiating the restart to make sure Apache  doesn't
-                 die.
-
-     fullstatus  Displays a full status report  from  mod_status.
-                 For  this  to  work, you need to have mod_status
-                 enabled on your server and a text-based  browser
-                 such  as lynx available on your system.  The URL
-                 used to access the status report can be  set  by
-                 editing the STATUSURL variable in the script.
-
-     status      Displays a brief status report.  Similar to  the
-                 fullstatus  option,  except  that  the  list  of
-                 requests currently being served is omitted.
-
-     graceful    Gracefully restarts the Apache daemon by sending
-                 it  a SIGUSR1.  If the daemon is not running, it
-                 is started.  This differs from a normal  restart
-                 in  that  currently  open  connections  are  not
-                 aborted.  A side effect is that  old  log  files
-                 will not be closed immediately.  This means that
-                 if used in a log rotation script, a  substantial
-                 delay  may  be  necessary to ensure that the old
-                 log files are  closed  before  processing  them.
-                 This command automatically checks the configura-
-                 tion files via configtest before initiating  the
-                 restart to make sure Apache doesn't die.
-
-     configtest  Run a configuration file syntax test. It  parses
-                 the  configuration files and either reports Syn-
-                 tax Ok or detailed information about the partic-
-                 ular syntax error.
-
-     help        Displays a short help message.
-
-SEE ALSO
-     httpd(8)
-
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/programs/htpasswd.html b/usr.sbin/httpd/htdocs/manual/programs/htpasswd.html new file mode 100644 index 00000000000..90086a0b833 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/programs/htpasswd.html @@ -0,0 +1,189 @@ + + + + + + + + Manual Page: htpasswd - Apache HTTP Server + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Manual Page: htpasswd

+ +
+NAME
+     htpasswd - Create and update user authentication files
+
+SYNOPSIS
+     htpasswd [ -c ] [ -m | -d | -s | -p ] passwdfile username
+     htpasswd -b [ -c ] [ -m | -d | -s | -p ] passwdfile username
+     password
+     htpasswd -n [ -m | -d | -s | -p ] username
+     htpasswd -nb [ -m | -d | -s | -p ] username password
+
+DESCRIPTION
+     htpasswd is used to create and update the flat-files used to
+     store  usernames  and  password  for basic authentication of
+     HTTP users.  If htpasswd cannot access a file, such  as  not
+     being  able to write to the output file or not being able to
+     read the file in order to update it,  it  returns  an  error
+     status and makes no changes.
+
+     Resources available from the httpd Apache web server can  be
+     restricted  to just the users listed in the files created by
+     htpasswd. This program can only manage usernames  and  pass-
+     words  stored  in  a  flat-file.  It can encrypt and display
+     password information for use in other types of data  stores,
+     though.  To use a DBM database see dbmmanage.
+
+     htpasswd encrypts passwords using either a  version  of  MD5
+     modified for Apache, or the system's crypt() routine.  Files
+     managed by htpasswd may contain  both  types  of  passwords;
+     some  user  records  may  have MD5-encrypted passwords while
+     others in the same file may have  passwords  encrypted  with
+     crypt().
+
+     This manual page only lists the command line arguments.  For
+     details  of  the  directives  necessary  to  configure  user
+     authentication in httpd see the Apache manual, which is part
+     of   the   Apache   distribution   or   can   be   found  at
+     <URL:http://www.apache.org/>.
+
+OPTIONS
+     -b   Use batch mode; i.e., get the password from the command
+          line  rather  than prompting for it. This option should
+          be used  with  extreme  care,  since  the  password  is
+          clearly visible on the command line.
+
+     -c   Create the passwdfile. If passwdfile already exists, it
+          is rewritten and truncated.  This option cannot be com-
+          bined with the -n option.
+
+     -n   Display the results  on  standard  output  rather  than
+          updating  a  file.  This is useful for generating pass-
+          word records acceptable  to  Apache  for  inclusion  in
+          non-text  data  stores.  This option changes the syntax
+          of the command  line,  since  the  passwdfile  argument
+          (usually  the first one) is omitted.  It cannot be com-
+          bined with the -c option.
+
+     -m   Use Apache's  modified  MD5  algorithm  for  passwords.
+          Passwords  encrypted with this algorithm are transport-
+          able to any platform (Windows, Unix, BeOS,  et  cetera)
+          running  Apache  1.3.9  or  later.  On Windows and TPF,
+          this flag is the default.
+
+     -d   Use crypt() encryption for passwords.  The  default  on
+          all platforms but Windows and TPF. Though possibly sup-
+          ported by htpasswd on all platforms,  it  is  not  sup-
+          ported by the httpd server on Windows and TPF.
+
+     -s   Use SHA encryption for passwords. Faciliates  migration
+          from/to  Netscape  servers  using  the  LDAP  Directory
+          Interchange Format (ldif).
+
+     -p   Use plaintext passwords. Though htpasswd  will  support
+          creation  on  all platforms, the httpd deamon will only
+          accept plain text passwords on Windows and TPF.
+
+     passwdfile
+          Name of the file to contain the user name and password.
+          If  -c  is  given,  this file is created if it does not
+          already exist, or rewritten and truncated  if  it  does
+          exist.
+
+     username
+          The username to create  or  update  in  passwdfile.  If
+          username  does  not  exist  in  this  file, an entry is
+          added. If it does exist, the password is changed.
+
+     password
+          The plaintext password to be encrypted  and  stored  in
+          the file.  Only used with the -b flag.
+
+EXIT STATUS
+     htpasswd returns a zero status ("true") if the username  and
+     password  have  been  successfully  added  or updated in the
+     passwdfile.  htpasswd returns 1 if it encounters some  prob-
+     lem  accessing  files,  2 if there was a syntax problem with
+     the command line, 3 if the  password  was  entered  interac-
+     tively  and  the  verification  entry didn't match, 4 if its
+     operation was interrupted, 5 if a value is too  long  (user-
+     name,  filename,  password, or final computed record), and 6
+     if the username contains illegal characters  (see  the  RES-
+     TRICTIONS section).
+
+EXAMPLES
+     htpasswd /usr/local/etc/apache/.htpasswd-users jsmith
+
+          Adds or modifies the password for user jsmith. The user
+          is prompted for the password.  If executed on a Windows
+          system, the password will be encrypted using the  modi-
+          fied  Apache  MD5  algorithm;  otherwise,  the system's
+          crypt() routine will be used.  If  the  file  does  not
+          exist, htpasswd will do nothing except return an error.
+
+     htpasswd -c /home/doe/public_html/.htpasswd jane
+
+          Creates a new file and stores a record in it  for  user
+          jane.   The  user is prompted for the password.  If the
+          file exists and cannot be read, or cannot  be  written,
+          it  is  not altered and htpasswd will display a message
+          and return an error status.
+
+     htpasswd -mb /usr/web/.htpasswd-all jones Pwd4Steve
+
+          Encrypts the password from the command line (Pwd4Steve)
+          using the MD5 algorithm, and stores it in the specified
+          file.
+
+SECURITY CONSIDERATIONS
+     Web password files such as those managed by htpasswd  should
+     not  be  within  the Web server's URI space -- that is, they
+     should not be fetchable with a browser.
+
+     The use of the -b option is discouraged, since  when  it  is
+     used the unencrypted password appears on the command line.
+
+RESTRICTIONS
+     On the Windows and MPE platforms, passwords  encrypted  with
+     htpasswd  are  limited  to  no  more  than 255 characters in
+     length.  Longer passwords will be truncated to  255  charac-
+     ters.
+
+     The MD5 algorithm used by htpasswd is specific to the Apache
+     software;  passwords  encrypted  using it will not be usable
+     with other Web servers.
+
+     Usernames are limited to 255 bytes and may not  include  the
+     character ':'.
+
+SEE ALSO
+     httpd(8) and the scripts in support/SHA1 which come with the
+     distribution.
+
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/programs/htpasswd.html.html b/usr.sbin/httpd/htdocs/manual/programs/htpasswd.html.html deleted file mode 100644 index 90086a0b833..00000000000 --- a/usr.sbin/httpd/htdocs/manual/programs/htpasswd.html.html +++ /dev/null @@ -1,189 +0,0 @@ - - - - - - - - Manual Page: htpasswd - Apache HTTP Server - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Manual Page: htpasswd

- -
-NAME
-     htpasswd - Create and update user authentication files
-
-SYNOPSIS
-     htpasswd [ -c ] [ -m | -d | -s | -p ] passwdfile username
-     htpasswd -b [ -c ] [ -m | -d | -s | -p ] passwdfile username
-     password
-     htpasswd -n [ -m | -d | -s | -p ] username
-     htpasswd -nb [ -m | -d | -s | -p ] username password
-
-DESCRIPTION
-     htpasswd is used to create and update the flat-files used to
-     store  usernames  and  password  for basic authentication of
-     HTTP users.  If htpasswd cannot access a file, such  as  not
-     being  able to write to the output file or not being able to
-     read the file in order to update it,  it  returns  an  error
-     status and makes no changes.
-
-     Resources available from the httpd Apache web server can  be
-     restricted  to just the users listed in the files created by
-     htpasswd. This program can only manage usernames  and  pass-
-     words  stored  in  a  flat-file.  It can encrypt and display
-     password information for use in other types of data  stores,
-     though.  To use a DBM database see dbmmanage.
-
-     htpasswd encrypts passwords using either a  version  of  MD5
-     modified for Apache, or the system's crypt() routine.  Files
-     managed by htpasswd may contain  both  types  of  passwords;
-     some  user  records  may  have MD5-encrypted passwords while
-     others in the same file may have  passwords  encrypted  with
-     crypt().
-
-     This manual page only lists the command line arguments.  For
-     details  of  the  directives  necessary  to  configure  user
-     authentication in httpd see the Apache manual, which is part
-     of   the   Apache   distribution   or   can   be   found  at
-     <URL:http://www.apache.org/>.
-
-OPTIONS
-     -b   Use batch mode; i.e., get the password from the command
-          line  rather  than prompting for it. This option should
-          be used  with  extreme  care,  since  the  password  is
-          clearly visible on the command line.
-
-     -c   Create the passwdfile. If passwdfile already exists, it
-          is rewritten and truncated.  This option cannot be com-
-          bined with the -n option.
-
-     -n   Display the results  on  standard  output  rather  than
-          updating  a  file.  This is useful for generating pass-
-          word records acceptable  to  Apache  for  inclusion  in
-          non-text  data  stores.  This option changes the syntax
-          of the command  line,  since  the  passwdfile  argument
-          (usually  the first one) is omitted.  It cannot be com-
-          bined with the -c option.
-
-     -m   Use Apache's  modified  MD5  algorithm  for  passwords.
-          Passwords  encrypted with this algorithm are transport-
-          able to any platform (Windows, Unix, BeOS,  et  cetera)
-          running  Apache  1.3.9  or  later.  On Windows and TPF,
-          this flag is the default.
-
-     -d   Use crypt() encryption for passwords.  The  default  on
-          all platforms but Windows and TPF. Though possibly sup-
-          ported by htpasswd on all platforms,  it  is  not  sup-
-          ported by the httpd server on Windows and TPF.
-
-     -s   Use SHA encryption for passwords. Faciliates  migration
-          from/to  Netscape  servers  using  the  LDAP  Directory
-          Interchange Format (ldif).
-
-     -p   Use plaintext passwords. Though htpasswd  will  support
-          creation  on  all platforms, the httpd deamon will only
-          accept plain text passwords on Windows and TPF.
-
-     passwdfile
-          Name of the file to contain the user name and password.
-          If  -c  is  given,  this file is created if it does not
-          already exist, or rewritten and truncated  if  it  does
-          exist.
-
-     username
-          The username to create  or  update  in  passwdfile.  If
-          username  does  not  exist  in  this  file, an entry is
-          added. If it does exist, the password is changed.
-
-     password
-          The plaintext password to be encrypted  and  stored  in
-          the file.  Only used with the -b flag.
-
-EXIT STATUS
-     htpasswd returns a zero status ("true") if the username  and
-     password  have  been  successfully  added  or updated in the
-     passwdfile.  htpasswd returns 1 if it encounters some  prob-
-     lem  accessing  files,  2 if there was a syntax problem with
-     the command line, 3 if the  password  was  entered  interac-
-     tively  and  the  verification  entry didn't match, 4 if its
-     operation was interrupted, 5 if a value is too  long  (user-
-     name,  filename,  password, or final computed record), and 6
-     if the username contains illegal characters  (see  the  RES-
-     TRICTIONS section).
-
-EXAMPLES
-     htpasswd /usr/local/etc/apache/.htpasswd-users jsmith
-
-          Adds or modifies the password for user jsmith. The user
-          is prompted for the password.  If executed on a Windows
-          system, the password will be encrypted using the  modi-
-          fied  Apache  MD5  algorithm;  otherwise,  the system's
-          crypt() routine will be used.  If  the  file  does  not
-          exist, htpasswd will do nothing except return an error.
-
-     htpasswd -c /home/doe/public_html/.htpasswd jane
-
-          Creates a new file and stores a record in it  for  user
-          jane.   The  user is prompted for the password.  If the
-          file exists and cannot be read, or cannot  be  written,
-          it  is  not altered and htpasswd will display a message
-          and return an error status.
-
-     htpasswd -mb /usr/web/.htpasswd-all jones Pwd4Steve
-
-          Encrypts the password from the command line (Pwd4Steve)
-          using the MD5 algorithm, and stores it in the specified
-          file.
-
-SECURITY CONSIDERATIONS
-     Web password files such as those managed by htpasswd  should
-     not  be  within  the Web server's URI space -- that is, they
-     should not be fetchable with a browser.
-
-     The use of the -b option is discouraged, since  when  it  is
-     used the unencrypted password appears on the command line.
-
-RESTRICTIONS
-     On the Windows and MPE platforms, passwords  encrypted  with
-     htpasswd  are  limited  to  no  more  than 255 characters in
-     length.  Longer passwords will be truncated to  255  charac-
-     ters.
-
-     The MD5 algorithm used by htpasswd is specific to the Apache
-     software;  passwords  encrypted  using it will not be usable
-     with other Web servers.
-
-     Usernames are limited to 255 bytes and may not  include  the
-     character ':'.
-
-SEE ALSO
-     httpd(8) and the scripts in support/SHA1 which come with the
-     distribution.
-
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/programs/httpd.html b/usr.sbin/httpd/htdocs/manual/programs/httpd.html new file mode 100644 index 00000000000..3a98dcd3bd1 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/programs/httpd.html @@ -0,0 +1,145 @@ + + + + + + + + Manual Page: httpd - Apache HTTP Server + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Manual Page: httpd

+ +
+NAME
+     httpd - Apache hypertext transfer protocol server
+
+SYNOPSIS
+     httpd [ -X ] [ -R libexecdir ] [ -d serverroot ] [ -f config
+     ] [ -C directive ] [ -c directive ] [ -D parameter ]
+
+     httpd [ -h ] [ -l ] [ -L ] [ -v ] [ -V ] [ -S ] [ -t ] [  -T
+     ]
+
+DESCRIPTION
+     httpd is  the  Apache  HyperText  Transfer  Protocol  (HTTP)
+     server  program.  It  is  designed to be run as a standalone
+     daemon process. When used like this it will create a pool of
+     child  processes to handle requests. To stop it, send a TERM
+     signal to the initial (parent) process. The PID of this pro-
+     cess  is  written  to  a  file as given in the configuration
+     file.  Alternatively httpd may be invoked  by  the  Internet
+     daemon  inetd(8)  each time a connection to the HTTP service
+     is made.
+
+     This manual page only lists the command line arguments.  For
+     details  of  the directives necessary to configure httpd see
+     the Apache manual, which is part of the Apache  distribution
+     or  can  be  found  at http://www.apache.org/. Paths in this
+     manual may not reflect those compiled into httpd.
+
+OPTIONS
+     -R libexecdir
+                 This option is  only  available  if  Apache  was
+                 built  with  the  SHARED_CORE rule enabled which
+                 forces the Apache core code to be placed into  a
+                 dynamic  shared  object (DSO) file. This file is
+                 searched in a hardcoded  path  under  ServerRoot
+                 per  default.  Use  this  option  if you want to
+                 override it.
+
+     -d serverroot
+                 Set the initial value for the ServerRoot  direc-
+                 tive  to  serverroot.  This can be overridden by
+                 the  ServerRoot  command  in  the  configuration
+                 file. The default is /usr/local/apache.
+
+     -f config   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 Server-
+                 Root. The default is conf/httpd.conf.
+
+     -C directive
+                 Process the configuration directive before read-
+                 ing config files.
+
+     -c directive
+                 Process the configuration directive after  read-
+                 ing config files.
+
+     -D parameter
+                 Sets a configuration parameter which can be used
+                 with  <IfDefine>...</IfDefine>  sections  in the
+                 configuration files  to  conditionally  skip  or
+                 process commands.
+
+     -h          Output a short summary of available command line
+                 options.
+
+     -l          Output a  list  of  modules  compiled  into  the
+                 server.
+
+     -L          Output  a  list  of  directives  together   with
+                 expected  arguments  and places where the direc-
+                 tive is valid.
+
+     -S          Show the settings as parsed from the config file
+                 (currently only shows the virtualhost settings).
+
+     -t          Run syntax tests for configuration  files  only.
+                 The program immediately exits after these syntax
+                 parsing with either a return code of  0  (Syntax
+                 OK)  or  return  code  not  equal  to  0 (Syntax
+                 Error).
+
+     -T          Same as option -t but does not check the config-
+                 ured document roots.
+
+     -X          Run in single-process mode, for internal  debug-
+                 ging  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.
+
+     -V          Print the version and build parameters of  httpd
+                 , and then exit.
+
+FILES
+     /usr/local/apache/conf/httpd.conf
+     /usr/local/apache/conf/srm.conf
+     /usr/local/apache/conf/access.conf
+     /usr/local/apache/conf/mime.types
+     /usr/local/apache/conf/magic
+     /usr/local/apache/logs/error_log
+     /usr/local/apache/logs/access_log
+     /usr/local/apache/logs/httpd.pid
+
+SEE ALSO
+     inetd(8).
+
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/programs/httpd.html.html b/usr.sbin/httpd/htdocs/manual/programs/httpd.html.html deleted file mode 100644 index 3a98dcd3bd1..00000000000 --- a/usr.sbin/httpd/htdocs/manual/programs/httpd.html.html +++ /dev/null @@ -1,145 +0,0 @@ - - - - - - - - Manual Page: httpd - Apache HTTP Server - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Manual Page: httpd

- -
-NAME
-     httpd - Apache hypertext transfer protocol server
-
-SYNOPSIS
-     httpd [ -X ] [ -R libexecdir ] [ -d serverroot ] [ -f config
-     ] [ -C directive ] [ -c directive ] [ -D parameter ]
-
-     httpd [ -h ] [ -l ] [ -L ] [ -v ] [ -V ] [ -S ] [ -t ] [  -T
-     ]
-
-DESCRIPTION
-     httpd is  the  Apache  HyperText  Transfer  Protocol  (HTTP)
-     server  program.  It  is  designed to be run as a standalone
-     daemon process. When used like this it will create a pool of
-     child  processes to handle requests. To stop it, send a TERM
-     signal to the initial (parent) process. The PID of this pro-
-     cess  is  written  to  a  file as given in the configuration
-     file.  Alternatively httpd may be invoked  by  the  Internet
-     daemon  inetd(8)  each time a connection to the HTTP service
-     is made.
-
-     This manual page only lists the command line arguments.  For
-     details  of  the directives necessary to configure httpd see
-     the Apache manual, which is part of the Apache  distribution
-     or  can  be  found  at http://www.apache.org/. Paths in this
-     manual may not reflect those compiled into httpd.
-
-OPTIONS
-     -R libexecdir
-                 This option is  only  available  if  Apache  was
-                 built  with  the  SHARED_CORE rule enabled which
-                 forces the Apache core code to be placed into  a
-                 dynamic  shared  object (DSO) file. This file is
-                 searched in a hardcoded  path  under  ServerRoot
-                 per  default.  Use  this  option  if you want to
-                 override it.
-
-     -d serverroot
-                 Set the initial value for the ServerRoot  direc-
-                 tive  to  serverroot.  This can be overridden by
-                 the  ServerRoot  command  in  the  configuration
-                 file. The default is /usr/local/apache.
-
-     -f config   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 Server-
-                 Root. The default is conf/httpd.conf.
-
-     -C directive
-                 Process the configuration directive before read-
-                 ing config files.
-
-     -c directive
-                 Process the configuration directive after  read-
-                 ing config files.
-
-     -D parameter
-                 Sets a configuration parameter which can be used
-                 with  <IfDefine>...</IfDefine>  sections  in the
-                 configuration files  to  conditionally  skip  or
-                 process commands.
-
-     -h          Output a short summary of available command line
-                 options.
-
-     -l          Output a  list  of  modules  compiled  into  the
-                 server.
-
-     -L          Output  a  list  of  directives  together   with
-                 expected  arguments  and places where the direc-
-                 tive is valid.
-
-     -S          Show the settings as parsed from the config file
-                 (currently only shows the virtualhost settings).
-
-     -t          Run syntax tests for configuration  files  only.
-                 The program immediately exits after these syntax
-                 parsing with either a return code of  0  (Syntax
-                 OK)  or  return  code  not  equal  to  0 (Syntax
-                 Error).
-
-     -T          Same as option -t but does not check the config-
-                 ured document roots.
-
-     -X          Run in single-process mode, for internal  debug-
-                 ging  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.
-
-     -V          Print the version and build parameters of  httpd
-                 , and then exit.
-
-FILES
-     /usr/local/apache/conf/httpd.conf
-     /usr/local/apache/conf/srm.conf
-     /usr/local/apache/conf/access.conf
-     /usr/local/apache/conf/mime.types
-     /usr/local/apache/conf/magic
-     /usr/local/apache/logs/error_log
-     /usr/local/apache/logs/access_log
-     /usr/local/apache/logs/httpd.pid
-
-SEE ALSO
-     inetd(8).
-
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/programs/index.html b/usr.sbin/httpd/htdocs/manual/programs/index.html new file mode 100644 index 00000000000..c3bcf6c8f96 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/programs/index.html @@ -0,0 +1,86 @@ + + + + + + + + Apache HTTP Server and Supporting Programs + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Server and Supporting Programs

+ +

This page documents all the executable programs included + with the Apache HTTP Server.

+ +
+
httpd
+ +
Apache hypertext transfer protocol server
+ +
apachectl
+ +
Apache HTTP server control interface
+ +
ab
+ +
Apache HTTP server benchmarking tool
+ +
apxs
+ +
APache eXtenSion tool
+ +
dbmmanage
+ +
Create and update user authentication files in DBM format + for basic authentication
+ +
htdigest
+ +
Create and update user authentication files for digest + authentication
+ +
htpasswd
+ +
Create and update user authentication files for basic + authentication
+ +
logresolve
+ +
Resolve hostnames for IP-addresses in Apache + logfiles
+ +
rotatelogs
+ +
Rotate Apache logs without having to kill the server
+ +
suexec
+ +
Switch User For Exec
+ +
Other Programs
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/programs/index.html.html b/usr.sbin/httpd/htdocs/manual/programs/index.html.html deleted file mode 100644 index c3bcf6c8f96..00000000000 --- a/usr.sbin/httpd/htdocs/manual/programs/index.html.html +++ /dev/null @@ -1,86 +0,0 @@ - - - - - - - - Apache HTTP Server and Supporting Programs - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Server and Supporting Programs

- -

This page documents all the executable programs included - with the Apache HTTP Server.

- -
-
httpd
- -
Apache hypertext transfer protocol server
- -
apachectl
- -
Apache HTTP server control interface
- -
ab
- -
Apache HTTP server benchmarking tool
- -
apxs
- -
APache eXtenSion tool
- -
dbmmanage
- -
Create and update user authentication files in DBM format - for basic authentication
- -
htdigest
- -
Create and update user authentication files for digest - authentication
- -
htpasswd
- -
Create and update user authentication files for basic - authentication
- -
logresolve
- -
Resolve hostnames for IP-addresses in Apache - logfiles
- -
rotatelogs
- -
Rotate Apache logs without having to kill the server
- -
suexec
- -
Switch User For Exec
- -
Other Programs
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/programs/suexec.html b/usr.sbin/httpd/htdocs/manual/programs/suexec.html new file mode 100644 index 00000000000..71698f43667 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/programs/suexec.html @@ -0,0 +1,56 @@ + + + + + + + + Manual Page: suexec - Apache HTTP Server + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Manual Page: suexec

+ +
+NAME
+     suexec - Switch User For Exec
+
+SYNOPSIS
+     No synopsis for usage, because this program is  used  inter-
+     nally by Apache only.
+
+DESCRIPTION
+     suexec is the  "wrapper"  support  program  for  the  suEXEC
+     behavior for Apache.  It is run from within Apache automat-
+     ically to switch the user when an external program has to be
+     run  under  a  different  user.  For  more information about
+     suEXEC  see  the  document  `Apache  suEXEC  Support'  under
+     http://www.apache.org/docs/suexec.html .
+
+SEE ALSO
+     httpd(8)
+
+
+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/programs/suexec.html.html b/usr.sbin/httpd/htdocs/manual/programs/suexec.html.html deleted file mode 100644 index 71698f43667..00000000000 --- a/usr.sbin/httpd/htdocs/manual/programs/suexec.html.html +++ /dev/null @@ -1,56 +0,0 @@ - - - - - - - - Manual Page: suexec - Apache HTTP Server - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Manual Page: suexec

- -
-NAME
-     suexec - Switch User For Exec
-
-SYNOPSIS
-     No synopsis for usage, because this program is  used  inter-
-     nally by Apache only.
-
-DESCRIPTION
-     suexec is the  "wrapper"  support  program  for  the  suEXEC
-     behavior for Apache.  It is run from within Apache automat-
-     ically to switch the user when an external program has to be
-     run  under  a  different  user.  For  more information about
-     suEXEC  see  the  document  `Apache  suEXEC  Support'  under
-     http://www.apache.org/docs/suexec.html .
-
-SEE ALSO
-     httpd(8)
-
-
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/sections.html b/usr.sbin/httpd/htdocs/manual/sections.html new file mode 100644 index 00000000000..d6ee901c52c --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/sections.html @@ -0,0 +1,169 @@ + + + + + + + + How Directory, Location and Files sections work + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

How Directory, Location and Files sections + work

+ +

The sections <Directory>, + <Location> + and <Files> can + contain directives which only apply to specified directories, + URLs or files respectively. Also htaccess files can be used + inside a directory to apply directives to that directory. This + document explains how these different sections differ and how + they relate to each other when Apache decides which directives + apply for a particular directory or request URL.

+ +

Directives allowed in the sections

+ +

Everything that is syntactically allowed in + <Directory> is also allowed in + <Location> (except a + sub-<Files> section). Semantically, however + some things, most notably AllowOverride and the + two options FollowSymLinks and + SymLinksIfOwnerMatch, make no sense in + <Location>, + <LocationMatch> or + <DirectoryMatch>. The same for + <Files> -- syntactically everything is fine, + but semantically some things are different.

+ +

How the sections are merged

+ +

The order of merging is:

+ +
    +
  1. <Directory> (except regular + expressions) and .htaccess done simultaneously (with + .htaccess, if allowed, overriding + <Directory>)
    2. + +
  2. <DirectoryMatch>, and + <Directory> with regular expressions
    3. + +
  3. <Files> and + <FilesMatch> done simultaneously
    4. + +
  4. <Location> and + <LocationMatch> done simultaneously
    5. +
+ +

Apart from <Directory>, each group is + processed in the order that they appear in the configuration + files. <Directory> (group 1 above) is + processed in the order shortest directory component to longest. + If multiple <Directory> sections apply to + the same directory they are processed in the configuration + file order. The configuration files are read in the order + httpd.conf, srm.conf and access.conf. Configurations included + via the Include directive will be treated as if + they were inside the including file at the location of the + Include directive.

+ +

Sections inside <VirtualHost> sections + are applied after the corresponding sections outside + the virtual host definition. This allows virtual hosts to + override the main server configuration. (Note: this only works + correctly from 1.2.2 and 1.3a2 onwards. Before those releases + sections inside virtual hosts were applied before the + main server).

+ +

Later sections override earlier ones.

+ +

Notes about using sections

+ +

The general guidelines are:

+ + + +

But a notable exception is:

+ + + +

Note about .htaccess parsing:

+ + + +

<Location> and symbolic links:

+ + + +

<Files> and Options:

+ + + +

Another note:

+ + +
+ +

Apache HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/sections.html.html b/usr.sbin/httpd/htdocs/manual/sections.html.html deleted file mode 100644 index d6ee901c52c..00000000000 --- a/usr.sbin/httpd/htdocs/manual/sections.html.html +++ /dev/null @@ -1,169 +0,0 @@ - - - - - - - - How Directory, Location and Files sections work - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

How Directory, Location and Files sections - work

- -

The sections <Directory>, - <Location> - and <Files> can - contain directives which only apply to specified directories, - URLs or files respectively. Also htaccess files can be used - inside a directory to apply directives to that directory. This - document explains how these different sections differ and how - they relate to each other when Apache decides which directives - apply for a particular directory or request URL.

- -

Directives allowed in the sections

- -

Everything that is syntactically allowed in - <Directory> is also allowed in - <Location> (except a - sub-<Files> section). Semantically, however - some things, most notably AllowOverride and the - two options FollowSymLinks and - SymLinksIfOwnerMatch, make no sense in - <Location>, - <LocationMatch> or - <DirectoryMatch>. The same for - <Files> -- syntactically everything is fine, - but semantically some things are different.

- -

How the sections are merged

- -

The order of merging is:

- -
    -
  1. <Directory> (except regular - expressions) and .htaccess done simultaneously (with - .htaccess, if allowed, overriding - <Directory>)
    2. - -
  2. <DirectoryMatch>, and - <Directory> with regular expressions
    3. - -
  3. <Files> and - <FilesMatch> done simultaneously
    4. - -
  4. <Location> and - <LocationMatch> done simultaneously
    5. -
- -

Apart from <Directory>, each group is - processed in the order that they appear in the configuration - files. <Directory> (group 1 above) is - processed in the order shortest directory component to longest. - If multiple <Directory> sections apply to - the same directory they are processed in the configuration - file order. The configuration files are read in the order - httpd.conf, srm.conf and access.conf. Configurations included - via the Include directive will be treated as if - they were inside the including file at the location of the - Include directive.

- -

Sections inside <VirtualHost> sections - are applied after the corresponding sections outside - the virtual host definition. This allows virtual hosts to - override the main server configuration. (Note: this only works - correctly from 1.2.2 and 1.3a2 onwards. Before those releases - sections inside virtual hosts were applied before the - main server).

- -

Later sections override earlier ones.

- -

Notes about using sections

- -

The general guidelines are:

- - - -

But a notable exception is:

- - - -

Note about .htaccess parsing:

- - - -

<Location> and symbolic links:

- - - -

<Files> and Options:

- - - -

Another note:

- - -
- -

Apache HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/server-wide.html b/usr.sbin/httpd/htdocs/manual/server-wide.html new file mode 100644 index 00000000000..27046b193bd --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/server-wide.html @@ -0,0 +1,283 @@ + + + + + + + + Server-Wide Configuration + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Server-Wide Configuration

+ +

This document explains some of the directives provided by + the core server which are used to + configure the basic operations of the server.

+ + +
+ +

Server + Identification

+ + + + + +
Related Directives
+
+ ServerName
+ ServerAdmin
+ ServerSignature
+ ServerTokens
+ UseCanonicalName
+
+ +

The ServerAdmin and ServerTokens + directives control what information about the server will be + presented in server-generated documents such as error messages. + The ServerTokens directive sets the value of the + Server HTTP response header field.

+ +

The ServerName and + UseCanonicalName directives are used by the server + to determine how to construct self-referential URLs. For + example, when a client requests a directory, but does not + include the trailing slash in the directory name, Apache must + redirect the client to the full name including the trailing + slash so that the client will correctly resolve relative + references in the document.

+
+ +

File Locations

+ + + + + +
Related Directives
+
+ CoreDumpDirectory
+ DocumentRoot
+ ErrorLog
+ Lockfile
+ PidFile
+ ScoreBoardFile
+ ServerRoot
+
+ +

These directives control the locations of the various files + that Apache needs for proper operation. When the pathname used + does not begin with a slash "/", the files are located relative + to the ServerRoot. Be careful about locating files + in paths which are writable by non-root users. See the security tips documentation + for more details.

+
+ +

Process Creation

+ + + + + +
Related Directives
+
+ BS2000Account
+ Group
+ MaxClients
+ MaxRequestsPerChild
+ MaxSpareServers
+ MinSpareServers
+ ServerType
+ StartServers
+ ThreadsPerChild
+ User
+
+ +

When ServerType is set to its recommended value + of Standalone, Apache 1.3 for Unix is a + pre-forking web server. A single control process is responsible + for launching child processes which listen for connections and + serve them when they arrive. Apache always tries to maintain + several spare or idle server processes, which stand + ready to serve incoming requests. In this way, clients do not + need to wait for a new child processes to be forked before + their requests can be served.

+ +

The StartServers, MinSpareServers, + MaxSpareServers, and MaxServers + regulate how the parent process creates children to serve + requests. In general, Apache is very self-regulating, so most + sites do not need to adjust these directives from their default + values. Sites which need to serve more than 256 simultaneous + requests may need to increase MaxClients, while + sites with limited memory may need to decrease + MaxClients to keep the server from thrashing + (swapping memory to disk and back). More information about + tuning process creation is provided in the performance hints + documentation.

+ +

While the parent process is usually started as root under + Unix in order to bind to port 80, the child processes are + launched by Apache as a less-privileged user. The + User and Group directives are used to + set the privileges of the Apache child processes. The child + processes must be able to read all the content that will be + served, but should have as few privileges beyond that as + possible. In addition, unless suexec + is used, these directives also set the privileges which will be + inherited by CGI scripts.

+ +

MaxRequestsPerChild controls how frequently the + server recycles processes by killing old ones and launching new + ones.

+ +

Under Windows, Apache launches one control process and one + child process. The child process creates multiple threads to + serve requests. The number of threads is controlled by the + ThreadsPerChild directive.

+
+ +

Network + Configuration

+ + + + + +
Related Directives
+
+ BindAddress
+ KeepAlive
+ KeepAliveTimeout
+ Listen
+ ListenBackLog
+ AcceptFilter
+ AcceptMutex
+ MaxKeepAliveRequests
+ Port
+ SendBufferSize
+ TimeOut
+
+ +

When Apache starts, it connects to some port and address on + the local machine and waits for incoming requests. By default, + it listens to all addresses on the machine, and to the port as + specified by the Port directive in the server + configuration. However, it can be told to listen to more than + one port, to listen to only selected addresses, or a + combination. This is often combined with the Virtual Host feature which determines how + Apache responds to different IP addresses, hostnames and + ports.

+ +

There are two directives used to restrict or specify which + addresses and ports Apache listens to. The + BindAddress directive is used to restrict the + server to listening to a single IP address. The + Listen directive can be used to specify multiple + IP addresses and/or Ports to which Apache will listen.

+ +

The ListenBackLog, SendBufferSize, + and TimeOut directives are used to adjust how + Apache interacts with the network.AcceptFilter + controls a BSD specific filter optimization. See the BSD + section on performance hints + documentation. AcceptMutex controls which accept + mutex method will be used. For an explanation of what this is + and why it's needed, see the performance tuning guide

+ +

The KeepAlive, KeepAliveTimeout, + and MaxKeepAliveRequests directives are used to + configure how Apache handles persistent connections.

+
+ +

Limiting Resource + Usage

+ + + + + +
Related Directives
+
+ LimitRequestBody
+ LimitRequestFields
+ LimitRequestFieldsize
+ LimitRequestLine
+ RLimitCPU
+ RLimitMEM
+ RLimitNPROC
+ ThreadStackSize
+
+ +

The LimitRequest* directives are used to place + limits on the amount of resources Apache will use in reading + requests from clients. By limiting these values, some kinds of + denial of service attacks can be mitigated.

+ +

The RLimit* directives are used to limit the + amount of resources which can be used by processes forked off + from the Apache children. In particular, this will control + resources used by CGI scripts and SSI exec commands.

+ +

The ThreadStackSize directive is used only on + Netware to control the stack size.

+
+ +

Apache HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/server-wide.html.html b/usr.sbin/httpd/htdocs/manual/server-wide.html.html deleted file mode 100644 index 27046b193bd..00000000000 --- a/usr.sbin/httpd/htdocs/manual/server-wide.html.html +++ /dev/null @@ -1,283 +0,0 @@ - - - - - - - - Server-Wide Configuration - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Server-Wide Configuration

- -

This document explains some of the directives provided by - the core server which are used to - configure the basic operations of the server.

- - -
- -

Server - Identification

- - - - - -
Related Directives
-
- ServerName
- ServerAdmin
- ServerSignature
- ServerTokens
- UseCanonicalName
-
- -

The ServerAdmin and ServerTokens - directives control what information about the server will be - presented in server-generated documents such as error messages. - The ServerTokens directive sets the value of the - Server HTTP response header field.

- -

The ServerName and - UseCanonicalName directives are used by the server - to determine how to construct self-referential URLs. For - example, when a client requests a directory, but does not - include the trailing slash in the directory name, Apache must - redirect the client to the full name including the trailing - slash so that the client will correctly resolve relative - references in the document.

-
- -

File Locations

- - - - - -
Related Directives
-
- CoreDumpDirectory
- DocumentRoot
- ErrorLog
- Lockfile
- PidFile
- ScoreBoardFile
- ServerRoot
-
- -

These directives control the locations of the various files - that Apache needs for proper operation. When the pathname used - does not begin with a slash "/", the files are located relative - to the ServerRoot. Be careful about locating files - in paths which are writable by non-root users. See the security tips documentation - for more details.

-
- -

Process Creation

- - - - - -
Related Directives
-
- BS2000Account
- Group
- MaxClients
- MaxRequestsPerChild
- MaxSpareServers
- MinSpareServers
- ServerType
- StartServers
- ThreadsPerChild
- User
-
- -

When ServerType is set to its recommended value - of Standalone, Apache 1.3 for Unix is a - pre-forking web server. A single control process is responsible - for launching child processes which listen for connections and - serve them when they arrive. Apache always tries to maintain - several spare or idle server processes, which stand - ready to serve incoming requests. In this way, clients do not - need to wait for a new child processes to be forked before - their requests can be served.

- -

The StartServers, MinSpareServers, - MaxSpareServers, and MaxServers - regulate how the parent process creates children to serve - requests. In general, Apache is very self-regulating, so most - sites do not need to adjust these directives from their default - values. Sites which need to serve more than 256 simultaneous - requests may need to increase MaxClients, while - sites with limited memory may need to decrease - MaxClients to keep the server from thrashing - (swapping memory to disk and back). More information about - tuning process creation is provided in the performance hints - documentation.

- -

While the parent process is usually started as root under - Unix in order to bind to port 80, the child processes are - launched by Apache as a less-privileged user. The - User and Group directives are used to - set the privileges of the Apache child processes. The child - processes must be able to read all the content that will be - served, but should have as few privileges beyond that as - possible. In addition, unless suexec - is used, these directives also set the privileges which will be - inherited by CGI scripts.

- -

MaxRequestsPerChild controls how frequently the - server recycles processes by killing old ones and launching new - ones.

- -

Under Windows, Apache launches one control process and one - child process. The child process creates multiple threads to - serve requests. The number of threads is controlled by the - ThreadsPerChild directive.

-
- -

Network - Configuration

- - - - - -
Related Directives
-
- BindAddress
- KeepAlive
- KeepAliveTimeout
- Listen
- ListenBackLog
- AcceptFilter
- AcceptMutex
- MaxKeepAliveRequests
- Port
- SendBufferSize
- TimeOut
-
- -

When Apache starts, it connects to some port and address on - the local machine and waits for incoming requests. By default, - it listens to all addresses on the machine, and to the port as - specified by the Port directive in the server - configuration. However, it can be told to listen to more than - one port, to listen to only selected addresses, or a - combination. This is often combined with the Virtual Host feature which determines how - Apache responds to different IP addresses, hostnames and - ports.

- -

There are two directives used to restrict or specify which - addresses and ports Apache listens to. The - BindAddress directive is used to restrict the - server to listening to a single IP address. The - Listen directive can be used to specify multiple - IP addresses and/or Ports to which Apache will listen.

- -

The ListenBackLog, SendBufferSize, - and TimeOut directives are used to adjust how - Apache interacts with the network.AcceptFilter - controls a BSD specific filter optimization. See the BSD - section on performance hints - documentation. AcceptMutex controls which accept - mutex method will be used. For an explanation of what this is - and why it's needed, see the performance tuning guide

- -

The KeepAlive, KeepAliveTimeout, - and MaxKeepAliveRequests directives are used to - configure how Apache handles persistent connections.

-
- -

Limiting Resource - Usage

- - - - - -
Related Directives
-
- LimitRequestBody
- LimitRequestFields
- LimitRequestFieldsize
- LimitRequestLine
- RLimitCPU
- RLimitMEM
- RLimitNPROC
- ThreadStackSize
-
- -

The LimitRequest* directives are used to place - limits on the amount of resources Apache will use in reading - requests from clients. By limiting these values, some kinds of - denial of service attacks can be mitigated.

- -

The RLimit* directives are used to limit the - amount of resources which can be used by processes forked off - from the Apache children. In particular, this will control - resources used by CGI scripts and SSI exec commands.

- -

The ThreadStackSize directive is used only on - Netware to control the stack size.

-
- -

Apache HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/stopping.html b/usr.sbin/httpd/htdocs/manual/stopping.html new file mode 100644 index 00000000000..8b840ced617 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/stopping.html @@ -0,0 +1,207 @@ + + + + + + + + Stopping and Restarting Apache + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Stopping and Restarting Apache

+ +

You will notice many 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.

+ +

To send a signal to the parent you should issue a command + such as:

+ +
+
+    kill -TERM `cat /usr/local/apache/logs/httpd.pid`
+
+
+ You can read about its progress by issuing: + +
+
+    tail -f /usr/local/apache/logs/error_log
+
+
+ Modify those examples to match your ServerRoot and PidFile settings. + +

As of Apache 1.3 we provide a script called apachectl which can be used + to start, stop, and restart Apache. It may need a little + customization for your system, see the comments at the top of + the script.

+ +

TERM Signal: stop now

+ +

Sending the 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

+ +

Sending the 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.

+ +

Users of the status module + will notice that the server statistics are set to zero when a + HUP is sent.

+ +

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.

+ +

USR1 Signal: graceful restart

+ +

Note: prior to release 1.2b9 this code is + quite unstable and shouldn't be used at all.

+ +

The 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.

+ +

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 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.

+ +

The status module will also use a G to indicate + those children which are still serving requests started before + the graceful restart was given.

+ +

At present there is no way for a log rotation script using + 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.

+ +

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. Before doing a restart, you can check the + syntax of the configuration files with the -t + command line argument (see httpd ). This still will not + guarantee that the server will restart correctly. To check the + semantics of the configuration files as well as the syntax, you + can try starting 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.

+ +

Appendix: signals and race conditions

+ +

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 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 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. + +

+ +

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. +

+ +

Apache HTTP Server

+ Index + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/stopping.html.html b/usr.sbin/httpd/htdocs/manual/stopping.html.html deleted file mode 100644 index 8b840ced617..00000000000 --- a/usr.sbin/httpd/htdocs/manual/stopping.html.html +++ /dev/null @@ -1,207 +0,0 @@ - - - - - - - - Stopping and Restarting Apache - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Stopping and Restarting Apache

- -

You will notice many 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.

- -

To send a signal to the parent you should issue a command - such as:

- -
-
-    kill -TERM `cat /usr/local/apache/logs/httpd.pid`
-
-
- You can read about its progress by issuing: - -
-
-    tail -f /usr/local/apache/logs/error_log
-
-
- Modify those examples to match your ServerRoot and PidFile settings. - -

As of Apache 1.3 we provide a script called apachectl which can be used - to start, stop, and restart Apache. It may need a little - customization for your system, see the comments at the top of - the script.

- -

TERM Signal: stop now

- -

Sending the 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

- -

Sending the 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.

- -

Users of the status module - will notice that the server statistics are set to zero when a - HUP is sent.

- -

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.

- -

USR1 Signal: graceful restart

- -

Note: prior to release 1.2b9 this code is - quite unstable and shouldn't be used at all.

- -

The 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.

- -

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 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.

- -

The status module will also use a G to indicate - those children which are still serving requests started before - the graceful restart was given.

- -

At present there is no way for a log rotation script using - 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.

- -

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. Before doing a restart, you can check the - syntax of the configuration files with the -t - command line argument (see httpd ). This still will not - guarantee that the server will restart correctly. To check the - semantics of the configuration files as well as the syntax, you - can try starting 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.

- -

Appendix: signals and race conditions

- -

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 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 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. - -

- -

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. -

- -

Apache HTTP Server

- Index - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/suexec.html b/usr.sbin/httpd/htdocs/manual/suexec.html new file mode 100644 index 00000000000..a5156ac40f3 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/suexec.html @@ -0,0 +1,613 @@ + + + + + + + + Apache suEXEC Support + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server

+
+ + + +

Apache suEXEC Support

+ +
    +
  1. CONTENTS
    2. + +
  2. What is suEXEC?
    3. + +
  3. Before we begin.
    4. + +
  4. suEXEC Security Model.
    5. + +
  5. Configuring & Installing + suEXEC
    6. + +
  6. Enabling & Disabling + suEXEC
    7. + +
  7. Using suEXEC
    8. + +
  8. Debugging suEXEC
    9. + +
  9. Beware the Jabberwock: Warnings + & Examples
    10. +
+ +

What is suEXEC?

+ +

The suEXEC feature -- + introduced in Apache 1.2 -- provides Apache users the ability + to run CGI and SSI programs + under user IDs different from the user ID of the calling + web-server. Normally, when a CGI or SSI program executes, it + runs as the same user who is running the web server.

+ +

Used properly, this feature can reduce + considerably the security risks involved with allowing users to + develop and run private CGI or SSI programs. However, if suEXEC + is improperly configured, it can cause any number of problems + and possibly create new holes in your computer's security. If + you aren't familiar with managing setuid root programs and the + security issues they present, we highly recommend that you not + consider using suEXEC.

+ +

BACK TO + CONTENTS

+ +

Before we begin.

+ +

Before jumping head-first into this document, + you should be aware of the assumptions made on the part of the + Apache Group and this document.

+ +

First, it is assumed that you are using a UNIX + derivate operating system that is capable of + setuid and setgid operations. + All command examples are given in this regard. Other platforms, + if they are capable of supporting suEXEC, may differ in their + configuration.

+ +

Second, it is assumed you are familiar with + some basic concepts of your computer's security and its + administration. This involves an understanding of + setuid/setgid operations and the various + effects they may have on your system and its level of + security.

+ +

Third, it is assumed that you are using an + unmodified version of suEXEC code. All code + for suEXEC has been carefully scrutinized and tested by the + developers as well as numerous beta testers. Every precaution + has been taken to ensure a simple yet solidly safe base of + code. Altering this code can cause unexpected problems and new + security risks. It is highly recommended that + you do not alter the suEXEC code unless you are well versed in + the particulars of security programming and are willing to share + your work with the Apache Group for consideration.

+ +

Fourth, and last, it has been the decision of + the Apache Group to NOT make suEXEC part of + the default installation of Apache. To this end, suEXEC + configuration requires careful attention to details from the + administrator. After due consideration has been given to the + various settings for suEXEC, the administrator may install + suEXEC through normal installation methods. The values for + these settings need to be carefully determined and specified by + the administrator to properly maintain system security during + the use of suEXEC functionality. It is through this detailed + process that the Apache Group hopes to limit suEXEC + installation only to those who are careful and determined + enough to use it.

+ +

Still with us? Yes? Good. Let's move on!

+ +

BACK TO + CONTENTS

+ +

suEXEC Security Model

+ +

Before we begin configuring and installing + suEXEC, we will first discuss the security model you are about + to implement. By doing so, you may better understand what + exactly is going on inside suEXEC and what precautions are + taken to ensure your system's security.

+ +

suEXEC is based on a setuid + "wrapper" program that is called by the main Apache web server. + This wrapper is called when an HTTP request is made for a CGI + or SSI program that the administrator has designated to run as + a userid other than that of the main server. When such a + request is made, Apache provides the suEXEC wrapper with the + program's name and the user and group IDs under which the + program is to execute.

+ +

The wrapper then employs the following process + to determine success or failure -- if any one of these + conditions fail, the program logs the failure and exits with an + error, otherwise it will continue:

+ +
    +
  1. + Was the wrapper called with the proper number of + arguments? + +
    + The wrapper will only execute if it is given the proper + number of arguments. The proper argument format is known + to the Apache web server. If the wrapper is not receiving + the proper number of arguments, it is either being + hacked, or there is something wrong with the suEXEC + portion of your Apache binary. +
    +
    2. + +
  2. + Is the user executing this wrapper a valid user of + this system? + +
    + This is to ensure that the user executing the wrapper is + truly a user of the system. +
    +
    3. + +
  3. + Is this valid user allowed to run the + wrapper? + +
    + Is this user the user allowed to run this wrapper? Only + one user (the Apache user) is allowed to execute this + program. +
    +
    4. + +
  4. + Does the target program have an unsafe hierarchical + reference? + +
    + Does the target program contain a leading '/' or have a + '..' backreference? These are not allowed; the target + program must reside within the Apache webspace. +
    +
    5. + +
  5. + Is the target user name valid? + +
    + Does the target user exist? +
    +
    6. + +
  6. + Is the target group name valid? + +
    + Does the target group exist? +
    +
    7. + +
  7. + Is the target user NOT superuser? + + +
    + Presently, suEXEC does not allow 'root' to execute + CGI/SSI programs. +
    +
    8. + +
  8. + Is the target userid ABOVE the minimum ID + number? + +
    + The minimum user ID number is specified during + configuration. This allows you to set the lowest possible + userid that will be allowed to execute CGI/SSI programs. + This is useful to block out "system" accounts. +
    +
    9. + +
  9. + Is the target group NOT the superuser + group? + +
    + Presently, suEXEC does not allow the 'root' group to + execute CGI/SSI programs. +
    +
    10. + +
  10. + Is the target groupid ABOVE the minimum ID + number? + +
    + The minimum group ID number is specified during + configuration. This allows you to set the lowest possible + groupid that will be allowed to execute CGI/SSI programs. + This is useful to block out "system" groups. +
    +
    11. + +
  11. + Can the wrapper successfully become the target user + and group? + +
    + Here is where the program becomes the target user and + group via setuid and setgid calls. The group access list + is also initialized with all of the groups of which the + user is a member. +
    +
    12. + +
  12. + Does the directory in which the program resides + exist? + +
    + If it doesn't exist, it can't very well contain files. +
    +
    13. + +
  13. + Is the directory within the Apache + webspace? + +
    + If the request is for a regular portion of the server, is + the requested directory within the server's document + root? If the request is for a UserDir, is the requested + directory within the user's document root? +
    +
    14. + +
  14. + Is the directory NOT writable by anyone + else? + +
    + We don't want to open up the directory to others; only + the owner user may be able to alter this directories + contents. +
    +
    15. + +
  15. + Does the target program exist? + +
    + If it doesn't exists, it can't very well be executed. +
    +
    16. + +
  16. + Is the target program NOT writable by + anyone else? + +
    + We don't want to give anyone other than the owner the + ability to change the program. +
    +
    17. + +
  17. + Is the target program NOT setuid or + setgid? + +
    + We do not want to execute programs that will then change + our UID/GID again. +
    +
    18. + +
  18. + Is the target user/group the same as the program's + user/group? + +
    + Is the user the owner of the file? +
    +
    19. + +
  19. + Can we successfully clean the process environment + to ensure safe operations? + +
    + suEXEC cleans the process' environment by establishing a + safe execution PATH (defined during configuration), as + well as only passing through those variables whose names + are listed in the safe environment list (also created + during configuration). +
    +
    20. + +
  20. + Can we successfully become the target program and + execute? + +
    + Here is where suEXEC ends and the target program begins. +
    +
    21. +
+ +

This is the standard operation of the + suEXEC wrapper's security model. It is somewhat stringent and + can impose new limitations and guidelines for CGI/SSI design, + but it was developed carefully step-by-step with security in + mind.

+ +

For more information as to how this security + model can limit your possibilities in regards to server + configuration, as well as what security risks can be avoided + with a proper suEXEC setup, see the "Beware the Jabberwock" section of this + document.

+ +

BACK TO + CONTENTS

+ +

Configuring & Installing + suEXEC

+ +

APACI's suEXEC configuration + options
+

+ +
+
--enable-suexec
+ +
This option enables the suEXEC feature which is never + installed or activated by default. At least one + --suexec-xxxxx option has to be provided together with the + --enable-suexec option to let APACI accept your request for + using the suEXEC feature.
+ +
--suexec-caller=UID
+ +
The username under which + Apache normally runs. This is the only user allowed to + execute this program.
+ +
--suexec-docroot=DIR
+ +
Define as the DocumentRoot set for Apache. This will be + the only hierarchy (aside from UserDirs) that can be used for + suEXEC behavior. The default directory is the --datadir value + with the suffix "/htdocs", e.g. if you configure + with "--datadir=/home/apache" the directory + "/home/apache/htdocs" is used as document root for the suEXEC + wrapper.
+ +
--suexec-logfile=FILE
+ +
This defines the filename to which all suEXEC + transactions and errors are logged (useful for auditing and + debugging purposes). By default the logfile is named + "suexec_log" and located in your standard logfile directory + (--logfiledir).
+ +
--suexec-userdir=DIR
+ +
Define to be the subdirectory under users' home + directories where suEXEC access should be allowed. All + executables under this directory will be executable by suEXEC + as the user so they should be "safe" programs. If you are + using a "simple" UserDir directive (ie. one without a "*" in + it) this should be set to the same value. suEXEC will not + work properly in cases where the UserDir directive points to + a location that is not the same as the user's home directory + as referenced in the passwd file. Default value is + "public_html".
+ If you have virtual hosts with a different UserDir for each, + you will need to define them to all reside in one parent + directory; then name that parent directory here. If + this is not defined properly, "~userdir" cgi requests will + not work!
+ +
--suexec-uidmin=UID
+ +
Define this as the lowest UID allowed to be a target user + for suEXEC. For most systems, 500 or 100 is common. Default + value is 100.
+ +
--suexec-gidmin=GID
+ +
Define this as the lowest GID allowed to be a target + group for suEXEC. For most systems, 100 is common and + therefore used as default value.
+ +
--suexec-safepath=PATH
+ +
Define a safe PATH environment to pass to CGI + executables. Default value is + "/usr/local/bin:/usr/bin:/bin".
+
+ +

Checking your suEXEC + setup
+ Before you compile and install the suEXEC wrapper you can + check the configuration with the --layout option.
+ Example output:

+
+    suEXEC setup:
+            suexec binary: /usr/local/apache/sbin/suexec
+            document root: /usr/local/apache/share/htdocs
+           userdir suffix: public_html
+                  logfile: /usr/local/apache/var/log/suexec_log
+                safe path: /usr/local/bin:/usr/bin:/bin
+                caller ID: www
+          minimum user ID: 100
+         minimum group ID: 100
+
+ +

Compiling and installing the suEXEC + wrapper
+ If you have enabled the suEXEC feature with the + --enable-suexec option the suexec binary (together with Apache + itself) is automatically built if you execute the command + "make".
+ After all components have been built you can execute the + command "make install" to install them. The binary image + "suexec" is installed in the directory defined by the --sbindir + option. Default location is + "/usr/local/apache/sbin/suexec".
+ Please note that you need root + privileges for the installation step. In order + for the wrapper to set the user ID, it must be installed as + owner root and must have the setuserid + execution bit set for file modes.

+ +

BACK TO + CONTENTS

+ +

Enabling & Disabling + suEXEC

+ +

Upon startup of Apache, it looks for the file + "suexec" in the "sbin" directory (default is + "/usr/local/apache/sbin/suexec"). If Apache finds a properly + configured suEXEC wrapper, it will print the following message + to the error log:

+
+    [notice] suEXEC mechanism enabled (wrapper: /path/to/suexec)
+
+ +

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.
+ If you want to enable the suEXEC mechanism for the first time + and an Apache server is already running you must kill and + restart Apache. Restarting it with a simple HUP or USR1 signal + will not be enough.
+ If you want to disable suEXEC you should kill and restart + Apache after you have removed the "suexec" file.

+ +

BACK TO + CONTENTS

+ +

Using suEXEC

+ +

Virtual Hosts:
+ One way to use the suEXEC wrapper 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.

+ +

User directories:
+ The suEXEC wrapper can also be used 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.

+ +

BACK TO + CONTENTS

+ +

Debugging suEXEC

+ +

The suEXEC wrapper will write log information + to the file defined with the --suexec-logfile option 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.

+ +

BACK TO + CONTENTS

+ +

Beware the Jabberwock: + Warnings & Examples

+ +

NOTE! This section may not be + complete. For the latest revision of this section of the + documentation, see the Apache Group's Online + Documentation version.

+ +

There are a few points of interest regarding + the wrapper that can cause limitations on server setup. Please + review these before submitting any "bugs" regarding suEXEC.

+ + + +

BACK TO + CONTENTS

+
+ +

Apache HTTP Server

+ Index + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/suexec.html.html b/usr.sbin/httpd/htdocs/manual/suexec.html.html deleted file mode 100644 index a5156ac40f3..00000000000 --- a/usr.sbin/httpd/htdocs/manual/suexec.html.html +++ /dev/null @@ -1,613 +0,0 @@ - - - - - - - - Apache suEXEC Support - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server

-
- - - -

Apache suEXEC Support

- -
    -
  1. CONTENTS
    2. - -
  2. What is suEXEC?
    3. - -
  3. Before we begin.
    4. - -
  4. suEXEC Security Model.
    5. - -
  5. Configuring & Installing - suEXEC
    6. - -
  6. Enabling & Disabling - suEXEC
    7. - -
  7. Using suEXEC
    8. - -
  8. Debugging suEXEC
    9. - -
  9. Beware the Jabberwock: Warnings - & Examples
    10. -
- -

What is suEXEC?

- -

The suEXEC feature -- - introduced in Apache 1.2 -- provides Apache users the ability - to run CGI and SSI programs - under user IDs different from the user ID of the calling - web-server. Normally, when a CGI or SSI program executes, it - runs as the same user who is running the web server.

- -

Used properly, this feature can reduce - considerably the security risks involved with allowing users to - develop and run private CGI or SSI programs. However, if suEXEC - is improperly configured, it can cause any number of problems - and possibly create new holes in your computer's security. If - you aren't familiar with managing setuid root programs and the - security issues they present, we highly recommend that you not - consider using suEXEC.

- -

BACK TO - CONTENTS

- -

Before we begin.

- -

Before jumping head-first into this document, - you should be aware of the assumptions made on the part of the - Apache Group and this document.

- -

First, it is assumed that you are using a UNIX - derivate operating system that is capable of - setuid and setgid operations. - All command examples are given in this regard. Other platforms, - if they are capable of supporting suEXEC, may differ in their - configuration.

- -

Second, it is assumed you are familiar with - some basic concepts of your computer's security and its - administration. This involves an understanding of - setuid/setgid operations and the various - effects they may have on your system and its level of - security.

- -

Third, it is assumed that you are using an - unmodified version of suEXEC code. All code - for suEXEC has been carefully scrutinized and tested by the - developers as well as numerous beta testers. Every precaution - has been taken to ensure a simple yet solidly safe base of - code. Altering this code can cause unexpected problems and new - security risks. It is highly recommended that - you do not alter the suEXEC code unless you are well versed in - the particulars of security programming and are willing to share - your work with the Apache Group for consideration.

- -

Fourth, and last, it has been the decision of - the Apache Group to NOT make suEXEC part of - the default installation of Apache. To this end, suEXEC - configuration requires careful attention to details from the - administrator. After due consideration has been given to the - various settings for suEXEC, the administrator may install - suEXEC through normal installation methods. The values for - these settings need to be carefully determined and specified by - the administrator to properly maintain system security during - the use of suEXEC functionality. It is through this detailed - process that the Apache Group hopes to limit suEXEC - installation only to those who are careful and determined - enough to use it.

- -

Still with us? Yes? Good. Let's move on!

- -

BACK TO - CONTENTS

- -

suEXEC Security Model

- -

Before we begin configuring and installing - suEXEC, we will first discuss the security model you are about - to implement. By doing so, you may better understand what - exactly is going on inside suEXEC and what precautions are - taken to ensure your system's security.

- -

suEXEC is based on a setuid - "wrapper" program that is called by the main Apache web server. - This wrapper is called when an HTTP request is made for a CGI - or SSI program that the administrator has designated to run as - a userid other than that of the main server. When such a - request is made, Apache provides the suEXEC wrapper with the - program's name and the user and group IDs under which the - program is to execute.

- -

The wrapper then employs the following process - to determine success or failure -- if any one of these - conditions fail, the program logs the failure and exits with an - error, otherwise it will continue:

- -
    -
  1. - Was the wrapper called with the proper number of - arguments? - -
    - The wrapper will only execute if it is given the proper - number of arguments. The proper argument format is known - to the Apache web server. If the wrapper is not receiving - the proper number of arguments, it is either being - hacked, or there is something wrong with the suEXEC - portion of your Apache binary. -
    -
    2. - -
  2. - Is the user executing this wrapper a valid user of - this system? - -
    - This is to ensure that the user executing the wrapper is - truly a user of the system. -
    -
    3. - -
  3. - Is this valid user allowed to run the - wrapper? - -
    - Is this user the user allowed to run this wrapper? Only - one user (the Apache user) is allowed to execute this - program. -
    -
    4. - -
  4. - Does the target program have an unsafe hierarchical - reference? - -
    - Does the target program contain a leading '/' or have a - '..' backreference? These are not allowed; the target - program must reside within the Apache webspace. -
    -
    5. - -
  5. - Is the target user name valid? - -
    - Does the target user exist? -
    -
    6. - -
  6. - Is the target group name valid? - -
    - Does the target group exist? -
    -
    7. - -
  7. - Is the target user NOT superuser? - - -
    - Presently, suEXEC does not allow 'root' to execute - CGI/SSI programs. -
    -
    8. - -
  8. - Is the target userid ABOVE the minimum ID - number? - -
    - The minimum user ID number is specified during - configuration. This allows you to set the lowest possible - userid that will be allowed to execute CGI/SSI programs. - This is useful to block out "system" accounts. -
    -
    9. - -
  9. - Is the target group NOT the superuser - group? - -
    - Presently, suEXEC does not allow the 'root' group to - execute CGI/SSI programs. -
    -
    10. - -
  10. - Is the target groupid ABOVE the minimum ID - number? - -
    - The minimum group ID number is specified during - configuration. This allows you to set the lowest possible - groupid that will be allowed to execute CGI/SSI programs. - This is useful to block out "system" groups. -
    -
    11. - -
  11. - Can the wrapper successfully become the target user - and group? - -
    - Here is where the program becomes the target user and - group via setuid and setgid calls. The group access list - is also initialized with all of the groups of which the - user is a member. -
    -
    12. - -
  12. - Does the directory in which the program resides - exist? - -
    - If it doesn't exist, it can't very well contain files. -
    -
    13. - -
  13. - Is the directory within the Apache - webspace? - -
    - If the request is for a regular portion of the server, is - the requested directory within the server's document - root? If the request is for a UserDir, is the requested - directory within the user's document root? -
    -
    14. - -
  14. - Is the directory NOT writable by anyone - else? - -
    - We don't want to open up the directory to others; only - the owner user may be able to alter this directories - contents. -
    -
    15. - -
  15. - Does the target program exist? - -
    - If it doesn't exists, it can't very well be executed. -
    -
    16. - -
  16. - Is the target program NOT writable by - anyone else? - -
    - We don't want to give anyone other than the owner the - ability to change the program. -
    -
    17. - -
  17. - Is the target program NOT setuid or - setgid? - -
    - We do not want to execute programs that will then change - our UID/GID again. -
    -
    18. - -
  18. - Is the target user/group the same as the program's - user/group? - -
    - Is the user the owner of the file? -
    -
    19. - -
  19. - Can we successfully clean the process environment - to ensure safe operations? - -
    - suEXEC cleans the process' environment by establishing a - safe execution PATH (defined during configuration), as - well as only passing through those variables whose names - are listed in the safe environment list (also created - during configuration). -
    -
    20. - -
  20. - Can we successfully become the target program and - execute? - -
    - Here is where suEXEC ends and the target program begins. -
    -
    21. -
- -

This is the standard operation of the - suEXEC wrapper's security model. It is somewhat stringent and - can impose new limitations and guidelines for CGI/SSI design, - but it was developed carefully step-by-step with security in - mind.

- -

For more information as to how this security - model can limit your possibilities in regards to server - configuration, as well as what security risks can be avoided - with a proper suEXEC setup, see the "Beware the Jabberwock" section of this - document.

- -

BACK TO - CONTENTS

- -

Configuring & Installing - suEXEC

- -

APACI's suEXEC configuration - options
-

- -
-
--enable-suexec
- -
This option enables the suEXEC feature which is never - installed or activated by default. At least one - --suexec-xxxxx option has to be provided together with the - --enable-suexec option to let APACI accept your request for - using the suEXEC feature.
- -
--suexec-caller=UID
- -
The username under which - Apache normally runs. This is the only user allowed to - execute this program.
- -
--suexec-docroot=DIR
- -
Define as the DocumentRoot set for Apache. This will be - the only hierarchy (aside from UserDirs) that can be used for - suEXEC behavior. The default directory is the --datadir value - with the suffix "/htdocs", e.g. if you configure - with "--datadir=/home/apache" the directory - "/home/apache/htdocs" is used as document root for the suEXEC - wrapper.
- -
--suexec-logfile=FILE
- -
This defines the filename to which all suEXEC - transactions and errors are logged (useful for auditing and - debugging purposes). By default the logfile is named - "suexec_log" and located in your standard logfile directory - (--logfiledir).
- -
--suexec-userdir=DIR
- -
Define to be the subdirectory under users' home - directories where suEXEC access should be allowed. All - executables under this directory will be executable by suEXEC - as the user so they should be "safe" programs. If you are - using a "simple" UserDir directive (ie. one without a "*" in - it) this should be set to the same value. suEXEC will not - work properly in cases where the UserDir directive points to - a location that is not the same as the user's home directory - as referenced in the passwd file. Default value is - "public_html".
- If you have virtual hosts with a different UserDir for each, - you will need to define them to all reside in one parent - directory; then name that parent directory here. If - this is not defined properly, "~userdir" cgi requests will - not work!
- -
--suexec-uidmin=UID
- -
Define this as the lowest UID allowed to be a target user - for suEXEC. For most systems, 500 or 100 is common. Default - value is 100.
- -
--suexec-gidmin=GID
- -
Define this as the lowest GID allowed to be a target - group for suEXEC. For most systems, 100 is common and - therefore used as default value.
- -
--suexec-safepath=PATH
- -
Define a safe PATH environment to pass to CGI - executables. Default value is - "/usr/local/bin:/usr/bin:/bin".
-
- -

Checking your suEXEC - setup
- Before you compile and install the suEXEC wrapper you can - check the configuration with the --layout option.
- Example output:

-
-    suEXEC setup:
-            suexec binary: /usr/local/apache/sbin/suexec
-            document root: /usr/local/apache/share/htdocs
-           userdir suffix: public_html
-                  logfile: /usr/local/apache/var/log/suexec_log
-                safe path: /usr/local/bin:/usr/bin:/bin
-                caller ID: www
-          minimum user ID: 100
-         minimum group ID: 100
-
- -

Compiling and installing the suEXEC - wrapper
- If you have enabled the suEXEC feature with the - --enable-suexec option the suexec binary (together with Apache - itself) is automatically built if you execute the command - "make".
- After all components have been built you can execute the - command "make install" to install them. The binary image - "suexec" is installed in the directory defined by the --sbindir - option. Default location is - "/usr/local/apache/sbin/suexec".
- Please note that you need root - privileges for the installation step. In order - for the wrapper to set the user ID, it must be installed as - owner root and must have the setuserid - execution bit set for file modes.

- -

BACK TO - CONTENTS

- -

Enabling & Disabling - suEXEC

- -

Upon startup of Apache, it looks for the file - "suexec" in the "sbin" directory (default is - "/usr/local/apache/sbin/suexec"). If Apache finds a properly - configured suEXEC wrapper, it will print the following message - to the error log:

-
-    [notice] suEXEC mechanism enabled (wrapper: /path/to/suexec)
-
- -

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.
- If you want to enable the suEXEC mechanism for the first time - and an Apache server is already running you must kill and - restart Apache. Restarting it with a simple HUP or USR1 signal - will not be enough.
- If you want to disable suEXEC you should kill and restart - Apache after you have removed the "suexec" file.

- -

BACK TO - CONTENTS

- -

Using suEXEC

- -

Virtual Hosts:
- One way to use the suEXEC wrapper 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.

- -

User directories:
- The suEXEC wrapper can also be used 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.

- -

BACK TO - CONTENTS

- -

Debugging suEXEC

- -

The suEXEC wrapper will write log information - to the file defined with the --suexec-logfile option 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.

- -

BACK TO - CONTENTS

- -

Beware the Jabberwock: - Warnings & Examples

- -

NOTE! This section may not be - complete. For the latest revision of this section of the - documentation, see the Apache Group's Online - Documentation version.

- -

There are a few points of interest regarding - the wrapper that can cause limitations on server setup. Please - review these before submitting any "bugs" regarding suEXEC.

- - - -

BACK TO - CONTENTS

-
- -

Apache HTTP Server

- Index - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html b/usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html new file mode 100644 index 00000000000..b548c1606b8 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html @@ -0,0 +1,87 @@ + + + + + + + + Apache Server Virtual Host Support + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

File Descriptor Limits

+ +

When using a large number of Virtual Hosts, Apache may run + out of available file descriptors (sometimes called file + handles if each Virtual Host specifies different log + files. The total number of file descriptors used by Apache is + one for each distinct error log file, one for every other log + file directive, plus 10-20 for internal use. Unix operating + systems limit the number of file descriptors that may be used + by a process; the limit is typically 64, and may usually be + increased up to a large hard-limit.

+ +

Although Apache attempts to increase the limit as required, + this may not work if:

+ +
    +
  1. Your system does not provide the setrlimit() system + call.
    2. + +
  2. The setrlimit(RLIMIT_NOFILE) call does not function on + your system (such as Solaris 2.3)
    3. + +
  3. The number of file descriptors required exceeds the hard + limit.
    4. + +
  4. Your system imposes other limits on file descriptors, + such as a limit on stdio streams only using file descriptors + below 256. (Solaris 2)
    5. +
+ In the event of problems you can: + + + +

Please see the Descriptors and Apache + document containing further details about file descriptor + problems and how they can be solved on your operating + system.

+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html.html b/usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html.html deleted file mode 100644 index b548c1606b8..00000000000 --- a/usr.sbin/httpd/htdocs/manual/vhosts/fd-limits.html.html +++ /dev/null @@ -1,87 +0,0 @@ - - - - - - - - Apache Server Virtual Host Support - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

File Descriptor Limits

- -

When using a large number of Virtual Hosts, Apache may run - out of available file descriptors (sometimes called file - handles if each Virtual Host specifies different log - files. The total number of file descriptors used by Apache is - one for each distinct error log file, one for every other log - file directive, plus 10-20 for internal use. Unix operating - systems limit the number of file descriptors that may be used - by a process; the limit is typically 64, and may usually be - increased up to a large hard-limit.

- -

Although Apache attempts to increase the limit as required, - this may not work if:

- -
    -
  1. Your system does not provide the setrlimit() system - call.
    2. - -
  2. The setrlimit(RLIMIT_NOFILE) call does not function on - your system (such as Solaris 2.3)
    3. - -
  3. The number of file descriptors required exceeds the hard - limit.
    4. - -
  4. Your system imposes other limits on file descriptors, - such as a limit on stdio streams only using file descriptors - below 256. (Solaris 2)
    5. -
- In the event of problems you can: - - - -

Please see the Descriptors and Apache - document containing further details about file descriptor - problems and how they can be solved on your operating - system.

-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/index.html b/usr.sbin/httpd/htdocs/manual/vhosts/index.html new file mode 100644 index 00000000000..8d3af61f1bf --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/index.html @@ -0,0 +1,98 @@ + + + + + + + + Apache Virtual Host documentation + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Apache Virtual Host documentation

+ +

The term Virtual Host refers to the practice of + maintaining more than one server on one machine, as + differentiated by their apparent hostname. For example, it is + often desirable for companies sharing a web server to have + their own domains, with web servers accessible as + www.company1.com and + www.company2.com, without requiring the user to + know any extra path information.

+ +

Apache was one of the first servers to support IP-based + virtual hosts right out of the box. Versions 1.1 and later of + Apache support both, IP-based and name-based virtual hosts + (vhosts). The latter variant of virtual hosts is sometimes also + called host-based or non-IP virtual hosts.

+ +

Below is a list of documentation pages which explain all + details of virtual host support in Apache version 1.3 and + later.

+
+ +

Virtual Host Support

+ + + +

Configuration directives

+ + + +

Folks trying to debug their virtual host configuration may + find the Apache -S command line switch useful. It + will dump out a description of how Apache parsed the + configuration file. Careful examination of the IP addresses and + server names may help uncover configuration mistakes. +

+ +

Apache HTTP Server Version 1.3

+ Index + Home + +

+ + + + + diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/index.html.html b/usr.sbin/httpd/htdocs/manual/vhosts/index.html.html deleted file mode 100644 index 8d3af61f1bf..00000000000 --- a/usr.sbin/httpd/htdocs/manual/vhosts/index.html.html +++ /dev/null @@ -1,98 +0,0 @@ - - - - - - - - Apache Virtual Host documentation - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Apache Virtual Host documentation

- -

The term Virtual Host refers to the practice of - maintaining more than one server on one machine, as - differentiated by their apparent hostname. For example, it is - often desirable for companies sharing a web server to have - their own domains, with web servers accessible as - www.company1.com and - www.company2.com, without requiring the user to - know any extra path information.

- -

Apache was one of the first servers to support IP-based - virtual hosts right out of the box. Versions 1.1 and later of - Apache support both, IP-based and name-based virtual hosts - (vhosts). The latter variant of virtual hosts is sometimes also - called host-based or non-IP virtual hosts.

- -

Below is a list of documentation pages which explain all - details of virtual host support in Apache version 1.3 and - later.

-
- -

Virtual Host Support

- - - -

Configuration directives

- - - -

Folks trying to debug their virtual host configuration may - find the Apache -S command line switch useful. It - will dump out a description of how Apache parsed the - configuration file. Careful examination of the IP addresses and - server names may help uncover configuration mistakes. -

- -

Apache HTTP Server Version 1.3

- Index - Home - -

- - - - - diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html b/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html new file mode 100644 index 00000000000..8940a29c191 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html @@ -0,0 +1,254 @@ + + + + + + Name-based Virtual Hosts + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 1.3

+
+ + +

Name-based Virtual Host Support

+ +

This document describes when and how to use name-based virtual hosts.

+ + + +

See also: Virtual Host examples for common +setups, IP-based Virtual Host Support, +An In-Depth Discussion of Virtual Host +Matching, and Dynamically configured mass +virtual hosting.

+ +
+ +

Name-based vs. IP-based Virtual Hosts

+ +

IP-based virtual hosts use the IP address of the connection to +determine the correct virtual host to serve. Therefore you need to +have a separate IP address for each host. With name-based virtual +hosting, the server relies on the client to report the hostname as +part of the HTTP headers. Using this technique, many different hosts +can share the same IP address.

+ +

Name-based virtual hosting is usually simpler, since you need +only configure your DNS server to map each hostname to the correct +IP address and then configure the Apache HTTP Server to recognize +the different hostnames. Name-based virtual hosting also eases +the demand for scarce IP addresses. Therefore you should use +name-based virtual hosting unless there is a specific reason to +choose IP-based virtual hosting. Some reasons why you might consider +using IP-based virtual hosting:

+ + + +

Using Name-based Virtual Hosts

+ + +
+Related Directives

+ +DocumentRoot
+NameVirtualHost
+ServerAlias
+ServerName
+ServerPath
+VirtualHost
+
+ +

To use name-based virtual hosting, you must designate the IP +address (and possibly port) on the server that will be accepting +requests for the hosts. This is configured using the NameVirtualHost directive. +In the normal case where any and all IP addresses on the server should +be used, you can use * as the argument to +NameVirtualHost. (NameVirtualHost * will +work only in version 1.3.13 and later.) Note that mentioning an IP +address in a NameVirtualHost directive does not +automatically make the server listen to that IP address. See Setting which addresses and ports Apache uses +for more details. In addition, any IP address specified here must be +associated with a network interface on the server.

+ +

The next step is to create a <VirtualHost> block for +each different host that you would like to serve. The argument to the +<VirtualHost> directive should be the same as the +argument to the NameVirtualHost directive (ie, an IP +address, or * for all addresses). Inside each +<VirtualHost> block, you will need at minimum a ServerName directive to +designate which host is served and a DocumentRoot directive to +show where in the filesystem the content for that host lives.

+ +

If you are adding virtual hosts to an existing web server, you +must also create a <VirtualHost> block for the existing host. +The ServerName and DocumentRoot included in +this virtual host should be the same as the global +ServerName and DocumentRoot. List this +virtual host first in the configuration file so that it will act as +the default host.

+ +

For example, suppose that you are serving the domain +www.domain.tld and you wish to add the virtual host +www.otherdomain.tld, which points at the same IP address. +Then you simply add the following to httpd.conf:

+
+    NameVirtualHost *
+
+    <VirtualHost *>
+    ServerName www.domain.tld
+    DocumentRoot /www/domain
+    </VirtualHost>
+
+    <VirtualHost *>
+    ServerName www.otherdomain.tld
+    DocumentRoot /www/otherdomain
+    </VirtualHost>
+
+ +

You can alternatively specify an explicit IP address in place of +the * in both the NameVirtualHost and +<VirtualHost> directives. The IP address is +required in version 1.3.12 and earlier.

+ +

Many servers want to be accessible by more than one name. This is +possible with the ServerAlias +directive, placed inside the <VirtualHost> section. For +example if you add this to the first <VirtualHost> block +above

+ +
+ServerAlias domain.tld *.domain.tld +
+ +

then requests for all hosts in the domain.tld domain +will be served by the www.domain.tld virtual host. The +wildcard characters * and ? can be used to match names. Of course, +you can't just make up names and place them in ServerName +or ServerAlias. You must first have your DNS server +properly configured to map those names to an IP address associated +with your server.

+ +

Finally, you can fine-tune the configuration of the virtual hosts +by placing other directives inside the +<VirtualHost> containers. Most directives can be +placed in these containers and will then change the configuration only +of the relevant virtual host. To find out if a particular directive +is allowed, check the Context of the +directive. Configuration directives set in the main server +context (outside any <VirtualHost> container) +will be used only if they are not overriden by the virtual host +settings.

+ +

Now when a request arrives, the server will first check if it is +using an IP address that matches the NameVirtualHost. If +it is, then it will look at each <VirtualHost> +section with a matching IP address and try to find one where the +ServerName or ServerAlias matches the +requested hostname. If it finds one, then it uses the configuration +for that server. If no matching virtual host is found, then +the first listed virtual host that matches the IP +address will be used.

+ +

As a consequence, the first listed virtual host is the +default virtual host. The DocumentRoot from the +main server will never be used when an IP +address matches the NameVirtualHost directive. If you +would like to have a special configuration for requests that do not +match any particular virtual host, simply put that configuration in a +<VirtualHost> container and list it first in the +configuration file.

+ +

Compatibility with Older Browsers

+ +

As mentioned earlier, there are some clients + who do not send the required data for the name-based virtual + hosts to work properly. These clients will always be sent the + pages from the first virtual host listed for that IP address + (the primary name-based virtual host).

+ +

There is a possible workaround with the ServerPath + directive, albeit a slightly cumbersome one:

+ +

Example configuration:

+
+    NameVirtualHost 111.22.33.44
+
+    <VirtualHost 111.22.33.44>
+    ServerName www.domain.tld
+    ServerPath /domain
+    DocumentRoot /web/domain
+    </VirtualHost>
+
+ +

What does this mean? It means that a request for any URI + beginning with "/domain" will be served from the + virtual host www.domain.tld This means that the + pages can be accessed as + http://www.domain.tld/domain/ for all clients, + although clients sending a Host: header can also + access it as http://www.domain.tld/.

+ +

In order to make this work, put a link on your primary + virtual host's page to + http://www.domain.tld/domain/ Then, in the virtual + host's pages, be sure to use either purely relative links + (e.g., "file.html" or + "../icons/image.gif" or links containing the + prefacing /domain/ (e.g., + "http://www.domain.tld/domain/misc/file.html" or + "/domain/misc/file.html").

+ +

This requires a bit of discipline, but adherence to these + guidelines will, for the most part, ensure that your pages will + work with all browsers, new and old.

+ +

See also: ServerPath + configuration example

+
+ +

Apache HTTP Server Version 1.3

+ Index + Home + + + + + + diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html.html b/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html.html deleted file mode 100644 index 8940a29c191..00000000000 --- a/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html.html +++ /dev/null @@ -1,254 +0,0 @@ - - - - - - Name-based Virtual Hosts - - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- - -

Name-based Virtual Host Support

- -

This document describes when and how to use name-based virtual hosts.

- - - -

See also: Virtual Host examples for common -setups, IP-based Virtual Host Support, -An In-Depth Discussion of Virtual Host -Matching, and Dynamically configured mass -virtual hosting.

- -
- -

Name-based vs. IP-based Virtual Hosts

- -

IP-based virtual hosts use the IP address of the connection to -determine the correct virtual host to serve. Therefore you need to -have a separate IP address for each host. With name-based virtual -hosting, the server relies on the client to report the hostname as -part of the HTTP headers. Using this technique, many different hosts -can share the same IP address.

- -

Name-based virtual hosting is usually simpler, since you need -only configure your DNS server to map each hostname to the correct -IP address and then configure the Apache HTTP Server to recognize -the different hostnames. Name-based virtual hosting also eases -the demand for scarce IP addresses. Therefore you should use -name-based virtual hosting unless there is a specific reason to -choose IP-based virtual hosting. Some reasons why you might consider -using IP-based virtual hosting:

- - - -

Using Name-based Virtual Hosts

- - -
-Related Directives

- -DocumentRoot
-NameVirtualHost
-ServerAlias
-ServerName
-ServerPath
-VirtualHost
-
- -

To use name-based virtual hosting, you must designate the IP -address (and possibly port) on the server that will be accepting -requests for the hosts. This is configured using the NameVirtualHost directive. -In the normal case where any and all IP addresses on the server should -be used, you can use * as the argument to -NameVirtualHost. (NameVirtualHost * will -work only in version 1.3.13 and later.) Note that mentioning an IP -address in a NameVirtualHost directive does not -automatically make the server listen to that IP address. See Setting which addresses and ports Apache uses -for more details. In addition, any IP address specified here must be -associated with a network interface on the server.

- -

The next step is to create a <VirtualHost> block for -each different host that you would like to serve. The argument to the -<VirtualHost> directive should be the same as the -argument to the NameVirtualHost directive (ie, an IP -address, or * for all addresses). Inside each -<VirtualHost> block, you will need at minimum a ServerName directive to -designate which host is served and a DocumentRoot directive to -show where in the filesystem the content for that host lives.

- -

If you are adding virtual hosts to an existing web server, you -must also create a <VirtualHost> block for the existing host. -The ServerName and DocumentRoot included in -this virtual host should be the same as the global -ServerName and DocumentRoot. List this -virtual host first in the configuration file so that it will act as -the default host.

- -

For example, suppose that you are serving the domain -www.domain.tld and you wish to add the virtual host -www.otherdomain.tld, which points at the same IP address. -Then you simply add the following to httpd.conf:

-
-    NameVirtualHost *
-
-    <VirtualHost *>
-    ServerName www.domain.tld
-    DocumentRoot /www/domain
-    </VirtualHost>
-
-    <VirtualHost *>
-    ServerName www.otherdomain.tld
-    DocumentRoot /www/otherdomain
-    </VirtualHost>
-
- -

You can alternatively specify an explicit IP address in place of -the * in both the NameVirtualHost and -<VirtualHost> directives. The IP address is -required in version 1.3.12 and earlier.

- -

Many servers want to be accessible by more than one name. This is -possible with the ServerAlias -directive, placed inside the <VirtualHost> section. For -example if you add this to the first <VirtualHost> block -above

- -
-ServerAlias domain.tld *.domain.tld -
- -

then requests for all hosts in the domain.tld domain -will be served by the www.domain.tld virtual host. The -wildcard characters * and ? can be used to match names. Of course, -you can't just make up names and place them in ServerName -or ServerAlias. You must first have your DNS server -properly configured to map those names to an IP address associated -with your server.

- -

Finally, you can fine-tune the configuration of the virtual hosts -by placing other directives inside the -<VirtualHost> containers. Most directives can be -placed in these containers and will then change the configuration only -of the relevant virtual host. To find out if a particular directive -is allowed, check the Context of the -directive. Configuration directives set in the main server -context (outside any <VirtualHost> container) -will be used only if they are not overriden by the virtual host -settings.

- -

Now when a request arrives, the server will first check if it is -using an IP address that matches the NameVirtualHost. If -it is, then it will look at each <VirtualHost> -section with a matching IP address and try to find one where the -ServerName or ServerAlias matches the -requested hostname. If it finds one, then it uses the configuration -for that server. If no matching virtual host is found, then -the first listed virtual host that matches the IP -address will be used.

- -

As a consequence, the first listed virtual host is the -default virtual host. The DocumentRoot from the -main server will never be used when an IP -address matches the NameVirtualHost directive. If you -would like to have a special configuration for requests that do not -match any particular virtual host, simply put that configuration in a -<VirtualHost> container and list it first in the -configuration file.

- -

Compatibility with Older Browsers

- -

As mentioned earlier, there are some clients - who do not send the required data for the name-based virtual - hosts to work properly. These clients will always be sent the - pages from the first virtual host listed for that IP address - (the primary name-based virtual host).

- -

There is a possible workaround with the ServerPath - directive, albeit a slightly cumbersome one:

- -

Example configuration:

-
-    NameVirtualHost 111.22.33.44
-
-    <VirtualHost 111.22.33.44>
-    ServerName www.domain.tld
-    ServerPath /domain
-    DocumentRoot /web/domain
-    </VirtualHost>
-
- -

What does this mean? It means that a request for any URI - beginning with "/domain" will be served from the - virtual host www.domain.tld This means that the - pages can be accessed as - http://www.domain.tld/domain/ for all clients, - although clients sending a Host: header can also - access it as http://www.domain.tld/.

- -

In order to make this work, put a link on your primary - virtual host's page to - http://www.domain.tld/domain/ Then, in the virtual - host's pages, be sure to use either purely relative links - (e.g., "file.html" or - "../icons/image.gif" or links containing the - prefacing /domain/ (e.g., - "http://www.domain.tld/domain/misc/file.html" or - "/domain/misc/file.html").

- -

This requires a bit of discipline, but adherence to these - guidelines will, for the most part, ensure that your pages will - work with all browsers, new and old.

- -

See also: ServerPath - configuration example

-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - -- cgit v1.2.3