Server Configuration Reference
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
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 Tomcat 4,
and is the base directory against which most relative paths are
resolved. However, if you have configured Tomcat 4 for multiple
instances by setting a CATALINA_BASE directory, you should use
$CATALINA_BASE instead of $CATALINA_HOME for each of these
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
$CATALINA_HOME directory. See
Deployment for more information on automatic recognition and
deployment of web applications to be deployed automatically.
This flag value indicates if web applications from this host
be automatically deployed by the host configurator at
The flag's value defaults to true. Note
that if this
flag is set to false and livedeploy is set
to true then
applications will still be deployed shortly after
Deployment for more information.
Java class name of the implementation to use. This class must
If not specified, the standard value (defined below) will be used.
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
defaultHost setting for that Engine. See
Host Name Aliases for information
on how to assign more than one network name to the same
The standard implementation of Host is
It supports the following additional attributes (in addition to the
common attributes listed above):
The level of debugging detail logged by this Engine
to the associated Logger. Higher numbers
generate more detailed output. If not specified, the default
debugging detail level is zero (0).
false if you want to disable deploying
applications using a Context XML config file. This also disables
the ability to install web application directories or ".war" files
with the manager app which are not located in the Host appBase
directory. Applications are deployed with the security permissions
of catalina, for security this may need to be set to
if untrusted users can manage web applications. The flag's value
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 Tomcat. This class must
org.apache.catalina.Valve interface. If none is specified,
will be used by default.
This flag value indicates if new web applications, dropped in to
appBase directory while Tomcat is running, should
be automatically deployed. The flag's value defaults to true. See
Deployment for more information.
true if you want web applications that are
placed in the
appBase directory as web application
archive (WAR) files to be unpacked into a corresponding disk directory
false to run such web applications directly
from a WAR file. See
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.tempdir as described in the
Servlet Specification. If not specified, a suitable directory
$CATALINA_HOME/work will 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. In addition, you can nest a
single DefaultContext element that defines
default values for subsequently deployed web applications.
You can optional nest a DefaultContext
element inside this Host element, to define the default
characteristics of web applications that are automatically deployed.
You can nest at most one instance of the following utility components
by nesting a corresponding element inside your Host
- Logger -
Configure a logger that will receive
and process all log messages for this Host, plus
messages from Contexts associated with
this Host (unless overridden by a
Logger configuration at a lower level).
- 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).
|Automatic Application Deployment|
If you are using the standard Host implementation,
the following actions take place automatically when Catalina is first
started, if the
autoDeploy property is set to
true (which is the default value):
- Any XML file in the directory defined by appBase
(Application Base directory) is assumed to contain a
Context element (and its associated
subelements) for a single web application. The
attribute 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).
- Any web application archive file that does not have a corresponding
directory of the same name (without the ".war" extension) will be
automatically expanded, unless the
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.
- Any subdirectory within the Application Base directory
that appears to be an unpacked web application (that is, it contains
/WEB-INF/web.xml file) will receive an automatically
generated Context element, even if this
directory is not mentioned in the
This generated Context entry will be configured according to the
properties set in any DefaultContext
element nested in this Host element. 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 ("").
In addition to the automatic deployment that occurs at startup time,
you can also request that new XML configuration files, WAR files, or
subdirectories (containing web applications) that are dropped in to the
appBase directory while Tomcat is running will be
automatically deployed, according to the rules described above by
setting the livedeploy attribute to true.
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.
|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" ...>
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
- 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
- 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 or timing out 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.