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