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