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.
Normally, you will define at least one Host component named
localhost
, to receive requests sent from a client running on
the same server. Often, you will also want this Host to receive all
requests for a host name that does not match one of the other defined Hosts
for this server. You indicate this by setting the defaultHost
attribute of the Engine component to the
localhost
(or whatever other Host name you wish to receive
requests for unknown hosts).
All implementations of the Host component support the following
attributes, which can be defined in a <Host>
element:
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.tomcat.Host interface. If
no class name is specified, the standard implementation will be
used (org.apache.tomcat.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.
|
The standard implementation of the Host component supports the following attributes in addition to those supported by all implementations:
Attribute | Description |
---|---|
debug |
The level of debugging detail logged by this Engine to the associated Logger, with higher numbers generating more detailed output. If not specified, the debugging detail level will be set to zero (0). |
root |
Boolean attribute stating whether calls to
ServletContext.getContext() on web applications
running in this virtual host should allow one application to gain
access to the ServletContext of another. Set to false
to disallow such access. If not specified, the default value
(false ) will be used.
|
You can attach one or more of the following utility components by nesting a corresponding declaration element 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:
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="www.mycompany.com" ...> ... <Valve className="org.apache.tomcat.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.
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
attribute. No special configuration is required to enable these activities.
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.
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.
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 my Connector is listening on port 8080):
http://mycompany.com:8080 http://www.mycompany.com:8080
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.tomcat.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>
See Listeners for more information about lifecycle listeners.
You can ask Catalina to check the IP address, or host name, of an incoming request for this particular 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. An example configuration that rejects requests from any domain except "mycompany.com" would be:
<Host name="www.mycompany.com" ...> ... <Valve className="org.apache.tomcat.valves.RemoteHostValve" allow="*.mycompany.com"/> ... </Host>
See Request Filter Valve for more information on the syntax of the filters, and the logic that is applied when they are executed.
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.tomcat.startup.UserConfig" directoryName="public_html" userClass="org.apache.tomcat.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.tomcat.startup.UserConfig" directoryName="public_html" homeBase="c:\Homes" userClass="org.apache.tomcat.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.
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.