| Links Top Level Elements Executors Connectors Containers Nested Components Cluster Elements web.xml Other | Apache Tomcat Configuration ReferenceThe Host Container| Introduction |  | 
  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 www.mycompany.comandcompany.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
  defaultHostattribute of that Engine. 
    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. | 
 | Attributes |  | 
  | Common Attributes |  | 
    All implementations of Host
    support the following attributes: | Attribute | Description | 
|---|
 | appBase | 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
        $CATALINA_BASEdirectory.  See
        Automatic Application
        Deployment for more information on automatic recognition and
        deployment of web applications. If not specified, the default ofwebappswill be used. |  | autoDeploy | 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 appBaseand$CATALINA_BASE/conf/[engine_name]/[host_name]directories and deploys any new web applications or context XML
        descriptors found. Updated web applications or context XML descriptors
        will trigger a reload of the web application. The flag's value defaults
        to true.  See
        Automatic Application
        Deployment for more information. |  | backgroundProcessorDelay | 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. |  | className | 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. |  | deployIgnore | A regular expression defining paths to ignore when
        autoDeployanddeployOnStartupare set. This
        allows you to keep your configuration in a version control system, for
        example, and not deploy a .svn or CVS folder that happens to be in theappBase. This regular expression is relative to appBase. It is
        also anchored, meaning the match is performed against the
        entire file/directory name. So,foomatches only a file or
        directory namedfoobut notfoo.war,foobar, ormyfooapp. To match anything with
        "foo", you could use.*foo.*. See Automatic Application
        Deployment for more information. |  | deployOnStartup | 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. |  | name | Network name of this virtual host, as registered in your
        Domain Name Service server. Regardless of the case used to
        specify the hostname, Tomcat will convert it to lower case internally.
        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. | 
 | 
 | Standard Implementation |  | 
    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): | Attribute | Description | 
