| <?xml version='1.0' encoding='UTF-8' ?> |
| <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd"> |
| <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| 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 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <manualpage metafile="configuring.xml.meta"> |
| |
| <title>Configuration Files</title> |
| |
| <summary> |
| <p>This document describes the files used to configure Apache HTTP |
| Server.</p> |
| </summary> |
| |
| <section id="main"> |
| <title>Main Configuration Files</title> |
| <related> |
| <modulelist> |
| <module>mod_mime</module> |
| </modulelist> |
| <directivelist> |
| <directive module="core" type="section">IfDefine</directive> |
| <directive module="core">Include</directive> |
| <directive module="mod_mime">TypesConfig</directive> |
| </directivelist> |
| </related> |
| |
| <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 |
| compile-time, but may be overridden with the <code>-f</code> |
| command line flag. In addition, other configuration files may be |
| 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 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 |
| module="mod_mime">TypesConfig</directive> directive, |
| and is <code>mime.types</code> by default.</p> |
| </section> |
| |
| <section id="syntax"> |
| <title>Syntax of the Configuration Files</title> |
| |
| <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 |
| 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 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"> |
| <title>Modules</title> |
| |
| <related> |
| <modulelist> |
| <module>mod_so</module> |
| </modulelist> |
| <directivelist> |
| <directive module="core" type="section">IfModule</directive> |
| <directive module="mod_so">LoadModule</directive> |
| </directivelist> |
| </related> |
| |
| <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 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, 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. 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. You can also |
| see what modules are loaded dynamically using the <code>-M</code> |
| command line option.</p> |
| </section> |
| |
| <section id="scope"> |
| <title>Scope of Directives</title> |
| |
| <related> |
| <directivelist> |
| <directive module="core" type="section">Directory</directive> |
| <directive module="core" type="section">DirectoryMatch</directive> |
| <directive module="core" type="section">Files</directive> |
| <directive module="core" type="section">FilesMatch</directive> |
| <directive module="core" type="section">Location</directive> |
| <directive module="core" type="section">LocationMatch</directive> |
| <directive module="core" type="section">VirtualHost</directive> |
| </directivelist> |
| </related> |
| |
| <p>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 <directive module="core" |
| type="section">Directory</directive>, <directive module="core" |
| type="section">DirectoryMatch</directive>, <directive module="core" |
| type="section">Files</directive>, <directive module="core" |
| type="section">FilesMatch</directive>, <directive module="core" |
| type="section">Location</directive>, and <directive module="core" |
| type="section">LocationMatch</directive> |
| 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.</p> |
| |
| <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> |
| sections, so that they will only apply to requests for a |
| particular website.</p> |
| |
| <p>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 <a |
| href="mod/directive-dict.html#Context">Context</a> of the |
| directive. For further information, we provide details on <a |
| href="sections.html">How Directory, Location and Files sections |
| work</a>.</p> |
| </section> |
| |
| <section id="htaccess"> |
| <title>.htaccess Files</title> |
| |
| <related> |
| <directivelist> |
| <directive module="core">AccessFileName</directive> |
| <directive module="core">AllowOverride</directive> |
| </directivelist> |
| </related> |
| |
| <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> |
| directive. Directives placed in <code>.htaccess</code> files |
| apply to the directory where you place the file, and all |
| sub-directories. The <code>.htaccess</code> files follow the |
| same syntax as the main configuration files. Since |
| <code>.htaccess</code> files are read on every request, changes |
| made in these files take immediate effect.</p> |
| |
| <p>To find which directives can be placed in |
| <code>.htaccess</code> files, check the <a |
| href="mod/directive-dict.html#Context">Context</a> of the |
| directive. The server administrator further controls what |
| directives may be placed in <code>.htaccess</code> files by |
| configuring the <directive module="core">AllowOverride</directive> |
| directive in the main configuration files.</p> |
| |
| <p>For more information on <code>.htaccess</code> files, see |
| the <a href="howto/htaccess.html">.htaccess tutorial</a>.</p> |
| </section> |
| </manualpage> |