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

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
   4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>mod_vhost_alias - Apache HTTP Server Version 2.5</title>
  11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  18 <body>
  19 <div id="page-header">
  20 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  21 <p class="apache">Apache HTTP Server Version 2.5</p>
  22 <img alt="" src="../images/feather.png" /></div>
  23 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  24 <div id="path">
  25 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
  26 <div id="page-content">
  27 <div id="preamble"><h1>Apache Module mod_vhost_alias</h1>
  28 <div class="toplang">
  29 <p><span>Available Languages: </span><a href="../en/mod/mod_vhost_alias.html" title="English">&nbsp;en&nbsp;</a> |
  30 <a href="../fr/mod/mod_vhost_alias.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  31 <a href="../tr/mod/mod_vhost_alias.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  32 </div>
  33 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides for dynamically configured mass virtual
  34 hosting</td></tr>
  35 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  36 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>vhost_alias_module</td></tr>
  37 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_vhost_alias.c</td></tr></table>
  38 <h3>Summary</h3>
  39
  40     <p>This module creates dynamically configured virtual hosts, by
  41     allowing the IP address and/or the <code>Host:</code> header of
  42     the HTTP request to be used as part of the pathname to
  43     determine what files to serve. This allows for easy use of a
  44     huge number of virtual hosts with similar configurations.</p>
  45
  46     <div class="note"><h3>Note</h3>
  47       <p>If <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> or <code class="module"><a href="../mod/mod_userdir.html">mod_userdir</a></code> are
  48       used for translating URIs to filenames, they will override the
  49       directives of <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> described below. For
  50       example, the following configuration will map <code>
  51       /cgi-bin/script.pl</code> to <code>
  52       /usr/local/apache2/cgi-bin/script.pl</code> in all cases:</p>
  53
  54       <pre class="prettyprint lang-config">ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/"
  55 VirtualScriptAlias "/never/found/%0/cgi-bin/"</pre>
  56
  57     </div>
  58 </div>
  59 <div id="quickview"><h3>Topics</h3>
  60 <ul id="topics">
  61 <li><img alt="" src="../images/down.gif" /> <a href="#interpol">Directory Name Interpolation</a></li>
  62 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
  63 </ul><h3 class="directives">Directives</h3>
  64 <ul id="toc">
  65 <li><img alt="" src="../images/down.gif" /> <a href="#virtualdocumentroot">VirtualDocumentRoot</a></li>
  66 <li><img alt="" src="../images/down.gif" /> <a href="#virtualdocumentrootip">VirtualDocumentRootIP</a></li>
  67 <li><img alt="" src="../images/down.gif" /> <a href="#virtualscriptalias">VirtualScriptAlias</a></li>
  68 <li><img alt="" src="../images/down.gif" /> <a href="#virtualscriptaliasip">VirtualScriptAliasIP</a></li>
  69 </ul>
  70 <h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&amp;list_id=144532&amp;product=Apache%20httpd-2&amp;query_format=specific&amp;order=changeddate%20DESC%2Cpriority%2Cbug_severity&amp;component=mod_vhost_alias">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&amp;component=mod_vhost_alias">Report a bug</a></li></ul><h3>See also</h3>
  71 <ul class="seealso">
  72 <li><code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code></li>
  73 <li><a href="../vhosts/mass.html">Dynamically configured mass
  74     virtual hosting</a></li>
  75 <li><a href="#comments_section">Comments</a></li></ul></div>
  76 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  77 <div class="section">
  78 <h2><a name="interpol" id="interpol">Directory Name Interpolation</a></h2>
  79
  80
  81     <p>All the directives in this module interpolate a string into
  82     a pathname. The interpolated string (henceforth called the
  83     "name") may be either the server name (see the <code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code>
  84     directive for details on how this is determined) or the IP
  85     address of the virtual host on the server in dotted-quad
  86     format. The interpolation is controlled by specifiers inspired
  87     by <code>printf</code> which have a number of formats:</p>
  88
  89 <table>
  90
  91 <tr><td><code>%%</code></td>
  92 <td>insert a <code>%</code></td></tr>
  93
  94 <tr><td><code>%p</code></td>
  95 <td>insert the port number of the virtual host</td></tr>
  96
  97 <tr><td><code>%N.M</code></td>
  98 <td>insert (part of) the name</td></tr>
  99
 100 </table>
 101
 102     <p><code>N</code> and <code>M</code> are used to specify
 103     substrings of the name. <code>N</code> selects from the
 104     dot-separated components of the name, and <code>M</code>
 105     selects characters within whatever <code>N</code> has selected.
 106     <code>M</code> is optional and defaults to zero if it isn't
 107     present; the dot must be present if and only if <code>M</code>
 108     is present. The interpretation is as follows:</p>
 109
 110     <table>
 111
 112       <tr><td><code>0</code></td>
 113       <td>the whole name</td></tr>
 114
 115       <tr><td><code>1</code></td>
 116       <td>the first part</td></tr>
 117
 118       <tr><td><code>2</code></td>
 119       <td>the second part</td></tr>
 120
 121       <tr><td><code>-1</code></td>
 122       <td>the last part</td></tr>
 123
 124       <tr><td><code>-2</code></td>
 125       <td>the penultimate part</td></tr>
 126
 127       <tr><td><code>2+</code></td>
 128       <td>the second and all subsequent parts</td></tr>
 129
 130       <tr><td><code>-2+</code></td>
 131       <td>the penultimate and all preceding parts</td></tr>
 132
 133       <tr><td><code>1+</code> and <code>-1+</code></td>
 134       <td>the same as <code>0</code></td></tr>
 135     </table>
 136
 137     <p>If <code>N</code> or <code>M</code> is greater than the number
 138     of parts available a single underscore is interpolated. </p>
 139
 140 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 141 <div class="section">
 142 <h2><a name="examples" id="examples">Examples</a></h2>
 143
 144
 145     <p>For simple name-based virtual hosts you might use the
 146     following directives in your server configuration file:</p>
 147
 148     <pre class="prettyprint lang-config">UseCanonicalName    Off
 149 VirtualDocumentRoot "/usr/local/apache/vhosts/%0"</pre>
 150
 151
 152     <p>A request for
 153     <code>http://www.example.com/directory/file.html</code> will be
 154     satisfied by the file
 155     <code>/usr/local/apache/vhosts/www.example.com/directory/file.html</code>.
 156     </p>
 157
 158     <p>For a very large number of virtual hosts it is a good idea
 159     to arrange the files to reduce the size of the
 160     <code>vhosts</code> directory. To do this you might use the
 161     following in your configuration file:</p>
 162
 163     <pre class="prettyprint lang-config">UseCanonicalName    Off
 164 VirtualDocumentRoot "/usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2"</pre>
 165
 166
 167     <p>A request for
 168     <code>http://www.domain.example.com/directory/file.html</code>
 169     will be satisfied by the file
 170     <code>/usr/local/apache/vhosts/example.com/d/o/m/domain/directory/file.html</code>.</p>
 171
 172     <p>A more even spread of files can be achieved by hashing from the
 173     end of the name, for example: </p>
 174
 175 <pre class="prettyprint lang-config">VirtualDocumentRoot "/usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2"</pre>
 176
 177
 178     <p>The example request would come from
 179     <code>/usr/local/apache/vhosts/example.com/n/i/a/domain/directory/file.html</code>.</p>
 180
 181     <p>Alternatively you might use: </p>
 182
 183 <pre class="prettyprint lang-config">VirtualDocumentRoot "/usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+"</pre>
 184
 185
 186     <p>The example request would come from
 187     <code>/usr/local/apache/vhosts/example.com/d/o/m/ain/directory/file.html</code>.</p>
 188
 189 <p> A very common request by users is the ability to point multiple domains to multiple
 190 document roots without having to worry about the length or number of parts of the
 191 hostname being requested. If the requested hostname is <code>sub.www.domain.example.com</code>
 192  instead of simply <code>www.domain.example.com</code>, then using %3+ will result in the document
 193 root being <code>/usr/local/apache/vhosts/domain.example.com/...</code> instead of the
 194 intended <code>example.com</code> directory. In such cases, it can be beneficial to use
 195 the combination <code>%-2.0.%-1.0</code>, which will always yield the domain name and the
 196 tld, for example <code>example.com</code> regardless of the number of subdomains appended
 197 to the hostname. As such, one can make a configuration that will direct all first, second
 198 or third level subdomains to the same directory:
 199 </p>
 200 <pre class="prettyprint lang-config">VirtualDocumentRoot "/usr/local/apache/vhosts/%-2.0.%-1.0"</pre>
 201
 202 <p>
 203 In the example above, both <code>www.example.com</code> as well as <code>www.sub.example.com</code>
 204 or <code>example.com</code> will all point to <code>/usr/local/apache/vhosts/example.com</code>.
 205 </p>
 206
 207     <p>For IP-based virtual hosting you might use the following in
 208     your configuration file:</p>
 209
 210     <pre class="prettyprint lang-config">UseCanonicalName DNS
 211 VirtualDocumentRootIP "/usr/local/apache/vhosts/%1/%2/%3/%4/docs"
 212 VirtualScriptAliasIP  "/usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin"</pre>
 213
 214
 215     <p>A request for
 216     <code>http://www.domain.example.com/directory/file.html</code>
 217     would be satisfied by the file
 218     <code>/usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html</code>
 219     if the IP address of <code>www.domain.example.com</code> were
 220     10.20.30.40. A request for
 221     <code>http://www.domain.example.com/cgi-bin/script.pl</code> would
 222     be satisfied by executing the program
 223     <code>/usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl</code>.</p>
 224
 225     <p>If you want to include the <code>.</code> character in a
 226     <code>VirtualDocumentRoot</code> directive, but it clashes with
 227     a <code>%</code> directive, you can work around the problem in
 228     the following way:</p>
 229
 230     <pre class="prettyprint lang-config">VirtualDocumentRoot "/usr/local/apache/vhosts/%2.0.%3.0"</pre>
 231
 232
 233     <p>A request for
 234     <code>http://www.domain.example.com/directory/file.html</code>
 235     will be satisfied by the file
 236     <code>/usr/local/apache/vhosts/domain.example/directory/file.html</code>.</p>
 237
 238     <p>The <code class="directive"><a href="../mod/mod_log_config.html#logformat">LogFormat</a></code>
 239     directives <code>%V</code> and <code>%A</code> are useful
 240     in conjunction with this module.</p>
 241 </div>
 242 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 243 <div class="directive-section"><h2><a name="VirtualDocumentRoot" id="VirtualDocumentRoot">VirtualDocumentRoot</a> <a name="virtualdocumentroot" id="virtualdocumentroot">Directive</a></h2>
 244 <table class="directive">
 245 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the document root
 246 for a given virtual host</td></tr>
 247 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualDocumentRoot <em>interpolated-directory</em>|none</code></td></tr>
 248 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualDocumentRoot none</code></td></tr>
 249 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 250 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 251 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
 252 </table>
 253
 254     <p>The <code class="directive">VirtualDocumentRoot</code> directive allows you to
 255     determine where Apache HTTP Server will find your documents based on the
 256     value of the server name. The result of expanding
 257     <em>interpolated-directory</em> is used as the root of the
 258     document tree in a similar manner to the <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directive's argument.
 259     If <em>interpolated-directory</em> is <code>none</code> then
 260     <code class="directive">VirtualDocumentRoot</code> is turned off. This directive
 261     cannot be used in the same context as <code class="directive"><a href="#virtualdocumentrootip">VirtualDocumentRootIP</a></code>.</p>
 262
 263 <div class="warning"><h3>Note</h3>
 264 <code class="directive">VirtualDocumentRoot</code> will override any <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directives you may have put in the same
 265 context or child contexts. Putting a <code class="directive">VirtualDocumentRoot</code>
 266 in the global server scope will effectively override <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directives in any virtual hosts defined later
 267 on, unless you set <code class="directive">VirtualDocumentRoot</code> to <code>None</code>
 268 in each virtual host.
 269 </div>
 270
 271
 272 </div>
 273 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 274 <div class="directive-section"><h2><a name="VirtualDocumentRootIP" id="VirtualDocumentRootIP">VirtualDocumentRootIP</a> <a name="virtualdocumentrootip" id="virtualdocumentrootip">Directive</a></h2>
 275 <table class="directive">
 276 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the document root
 277 for a given virtual host</td></tr>
 278 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualDocumentRootIP <em>interpolated-directory</em>|none</code></td></tr>
 279 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualDocumentRootIP none</code></td></tr>
 280 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 281 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 282 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
 283 </table>
 284
 285 <p>The <code class="directive">VirtualDocumentRootIP</code> directive is like the
 286     <code class="directive"><a href="#virtualdocumentroot">VirtualDocumentRoot</a></code>
 287     directive, except that it uses the IP address of the server end
 288     of the connection for directory interpolation instead of the server
 289     name.</p>
 290
 291 </div>
 292 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 293 <div class="directive-section"><h2><a name="VirtualScriptAlias" id="VirtualScriptAlias">VirtualScriptAlias</a> <a name="virtualscriptalias" id="virtualscriptalias">Directive</a></h2>
 294 <table class="directive">
 295 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the CGI directory for
 296 a given virtual host</td></tr>
 297 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualScriptAlias <em>interpolated-directory</em>|none</code></td></tr>
 298 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualScriptAlias none</code></td></tr>
 299 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 300 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 301 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
 302 </table>
 303
 304     <p>The <code class="directive">VirtualScriptAlias</code> directive allows you to
 305     determine where Apache httpd will find CGI scripts in a similar
 306     manner to <code class="directive"><a href="#virtualdocumentroot">VirtualDocumentRoot</a></code> does for other documents. It matches
 307     requests for URIs starting <code>/cgi-bin/</code>, much like <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
 308     <code>/cgi-bin/</code> would.</p>
 309
 310
 311 </div>
 312 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 313 <div class="directive-section"><h2><a name="VirtualScriptAliasIP" id="VirtualScriptAliasIP">VirtualScriptAliasIP</a> <a name="virtualscriptaliasip" id="virtualscriptaliasip">Directive</a></h2>
 314 <table class="directive">
 315 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the CGI directory for
 316 a given virtual host</td></tr>
 317 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualScriptAliasIP <em>interpolated-directory</em>|none</code></td></tr>
 318 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualScriptAliasIP none</code></td></tr>
 319 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 320 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 321 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
 322 </table>
 323
 324     <p>The <code class="directive">VirtualScriptAliasIP</code> directive is like the
 325     <code class="directive"><a href="#virtualscriptalias">VirtualScriptAlias</a></code>
 326     directive, except that it uses the IP address of the server end
 327     of the connection for directory interpolation instead of the server
 328     name.</p>
 329
 330
 331 </div>
 332 </div>
 333 <div class="bottomlang">
 334 <p><span>Available Languages: </span><a href="../en/mod/mod_vhost_alias.html" title="English">&nbsp;en&nbsp;</a> |
 335 <a href="../fr/mod/mod_vhost_alias.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
 336 <a href="../tr/mod/mod_vhost_alias.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
 337 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
 338 <script type="text/javascript"><!--//--><![CDATA[//><!--
 339 var comments_shortname = 'httpd';
 340 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_vhost_alias.html';
 341 (function(w, d) {
 342     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 343         d.write('<div id="comments_thread"><\/div>');
 344         var s = d.createElement('script');
 345         s.type = 'text/javascript';
 346         s.async = true;
 347         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 348         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 349     }
 350     else {
 351         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 352     }
 353 })(window, document);
 354 //--><!]]></script></div><div id="footer">
 355 <p class="apache">Copyright 2017 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 356 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 357 if (typeof(prettyPrint) !== 'undefined') {
 358     prettyPrint();
 359 }
 360 //--><!]]></script>
 361 </body></html>