The Host Container
The Host element represents a virtual host, which is an association of a network name for a server (such as "www.mycompany.com" with the particular server on which Catalina is running. In order to be effective, this name must be registered in the Domain Name Service (DNS) server that manages the Internet domain you belong to - contact your Network Administrator for more information.
In many cases, System Administrators wish to associate more than
one network name (such as
company.com) with the same virtual host and applications.
This can be accomplished using the Host
Name Aliases feature discussed below.
One or more Host elements are nested inside an
Engine element. Inside the Host element, you
can nest Context elements for the web
applications associated with this virtual host. Exactly one of the Hosts
associated with each Engine MUST have a name matching the
defaultHost attribute of that Engine.
The description below uses the variable name $CATALINA_HOME to refer to the directory into which you have installed JBoss Web, and is the base directory against which most relative paths are resolved. However, if you have configured JBoss Web for multiple instances by setting a CATALINA_BASE directory, you should use $CATALINA_BASE instead of $CATALINA_HOME for each of these references.
All implementations of Host support the following attributes:
The Application Base directory for this virtual host. This is the pathname of a directory that may contain web applications to be deployed on this virtual host. You may specify an absolute pathname for this directory, or a pathname that is relative to the
$CATALINA_BASEdirectory. See Automatic Application Deployment for more information on automatic recognition and deployment of web applications to be deployed automatically.
This flag value indicates if new web applications, dropped in to the
appBasedirectory while JBoss Web is running, should be automatically deployed. The flag's value defaults to true. See Automatic Application Deployment for more information.
This value represents the delay in seconds between the invocation of the backgroundProcess method on this host and its child containers, including all contexts. Child containers will not be invoked if their delay value is not negative (which would mean they are using their own processing thread). Setting this to a positive value will cause a thread to be spawn. After waiting the specified amount of time, the thread will invoke the backgroundProcess method on this host and all its child containers. A host will use background processing to perform live web application deployment related tasks. If not specified, the default value for this attribute is -1, which means the host will rely on the background processing thread of its parent engine.
Java class name of the implementation to use. This class must implement the
org.apache.catalina.Hostinterface. If not specified, the standard value (defined below) will be used.
This flag value indicates if web applications from this host should be automatically deployed by the host configurator. The flag's value defaults to true. See Automatic Application Deployment for more information.
Network name of this virtual host, as registered in your Domain Name Service server. One of the Hosts nested within an Engine MUST have a name that matches the
defaultHostsetting for that Engine. See Host Name Aliases for information on how to assign more than one network name to the same virtual host.
The standard implementation of Host is org.apache.catalina.core.StandardHost. It supports the following additional attributes (in addition to the common attributes listed above):
falseif you want to disable parsing the context.xml file embedded inside the application (located at
/META-INF/context.xml). Security consious environments should set this to
falseto prevent applications from interacting with the container's configuration. The administrator will then be responsible for providing an external context configuration file, and put it in
$CATALINA_HOME/conf/[enginename]/[hostname]/. The flag's value defaults to
Java class name of the error reporting valve which will be used by this Host. The responsability of this valve is to output error reports. Setting this property allows to customize the look of the error pages which will be generated by JBoss Web. This class must implement the
org.apache.catalina.Valveinterface. If none is specified, the value
org.apache.catalina.valves.ErrorReportValvewill be used by default.
trueif you want web applications that are placed in the
appBasedirectory as web application archive (WAR) files to be unpacked into a corresponding disk directory structure,
falseto run such web applications directly from a WAR file. See Automatic Application Deployment for more information.
Pathname to a scratch directory to be used by applications for this Host. Each application will have its own sub directory with temporary read-write use. Configuring a Context workDir will override use of the Host workDir configuration. This directory will be made visible to servlets in the web application by a servlet context attribute (of type
javax.servlet.context.tempdiras described in the Servlet Specification. If not specified, a suitable directory underneath
$CATALINA_HOME/workwill be provided.
You can nest one or more Context elements inside this Host element, each representing a different web application associated with this virtual host.
You can nest at most one instance of the following utility components by nesting a corresponding element inside your Host element:
- Realm - Configure a realm that will allow its database of users, and their associated roles, to be shared across all Contexts nested inside this Host (unless overridden by a Realm configuration at a lower level).
A host is associated with the
org.apache.catalina.core.ContainerBase.[enginename].[hostname]log category. Note that the brackets are actuall part of the name, don't omit them.
When you run a web server, one of the output files normally generated is an access log, which generates one line of information for each request processed by the server, in a standard format. Catalina includes an optional Valve implementation that can create access logs in the same standard format created by web servers, or in any number of custom formats.<Host name="localhost" ...> ... <Valve className="org.apache.catalina.valves.AccessLogValve" prefix="localhost_access_log." suffix=".txt" pattern="common"/> ... </Host>
See Access Log Valve for more information on the configuration attributes that are supported.
If you are using the standard Host implementation, the following actions take place automatically when Catalina is first started, if the
deployOnStartupproperty is set to
true(which is the default value):
- Any XML file in the
$CATALINA_BASE/conf/[engine_name]/[host_name]directory is assumed to contain a Context element (and its associated subelements) for a single web application. The
docBaseattribute of this
<Context>element will typically be the absolute pathname to a web application directory, or the absolute pathname of a web application archive (WAR) file (which will not be expanded). The path attribute will be automatically set as defined in the Context documentation.
- Any web application archive file within the application base (appBase) directory that does not have a corresponding directory of the same name (without the ".war" extension) will be automatically expanded, unless the
unpackWARsproperty is set to
false. If you redeploy an updated WAR file, be sure to delete the expanded directory when restarting Tomcat, so that the updated WAR file will be re-expanded (note that the auto deployer, if enabled, will automatically expand the updated WAR file once the previously expanded directory is removed). Multi-level contexts may be defined by using #, eg use a WAR named
foo#bar.warfor a context path of
- Any subdirectory within the application base directory will receive an automatically generated Context element, even if this directory is not mentioned in the
conf/server.xmlfile. The context path for this deployed Context will be a slash character ("/") followed by the directory name, unless the directory name is ROOT, in which case the context path will be an empty string (""). Multi-level contexts may be defined by using #, eg use a directory named
foo#barfor a context path of
In addition to the automatic deployment that occurs at startup time, you can also request that new XML configuration files, WAR files, or subdirectories that are dropped in to the
$CATALINA_HOME/conf/[engine_name]/[host_name]in the case of an XML configuration file) directory while JBoss Web is running will be automatically deployed, according to the rules described above. The auto deployer will also track web applications for the following changes:
- An update to the WEB-INF/web.xml file will trigger a reload of the web application
- An update to a WAR which has been expanded will trigger an undeploy (with a removal of the expanded webapp), followed by a deployment
- An update to a XML configuration file will trigger an undeploy (without the removal of any expanded directory), followed by a deployment of the associated web application
When using automatic deployment, the
docBasedefined by an XML Context file should be outside of the
appBasedirectory. If this is not the case difficulties may be experienced deploying the web application or the application may be deployed twice.
Finally, note that if you are defining contexts explicitly, you should probably turn off automatic application deployment. Otherwise, your context will be deployed twice each, and that may cause problems for your app.
In many server environments, Network Administrators have configured more than one network name (in the Domain Name Service (DNS) server), that resolve to the IP address of the same server. Normally, each such network name would be configured as a separate Host element in
conf/server.xml, each with its own set of web applications.
However, in some circumstances, it is desireable that two or more network names should resolve to the same virtual host, running the same set of applications. A common use case for this scenario is a corporate web site, where it is desireable that users be able to utilize either
company.comto access exactly the same content and applications.
This is accomplished by utilizing one or more Alias elements nested inside your Host element. For example:<Host name="www.mycompany.com" ...> ... <Alias>mycompany.com</Alias> ... </Host>
In order for this strategy to be effective, all of the network names involved must be registered in your DNS server to resolve to the same computer that is running this instance of Catalina.
If you have implemented a Java object that needs to know when this Host is started or stopped, you can declare it by nesting a Listener element inside this element. The class name you specify must implement the
org.apache.catalina.LifecycleListenerinterface, and it will be notified about the occurrence of the coresponding lifecycle events. Configuration of such a listener looks like this:<Host name="localhost" ...> ... <Listener className="com.mycompany.mypackage.MyListener" ... > ... </Host>
Note that a Listener can have any number of additional properties that may be configured from this element. Attribute names are matched to corresponding JavaBean property names using the standard property method naming patterns.
You can ask Catalina to check the IP address, or host name, on every incoming request directed to the surrounding Engine, Host, or Context element. The remote address or name will be checked against a configured list of "accept" and/or "deny" filters, which are defined using the Regular Expression syntax supported by the Jakarta Regexp regular expression library. Requests that come from locations that are not accepted will be rejected with an HTTP "Forbidden" error. Example filter declarations:<Host name="localhost" ...> ... <Valve className="org.apache.catalina.valves.RemoteHostValve" allow="*.mycompany.com,www.yourcompany.com"/> <Valve className="org.apache.catalina.valves.RemoteAddrValve" deny="192.168.1.*"/> ... </Host>
In many environments, but particularly in portal environments, it is desireable to have a user challenged to authenticate themselves only once over a set of web applications deployed on a particular virtual host. This can be accomplished by nesting an element like this inside the Host element for this virtual host:<Host name="localhost" ...> ... <Valve className="org.apache.catalina.authenticator.SingleSignOn" debug="0"/> ... </Host>
The Single Sign On facility operates according to the following rules:
- All web applications configured for this virtual host must share the same Realm. In practice, that means you can nest the Realm element inside this Host element (or the surrounding Engine element), but not inside a Context element for one of the involved web applications.
- As long as the user accesses only unprotected resources in any of the web applications on this virtual host, they will not be challenged to authenticate themselves.
- As soon as the user accesses a protected resource in any web application associated with this virtual host, the user will be challenged to authenticate himself or herself, using the login method defined for the web application currently being accessed.
- Once authenticated, the roles associated with this user will be utilized for access control decisions across all of the associated web applications, without challenging the user to authenticate themselves to each application individually.
- As soon as the user logs out of one web application (for example, by invalidating the corresponding session if form based login is used), the user's sessions in all web applications will be invalidated. Any subsequent attempt to access a protected resource in any application will require the user to authenticate himself or herself again.
- The Single Sign On feature utilizes HTTP cookies to transmit a token that associates each request with the saved user identity, so it can only be utilized in client environments that support cookies.
Many web servers can automatically map a request URI starting with a tilde character ("~") and a username to a directory (commonly named
public_html) in that user's home directory on the server. You can accomplish the same thing in Catalina by using a special Listener element like this (on a Unix system that uses the
/etc/passwdfile to identify valid users):<Host name="localhost" ...> ... <Listener className="org.apache.catalina.startup.UserConfig" directoryName="public_html" userClass="org.apache.catalina.startup.PasswdUserDatabase"/> ... </Host>
On a server where
/etc/passwdis not in use, you can request Catalina to consider all directories found in a specified base directory (such as
c:\Homesin this example) to be considered "user home" directories for the purposes of this directive:<Host name="localhost" ...> ... <Listener className="org.apache.catalina.startup.UserConfig" directoryName="public_html" homeBase=c:\Homes" userClass="org.apache.catalina.startup.HomesUserDatabase"/> ... </Host>
If a user home directory has been set up for a user named
craigmcc, then its contents will be visible from a client browser by making a request to a URL like:http://www.mycompany.com:8080/~craigmcc
Successful use of this feature requires recognition of the following considerations:
- Each user web application will be deployed with characteristics established by the global and host level default context settings.
- It is legal to include more than one instance of this Listener element. This would only be useful, however, in circumstances where you wanted to configure more than one "homeBase" directory.
- The operating system username under which Catalina is executed MUST have read access to each user's web application directory, and all of its contents.