By jluehe on Dec 13, 2006
Virtual Hosting Features in GlassFish
- Isolation levels
- Root context configuration choices
- Alternate docroots
This document describes the virtual hosting features available in GlassFish v2.
Virtual hosting refers to the ability to run several web sites (domains) from a single physical server machine with a single IP address. Each web site is identified by its domain (host) name. HTTP requests are routed to the appropriate domain based on their host name. In order for this name-based form of virtual hosting (also known as shared IP hosting) to work, the DNS must be configured in such a way that each hosted domain name resolves to the server's IP address. Virtual hosting enables ISP/ASP business models.
In name-based virtual hosting, virtual servers are isolated by their host (domain) names. Each virtual server is assigned a unique host (domain) name, and may also be assigned one or more alias names. The web container will route a request to a virtual server based on the host name in the request URL.
GlassFish provides one additional level of isolation between virtual servers: at the HTTP port level, which allows virtual servers to be assigned HTTP ports for their exclusive use.
In GlassFish, it is possible to associate a virtual server with only a subset of the configured HTTP listeners: A virtual server will receive only those requests that were received on any of the HTTP listeners listed in its
http-listeners attribute. As a result of this, virtual servers, or groups of them, may be isolated from
each other at the HTTP port level by configuring their
http-listeners attributes with mutually exclusive sets of HTTP listeners.
Isolation at the HTTP port level is not supported by Tomcat, where a virtual server is always bound to all HTTP listeners that belong to the same
<Service> unit as the
<Engine> unit to which the virtual server belongs. (In Tomcat, a
<Service> element represents the combination of one or more
<Connector> components that share a single
<Engine> component for processing incoming requests, where an
<Engine> contains one or more
<Host> children, each with one or more
Consider the following request mapping table:
Target Virtual Server
The above request mapping requirements, which isolate virtual servers
vs-2at both the domain name and HTTP port levels, can be configured very easily in GlassFish, by leveraging the
<virtual-server>, as follows:
<http-listener id="http-listener-1" port="1111"/> <http-listener id="http-listener-2" port="2222" security-enabled="true"> <ssl cert-nickname="nickname-1"/> </http-listener> <http-listener id="http-listener-3" port="3333"/> <http-listener id="http-listener-4" port="4444" security-enabled="true"> <ssl cert-nickname="nickname-2"/> </http-listener> <virtual-server id="vs-1" hosts="mydomain.com" http-listeners="http-listener-1,http-listener-2"/> <virtual-server id="vs-2" hosts="yourdomain.com" http-listeners="http-listener-3,http-listener-4"/>
A virtual server's root context is defined as the context with the empty path (
/). Any requests that cannot be mapped to any of the web modules deployed on
a virtual server are mapped to the virtual server's root context.
The physical location of a virtual server's root context is given by the virtual server's
docroot property. Each virtual server may be configured with its own individual docroot.
In GlassFish, it is possible to map a virtual server's root context to one of the virtual server's web modules, by adding a
default-web-module attribute to
the virtual server's
<virtual-server> entry and having its value reference the selected web module.
A virtual server's default web module "shadows" the virtual server's docroot, with the effect that any requests that cannot be mapped to any of the web modules deployed on the virtual server will now be mapped to the virtual server's default web module instead of the virtual server's docroot. In other words, a web module that has been designated as a virtual server's default web module will serve any requests that match its context path plus any requests that map to the virtual server's root context.
A virtual server's docroot remains shadowed for as long as the virtual server declares a default web module. Once a virtual server's
default-web-module attribute has been removed, the virtual server's docroot will be reinstantiated as the virtual server's root context.
The default-web-module mechanism is a convenient way for having a single web module occupy both its designated context path as well as the virtual server's root context.
In GlassFish, a virtual server may specify alternate docroots in addition to its main docroot. Each alternate docroot is associated with one or more URI patterns. An alternate docroot is selected over the main docroot if the request matches one of its URI patterns. Both path (prefix) and extension matches are supported.
For example, it is possible to configure a virtual server in such a way that any requests (with an empty context path) whose URI starts with
be mapped to one alternate docroot, whereas any requests (with an empty context path) whose URI ends in
\*.jsp will be mapped to a different alternate docroot.
All other requests (with an empty context path) will be mapped to the virtual server's main docroot.
If a request matches multiple alternate docroot URI patterns, the following precedence order is used:
- Exact match
- Longest path match
- Extension match
Alternate docroots allow virtual servers to share a subset of their docroot resources.
See my blog for additional details and examples.
- Single Sign On Single Sign On (SSO) enables web applications to share client authentication state. SSO is enabled at the virtual server level (and configured as a virtual server property). With SSO, a user who successfully authenticates to one web application becomes implicitly logged in to any other web application (deployed on the same virtual server) that shares the same authentication realm.
- Security realm
- Security credentials GlassFish allows HTTP(S) listeners to be assigned to a virtual server (or group of virtual servers) for its (their) exclusive use (see the earlier section that talks about isolation levels). Ideally, the HTTPS listeners assigned to one group of virtual servers will have their security credentials (i.e., private keys and supporting certificate chains) separated from the security credentials of a different set of HTTPS listeners serving a different group of virtual servers.
In many cases, it is useful to configure a security realm at the virtual server level, with the expectation that this security realm apply to all web modules deployed on the virtual server.
GlassFish supports this requirement, by defining a property named
authRealm at the
<virtual-server> level, whose value must be the name of an authentication realm declared in
Standalone web modules (that is, those not bundled in an EAR file) inherit the realm referenced by the virtual server on which they are deployed, unless they specify a realm name in their
web.xml deployment descriptor, which takes precedence.
See my blog for additional details.
GlassFish currently supports only a single keystore per server instance, which means the security credentials of all of the instance's HTTPS listeners must be stored in
the same keystore, and may be differentiated by an alias name (
cert-nickname) only. There has been an enhancement filed against GlassFish (see Issue 657) to support multiple key- and truststores per server instance.
Virtual servers, including their attributes and properties, are dynamically reconfigurable, that is, the creation or deletion of a virtual server, or any changes to its attributes or properties, do not require a server restart in order to take effect.