Configuring Virtual Hosts

Configuring Virtual Hosts
Previous	Chapter 5. Configuring Contexts Home	Next

Virtual Host Names
Example Virtual Host Configuration
Using Different Sets of Virtual Hosts to Select Different Contexts
Using Different Sets of Virtual Hosts to Select Different Contexts at the Same Context Path

A virtual host is an alternative name, registered in DNS, for an IP address such that multiple domain names will resolve to the same IP of a shared server instance. If the content to be served to the aliases names is different, then a virtual host needs to be configured for each deployed context to indicate which names a context will respond to.

Virtual hosts are set on a context by calling the setVirtualHosts or addVirtualHost method which can be done in several ways:

Using a context XML file in the webapps directory (see the example in test.xml in the Jetty distribution).
Creating a custom deployer with a binding to configure virtual hosts for all contexts found in the same webapps directory.
Calling the API directly on an embedded usage.
Using a WEB-INF/jetty-web.xml file (now deprecated).

Virtual Host Names

Jetty supports the following styles of virtual host name:

www.hostname.com: A fully qualified host name. It is important to list all variants as a site may receive traffic from both www.hostname.com and just hostname.com
*.hostname.com: A wildcard qualified host which will match only one level of arbitrary names. *.foo.com will match www.foo.com and m.foo.com, but not www.other.foo.com
10.0.0.2: An IP address may be given as a virtual host name to indicate that a context should handle requests received on that server port that do not have a host name specified (HTTP/0.9 or HTTP/1.0).
@ConnectorName: A connector name, which is not strictly a virtual host, but instead will only match requests that are received on connectors that have a matching name set with Connector.setName(String).
www.√integral.com: Non-ASCII and IDN domain names can be set as virtual hosts using Puny Code equivalents that may be obtained from a Punycode/IDN converters. For example if the non-ASCII domain name www.√integral.com is given to a browser, then it will make a request that uses the domain name www.xn--integral-7g7d.com, which is the name that should be added as the virtual host name.

Example Virtual Host Configuration

Virtual hosts can be used with any context that is a subclass of ContextHandler. Lets look at an example where we configure a web application - represented by the WebAppContext class - with virtual hosts. You supply a list of IP addresses and names at which the web application is reachable, such as the following:

333.444.555.666
127.0.0.1
www.blah.com
www.blah.net
www.blah.org

Suppose you have a webapp called blah.war, that you want all of the above names and addresses to be served at path "/blah". Here’s how you would configure the virtual hosts with a context XML file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/blah</Set>
  <Set name="war"><Property name="jetty.webapps"/>blah.war</Set>
  <Set name="virtualHosts">
    <Array type="java.lang.String">
      <Item>333.444.555.666</Item>
      <Item>127.0.0.1</Item>
      <Item>www.blah.com</Item>
      <Item>www.blah.net</Item>
      <Item>www.blah.org</Item>
    </Array>
  </Set>
</Configure>

Using Different Sets of Virtual Hosts to Select Different Contexts

You can configure different contexts to respond on different virtual hosts by supplying a specific list of virtual hosts for each one.

For example, suppose your imaginary machine has these DNS names:

www.blah.com
www.blah.net
www.blah.org
www.other.com
www.other.net
www.other.org

Suppose also you have 2 webapps, one called blah.war that you would like served from the *.blah.* names, and one called other.war that you want served only from the *.other.* names.

Using the method of preparing contextXML files, one for each webapp yields the following:

For blah webapp:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/blah</Set>
  <Set name="war"><Property name="jetty.webapps"/>/blah.war</Set>
  <Set name="virtualHosts">
    <Array type="java.lang.String">
      <Item>www.blah.com</Item>
      <Item>www.blah.net</Item>
      <Item>www.blah.org</Item>
    </Array>
  </Set>
</Configure>

These URLs now resolve to the blah context (ie blah.war):

http://www.blah.com/blah
http://www.blah.net/blah
http://www.blah.org/blah

For other webapp:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/other</Set>
  <Set name="war"><Property name="jetty.webapps"/>/other.war</Set>
  <Set name="virtualHosts">
    <Array type="java.lang.String">
      <Item>www.other.com</Item>
      <Item>www.other.net</Item>
      <Item>www.other.org</Item>
    </Array>
  </Set>
</Configure>

These URLs now resolve to the other context (i.e. other.war):

http://www.other.com/other
http://www.other.net/other
http://www.other.org/other

Using Different Sets of Virtual Hosts to Select Different Contexts at the Same Context Path

In the previous section we setup 2 different contexts to be served from different virtual hosts at different context paths. However, there is no requirement that the context paths must be distinct: you may use the same context path for multiple contexts, and use virtual hosts to determine which one is served for a given request.

Consider an example where we have the same set of DNS names as before, and the same webapps blah.war and other.war. We still want blah.war to be served in response to hostnames of *.blah.*, and we still want other.war to be served in response to *.other.* names. However, we would likeall of our clients to use the "/" context path, no matter which context is being targeted.

In other words, we want all of the following URLs to map to blah.war:

http://www.blah.com/
http://www.blah.net/
http://www.blah.org/

Similarly, we want the following URLs to map to other.war:

http://www.other.com/
http://www.other.net/
http://www.other.org/

To achieve this, we simply use the same context path of / for each of our webapps, while still applying our different set of virtual host names.

For foo webapp:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/</Set>
  <Set name="war"><Property name="jetty.webapps"/>/foo.war</Set>
  <Set name="virtualHosts">
    <Array type="java.lang.String">
      <Item>www.blah.com</Item>
      <Item>www.blah.net</Item>
      <Item>www.blah.org</Item>
    </Array>
  </Set>
</Configure>

For bar webapp:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/</Set>
  <Set name="war"><Property name="jetty.webapps"/>/bar.war</Set>
  <Set name="virtualHosts">
    <Array type="java.lang.String">
      <Item>www.other.com</Item>
      <Item>www.other.net</Item>
      <Item>www.other.org</Item>
    </Array>
  </Set>
</Configure>

Previous	Top	Next
Chapter 5. Configuring Contexts	Home	Temporary Directories