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 <!-- $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 <a href="index.html">virtual hosts</a>. 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 multiple hostnames that resolve to a single address,
  42     and you want to respond differently for <code>www.example.com</code>
  43     and <code>www.example.org</code>.</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           <code>hosts</code> entries.</p>
  53     </note>
  54
  55     <highlight language="config">
  56 # Ensure that Apache listens on port 80
  57 Listen 80
  58 &lt;VirtualHost *:80&gt;
  59     DocumentRoot "/www/example1"
  60     ServerName www.example.com
  61
  62     # Other directives here
  63 &lt;/VirtualHost&gt;
  64
  65 &lt;VirtualHost *:80&gt;
  66     DocumentRoot "/www/example2"
  67     ServerName www.example.org
  68
  69     # Other directives here
  70 &lt;/VirtualHost&gt;
  71     </highlight>
  72
  73     <p>The asterisks match all addresses, so the main server serves no
  74     requests. Due to the fact that the virtual host with
  75     <code>ServerName www.example.com</code> is first
  76     in the configuration file, it has the highest priority and can be seen
  77     as the <cite>default</cite> or <cite>primary</cite> server. That means
  78     that if a request is received that does not match one of the specified
  79     <code>ServerName</code> directives, it will be served by this first
  80     <code>VirtualHost</code>.</p>
  81
  82     <p>The above configuration is what you will want to use in almost
  83     all name-based virtual hosting situations. The only thing that this
  84     configuration will not work for, in fact, is when you are serving
  85     different content based on differing IP addresses or ports.</p>
  86
  87     <note>
  88             <title>Note</title>
  89
  90            <p>You may replace <code>*</code> with a specific IP address
  91            on the system.  Such virtual hosts will only be used for
  92            HTTP requests received on connection to the specified IP
  93            address.</p>
  94
  95            <p>However, it is additionally useful to use <code>*</code>
  96            on systems where the IP address is not predictable - for
  97            example if you have a dynamic IP address with your ISP, and
  98            you are using some variety of dynamic DNS solution. Since
  99            <code>*</code> matches any IP address, this configuration
 100            would work without changes whenever your IP address
 101            changes.</p>
 102     </note>
 103   </section>
 104
 105   <section id="twoips"><title>Name-based hosts on more than one
 106     IP address.</title>
 107
 108     <note>
 109       <title>Note</title>
 110       <p>Any of the techniques discussed here can be extended to any
 111       number of IP addresses.</p>
 112     </note>
 113
 114     <p>The server has two IP addresses. On one (<code>172.20.30.40</code>), we
 115     will serve the "main" server, <code>server.example.com</code> and on the
 116     other (<code>172.20.30.50</code>), we will serve two or more virtual hosts.</p>
 117
 118     <highlight language="config">
 119 Listen 80
 120
 121 # This is the "main" server running on 172.20.30.40
 122 ServerName server.example.com
 123 DocumentRoot "/www/mainserver"
 124
 125 &lt;VirtualHost 172.20.30.50&gt;
 126     DocumentRoot "/www/example1"
 127     ServerName www.example.com
 128
 129     # Other directives here ...
 130 &lt;/VirtualHost&gt;
 131
 132 &lt;VirtualHost 172.20.30.50&gt;
 133     DocumentRoot "/www/example2"
 134     ServerName www.example.org
 135
 136     # Other directives here ...
 137 &lt;/VirtualHost&gt;
 138     </highlight>
 139
 140     <p>Any request to an address other than <code>172.20.30.50</code> will be
 141     served from the main server. A request to <code>172.20.30.50</code> with an
 142     unknown hostname, or no <code>Host:</code> header, will be served from
 143     <code>www.example.com</code>.</p>
 144
 145   </section>
 146
 147   <section id="intraextra"><title>Serving the same content on
 148     different IP addresses (such as an internal and external
 149     address).</title>
 150
 151     <p>The server machine has two IP addresses (<code>192.168.1.1</code>
 152     and <code>172.20.30.40</code>). The machine is sitting between an
 153     internal (intranet) network and an external (internet) network. Outside
 154     of the network, the name <code>server.example.com</code> resolves to
 155     the external address (<code>172.20.30.40</code>), but inside the
 156     network, that same name resolves to the internal address
 157     (<code>192.168.1.1</code>).</p>
 158
 159     <p>The server can be made to respond to internal and external requests
 160     with the same content, with just one <code>VirtualHost</code>
 161     section.</p>
 162
 163     <highlight language="config">
 164 &lt;VirtualHost 192.168.1.1 172.20.30.40&gt;
 165     DocumentRoot "/www/server1"
 166     ServerName server.example.com
 167     ServerAlias server
 168 &lt;/VirtualHost&gt;
 169     </highlight>
 170
 171     <p>Now requests from both networks will be served from the same
 172     <code>VirtualHost</code>.</p>
 173
 174     <note>
 175           <title>Note:</title><p>On the internal
 176           network, one can just use the name <code>server</code> rather
 177           than the fully qualified host name
 178           <code>server.example.com</code>.</p>
 179
 180           <p>Note also that, in the above example, you can replace the list
 181           of IP addresses with <code>*</code>, which will cause the server to
 182           respond the same on all addresses.</p>
 183     </note>
 184
 185   </section>
 186
 187   <section id="port"><title>Running different sites on different
 188     ports.</title>
 189
 190     <p>You have multiple domains going to the same IP and also want to
 191     serve multiple ports.  The example below illustrates that the name-matching
 192     takes place after the best matching IP address and port combination
 193     is determined.</p>
 194
 195     <highlight language="config">
 196 Listen 80
 197 Listen 8080
 198
 199 &lt;VirtualHost 172.20.30.40:80&gt;
 200     ServerName www.example.com
 201     DocumentRoot "/www/domain-80"
 202 &lt;/VirtualHost&gt;
 203
 204 &lt;VirtualHost 172.20.30.40:8080&gt;
 205     ServerName www.example.com
 206     DocumentRoot "/www/domain-8080"
 207 &lt;/VirtualHost&gt;
 208
 209 &lt;VirtualHost 172.20.30.40:80&gt;
 210     ServerName www.example.org
 211     DocumentRoot "/www/otherdomain-80"
 212 &lt;/VirtualHost&gt;
 213
 214 &lt;VirtualHost 172.20.30.40:8080&gt;
 215     ServerName www.example.org
 216     DocumentRoot "/www/otherdomain-8080"
 217 &lt;/VirtualHost&gt;
 218     </highlight>
 219
 220   </section>
 221
 222   <section id="ip"><title>IP-based virtual hosting</title>
 223
 224     <p>The server has two IP addresses (<code>172.20.30.40</code> and
 225     <code>172.20.30.50</code>) which resolve to the names
 226     <code>www.example.com</code> and <code>www.example.org</code>
 227     respectively.</p>
 228
 229     <highlight language="config">
 230 Listen 80
 231
 232 &lt;VirtualHost 172.20.30.40&gt;
 233     DocumentRoot "/www/example1"
 234     ServerName www.example.com
 235 &lt;/VirtualHost&gt;
 236
 237 &lt;VirtualHost 172.20.30.50&gt;
 238     DocumentRoot "/www/example2"
 239     ServerName www.example.org
 240 &lt;/VirtualHost&gt;
 241     </highlight>
 242
 243     <p>Requests for any address not specified in one of the
 244     <code>&lt;VirtualHost&gt;</code> directives (such as
 245     <code>localhost</code>, for example) will go to the main server, if
 246     there is one.</p>
 247
 248   </section>
 249
 250   <section id="ipport"><title>Mixed port-based and ip-based virtual
 251   hosts</title>
 252
 253     <p>The server machine has two IP addresses (<code>172.20.30.40</code> and
 254     <code>172.20.30.50</code>) which resolve to the names
 255     <code>www.example.com</code> and <code>www.example.org</code>
 256     respectively. In each case, we want to run hosts on ports 80 and
 257     8080.</p>
 258
 259     <highlight language="config">
 260 Listen 172.20.30.40:80
 261 Listen 172.20.30.40:8080
 262 Listen 172.20.30.50:80
 263 Listen 172.20.30.50:8080
 264
 265 &lt;VirtualHost 172.20.30.40:80&gt;
 266     DocumentRoot "/www/example1-80"
 267     ServerName www.example.com
 268 &lt;/VirtualHost&gt;
 269
 270 &lt;VirtualHost 172.20.30.40:8080&gt;
 271     DocumentRoot "/www/example1-8080"
 272     ServerName www.example.com
 273 &lt;/VirtualHost&gt;
 274
 275 &lt;VirtualHost 172.20.30.50:80&gt;
 276     DocumentRoot "/www/example2-80"
 277     ServerName www.example.org
 278 &lt;/VirtualHost&gt;
 279
 280 &lt;VirtualHost 172.20.30.50:8080&gt;
 281     DocumentRoot "/www/example2-8080"
 282     ServerName www.example.org
 283 &lt;/VirtualHost&gt;
 284     </highlight>
 285
 286   </section>
 287
 288   <section id="mixed"><title>Mixed name-based and IP-based
 289     vhosts</title>
 290
 291     <p>Any address mentioned in the argument to a virtualhost that never
 292     appears in another virtual host is a strictly IP-based virtual host.</p>
 293
 294     <highlight language="config">
 295 Listen 80
 296 &lt;VirtualHost 172.20.30.40&gt;
 297     DocumentRoot "/www/example1"
 298     ServerName www.example.com
 299 &lt;/VirtualHost&gt;
 300
 301 &lt;VirtualHost 172.20.30.40&gt;
 302     DocumentRoot "/www/example2"
 303     ServerName www.example.org
 304 &lt;/VirtualHost&gt;
 305
 306 &lt;VirtualHost 172.20.30.40&gt;
 307     DocumentRoot "/www/example3"
 308     ServerName www.example.net
 309 &lt;/VirtualHost&gt;
 310
 311 # IP-based
 312 &lt;VirtualHost 172.20.30.50&gt;
 313     DocumentRoot "/www/example4"
 314     ServerName www.example.edu
 315 &lt;/VirtualHost&gt;
 316
 317 &lt;VirtualHost 172.20.30.60&gt;
 318     DocumentRoot "/www/example5"
 319     ServerName www.example.gov
 320 &lt;/VirtualHost&gt;
 321     </highlight>
 322
 323   </section>
 324
 325     <section id="proxy"><title>Using <code>Virtual_host</code> and
 326     mod_proxy together</title>
 327
 328     <p>The following example allows a front-end machine to proxy a
 329     virtual host through to a server running on another machine. In the
 330     example, a virtual host of the same name is configured on a machine
 331     at <code>192.168.111.2</code>. The <directive
 332     module="mod_proxy" name="ProxyPreserveHost">ProxyPreserveHost
 333     On</directive> directive is used so that the desired hostname is
 334     passed through, in case we are proxying multiple hostnames to a
 335     single machine.</p>
 336
 337     <highlight language="config">
 338 &lt;VirtualHost *:*&gt;
 339     ProxyPreserveHost On
 340     ProxyPass        "/" "http://192.168.111.2/"
 341     ProxyPassReverse "/" "http://192.168.111.2/"
 342     ServerName hostname.example.com
 343 &lt;/VirtualHost&gt;
 344     </highlight>
 345
 346     </section>
 347
 348   <section id="default"><title>Using <code>_default_</code>
 349     vhosts</title>
 350
 351     <section id="defaultallports"><title><code>_default_</code> vhosts
 352     for all ports</title>
 353
 354     <p>Catching <em>every</em> request to any unspecified IP address and
 355     port, <em>i.e.</em>, an address/port combination that is not used for
 356     any other virtual host.</p>
 357
 358     <highlight language="config">
 359 &lt;VirtualHost _default_:*&gt;
 360     DocumentRoot "/www/default"
 361 &lt;/VirtualHost&gt;
 362     </highlight>
 363
 364     <p>Using such a default vhost with a wildcard port effectively prevents
 365     any request going to the main server.</p>
 366
 367     <p>A default vhost never serves a request that was sent to an
 368     address/port that is used for name-based vhosts. If the request
 369     contained an unknown or no <code>Host:</code> header it is always
 370     served from the primary name-based vhost (the vhost for that
 371     address/port appearing first in the configuration file).</p>
 372
 373     <p>You can use <directive module="mod_alias">AliasMatch</directive> or
 374     <directive module="mod_rewrite">RewriteRule</directive> to rewrite any
 375     request to a single information page (or script).</p>
 376     </section>
 377
 378     <section id="defaultdifferentports"><title><code>_default_</code> vhosts
 379     for different ports</title>
 380
 381     <p>Same as setup 1, but the server listens on several ports and we want
 382     to use a second <code>_default_</code> vhost for port 80.</p>
 383
 384     <highlight language="config">
 385 &lt;VirtualHost _default_:80&gt;
 386     DocumentRoot "/www/default80"
 387     # ...
 388 &lt;/VirtualHost&gt;
 389
 390 &lt;VirtualHost _default_:*&gt;
 391     DocumentRoot "/www/default"
 392     # ...
 393 &lt;/VirtualHost&gt;
 394     </highlight>
 395
 396     <p>The default vhost for port 80 (which <em>must</em> appear before any
 397     default vhost with a wildcard port) catches all requests that were sent
 398     to an unspecified IP address. The main server is never used to serve a
 399     request.</p>
 400     </section>
 401
 402     <section id="defaultoneport"><title><code>_default_</code> vhosts
 403     for one port</title>
 404
 405     <p>We want to have a default vhost for port 80, but no other default
 406     vhosts.</p>
 407
 408     <highlight language="config">
 409 &lt;VirtualHost _default_:80&gt;
 410     DocumentRoot "/www/default"
 411 ...
 412 &lt;/VirtualHost&gt;
 413     </highlight>
 414
 415     <p>A request to an unspecified address on port 80 is served from the
 416     default vhost. Any other request to an unspecified address and port is
 417     served from the main server.</p>
 418
 419     <p>Any use of <code>*</code> in a virtual host declaration will have
 420     higher precedence than <code>_default_</code>.</p>
 421
 422     </section>
 423
 424   </section>
 425
 426   <section id="migrate"><title>Migrating a name-based vhost to an
 427     IP-based vhost</title>
 428
 429     <p>The name-based vhost with the hostname
 430     <code>www.example.org</code> (from our <a
 431     href="#name">name-based</a> example, setup 2) should get its own IP
 432     address. To avoid problems with name servers or proxies who cached the
 433     old IP address for the name-based vhost we want to provide both
 434     variants during a migration phase.</p>
 435
 436     <p>
 437      The solution is easy, because we can simply add the new IP address
 438     (<code>172.20.30.50</code>) to the <code>VirtualHost</code>
 439     directive.</p>
 440
 441     <highlight language="config">
 442 Listen 80
 443 ServerName www.example.com
 444 DocumentRoot "/www/example1"
 445
 446 &lt;VirtualHost 172.20.30.40 172.20.30.50&gt;
 447     DocumentRoot "/www/example2"
 448     ServerName www.example.org
 449     # ...
 450 &lt;/VirtualHost&gt;
 451
 452 &lt;VirtualHost 172.20.30.40&gt;
 453     DocumentRoot "/www/example3"
 454     ServerName www.example.net
 455     ServerAlias *.example.net
 456     # ...
 457 &lt;/VirtualHost&gt;
 458     </highlight>
 459
 460     <p>The vhost can now be accessed through the new address (as an
 461     IP-based vhost) and through the old address (as a name-based
 462     vhost).</p>
 463
 464   </section>
 465
 466   <section id="serverpath"><title>Using the <code>ServerPath</code>
 467   directive</title>
 468
 469     <p>We have a server with two name-based vhosts. In order to match the
 470     correct virtual host a client must send the correct <code>Host:</code>
 471     header. Old HTTP/1.0 clients do not send such a header and Apache has
 472     no clue what vhost the client tried to reach (and serves the request
 473     from the primary vhost). To provide as much backward compatibility as
 474     possible we create a primary vhost which returns a single page
 475     containing links with an URL prefix to the name-based virtual
 476     hosts.</p>
 477
 478     <highlight language="config">
 479 &lt;VirtualHost 172.20.30.40&gt;
 480     # primary vhost
 481     DocumentRoot "/www/subdomain"
 482     RewriteEngine On
 483     RewriteRule . /www/subdomain/index.html
 484     # ...
 485 &lt;/VirtualHost&gt;
 486
 487 &lt;VirtualHost 172.20.30.40&gt;
 488     DocumentRoot "/www/subdomain/sub1"
 489     ServerName www.sub1.domain.tld
 490     ServerPath /sub1/
 491     RewriteEngine On
 492     RewriteRule ^(/sub1/.*) /www/subdomain$1
 493     # ...
 494 &lt;/VirtualHost&gt;
 495
 496 &lt;VirtualHost 172.20.30.40&gt;
 497     DocumentRoot "/www/subdomain/sub2"
 498     ServerName www.sub2.domain.tld
 499     ServerPath /sub2/
 500     RewriteEngine On
 501     RewriteRule ^(/sub2/.*) /www/subdomain$1
 502     # ...
 503 &lt;/VirtualHost&gt;
 504     </highlight>
 505
 506     <p>Due to the <directive module="core">ServerPath</directive>
 507     directive a request to the URL
 508     <code>http://www.sub1.domain.tld/sub1/</code> is <em>always</em> served
 509     from the sub1-vhost.<br /> A request to the URL
 510     <code>http://www.sub1.domain.tld/</code> is only
 511     served from the sub1-vhost if the client sent a correct
 512     <code>Host:</code> header. If no <code>Host:</code> header is sent the
 513     client gets the information page from the primary host.</p>
 514
 515     <p>Please note that there is one oddity: A request to
 516     <code>http://www.sub2.domain.tld/sub1/</code> is also served from the
 517     sub1-vhost if the client sent no <code>Host:</code> header.</p>
 518
 519     <p>The <directive module="mod_rewrite">RewriteRule</directive> directives
 520     are used to make sure that a client which sent a correct
 521     <code>Host:</code> header can use both URL variants, <em>i.e.</em>,
 522     with or without URL prefix.</p>
 523
 524   </section>
 525
 526 </manualpage>