granicus.if.org Git - apache/blob - docs/manual/mod/mod_vhost_alias.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4
   5 <!--
   6  Copyright 2002-2004 The Apache Software Foundation
   7
   8  Licensed under the Apache License, Version 2.0 (the "License");
   9  you may not use this file except in compliance with the License.
  10  You may obtain a copy of the License at
  11
  12      http://www.apache.org/licenses/LICENSE-2.0
  13
  14  Unless required by applicable law or agreed to in writing, software
  15  distributed under the License is distributed on an "AS IS" BASIS,
  16  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  See the License for the specific language governing permissions and
  18  limitations under the License.
  19 -->
  20
  21 <modulesynopsis metafile="mod_vhost_alias.xml.meta">
  22
  23 <name>mod_vhost_alias</name>
  24 <description>Provides for dynamically configured mass virtual
  25 hosting</description>
  26 <status>Extension</status>
  27 <sourcefile>mod_vhost_alias.c</sourcefile>
  28 <identifier>vhost_alias_module</identifier>
  29
  30 <summary>
  31     <p>This module creates dynamically configured virtual hosts, by
  32     allowing the IP address and/or the <code>Host:</code> header of
  33     the HTTP request to be used as part of the pathname to
  34     determine what files to serve. This allows for easy use of a
  35     huge number of virtual hosts with similar configurations.</p>
  36
  37     <note><title>Note</title>
  38       <p>If <module>mod_alias</module> or <module>mod_userdir</module> are
  39       used for translating URIs to filenames, they will override the
  40       directives of <module>mod_vhost_alias</module> described below. For
  41       example, the following configuration will map <code>
  42       /cgi-bin/script.pl</code> to <code>
  43       /usr/local/apache2/cgi-bin/script.pl</code> in all cases:</p>
  44
  45       <example>
  46         ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/<br />
  47         VirtualScriptAlias /never/found/%0/cgi-bin/
  48       </example>
  49     </note>
  50 </summary>
  51
  52 <seealso><directive module="core">UseCanonicalName</directive></seealso>
  53 <seealso><a href="../vhosts/mass.html">Dynamically configured mass
  54     virtual hosting</a></seealso>
  55
  56 <section id="interpol">
  57     <title>Directory Name Interpolation</title>
  58
  59     <p>All the directives in this module interpolate a string into
  60     a pathname. The interpolated string (henceforth called the
  61     "name") may be either the server name (see the <directive
  62     module="core">UseCanonicalName</directive>
  63     directive for details on how this is determined) or the IP
  64     address of the virtual host on the server in dotted-quad
  65     format. The interpolation is controlled by specifiers inspired
  66     by <code>printf</code> which have a number of formats:</p>
  67
  68 <table>
  69
  70 <tr><td><code>%%</code></td>
  71 <td>insert a <code>%</code></td></tr>
  72
  73 <tr><td><code>%p</code></td>
  74 <td>insert the port number of the virtual host</td></tr>
  75
  76 <tr><td><code>%N.M</code></td>
  77 <td>insert (part of) the name</td></tr>
  78
  79 </table>
  80
  81     <p><code>N</code> and <code>M</code> are used to specify
  82     substrings of the name. <code>N</code> selects from the
  83     dot-separated components of the name, and <code>M</code>
  84     selects characters within whatever <code>N</code> has selected.
  85     <code>M</code> is optional and defaults to zero if it isn't
  86     present; the dot must be present if and only if <code>M</code>
  87     is present. The interpretation is as follows:</p>
  88
  89     <table>
  90       <tr><td><code>0</code></td>
  91       <td>the whole name</td></tr>
  92
  93       <tr><td><code>1</code></td>
  94       <td>the first part</td></tr>
  95
  96       <tr><td><code>2</code></td>
  97       <td>the second part</td></tr>
  98
  99       <tr><td><code>-1</code></td>
 100       <td>the last part</td></tr>
 101
 102       <tr><td><code>-2</code></td>
 103       <td>the penultimate part</td></tr>
 104
 105       <tr><td><code>2+</code></td>
 106       <td>the second and all subsequent parts</td></tr>
 107
 108       <tr><td><code>-2+</code></td>
 109       <td>the penultimate and all preceding parts</td></tr>
 110
 111       <tr><td><code>1+</code> and <code>-1+</code></td>
 112       <td>the same as <code>0</code></td></tr>
 113     </table>
 114
 115     <p>If <code>N</code> or <code>M</code> is greater than the number
 116     of parts available a single underscore is interpolated. </p>
 117
 118 </section>
 119
 120 <section id="examples">
 121     <title>Examples</title>
 122
 123     <p>For simple name-based virtual hosts you might use the
 124     following directives in your server configuration file:</p>
 125
 126     <example>
 127       UseCanonicalName    Off<br />
 128       VirtualDocumentRoot /usr/local/apache/vhosts/%0
 129     </example>
 130
 131     <p>A request for
 132     <code>http://www.example.com/directory/file.html</code> will be
 133     satisfied by the file
 134     <code>/usr/local/apache/vhosts/www.example.com/directory/file.html</code>.
 135     </p>
 136
 137     <p>For a very large number of virtual hosts it is a good idea
 138     to arrange the files to reduce the size of the
 139     <code>vhosts</code> directory. To do this you might use the
 140     following in your configuration file:</p>
 141
 142     <example>
 143       UseCanonicalName    Off<br />
 144       VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2
 145     </example>
 146
 147     <p>A request for
 148     <code>http://www.domain.example.com/directory/file.html</code>
 149     will be satisfied by the file
 150     <code>/usr/local/apache/vhosts/example.com/d/o/m/domain/directory/file.html</code>.</p>
 151
 152     <p>A more even spread of files can be achieved by hashing from the
 153     end of the name, for example: </p>
 154
 155 <example>
 156     VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2
 157 </example>
 158
 159     <p>The example request would come from
 160     <code>/usr/local/apache/vhosts/example.com/n/i/a/domain/directory/file.html</code>.</p>
 161
 162     <p>Alternatively you might use: </p>
 163
 164 <example>
 165     VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+
 166 </example>
 167
 168     <p>The example request would come from
 169     <code>/usr/local/apache/vhosts/example.com/d/o/m/ain/directory/file.html</code>.</p>
 170
 171     <p>For IP-based virtual hosting you might use the following in
 172     your configuration file:</p>
 173
 174     <example>
 175       UseCanonicalName DNS<br />
 176       VirtualDocumentRootIP /usr/local/apache/vhosts/%1/%2/%3/%4/docs<br />
 177       VirtualScriptAliasIP  /usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin
 178     </example>
 179
 180     <p>A request for
 181     <code>http://www.domain.example.com/directory/file.html</code>
 182     would be satisfied by the file
 183     <code>/usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html</code>
 184     if the IP address of <code>www.domain.example.com</code> were
 185     10.20.30.40. A request for
 186     <code>http://www.domain.example.com/cgi-bin/script.pl</code> would
 187     be satisfied by executing the program
 188     <code>/usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl</code>.</p>
 189
 190     <p>If you want to include the <code>.</code> character in a
 191     <code>VirtualDocumentRoot</code> directive, but it clashes with
 192     a <code>%</code> directive, you can work around the problem in
 193     the following way:</p>
 194
 195 <example>
 196     VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0
 197 </example>
 198
 199     <p>A request for
 200     <code>http://www.domain.example.com/directory/file.html</code>
 201     will be satisfied by the file
 202     <code>/usr/local/apache/vhosts/domain.example/directory/file.html</code>.</p>
 203
 204     <p>The <directive module="mod_log_config">LogFormat</directive>
 205     directives <code>%V</code> and <code>%A</code> are useful
 206     in conjunction with this module.</p>
 207 </section>
 208
 209 <directivesynopsis>
 210 <name>VirtualDocumentRoot</name>
 211 <description>Dynamically configure the location of the document root
 212 for a given virtual host</description>
 213 <syntax>VirtualDocumentRoot <em>interpolated-directory</em>|none</syntax>
 214 <default>VirtualDocumentRoot none</default>
 215 <contextlist>
 216 <context>server config</context>
 217 <context>virtual host</context>
 218 </contextlist>
 219
 220 <usage>
 221
 222     <p>The <directive>VirtualDocumentRoot</directive> directive allows you to
 223     determine where Apache will find your documents based on the
 224     value of the server name. The result of expanding
 225     <em>interpolated-directory</em> is used as the root of the
 226     document tree in a similar manner to the <directive
 227     module="core">DocumentRoot</directive> directive's argument.
 228     If <em>interpolated-directory</em> is <code>none</code> then
 229     <directive>VirtualDocumentRoot</directive> is turned off. This directive
 230     cannot be used in the same context as <directive
 231     module="mod_vhost_alias">VirtualDocumentRootIP</directive>.</p>
 232
 233 </usage>
 234 </directivesynopsis>
 235
 236 <directivesynopsis>
 237 <name>VirtualDocumentRootIP</name>
 238 <description>Dynamically configure the location of the document root
 239 for a given virtual host</description>
 240 <syntax>VirtualDocumentRootIP <em>interpolated-directory</em>|none</syntax>
 241 <default>VirtualDocumentRootIP none</default>
 242 <contextlist>
 243 <context>server config</context>
 244 <context>virtual host</context>
 245 </contextlist>
 246
 247 <usage>
 248
 249 <p>The <directive>VirtualDocumentRootIP</directive> directive is like the
 250     <directive module="mod_vhost_alias">VirtualDocumentRoot</directive>
 251     directive, except that it uses the IP address of the server end
 252     of the connection for directory interpolation instead of the server
 253     name.</p>
 254 </usage>
 255 </directivesynopsis>
 256
 257 <directivesynopsis>
 258 <name>VirtualScriptAlias</name>
 259 <description>Dynamically configure the location of the CGI directory for
 260 a given virtual host</description>
 261 <syntax>VirtualScriptAlias <em>interpolated-directory</em>|none</syntax>
 262 <default>VirtualScriptAlias none</default>
 263 <contextlist>
 264 <context>server config</context>
 265 <context>virtual host</context>
 266 </contextlist>
 267
 268 <usage>
 269
 270     <p>The <directive>VirtualScriptAlias</directive> directive allows you to
 271     determine where Apache will find CGI scripts in a similar
 272     manner to <directive module="mod_vhost_alias"
 273     >VirtualDocumentRoot</directive> does for other documents. It matches
 274     requests for URIs starting <code>/cgi-bin/</code>, much like <directive
 275     module="mod_alias">ScriptAlias</directive>
 276     <code>/cgi-bin/</code> would.</p>
 277
 278 </usage>
 279 </directivesynopsis>
 280
 281 <directivesynopsis>
 282 <name>VirtualScriptAliasIP</name>
 283 <description>Dynamically configure the location of the cgi directory for
 284 a given virtual host</description>
 285 <syntax>VirtualScriptAliasIP <em>interpolated-directory</em>|none</syntax>
 286 <default>VirtualScriptAliasIP none</default>
 287 <contextlist>
 288 <context>server config</context>
 289 <context>virtual host</context>
 290 </contextlist>
 291
 292 <usage>
 293
 294     <p>The <directive>VirtualScriptAliasIP</directive> directive is like the
 295     <directive module="mod_vhost_alias">VirtualScriptAlias</directive>
 296     directive, except that it uses the IP address of the server end
 297     of the connection for directory interpolation instead of the server
 298     name.</p>
 299
 300     </usage>
 301
 302 </directivesynopsis>
 303 </modulesynopsis>
 304