| // ======================================================================== |
| // Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd. |
| // ======================================================================== |
| // All rights reserved. This program and the accompanying materials |
| // are made available under the terms of the Eclipse Public License v1.0 |
| // and Apache License v2.0 which accompanies this distribution. |
| // |
| // The Eclipse Public License is available at |
| // http://www.eclipse.org/legal/epl-v10.html |
| // |
| // The Apache License v2.0 is available at |
| // http://www.opensource.org/licenses/apache2.0.php |
| // |
| // You may elect to redistribute this code under either of these licenses. |
| // ======================================================================== |
| |
| [[configuring-virtual-hosts]] |
| === Configuring Virtual Hosts |
| |
| 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 link:#different-virtual-hosts-different-contexts[different], then a virtual host needs to be configured for each deployed link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] to indicate which names a context will respond to. |
| |
| Virtual hosts are set on a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] by calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-[`setVirtualHosts`] or link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#addVirtualHosts-java.lang.String:A-[`addVirtualHost`] method which can be done in several ways: |
| |
| * Using a link:#deployable-descriptor-file[context XML] file in the webapps directory (see the example in link:{SRCDIR}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/webapps/test.xml[test.xml] in the Jetty distribution). |
| * Creating a link:#deployment-architecture[custom deployer] with a binding to configure virtual hosts for all contexts found in the same `webapps` directory. |
| * Calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-[API] directly on an link:#advanced-embedding[embedded] usage. |
| * Using a `WEB-INF/jetty-web.xml` file (now deprecated). |
| |
| [[configuring-a-virtual-host]] |
| ==== 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 link:{JDURL}/org/eclipse/jetty/server/AbstractConnector.html#setName(java.lang.String)[Connector.setName(String)]. |
| www.√integral.com:: |
| Non-ASCII and http://en.wikipedia.org/wiki/Internationalized_domain_name[IDN] domain names can be set as virtual hosts using http://en.wikipedia.org/wiki/Punycode[Puny Code] equivalents that may be obtained from a http://network-tools.com/idn-convert.asp[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 link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler]. |
| Lets look at an example where we configure a web application - represented by the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[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 link:#deployable-descriptor-file[context XML] file: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> |
| |
| <Configure class="org.eclipse.jetty.webapp.WebAppContext"> |
| <Set name="contextPath">/blah</Set> |
| <Set name="war"><Property name="jetty.webapps"/>/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> |
| ---- |
| |
| [[different-virtual-hosts-different-contexts]] |
| ==== 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 link:#deployable-descriptor-file[contextXML] files, one for each webapp yields the following: |
| |
| For `blah` webapp: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> |
| |
| <Configure class="org.eclipse.jetty.webapp.WebAppContext"> |
| <Set name="contextPath">/blah</Set> |
| <Set name="war"><Property name="jetty.webapps"/>/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: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> |
| |
| <Configure class="org.eclipse.jetty.webapp.WebAppContext"> |
| <Set name="contextPath">/other</Set> |
| <Set name="war"><Property name="jetty.webapps"/>/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` |
| |
| [[different-virtual-hosts-different-context-same-path]] |
| ==== 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 like__all__ 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: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> |
| |
| <Configure class="org.eclipse.jetty.webapp.WebAppContext"> |
| <Set name="contextPath">/</Set> |
| <Set name="war"><Property name="jetty.webapps"/>/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: |
| |
| [source, xml, subs="{sub-order}"] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> |
| |
| <Configure class="org.eclipse.jetty.webapp.WebAppContext"> |
| <Set name="contextPath">/</Set> |
| <Set name="war"><Property name="jetty.webapps"/>/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> |
| ---- |