|---|
 | deployXML | Set to falseif you want to disable parsing the context
        XML descriptor embedded inside the application (located at/META-INF/context.xml). Security conscious environments
        should set this tofalseto prevent applications from
        interacting with the container's configuration. The  administrator will
        then be responsible for providing an external context configuration
        file, and putting it in$CATALINA_BASE/conf/[engine_name]/[host_name]. The flag's
        value defaults totrue. |  | errorReportValveClass | 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
        implement the
        org.apache.catalina.Valveinterface. If none is specified,
        the valueorg.apache.catalina.valves.ErrorReportValvewill be used by default. |  | unpackWARs | Set to trueif you want web applications that are
        placed in theappBasedirectory 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. WAR files located outside of the Host's
        appBase will not be expanded. See
        Automatic Application
        Deployment for more information. |  | workDir | 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 java.io.File) namedjavax.servlet.context.tempdiras described in the
        Servlet Specification.  If not specified, a suitable directory
        underneath$CATALINA_BASE/workwill be provided. | 
 | 
 | 
 | Nested Components |  | 
  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). | 
 | Special Features |  | 
  | Logging |  | 
    A host is associated with the 
       org.apache.catalina.core.ContainerBase.[engine_name].[host_name]log category.  Note that the brackets are part of the name,
       don't omit them. | 
 | Automatic Application Deployment |  | 
    If you are using the standard Host implementation,
    the following actions take place automatically when Catalina is first
    started, if the deployOnStartupproperty is set totrue(which is the default value): 
    Any XML file in
        $CATALINA_BASE/conf/[engine_name]/[host_name]is
        assumed to be a context XML descriptor containing a
        Context element (and its associated
        sub-elements) for a single web application. The web applications
        associated with each of these context XML descriptor files will be
        deployed first.The
 docBaseattribute of this<Context>element must only be set if the docBase is outside the Host'sappBase. For web applications located inside the Host'sappBase, thedocBasewill be the name of the
        XML file with ".xml" replaced with ".war" for a web application archive
        or the name of the XML file with ".xml" removed for a directory.The
 pathattribute must not be set. The context path used
        will be a slash character ("/") followed by the name of the XML file
        (less the .xml extension). Multi-level context paths may be defined
        using #, e.g.foo#bar.xmlfor a context path of/foo/bar. The default web application that has a context
        path of/may be defined by using a file calledROOT.xml.Any web application archive file within the Host's appBasedirectory that has not already been deployed as a result of a context
        XML descriptor, does not have a corresponding directory of the same
        name (without the ".war" extension), and is not excluded bydeployIgnorewill be deployed next. The context path
        used will be a slash character ("/") followed by the web application
        archive name less the ".war" extension. The one exception to this rule
        is that a web application archive named "ROOT.war" will be deployed with
        a context path of/. Multi-level contexts may be defined by
        using #, e.g. use a WAR namedfoo#bar.warfor a context
        path of/foo/bar.If the
 unpackWARsattribute istrue, the web
        application archive file will be expanded to a directory of the same
        name (without the ".war" extension".Note: If you re-deploy an updated WAR file while Tomcat is stopped, be
        sure to delete the associated expanded directory before restarting 
        Tomcat, so that the updated WAR file will be re-expanded when Tomcat
        restarts.
 Any web application archive file within the Hosts's
 appBasedirectory that does not have a corresponding context XML descriptor
        (with a ".xml" extension rather than a ".war" extension) in$CATALINA_BASE/conf/[engine_name]/[host_name]will be
        scanned to see if it contains a context XML descriptor (located at/META-INF/context.xml) and if one is found the descriptor
        will be copied to the$CATALINA_BASE/conf/[engine_name]/[host_name]directory and
        renamed.Finally, any sub-directory within the Host's appBasethat
        has not already been deployed as a result of a context XML descriptor
        and is not excluded bydeployIgnorewill be deployed.
        The context path used will be a slash character ("/") followed by the
        directory name, unless the directory name is ROOT, in which case the
        context path will/. Multi-level contexts may be defined by
        using #, e.g. use a directory namedfoo#barfor a context
        path of/foo/bar.Any directory within the Hosts's
 appBasedirectory that
        does not have a corresponding context XML descriptor in$CATALINA_BASE/conf/[engine_name]/[host_name]will be
        scanned to see if it contains a context XML descriptor (located at/META-INF/context.xml) and if one is found the descriptor
        will be copied to$CATALINA_BASE/conf/[engine_name]/[host_name]and renamed. In addition to the automatic deployment that occurs at startup time,
    you can also request that new XML configuration files, WAR files, or
    sub-directories that are dropped in to the appBase(or$CATALINA_BASE/conf/[engine_name]/[host_name]in the case of
    an XML configuration file) directory while Tomcat 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 applicationDeleting a WAR file will trigger an undeploy of the application with
          the removal of any associated expanded directory, context file and
          work directory. Any current user sessions will not be persisted.Deleting a directory will trigger an undeploy of the application
          with the removal of any associated context file and work directory.
          Any current user sessions will not be persisted. If there is an
          associated WAR file, it will not be deleted and the application will
          be redeployed from the WAR file the next time the auto deployer checks
          for changes.Deleting a context file will trigger an undeploy of the application
          with the removal of any associated work directory. Any current user
          sessions will not be persisted. If there is an associated WAR file
          and/or directory, they will not be deleted and the application will be
          redeployed from the WAR file (or from directory if there is no WAR
          file) the next time the auto deployer checks for changes.Updating a WAR file will trigger an undeploy of the application with
          the removal of any associated expanded directory, context file and
          work directory. Any current user sessions will not be persisted.Updating a directory (not the directory contents) will trigger an
          undeploy of the application with the removal of any associated context
          file and work directory. Any current user sessions will not be
          persisted. The application will be redeployed the next time the auto
          deployer checks for changes.Updating a context file will trigger an undeploy of the application
          with the removal of any associated work directory. Any current user
          sessions will not be persisted. The application will be redeployed the
          next time the auto deployer checks for changes. When using automatic deployment, the docBasedefined by
    an XML Context file should be outside of theappBasedirectory. If this is not the case, difficulties
    may be experienced deploying the web application or the application may
    be deployed twice. ThedeployIgnoreattribute can be used
    to avoid this situation. Finally, note that if you are defining contexts explicitly in server.xml,
    you should probably turn off automatic application deployment or specify
    deployIgnorecarefully. Otherwise, the web applications
    will each be deployed twice, and that may cause problems for the
    applications. | 
 | 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. | 
 | 
 |