private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery
This page contains content that we have migrated from Jetty 7 or Jetty 8 documentation into the correct format, but we have not yet audited it for technical accuracy in with Jetty 9. Be aware that examples or information contained on this page may be incorrect. Please check back soon as we continue improving the documentation, or submit corrections yourself to this page through Github. Thank you.
A virtual host is an alternative name, registered in DNS, for an IP address. Virtual hosting takes one of two forms:
Multiple names can resolve to a single IP address.
Multi-homed hosts, that is machines with more than one network interface, can have a different name for each IP address.
Jetty users often want to configure their web applications taking into account these different virtual hosts. Frequently, a machine with a single IP address has different DNS resolvable names associated with it, and a webapp deployed on it must be reachable from all of the alternative names. Another possibility is to serve different web applications from different virtual hosts.
You can set virtual hosts in various ways, including:
Using a context XML file in the context directory: setVirtualHosts.
This is the preferred method.
Java calls in an embedded usage: ???.
Within an explicitly deployed webapp (no deployer) listed in [[Jetty/Reference/jetty.xml|jetty.xml]] or similar.
Using a WEB-INF/jetty-web.xml
file
(deprecated, but works with the webapp provider if you do not use the
context provider).
For descriptions of the various ways to configure Jetty, including links to documents that provide detailed configuration instructions, see ???.
The examples that follow set virtual hosts in the preferred way, by
calling the method ContextHandler
.
setVirtualHosts.
When configuring a web application, you can supply a list of IP addresses and names at which the web application is reachable. Suppose you have a machine with these IP addresses and DNS resolvable names:
333.444.555.666
127.0.0.1
www.blah.com
www.blah.net
www.blah.org
Suppose you have a webapp, xxx.war, that you want all of the above names and addresses to serve. You would configure the webapp as follows:
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/xxx</Set> <Set name="war"><SystemProperty name="jetty.home"/>/webapps/xxx.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>
Assuming you have configured a connector listening on port 8080, webapp xxx.war is available at all of the following addresses:
http://333.444.555.666:8080/xxx
http://127.0.0.1:8080/xxx
http://www.blah.com:8080/xxx
http://www.blah.net:8080/xxx
http://www.blah.org:8080/xxx
You can configure different webapps for different virtual hosts by supplying a different list of virtual hosts for each webapp. For example, suppose your imaginary machine has these DNS names and IP addresses:
333.444.555.666
127.0.0.1
www.blah.com
www.blah.net
www.blah.org
777.888.888.111
www.other.com
www.other.net
www.other.org
Suppose also you have another webapp, zzz.war. You want xxx.war to deploy as above, and zzz.war to deploy only from 777.888.888.111, www.other.com, www.other.net and www.other.org:
<!-- webapp xxx.war --> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/xxx</Set> <Set name="war"><SystemProperty name="jetty.home"/>/webapps/xxx.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>
<!-- webapp zzz.war --> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/zzz</Set> <Set name="war"><SystemProperty name="jetty.home"/>/webapps/zzz.war</Set> <Set name="virtualHosts"> <Array type="java.lang.String"> <Item>777.888.888.111</Item> <Item>www.other.com</Item> <Item>www.other.net</Item> <Item>www.other.org</Item> </Array> </Set> </Configure>
Webapp xxx.war is still available at:
http://333.444.555.666:8080/xxx
http://127.0.0.1:8080/xxx
http://www.blah.com:8080/xxx
http://www.blah.net:8080/xxx
http://www.blah.org:8080/xxx
But now webapp ''zzz.war'' is available at:
http://777.888.888.111:8080/zzz
http://www.other.com:8080/zzz
http://www.other.net:8080/zzz
http://www.other.org:8080/zzz
In the example above, webapp zzz.war is
available not only at a certain set of virtual hosts, but also at the
context path /zzz
, whilst the other webapp is available at
both a different set of virtual hosts, and at a
different context path. What happens if you want them at the
same context path, but still at different sets of
virtual hosts? You just supply the same context path
for each webapp, leaving the disjoint set of virtual host definitions as
before:
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="war"><SystemProperty name="jetty.home"/>/webapps/xxx.war</Set> <Set name="contextPath">/</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>
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="war"><SystemProperty name="jetty.home"/>/webapps/zzz.war</Set> <Set name="contextPath">/</Set> <Set name="virtualHosts"> <Array type="java.lang.String"> <Item>777.888.888.111</Item> <Item>www.other.com</Item> <Item>www.other.net</Item> <Item>www.other.org</Item> </Array> </Set> </Configure>
Now, webapp xxx.war is available at:
http://333.444.555.666:8080/
http://127.0.0.1:8080/
http://www.blah.com:8080/
http://www.blah.net:8080/
http://www.blah.org:8080/
and webapp zzz.war is available at:
http://777.888.888.111:8080/
http://www.other.com:8080/
http://www.other.net:8080/
http://www.other.org:8080/
International
domain names are names containing non-ascii characters. For example
"http://www.bücher.com"
. The DNS internally remains
based on ascii, so these kinds of names are translated via an encoding
called punycode
into an ascii representation. Modern browsers detect these non-ascii
characters in URLs and automatically apply the punycode encoding. For
example, typing this URL into a browser:
http://www.åäö.com:8080/test/
translates to the following url:
http://www.xn--4cab6c.com:8080/test/
To use internationalized domain names with Jetty virtual hosts you need to supply the punycode form of the name in your context xml file (and of course you need to supply it to your DNS setup).
For example, if you are running a webapp on port 8080 at context
/test, and you want to configure a virtual host for
www.åäö.com
, you configure its ascii equivalent in
the context xml file for the context:
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/</Set> <Set name="war"><SystemProperty name="jetty.home" default="."/>/webapps/test.war</Set> <Set name="virtualHosts"> <Array type="String"> <Item>www.xn--4cab6c.com</Item> </Array> </Set> </Configure>
After starting Jetty, you can enter the url
http://www.åäö.com:8080/test/
in a browser and reach
the webapp.
If you don't have any webapps deployed at /, hitting the URL
http://www.åäö.com:8080
reaches Jetty's default
handler, which serves back a 404 page listing the available
contexts:
Error 404 - Not Found No context on this server matched or handled this request. Contexts known to this server are: /test @ www.xn--4cab6c.com:8080 ---> WebAppContext@82d210@82d210/test,file:/tmp/Jetty_0_0_0_0_8080_test.war__test_www.xn..4cab6c.com_1jadjg/webapp/,/home/janb/src/jetty-eclipse/jetty/trunk/jetty-distribution/target/distribution/webapps/test.war
Notice that the link already has the punycode transformed domain name in it.
See an error or something missing? Contribute to this documentation at Github!