granicus.if.org Git - apache/blob - docs/manual/vhosts/examples.xml

   1 <?xml version='1.0' encoding='UTF-8' ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.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 <manualpage metafile="examples.xml.meta">
  22 <parentdocument href="./">Virtual Hosts</parentdocument>
  23     <title>VirtualHost Examples</title>
  24
  25 <summary>
  26
  27     <p>This document attempts to answer the commonly-asked questions about
  28     setting up virtual hosts. These scenarios are those involving multiple
  29     web sites running on a single server, via <a
  30     href="name-based.html">name-based</a> or <a
  31     href="ip-based.html">IP-based</a> virtual hosts. A document should be
  32     coming soon about running sites on several servers behind a single
  33     proxy server.</p>
  34
  35 </summary>
  36
  37   <section id="purename"><title>Running several name-based web
  38     sites on a single IP address.</title>
  39
  40     <p>Your server has a single IP address, and multiple aliases (CNAMES)
  41     point to this machine in DNS. You want to run a web server for
  42     <code>www.example1.com</code> and <code>www.example2.org</code> on this
  43     machine.</p>
  44
  45     <note><title>Note</title><p>Creating virtual
  46           host configurations on your Apache server does not magically
  47           cause DNS entries to be created for those host names. You
  48           <em>must</em> have the names in DNS, resolving to your IP
  49           address, or nobody else will be able to see your web site. You
  50           can put entries in your <code>hosts</code> file for local
  51           testing, but that will work only from the machine with those
  52           hosts entries.</p>
  53     </note>
  54
  55     <example>
  56     <title>Server configuration</title>
  57
  58     # Ensure that Apache listens on port 80<br />
  59     Listen 80<br />
  60     <br />
  61     # Listen for virtual host requests on all IP addresses<br />
  62     NameVirtualHost *<br />
  63     <br />
  64     &lt;VirtualHost *&gt;<br />
  65     <indent>
  66       DocumentRoot /www/example1<br />
  67       ServerName www.example1.com<br />
  68       <br />
  69       # Other directives here<br />
  70       <br />
  71     </indent>
  72     &lt;/VirtualHost&gt;<br />
  73     <br />
  74     &lt;VirtualHost *&gt;<br />
  75     <indent>
  76       DocumentRoot /www/example2<br />
  77       ServerName www.example2.org<br />
  78       <br />
  79       # Other directives here<br />
  80       <br />
  81     </indent>
  82     &lt;/VirtualHost&gt;
  83     </example>
  84
  85     <p>The asterisks match all addresses, so the main server serves no
  86     requests. Due to the fact that <code>www.example1.com</code> is first
  87     in the configuration file, it has the highest priority and can be seen
  88     as the <cite>default</cite> or <cite>primary</cite> server. That means
  89     that if a request is received that does not match one of the specified
  90     <code>ServerName</code> directives, it will be served by this first
  91     <code>VirtualHost</code>.</p>
  92
  93     <note>
  94             <title>Note</title>
  95
  96             <p>You can, if you wish, replace <code>*</code> with the actual
  97             IP address of the system. In that case, the argument to
  98             <code>VirtualHost</code> <em>must</em> match the argument to
  99             <code>NameVirtualHost</code>:</p>
 100
 101             <example>
 102             NameVirtualHost 172.20.30.40<br />
 103                                                 <br />
 104             &lt;VirtualHost 172.20.30.40&gt;<br />
 105                         # etc ...
 106             </example>
 107
 108            <p>However, it is additionally useful to use <code>*</code>
 109            on systems where the IP address is not predictable - for
 110            example if you have a dynamic IP address with your ISP, and
 111            you are using some variety of dynamic DNS solution. Since
 112            <code>*</code> matches any IP address, this configuration
 113            would work without changes whenever your IP address
 114            changes.</p>
 115     </note>
 116
 117     <p>The above configuration is what you will want to use in almost
 118     all name-based virtual hosting situations. The only thing that this
 119     configuration will not work for, in fact, is when you are serving
 120     different content based on differing IP addresses or ports.</p>
 121
 122         </section>
 123
 124         <section id="twoips"><title>Name-based hosts on more than one
 125     IP address.</title>
 126
 127         <note>
 128                   <title>Note</title><p>Any of the
 129           techniques discussed here can be extended to any number of IP
 130           addresses.</p>
 131     </note>
 132
 133     <p>The server has two IP addresses. On one (<code>172.20.30.40</code>), we
 134     will serve the "main" server, <code>server.domain.com</code> and on the
 135     other (<code>172.20.30.50</code>), we will serve two or more virtual hosts.</p>
 136
 137     <example>
 138     <title>Server configuration</title>
 139
 140     Listen 80<br />
 141                 <br />
 142     # This is the "main" server running on 172.20.30.40<br />
 143     ServerName server.domain.com<br />
 144     DocumentRoot /www/mainserver<br />
 145                 <br />
 146     # This is the other address<br />
 147     NameVirtualHost 172.20.30.50<br />
 148                 <br />
 149     &lt;VirtualHost 172.20.30.50&gt;<br />
 150     <indent>
 151         DocumentRoot /www/example1<br />
 152         ServerName www.example1.com<br />
 153                         <br />
 154         # Other directives here ...<br />
 155                                 <br />
 156     </indent>
 157     &lt;/VirtualHost&gt;<br />
 158                 <br />
 159     &lt;VirtualHost 172.20.30.50&gt;<br />
 160     <indent>
 161         DocumentRoot /www/example2<br />
 162         ServerName www.example2.org<br />
 163                                 <br />
 164         # Other directives here ...<br />
 165                                 <br />
 166     </indent>
 167     &lt;/VirtualHost&gt;
 168     </example>
 169
 170     <p>Any request to an address other than <code>172.20.30.50</code> will be
 171     served from the main server. A request to <code>172.20.30.50</code> with an
 172     unknown hostname, or no <code>Host:</code> header, will be served from
 173     <code>www.example1.com</code>.</p>
 174
 175         </section>
 176
 177         <section id="intraextra"><title>Serving the same content on
 178     different IP addresses (such as an internal and external
 179     address).</title>
 180
 181     <p>The server machine has two IP addresses (<code>192.168.1.1</code>
 182     and <code>172.20.30.40</code>). The machine is sitting between an
 183     internal (intranet) network and an external (internet) network. Outside
 184     of the network, the name <code>server.example.com</code> resolves to
 185     the external address (<code>172.20.30.40</code>), but inside the
 186     network, that same name resolves to the internal address
 187     (<code>192.168.1.1</code>).</p>
 188
 189     <p>The server can be made to respond to internal and external requests
 190     with the same content, with just one <code>VirtualHost</code>
 191     section.</p>
 192
 193     <example>
 194     <title>Server configuration</title>
 195
 196     NameVirtualHost 192.168.1.1<br />
 197     NameVirtualHost 172.20.30.40<br />
 198                 <br />
 199     &lt;VirtualHost 192.168.1.1 172.20.30.40&gt;<br />
 200     <indent>
 201         DocumentRoot /www/server1<br />
 202         ServerName server.example.com<br />
 203         ServerAlias server<br />
 204     </indent>
 205     &lt;/VirtualHost&gt;
 206     </example>
 207
 208     <p>Now requests from both networks will be served from the same
 209     <code>VirtualHost</code>.</p>
 210
 211     <note>
 212           <title>Note:</title><p>On the internal
 213           network, one can just use the name <code>server</code> rather
 214           than the fully qualified host name
 215           <code>server.example.com</code>.</p>
 216
 217           <p>Note also that, in the above example, you can replace the list
 218           of IP addresses with <code>*</code>, which will cause the server to
 219           respond the same on all addresses.</p>
 220     </note>
 221
 222         </section>
 223
 224         <section id="port"><title>Running different sites on different
 225     ports.</title>
 226
 227     <p>You have multiple domains going to the same IP and also want to
 228     serve multiple ports. By defining the ports in the "NameVirtualHost"
 229     tag, you can allow this to work. If you try using &lt;VirtualHost
 230     name:port&gt; without the NameVirtualHost name:port or you try to use
 231     the Listen directive, your configuration will not work.</p>
 232
 233     <example>
 234     <title>Server configuration</title>
 235
 236     Listen 80<br />
 237     Listen 8080<br />
 238                 <br />
 239     NameVirtualHost 172.20.30.40:80<br />
 240     NameVirtualHost 172.20.30.40:8080<br />
 241                 <br />
 242     &lt;VirtualHost 172.20.30.40:80&gt;<br />
 243     <indent>
 244         ServerName www.example1.com<br />
 245         DocumentRoot /www/domain-80<br />
 246     </indent>
 247     &lt;/VirtualHost&gt;<br />
 248                 <br />
 249     &lt;VirtualHost 172.20.30.40:8080&gt;<br />
 250     <indent>
 251         ServerName www.example1.com<br />
 252         DocumentRoot /www/domain-8080<br />
 253     </indent>
 254     &lt;/VirtualHost&gt;<br />
 255                 <br />
 256     &lt;VirtualHost 172.20.30.40:80&gt;<br />
 257     <indent>
 258         ServerName www.example2.org<br />
 259         DocumentRoot /www/otherdomain-80<br />
 260     </indent>
 261     &lt;/VirtualHost&gt;<br />
 262                 <br />
 263     &lt;VirtualHost 172.20.30.40:8080&gt;<br />
 264     <indent>
 265         ServerName www.example2.org<br />
 266         DocumentRoot /www/otherdomain-8080<br />
 267     </indent>
 268     &lt;/VirtualHost&gt;
 269     </example>
 270
 271         </section>
 272
 273         <section id="ip"><title>IP-based virtual hosting</title>
 274
 275     <p>The server has two IP addresses (<code>172.20.30.40</code> and
 276     <code>172.20.30.50</code>) which resolve to the names
 277     <code>www.example1.com</code> and <code>www.example2.org</code>
 278     respectively.</p>
 279
 280     <example>
 281     <title>Server configuration</title>
 282
 283     Listen 80<br />
 284                 <br />
 285     &lt;VirtualHost 172.20.30.40&gt;<br />
 286     <indent>
 287         DocumentRoot /www/example1<br />
 288         ServerName www.example1.com<br />
 289     </indent>
 290     &lt;/VirtualHost&gt;<br />
 291                 <br />
 292     &lt;VirtualHost 172.20.30.50&gt;<br />
 293     <indent>
 294         DocumentRoot /www/example2<br />
 295         ServerName www.example2.org<br />
 296     </indent>
 297     &lt;/VirtualHost&gt;
 298     </example>
 299
 300     <p>Requests for any address not specified in one of the
 301     <code>&lt;VirtualHost&gt;</code> directives (such as
 302     <code>localhost</code>, for example) will go to the main server, if
 303     there is one.</p>
 304
 305         </section>
 306
 307         <section id="ipport"><title>Mixed port-based and ip-based virtual
 308         hosts</title>
 309
 310     <p>The server machine has two IP addresses (<code>172.20.30.40</code> and
 311     <code>172.20.30.50</code>) which resolve to the names
 312     <code>www.example1.com</code> and <code>www.example2.org</code>
 313     respectively. In each case, we want to run hosts on ports 80 and
 314     8080.</p>
 315
 316     <example>
 317     <title>Server configuration</title>
 318
 319     Listen 172.20.30.40:80<br />
 320     Listen 172.20.30.40:8080<br />
 321     Listen 172.20.30.50:80<br />
 322     Listen 172.20.30.50:8080<br />
 323                 <br />
 324     &lt;VirtualHost 172.20.30.40:80&gt;<br />
 325     <indent>
 326         DocumentRoot /www/example1-80<br />
 327         ServerName www.example1.com<br />
 328     </indent>
 329     &lt;/VirtualHost&gt;<br />
 330                 <br />
 331     &lt;VirtualHost 172.20.30.40:8080&gt;<br />
 332     <indent>
 333         DocumentRoot /www/example1-8080<br />
 334         ServerName www.example1.com<br />
 335                 </indent>
 336     &lt;/VirtualHost&gt;<br />
 337                 <br />
 338     &lt;VirtualHost 172.20.30.50:80&gt;<br />
 339     <indent>
 340         DocumentRoot /www/example2-80<br />
 341         ServerName www.example1.org<br />
 342     </indent>
 343     &lt;/VirtualHost&gt;<br />
 344                 <br />
 345     &lt;VirtualHost 172.20.30.50:8080&gt;<br />
 346     <indent>
 347         DocumentRoot /www/example2-8080<br />
 348         ServerName www.example2.org<br />
 349     </indent>
 350     &lt;/VirtualHost&gt;
 351     </example>
 352
 353         </section>
 354
 355         <section id="mixed"><title>Mixed name-based and IP-based
 356     vhosts</title>
 357
 358     <p>On some of my addresses, I want to do name-based virtual hosts, and
 359     on others, IP-based hosts.</p>
 360
 361     <example>
 362     <title>Server configuration</title>
 363
 364     Listen 80<br />
 365                 <br />
 366     NameVirtualHost 172.20.30.40<br />
 367                 <br />
 368     &lt;VirtualHost 172.20.30.40&gt;<br />
 369     <indent>
 370         DocumentRoot /www/example1<br />
 371         ServerName www.example1.com<br />
 372     </indent>
 373     &lt;/VirtualHost&gt;<br />
 374                 <br />
 375     &lt;VirtualHost 172.20.30.40&gt;<br />
 376     <indent>
 377         DocumentRoot /www/example2<br />
 378         ServerName www.example2.org<br />
 379     </indent>
 380     &lt;/VirtualHost&gt;<br />
 381                 <br />
 382     &lt;VirtualHost 172.20.30.40&gt;<br />
 383     <indent>
 384         DocumentRoot /www/example3<br />
 385         ServerName www.example3.net<br />
 386     </indent>
 387     &lt;/VirtualHost&gt;<br />
 388                 <br />
 389     # IP-based<br />
 390     &lt;VirtualHost 172.20.30.50&gt;<br />
 391     <indent>
 392         DocumentRoot /www/example4<br />
 393         ServerName www.example4.edu<br />
 394     </indent>
 395     &lt;/VirtualHost&gt;<br />
 396                 <br />
 397     &lt;VirtualHost 172.20.30.60&gt;<br />
 398     <indent>
 399         DocumentRoot /www/example5<br />
 400         ServerName www.example5.gov<br />
 401     </indent>
 402     &lt;/VirtualHost&gt;
 403     </example>
 404
 405         </section>
 406
 407         <section id="default"><title>Using <code>_default_</code>
 408     vhosts</title>
 409
 410         <section id="defaultallports"><title><code>_default_</code> vhosts
 411     for all ports</title>
 412
 413     <p>Catching <em>every</em> request to any unspecified IP address and
 414     port, <em>i.e.</em>, an address/port combination that is not used for
 415     any other virtual host.</p>
 416
 417     <example>
 418     <title>Server configuration</title>
 419
 420     &lt;VirtualHost _default_:*&gt;<br />
 421     <indent>
 422         DocumentRoot /www/default<br />
 423     </indent>
 424     &lt;/VirtualHost&gt;
 425     </example>
 426
 427     <p>Using such a default vhost with a wildcard port effectively prevents
 428     any request going to the main server.</p>
 429
 430     <p>A default vhost never serves a request that was sent to an
 431     address/port that is used for name-based vhosts. If the request
 432     contained an unknown or no <code>Host:</code> header it is always
 433     served from the primary name-based vhost (the vhost for that
 434     address/port appearing first in the configuration file).</p>
 435
 436     <p>You can use <directive module="mod_alias">AliasMatch</directive> or
 437     <directive module="mod_rewrite">RewriteRule</directive> to rewrite any
 438     request to a single information page (or script).</p>
 439     </section>
 440
 441     <section id="defaultdifferentports"><title><code>_default_</code> vhosts
 442     for different ports</title>
 443
 444     <p>Same as setup 1, but the server listens on several ports and we want
 445     to use a second <code>_default_</code> vhost for port 80.</p>
 446
 447     <example>
 448     <title>Server configuration</title>
 449
 450     &lt;VirtualHost _default_:80&gt;<br />
 451     <indent>
 452         DocumentRoot /www/default80<br />
 453         # ...<br />
 454     </indent>
 455     &lt;/VirtualHost&gt;<br />
 456                 <br />
 457     &lt;VirtualHost _default_:*&gt;<br />
 458     <indent>
 459         DocumentRoot /www/default<br />
 460         # ...<br />
 461     </indent>
 462     &lt;/VirtualHost&gt;
 463     </example>
 464
 465     <p>The default vhost for port 80 (which <em>must</em> appear before any
 466     default vhost with a wildcard port) catches all requests that were sent
 467     to an unspecified IP address. The main server is never used to serve a
 468     request.</p>
 469     </section>
 470
 471     <section id="defaultoneport"><title><code>_default_</code> vhosts
 472     for one port</title>
 473
 474     <p>We want to have a default vhost for port 80, but no other default
 475     vhosts.</p>
 476
 477     <example>
 478     <title>Server configuration</title>
 479
 480     &lt;VirtualHost _default_:80&gt;<br />
 481     DocumentRoot /www/default<br />
 482     ...<br />
 483     &lt;/VirtualHost&gt;
 484     </example>
 485
 486     <p>A request to an unspecified address on port 80 is served from the
 487     default vhost any other request to an unspecified address and port is
 488     served from the main server.</p>
 489     </section>
 490
 491         </section>
 492
 493         <section id="migrate"><title>Migrating a name-based vhost to an
 494     IP-based vhost</title>
 495
 496     <p>The name-based vhost with the hostname
 497     <code>www.example2.org</code> (from our <a
 498     href="#name">name-based</a> example, setup 2) should get its own IP
 499     address. To avoid problems with name servers or proxies who cached the
 500     old IP address for the name-based vhost we want to provide both
 501     variants during a migration phase.<br />
 502      The solution is easy, because we can simply add the new IP address
 503     (<code>172.20.30.50</code>) to the <code>VirtualHost</code>
 504     directive.</p>
 505
 506     <example>
 507     <title>Server configuration</title>
 508
 509     Listen 80<br />
 510     ServerName www.example1.com<br />
 511     DocumentRoot /www/example1<br />
 512                 <br />
 513     NameVirtualHost 172.20.30.40<br />
 514                 <br />
 515     &lt;VirtualHost 172.20.30.40 172.20.30.50&gt;<br />
 516     <indent>
 517         DocumentRoot /www/example2<br />
 518         ServerName www.example2.org<br />
 519         # ...<br />
 520     </indent>
 521     &lt;/VirtualHost&gt;<br />
 522                 <br />
 523     &lt;VirtualHost 172.20.30.40&gt;<br />
 524     <indent>
 525         DocumentRoot /www/example3<br />
 526         ServerName www.example3.net<br />
 527         ServerAlias *.example3.net<br />
 528         # ...<br />
 529     </indent>
 530     &lt;/VirtualHost&gt;
 531     </example>
 532
 533     <p>The vhost can now be accessed through the new address (as an
 534     IP-based vhost) and through the old address (as a name-based
 535     vhost).</p>
 536
 537         </section>
 538
 539         <section id="serverpath"><title>Using the <code>ServerPath</code>
 540         directive</title>
 541
 542     <p>We have a server with two name-based vhosts. In order to match the
 543     correct virtual host a client must send the correct <code>Host:</code>
 544     header. Old HTTP/1.0 clients do not send such a header and Apache has
 545     no clue what vhost the client tried to reach (and serves the request
 546     from the primary vhost). To provide as much backward compatibility as
 547     possible we create a primary vhost which returns a single page
 548     containing links with an URL prefix to the name-based virtual
 549     hosts.</p>
 550
 551     <example>
 552     <title>Server configuration</title>
 553
 554     NameVirtualHost 172.20.30.40<br />
 555                 <br />
 556     &lt;VirtualHost 172.20.30.40&gt;<br />
 557     <indent>
 558         # primary vhost<br />
 559         DocumentRoot /www/subdomain<br />
 560         RewriteEngine On<br />
 561         RewriteRule ^/.* /www/subdomain/index.html<br />
 562         # ...<br />
 563     </indent>
 564     &lt;/VirtualHost&gt;<br />
 565                 <br />
 566     &lt;VirtualHost 172.20.30.40&gt;<br />
 567     DocumentRoot /www/subdomain/sub1<br />
 568     <indent>
 569         ServerName www.sub1.domain.tld<br />
 570         ServerPath /sub1/<br />
 571         RewriteEngine On<br />
 572         RewriteRule ^(/sub1/.*) /www/subdomain$1<br />
 573         # ...<br />
 574     </indent>
 575     &lt;/VirtualHost&gt;<br />
 576                 <br />
 577     &lt;VirtualHost 172.20.30.40&gt;<br />
 578     <indent>
 579         DocumentRoot /www/subdomain/sub2<br />
 580         ServerName www.sub2.domain.tld<br />
 581         ServerPath /sub2/<br />
 582         RewriteEngine On<br />
 583         RewriteRule ^(/sub2/.*) /www/subdomain$1<br />
 584         # ...<br />
 585     </indent>
 586     &lt;/VirtualHost&gt;
 587     </example>
 588
 589     <p>Due to the <directive module="core">ServerPath</directive>
 590     directive a request to the URL
 591     <code>http://www.sub1.domain.tld/sub1/</code> is <em>always</em> served
 592     from the sub1-vhost.<br /> A request to the URL
 593     <code>http://www.sub1.domain.tld/</code> is only
 594     served from the sub1-vhost if the client sent a correct
 595     <code>Host:</code> header. If no <code>Host:</code> header is sent the
 596     client gets the information page from the primary host.<br />
 597      Please note that there is one oddity: A request to
 598     <code>http://www.sub2.domain.tld/sub1/</code> is also served from the
 599     sub1-vhost if the client sent no <code>Host:</code> header.<br />
 600      The <directive module="mod_rewrite">RewriteRule</directive> directives
 601     are used to make sure that a client which sent a correct
 602     <code>Host:</code> header can use both URL variants, <em>i.e.</em>,
 603     with or without URL prefix.</p>
 604
 605         </section>
 606
 607 </manualpage>