The Host Component

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:

Standard Implementation Attributes

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

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.