# The Host Component

[Introduction] [Common Attributes] [Standard Implementation Attributes] [Utility Components] [Special Features]

## Introduction

A Host component represents a "virtual host" that is running in an instance of Catalina, possibly in conjunction with many other virtual hosts. Each virtual host can be running one or more web applications, each represented by a Context component.

In order for a client, such as a web browser, to successfully send a request to a web application running in a particular virtual host, the client must specify a hostname that is mapped, in the Domain Name Service (DNS) to the server that Catalina is running on, and a port number on which you have defined a Connector to be listening.

You must define at least one Host component nested inside each Engine element. Typically, this Host will be named `localhost`, and will be declared as the default host for the owning Engine.

Request processing Valves that are nested here will be executed for every request received for processing by this virtual host.

## Common Attributes

All implementations of the Host component 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 executed in this virtual host. You may specify an absolute pathname to this directory, or a pathname that is relative to the "Catalina Home" directory. If not specified, the default value (`webapps`) will be used. See the Special Features section, below, for information about Automatic Application Deployment support provided by the standard Host implementation.
`className` | Java class name of the implementation to use. This class must implement the `org.apache.catalina.Host` interface. If no class name is specified, the standard implementation will be used (`org.apache.catalina.core.StandardHost`).
`name` | The host name of this virtual host. This name must match the name submitted on the `Host:` header in incoming requests. This attribute is required, and must be unique among the virtual hosts running in this servlet container. Note that hostname matching is not case sensitive.

## Standard Implementation Attributes

The standard implementation of the Host component also supports the following attributes:

Attribute | Description
--- | ---
`debug` | The level of debugging detail logged by this Host to the associated Logger, with higher numbers generating more detailed output. If not specified, the debugging detail level will be set to zero (0).
`unpackWARs` | Set to `true` if you want web applications that are deployed from a Web Application Archive (WAR) file to be unpacked into a disk directory structure (as was done in Tomcat 3.x), or `false` to run the application directly from the WAR file. If not specified, the default value is `true` for backwards compatibility.

## Utility Components

You can attach one or more of the following utility components by nesting a corresponding declaration inside your Host element. Unless overridden by a utility component of the same name being nested in a Context element, the utility components you declare here will be shared among all web applications running in this Host:

- Logger - Configure a logger that will receive all log messages from this Host, as well as from all web applications running on this Host.
- Realm - Configure a realm that will allow your database of users, and their associated roles, to be shared across all of the web applications running within this Host.

## Special Features

### Access Logs

When you run a web server, one of the output files normally generated is an access log, which generates one line of information, in a standard format, for each HTTP request that was received, and responded to, by the web server. Catalina includes an optional Valve implementation that can create access logs in the same standard format created by web servers, or in any custom format desired.

You can ask Catalina to create an access log for all requests to any web application for this Host, by nesting an element like this inside your Host element:

        <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 options that are supported.

### Automatic Application Deployment

If you are using the standard Host implementation, the following actions take place automatically when Catalina is first started. All processing takes place in the application base directory configured by the `appBase` property. No special configuration is required to enable these activities.

- Any web application archive file (that is, a JAR file whose name ends with ".war"), that does not have a corresponding directory of the same name without the extension, will be automatically expanded. The assumption is that this is a web application archive being deployed on this virtual host. (If you wish to redeploy an updated WAR file, be sure to delete the automatically expanded directory first).
- Any subdirectory within the `appBase` directory that appears to be an unpacked web application (i.e. it contains a `WEB-INF/web.xml` file), receives an automatically generated Context element, even if this directory is not specifically mentioned in the `conf/server.xml` file. The context path for this application will be a slash character ("/") followed by the directory name, unless the directory name is `ROOT`, in which case the context path will be "" (the empty string).

The net effect of this feature is that you need not specifically mention your web applications in the `conf/server.xml` file unless you wish to define non-default properties for the corresponding Context.

### Host Name Aliases

In many server environments, the system administrator has set up more than one host name in the Domain Name Service (DNS) entries for a company, and you would like all of these names to access the same Host component (and therefore execute the same web applications), no matter which host name was actually used in the request.

As an example of this, consider that many web sites are set up so that hostnames `www.mycompany.com` and `mycompany.com` go to the same pages. You can accomplish this with Catalina by setting up your server configuration like this:

        <Host name="www.mycompany.com" ...>
          ...
          <Alias name="mycompany.com"/>
          ...
        </Host>

With this setup, both of the following URLs will resolve to the same web application (assuming your Connector is listening on port 8080):

    	http://mycompany.com:8080
    	http://www.mycompany.com:8080

### Lifecycle Listeners

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 the `<Host>` element. The class you specify in the `className` attribute of this Listener must implement the `org.apache.catalina.LifecycleListener` interface, and it will be notified about the occurrence of the corresponding lifecycle events.

Configuration for such a listener might look like this:

        <Host name="www.mycompany.com" ...>
          ...
          <Listener className="com.mycompany.MyHostListener"/>
          ...
        </Host>

### Request Filters

You can ask Catalina to check the IP address, or host name, of an incoming request for this virtual host against a list of "accept" and "deny" filters, which are defined using the Regular Expression syntax supported by the jakarta-regexp regular expression library system. Requests that come from remote 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>

See Remote Address Filter or Remote Host Filter for more information on the syntax of these filters, and the logic that is applied when they are executed.

### User Web Applications

Many web servers automtically map a request path 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 this with Catalina by setting up your server configuration like this (on a Unix system that uses the `/etc/passwd` file to configure valid users):

        <Host name="www.mycompany.com" ...>
          ...
          <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, but one or more user home directories can be found in a common base directory (such as `c:\Homes`), you could do this instead:

        <Host name="www.mycompany.com" ...>
          ...
          <Listener className="org.apache.catalina.startup.UserConfig"
                    directoryName="public_html"
                    homeBase="c:\Homes"
                    userClass="org.apache.catalina.startup.HomesUserDatabase"/>
          ...
        </Host>

It is also acceptable to include more than one instance of this listener, if you have more than one home base directory containing user home directories. In all cases, the Context that is set up for user directories will have default values, just as is the case for Automatic Application Deployment, described above.

With either setup, if my username on the server is `craigmcc`, and I have a web application installed in a `public_html` subdirectory under my home directory, my application will receive all requests directed to:

    	http://www.mycompany.com:8080/~craigmcc

assuming my Connector is listening on port 8080.

IMPORTANT NOTE: The operating system username under which Catalina is executed must have read access to the user's web application, and all directories above it, for this feature to operate correctly.