The Host Container
Table of Contents
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 Tomcat is running. For clients to be able to connect to a Tomcat server using its network name, 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.
Clients normally use host names to identify the server they wish to connect to. This host name is also included in the HTTP request headers. Tomcat extracts the host name from the HTTP headers and looks for a Host with a matching name. If no match is found, the request is routed to the default host. The name of the default host does not have to match a DNS name (although it can) since any request where the DNS name does not match the name of a Host element will be routed to the default host.
The description below uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have installed Tomcat.
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, or a pathname that is relative to the
The XML Base directory for this virtual host.
This is the pathname of a directory that may contain context XML
descriptors to be deployed on this virtual host. You may specify an
absolute pathname for this directory, or a pathname that is relative
If set to true, Tomcat will attempt to create the directories defined
by the attributes
This flag value indicates if Tomcat should check periodically for new
or updated web applications while Tomcat is running. If true, Tomcat
periodically checks the
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
A regular expression defining paths to ignore when
This regular expression is relative to
See Automatic Application Deployment for more information.
This flag value indicates if web applications from this host should be automatically deployed when Tomcat starts. The flag's value defaults to true. See Automatic Application Deployment for more information.
Each child context may override this attribute.
If not specified, the default value of
Usually the network name of this virtual host, as registered in your
Domain Name Service server. Regardless of the case used to
specify the host name, Tomcat will convert it to lower case internally.
One of the Hosts nested within an Engine MUST
have a name that matches the
The number of threads this Host will use to start
child Context elements in parallel. The same
thread pool will be used to deploy new
Contexts if automatic deployment is being
used. The special value of 0 will result in the value of
This flag determines if Tomcat, as part of the auto deployment
process, will check for old, unused versions of web applications
deployed using parallel deployment and, if any are found, remove them.
This flag only applies if
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):
Java class name of the error reporting valve which will be used
by this Host. The responsibility 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 Tomcat. This class must
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
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:
A host is associated with the
log category. Note that the brackets are 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.
You can ask Catalina to create an access log for all requests processed by an Engine, Host, or Context by nesting a Valve element like this:
<Host name="localhost" ...> ... <Valve className="org.apache.catalina.valves.AccessLogValve" prefix="localhost_access_log." suffix=".txt" pattern="common"/> ... </Host>
See Access Logging Valves for more information on the configuration attributes that are supported.
Automatic Application Deployment
If you are using the standard Host implementation with
default settings then applications in the appBase or with context
files in the configBase are automatically deployed when Tomcat
deployOnStartup property defaults to
true) and reloaded or redeployed (as appropriate) when a change
is detected while Tomcat is running (the
also defaults to
execution of exactly the same code so the behaviour is very similar.
However, there is one key difference. When Tomcat starts it has no knowledge
of which files are the same, which have been changed and which are new. It
therefore treats all files as new. While Tomcat is running, it can
differentiate between unchanged, modified and new files. This leads to some
differences in behaviour between files being modified while Tomcat is
running and files being modified while Tomcat is stopped.
When you use automatic deployment, related files (a web application may have a context.xml file, a WAR and a directory) that exist in the Host's appBase and/or configBase must conform to the expected naming convention. In short, this means files for the same web application must share the same base name.
The automatic deployment process identifies new and/or modified web applications using the following search order:
- Web applications with a context.xml file located in the Host's configBase.
- Web applications with a WAR file located in the Host's appBase that have not already been identified during the scan for context.xml files.
- Web applications with a directory located in the Host's appBase that have not already been identified during the scans for context.xml and/or WAR files.
true, the automatic
deployment process will monitor the deployed web applications for changes.
Depending on exactly what changes, the web application will either be
re-deployed or reloaded. Re-deployment involves the creation of a new web
application and, if using the standard session manager, user sessions will
not be retained. Reloading uses the existing web application but re-parses
the web.xml and reloads any classes. If using the standard session manager,
user sessions will be persisted.
Users may add to the files that the automatic deployment process monitors for reloading (i.e. any change to one of these files triggers a reload of the web application) by adding a WatchedResources element to the context.xml file. See the Context documentation for further details.
When using automatic deployment, the
docBase defined by
an XML Context file should be outside of the
appBase directory. If this is not the case, difficulties
may be experienced deploying the web application or the application may
be deployed twice. The
deployIgnore attribute can be used
to avoid this situation.
Note that if you are defining contexts explicitly in server.xml, you
should probably turn off automatic application deployment or specify
deployIgnore carefully. Otherwise, the web applications
will each be deployed twice, and that may cause problems for the
There are many possible combinations of settings, new files, changed files and deleted files. A separate page describes the expected behaviour of the automatic deployment process in many of these scenarios.
Host Name Aliases
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
with its own set of web applications.
However, in some circumstances, it is desirable 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 desirable that users
be able to utilize either
company.com to access exactly the same content and
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.LifecycleListener interface, and
it will be notified about the occurrence of the corresponding
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 configured "accept" and/or "deny"
filters, which are defined using
Expression syntax. 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\.\d+"/> ... </Host>
See Remote Address Filter and Remote Host Filter for more information about the configuration options that are supported.
Single Sign On
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"/> ... </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.
User Web Applications
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
/etc/passwd file 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/passwd is not in use, you can
request Catalina to consider all directories found in a specified base
directory (such as
c:\Homes in 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:
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.