Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Deployment and Contexts

Virtual Hosts in Tomcat

Configure several domains in one Tomcat with Host elements: name, aliases, appBase, defaultHost, separate logs per host, and test host routing with a Java stand-in.

One Tomcat can answer for many domain names at once: www.example.com, blog.example.com and shop.example.org, each with its own applications, access logs and settings. This is done with virtual hosts, the <Host> elements inside the Engine. A client tells the server which site it wants with the Host header; Tomcat reads it and routes the request to the matching Host.

This lesson shows the configuration, the directory layout it creates, the role of aliases and the default host, and a runnable test that sends real requests with different Host headers to a tiny multi-host server.

Configuring hosts

XML
<Engine name="Catalina" defaultHost="www.example.com">

  <Host name="www.example.com" appBase="webapps-main"
        unpackWARs="true" autoDeploy="false">
    <Alias>example.com</Alias>
    <Valve className="org.apache.catalina.valves.AccessLogValve"
           directory="logs" prefix="main_access." suffix=".log"
           pattern="%h %l %u %t &quot;%r&quot; %s %b" />
  </Host>

  <Host name="blog.example.com" appBase="webapps-blog"
        unpackWARs="true" autoDeploy="false">
    <Valve className="org.apache.catalina.valves.AccessLogValve"
           directory="logs" prefix="blog_access." suffix=".log"
           pattern="%h %l %u %t &quot;%r&quot; %s %b" />
  </Host>

</Engine>

Create the appBase folders (webapps-main, webapps-blog) in CATALINA_BASE. Each host gets its own set of contexts: webapps-blog/ROOT.war is the blog's root application, while webapps-main/ROOT.war is the main site's. Context descriptors for each host live under conf/Catalina/<host name>/, for example conf/Catalina/blog.example.com/ROOT.xml.

One Tomcat, many sites

Host name Matches the Host header
Alias Extra names for the same host
appBase Own applications folder
Valves Own access log

defaultHost catches everything else.

1 / 2

Name matching

  • The engine compares the Host header (without the port) with each Host's name and its <Alias> entries, case-insensitively. A wildcard name such as *.example.com is supported (the wildcard may only be the leftmost label); an exact name wins over a wildcard.
  • If nothing matches, the request goes to defaultHost. That is why a request to the server's raw IP address, or to a domain that merely points at your server, ends up on the default host: do not make a sensitive application your default host, or any visitor can reach it by IP.
  • HTTP/1.1 requires the Host header. HTTP/1.0 clients without it also end up on the default host.
flowchart LR
    R["Request<br/>Host: blog.example.com"] --> E{"Engine<br/>compare name and aliases"}
    E -->|"match"| H1["Host blog.example.com"]
    E -->|"no match"| D["defaultHost<br/>www.example.com"]

Matching ignores the port and letter case.

Test it yourself

The program below starts a small server on a free loopback port that picks a "host" from the Host header with aliases, a wildcard and a default. A raw-socket client then sends several requests with chosen headers (the JDK HttpClient forbids setting Host, so raw sockets are used).

Java Host header routing over real sockets (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The last request shows the fallback: an unknown name lands on the default host.

Separate settings per host

A Host can have its own:

  • appBase and context descriptors (conf/Catalina/<host>/).
  • Valves, for example separate access logs per site (see logging).
  • Realm, if the sites authenticate against different user stores.
  • xmlBase, a different location for descriptors, and workDir for work files.
  • Deployment policy such as autoDeploy and deployOnStartup.

Applications in different hosts are fully isolated: each context has its own class loader and session store, and the same context path (/ or /app) can exist in several hosts.

Validating a host plan

Tomcat refuses to start (or logs an error) when two hosts claim the same name or alias, because routing would be ambiguous. This checker reviews a plan before you write the XML:

Java Find duplicate names and aliases (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Putting TLS and virtual hosts together

Since the Host header travels inside the encrypted request, the TLS handshake (which happens first) cannot use it to choose a certificate by itself. Browsers send the requested name in the SNI extension during the handshake. Tomcat can serve several certificates with SSLHostConfig elements inside a connector, one per host name (TLS later in this track). Until you configure that, all hosts share one certificate on a given connector, so use a wildcard or SAN certificate that covers every name.

Common mistakes

  • Forgetting the alias for the bare domain (example.com), so it hits the default host.
  • Making an admin application reachable through the default host.
  • Creating the Host but not the appBase directory.
  • Putting a descriptor in conf/Catalina/localhost/ when the application belongs to another host.
  • Testing with the browser address http://localhost:8080 and expecting a virtual host: use a real DNS name or an /etc/hosts entry, or curl -H "Host: blog.example.com" http://localhost:8080/.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which HTTP header makes Tomcat choose the virtual host?

    The Engine matches the Host header (without port) against Host names and aliases.
  2. 2. A request arrives with a Host header that matches no Host or Alias. What happens?

    defaultHost is used when no name matches, which is why it should hold a harmless site.
  3. 3. Where do context descriptors for host blog.example.com live?

    The folder under conf/<engine name>/ is named after the Host.
  4. 4. How do browsers tell the server which certificate they want during the TLS handshake?

    Server Name Indication sends the host name before encryption starts; the Host header arrives later, inside the encrypted channel.

Summary

  • A <Host> element defines a virtual host with its own appBase, aliases, valves and contexts.
  • The Engine picks the Host from the Host header and falls back to defaultHost.
  • Hosts are isolated from each other, and each can have its own access log.
  • Test with curl -H "Host: ..." or raw sockets; keep sensitive apps off the default host.
  • For several TLS names, use SNI with one SSLHostConfig per name.

Next: Class loading in Tomcat