X-Git-Url: https://granicus.if.org/sourcecode?a=blobdiff_plain;f=docs%2Fmanual%2Fconfiguring.xml;h=672491b2a8198e1bfe4726808306b99f18ddef88;hb=402ea113bbd93eef00e66ba0caaef75df15cd0e8;hp=0c4c322a6d8cb417e02d6b4c5987aadff3e61062;hpb=79bba88026028fa96782d09077247c96888717dc;p=apache

diff --git a/docs/manual/configuring.xml b/docs/manual/configuring.xml
index 0c4c322a6d..672491b2a8 100644
--- a/docs/manual/configuring.xml
+++ b/docs/manual/configuring.xml
@@ -1,14 +1,15 @@
 <?xml version='1.0' encoding='UTF-8' ?>
 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
-<!-- $Revision: 1.10 $ -->
+<!-- $LastChangedRevision$ -->
 
 <!--
- Copyright 2002-2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
 
      http://www.apache.org/licenses/LICENSE-2.0
 
@@ -24,8 +25,8 @@
   <title>Configuration Files</title>
 
 <summary>
-<p>This document describes the files used to configure the Apache
-HTTP server.</p>
+<p>This document describes the files used to configure Apache HTTP
+Server.</p>
 </summary>
 
   <section id="main">
@@ -41,7 +42,7 @@ HTTP server.</p>
       </directivelist>
     </related>
 
-    <p>Apache is configured by placing <a
+    <p>Apache HTTP Server is configured by placing <a
     href="mod/directives.html">directives</a> in plain text
     configuration files. The main configuration file is usually called
     <code>httpd.conf</code>. The location of this file is set at
@@ -50,8 +51,8 @@ HTTP server.</p>
     added using the <directive module="core">Include</directive>
     directive, and wildcards can be used to include many configuration
     files. 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.</p>
+    files. Changes to the main configuration files are only
+    recognized by httpd when it is started or restarted.</p>
 
     <p>The server also reads a file containing mime document types;
     the filename is set by the <directive
@@ -62,24 +63,59 @@ HTTP server.</p>
   <section id="syntax">
     <title>Syntax of the Configuration Files</title>
 
-    <p>Apache configuration files contain one directive per line.
-    The back-slash "\" may be used as the last character on a line
+    <p>httpd configuration files contain one directive per line.
+    The backslash "\" 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.</p>
+    backslash and the end of the line.</p>
+
+    <p>Arguments to directives are separated by whitespace. If an
+    argument contains spaces, you must enclose that argument in quotes.</p>
 
     <p>Directives in the configuration files are case-insensitive,
     but arguments to directives are often case sensitive. Lines
     that begin with the hash character "#" are considered
     comments, and are ignored. Comments may <strong>not</strong> 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.</p>
+    included on the same line as a configuration directive.
+    White space occurring before a directive is ignored, so
+    you may indent directives for clarity. Blank lines are also ignored.</p>
+
+    <p>The values of variables defined with the <directive
+    module="core">Define</directive> of or shell environment variables can
+    be used in configuration file lines using the syntax <code>${VAR}</code>.
+    If "VAR" is the name of a valid variable, the value of that variable is
+    substituted into that spot in the configuration file line, and processing
+    continues as if that text were found directly in the configuration file.
+    Variables defined with <directive module="core">Define</directive> take
+    precedence over shell environment variables.
+    If the "VAR" variable is not found, the characters <code>${VAR}</code>
+    are left unchanged, and a warning is logged.
+    Variable names may not contain colon ":" characters, to avoid clashes with
+    <directive module="mod_rewrite">RewriteMap</directive>'s syntax.</p>
+
+    <p>Only shell environment variables defined before the server is started
+    can be used in expansions. Environment variables defined in the
+    configuration file itself, for example with <directive
+    module="mod_env">SetEnv</directive>, take effect too late to be used for
+    expansions in the configuration file.</p>
+
+    <p>The maximum length of a line in normal configuration files, after
+    variable substitution and joining any continued lines, is approximately
+    16 MiB. In <a href="configuring.html#htaccess">.htaccess files</a>, the
+    maximum length is 8190 characters.</p>
 
     <p>You can check your configuration files for syntax errors
     without starting the server by using <code>apachectl
     configtest</code> or the <code>-t</code> command line
     option.</p>
+
+    <p>You can use <module>mod_info</module>'s <code>-DDUMP_CONFIG</code> to
+    dump the configuration with all included files and environment
+    variables resolved and all comments and non-matching
+    <directive module="core" type="section">IfDefine</directive> and
+    <directive module="core" type="section">IfModule</directive> sections
+    removed. However, the output does not reflect the merging or overriding
+    that may happen for repeated directives.</p>
   </section>
 
   <section id="modules">
@@ -95,24 +131,29 @@ HTTP server.</p>
       </directivelist>
     </related>
 
-    <p>Apache is a modular server. This implies that only the most
+    <p>httpd is a modular server. This implies that only the most
     basic functionality is included in the core server. Extended
     features are available through <a
     href="mod/">modules</a> which can be loaded
-    into Apache. By default, a <a
+    into httpd. By default, a <a
     href="mod/module-dict.html#Status">base</a> set of modules is
     included in the server at compile-time. If the server is
     compiled to use <a href="dso.html">dynamically loaded</a>
     modules, then modules can be compiled separately and added at
     any time using the <directive module="mod_so">LoadModule</directive>
     directive.
-    Otherwise, Apache must be recompiled to add or remove modules.
+    Otherwise, httpd 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<directive
-    module="core" type="section">IfModule</directive> block.</p>
+    presence of a particular module by enclosing them in an <directive
+    module="core" type="section">IfModule</directive> block. However,
+    <directive type="section">IfModule</directive> blocks are not
+    required, and in some cases may mask the fact that you're missing an
+    important module.</p>
 
     <p>To see which modules are currently compiled into the server,
-    you can use the <code>-l</code> command line option.</p>
+    you can use the <code>-l</code> command line option. You can also
+    see what modules are loaded dynamically using the <code>-M</code>
+    command line option.</p>
   </section>
 
   <section id="scope">
@@ -145,7 +186,7 @@ HTTP server.</p>
     locations or URLs. They can also be nested, allowing for very
     fine grained configuration.</p>
 
-    <p>Apache has the capability to serve many different websites
+    <p>httpd has the capability to serve many different websites
     simultaneously. This is called <a href="vhosts/">Virtual
     Hosting</a>. Directives can also be scoped by placing them
     inside <directive module="core" type="section">VirtualHost</directive>
@@ -173,7 +214,7 @@ HTTP server.</p>
       </directivelist>
     </related>
 
-    <p>Apache allows for decentralized management of configuration
+    <p>httpd allows for decentralized management of configuration
     via special files placed inside the web tree. The special files
     are usually called <code>.htaccess</code>, but any name can be
     specified in the <directive module="core">AccessFileName</directive>