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