virtual hosting

A Resin server can serve many virtual hosts, each with its own servlets and documents. The configuration is flexible, allowing dynamic host deployment in a hosts directory or using explicit <host> tags for additional control and security, and compatibility with existing Apache sites, enabling easy upgrades and evaluation for PHP servers to Quercus.

Virtual hosts are multiple internet domains served by the same Resin server. Because one JVM handles all the domains, its more memory and processing efficient, as well as sharing IP addresses. With Resin, adding virtual hosts can as easy as creating a directory like /var/www/hosts/foo.com and setting up the DNS name. Explicit virtual host is also possible to match existing layouts, like matching a /var/www/htdocs configuration when migrating a PHP mediawiki or wordpress site to use Quercus for security and performance.

The virtual host will contain one or more web-apps to serve the host's contents. Simple sites will use a fixed root webapp, like the Apache-style /var/www/htdocs. More complicated sites can use a webapps-style directory.

Each virtual host belongs to a Resin <cluster>, even if the cluster has only a single server.

For example, a Resin server might manage both the www.gryffindor.com and www.slytherin.com domains, storing the content in separate directories (/var/www/gryffindor and /var/www/slytherin), and using a single IP address for both domains. In this scenario, both www.gryffindor.com and www.slytherin.com are registered with the standard domain name service registry as having the IP address 192.168.0.13. When a user types in the url http://www.gryffindor.com/hello.jsp in their browser, the browser will send the HTTP request to the IP address 192.168.0.13 and send an additional HTTP header for the gryffindor host, "Host: www.gryffindor.com". When Resin receives the request it will grab the host header, and dispatch the request to the configured virtual host.

C: GET /test.jsp HTTP/1.1
C: Host: www.gryffindor.com
C:

1. host name
2. host aliases
3. optional host.xml
4. root directory
5. web-applications
6. configuration environment
7. logging

Resin can deploy virtual hosts automatically by scanning a host deployment directory for virtual host content. Each sub-directory in the hosts directory will cause Resin to create a new virtual host. To customize the configuration, you can add a host.xml in the host's root directory for shared databases, beans or security, or to add <host-alias> names.

You can add hosts dynamically to a running server just by creating a new host directory. Resin periodically scans the hosts directory looking for directory changes. When it detects a new host directory, it will automatically start serving files from the new virtual hosts.

If you add a default directory in the hosts, Resin will use it to serve all unknown virtual hosts. The default host is handy for simple servers with only a single virtual host and for sites where the virtual host is handled in software, like Drupal. If the default directory is missing, Resin will return 404 Not Found for any unknown virtual hosts.

/var/www/hosts/www.gryffindor.com/
                                 host.xml
                                 log/access.log
                                 webapps/ROOT/index.jsp
                                 webapps/ROOT/WEB-INF/resin-web.xml
				 
/var/www/hosts/www.slytherin.com/
                                host.xml
                                log/access.log
                                webapps/ROOT/index.php
                                webapps/ROOT/WEB-INF/resin-web.xml
				 
/var/www/hosts/default/
                      host.xml
                      log/access.log
                      webapps/ROOT/index.php
                      webapps/ROOT/WEB-INF/resin-web.xml

<host xmlns="http://caucho.com/ns/resin">
  <host-name>www.slytherin.com</host-name>
  <host-alias>slytherin.com</host-alias>
  <host-alias>quidditch.slytherin.com</host-alias>
</host>

<resin xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">
<cluster id="app-tier">
  <server id="app-a" address="192.168.1.13" port="6800">
    <http port="8080"/>
  </server>

  <development-mode-error-page/>

  <resin:import path="${__DIR__}/app-default.xml"/>
  
  <host-default>
    <resin:import path="host.xml" optional="true"/>

    <access-log path="log/access.log"/>
	
    <web-app-deploy path="webapps"/>
  </host-default>

  <host-deploy path="hosts">
  </host-deploy>
  
</cluster>
</resin>

${resin.root}/hosts/www.gryffindor.com/
${resin.root}/hosts/www.gryffindor.com/webapps/ROOT/index.jsp
${resin.root}/hosts/www.gryffindor.com/webapps/foo/index.jsp

${resin.root}/hosts/www.slytherin.com.jar

${resin.root}/hosts/www.gryffindor.com/lib/mysql-connector-java-3.1.0-alpha-bin.jar 
${resin.root}/hosts/www.gryffindor.com/classes/example/CustomAuthenticator.java

In a more structured site, you can take complete control of the virtual host configuration and configure each virtual host explicitly. Existing sites wanting to upgrade to Resin or sites with extra security needs may prefer to configure each <host> in the resin.xml. For example, a PHP Drupal site evaluating Quercus to improve performance and security might use the explicit <host> to point to the existing /var/www/htdocs directory.

In the explicit configuration, each virtual host has its own host block. At the very least, each host will define the id specifying the host name and a root web-app. A root-directory is often used to provide a host specific root for logfiles.

As with the dynamic hosting, servlets and web-apps must be configured either in a <host-default> or explicitly. If they are missing, Resin will return a 404 Not Found for security. The host id="" is the default host and will serve any request that doesn't match other hosts. If you don't have a default host, Resin will return a 404 Not Found for any unknown host.

The following sample configuration defines an explicit virtual hosts www.slytherin.com and a default host, each with its own root directory, access-log and a single explicit <web-app> in the htdocs directory. The default virtual host is configured just like a typical Apache configuration, so it can be used to upgrade an Apache/PHP site to use Quercus for security and performance.

<resin xmlns="http://caucho.com/ns/resin"
        xmlns:resin="urn:java:com.caucho.resin">
        
<cluster id="app-tier">
  <server id="app-a" address="192.168.1.10" port="6800">
    <http port="8080"/>
  </server>

  <development-mode-error-page/>

  <resin:import path="${__DIR__}/app-default.xml"/>

  <host id="">
    <root-directory>/var/www</root-directory>

    <access-log path="logs/access.log"/>

    <web-app id="" root-directory="htdocs"/>
  </host>

  <host id="www.slytherin.com">
    <host-alias>slytherin.com</host-alias>
    
    <root-directory>/var/slytherin</root-directory>

    <access-log path="logs/access.log"/>

    <web-app id="" root-directory="htdocs"/>
  </host>

</cluster>
</resin>

Browsing http://gryffindor.caucho.com/test.php will look for /var/www/htdocs/test.php.

Browsing http://slytherin.caucho.com/test.php will look for /var/slytherin/htdocs/test.php.

In some ISP setups, it may make sense to assign a server for each virtual host. The isolation of web-apps may not be sufficient; each host needs a separate JVM. In this configuration, each <host> belongs to its own <cluster> and has a dedicated <server>. Normally, this configuration will operate using load-balancing, so the load-balance server will dispatch requests as appropriate.

For further security restrictions, see the watchdog section. ISPs can also use the watchdog to assign different <user-name> values for each host and can even create chroot directories for each JVM.

A front-end web server receives all requests, and is configured to dispatch to back-end Resin server that correspond to the host name.

<resin xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">

  <cluster-default>
    <resin:import path="${resin.home}/conf/app-default.xml"/>
    
    <host-default>
      <web-app-deploy path="webapps"/>
    </host-default>
  </cluster-default>

  <cluster id="gryffindor>
    <server id="gryffindor" host="localhost" port="6800"/>

    <host id="www.gryffindor.com">
  
      <root-directory>/var/www/gryffindor</root-directory>

    </host>
  </cluster>

  <cluster id="slytherin">
    <server id="slytherin" host="localhost" port="6801"/>

    <host id="www.slytherin.com">
  
      <root-directory>/var/www/slytherin</root-directory>

    </host>
  </cluster>

  <cluster id="web-tier">
    <!-- see below -->
    ...
  </cluster>

</resin>

unix> java -jar lib/resin.jar -server gryffindor start
unix> java -jar lib/resin.jar -server slytherin start

unix> java -jar lib/resin.jar -server gryffindor stop
unix> java -jar lib/resin.jar -server slytherin stop

Resin web-tier load balancer

The host-specific back-end servers are ready to receive requests on their server ports. A third Resin server can be used as the front-end load-balancer. It receives all requests and dispatches to the back-end servers.

The Resin web server is configured using rewrite with a <resin:LoadBalance directive to dispatch to the back-end server. A cluster is defined for each back-end host, so that the <load-balance> knows how to find them.

Example: /etc/resin/resin.xml for front-end web server

<resin xmlns="http://caucho.com/ns/resin"
     xmlns:resin="urn:java:com.caucho.resin">
     
  <cluster id="web-tier">
    <server-default>
      <http port="80"/>
    </server-default>

    <server id="web" address="192.168.2.1" port="6800"/>

    <host id="gryffindor.com">
      <web-app id="/">

        <resin:LoadBalance regexp="" cluster="gryffindor"/>

      </web-app>
    </host>

    <host id="slytherin.com">
      <web-app id="/">

        <resin:LoadBalance regexp="" cluster="slytherin"/>

      </web-app>
    </host>
  </cluster>

  <cluster id="gryffindor">
    <server id="gryffindor" address="192.168.2.2" port="6800"/>

    <host id="www.gryffindor.com">
      ...
    </host>
  </cluster>

  <cluster id="slytherin">
    <server id="slytherin" address="192.168.2.2" port="6801"/>

    ...
  </cluster>
</resin>

Starting the servers on Unix

The front-end server JVM is started similar to the back-end JVMs:

Example: starting the load balancer

unix> java -jar lib/resin.jar -server web -conf conf/resin.xml start
...
unix> java -jar lib/resin.jar -server web -conf conf/resin.xml stop

Starting the servers on Windows

With Windows, each JVM is installed as a service. Service is installed using setup.exe graphical utility. It's possible to install a number of Resin services each using a unique name. The name will need to be supplied into 'Service Name' field.

You will either need to reboot the machine or start the service from the Control Panel/Services panel to start the server. On a machine reboot, NT will automatically start the service.

There is a bug in many JDKs which cause the JDK to exit when the administrator logs out. JDK 1.4 and later can avoid that bug if the JDK is started with -Xrs.

While Resin's virtual hosting is primarily aimed at named-based virtual hosts, it's possible to run Resin with IP-Based virtual hosts.

With IP virtual hosting, each <http> block is configured with the virtual host name. This configuration will override any virtual host supplied by the browser.

<resin xmlns="http://caucho.com/ns/resin">

<cluster id="web-tier">
  <server id="a">

    <http address="192.168.0.1" port="80"
          virtual-host="slytherin.caucho.com"/>

    <http address="192.168.0.2" port="80"
          virtual-host="gryffindor.caucho.com"/>

  </server>

  ...

  <host id="slytherin.caucho.com">
    ...
  </host>
</cluster>
</resin>

Resin's virtual hosting understands host names encoded using rfc3490 (Internationalizing Domain Names in Applications). This support should be transparent. Just specify the virtual host as usual, and Resin will translate the brower's encoded host name the unicode string.

Support, of course, depends on the browser. Mozilla 1.4 supports the encoding.

A common configuration uses virtual hosts with Apache or IIS. As usual, Apache or IIS will pass matching requests to Resin.

Apache

The Resin JVM configuration with Apache is identical to the standalone configuration. That similarity makes it easy to debug the Apache configuration by retreating to Resin standalone if needed.

The ServerName directive in Apache with the UseCanonicalName can be used to select a canonical name for the virtual host virtual hosting work. When Apache passes the request to Resin, it tells Resin the ServerName. Without the ServerName, Apache will use the "Host:" header in the HTTP request to select which host to serve.

httpd.conf

LoadModule caucho_module /usr/local/apache/libexec/mod_caucho.so

ResinConfigServer localhost 6802

UseCanonicalName on

<VirtualHost 127.0.0.1>
  ServerName gryffindor.caucho.com
</VirtualHost>

<VirtualHost 192.168.0.1>
  ServerName slytherin.caucho.com
</VirtualHost>

Note

You'll the LoadModule must appear before the ResinConfigServer for Apache to properly understand the ResinConfigServer command. If they're missing, Apache will send an error.

Apache front-end

The host-specific back-end JVMs are ready to receive requests on their server ports. Apache is the front-end server, and is configured to dispatch to the appropriate back-end Resin JVM for the host:

httpd.conf

UseCanonicalName on

<VirtualHost 127.0.0.1>
  ServerName gryffindor.caucho.com
  ResinConfigServer 192.168.0.10 6800
</VirtualHost>

<VirtualHost 192.168.0.1>
  ServerName slytherin.caucho.com
  ResinConfigServer 192.168.0.11 6800
</VirtualHost>

When you restart the Apache web server, you can look at http://gryffindor/caucho-status and http://slytherin/caucho-status to check your configuration. Check that each virtual host is using the server address and port that you expect.

During development and testing, it is often inconvenient or impossible to use real virtual host names that are registered as internet sites, and resolve to an internet-available IP address. OS-level features on the test client machine can be used to map a virtual host name to an IP address.

For example, developers often run the Resin server and the test client (usually a browser) on the same machine. The OS is configured to map the "www.gryffindor.com" and "www.slytherin.com" names to "127.0.0.1", pointing these host names back to computer that the client is running on.

Unix users edit the file /etc/hosts:

127.0.0.1       localhost

127.0.0.1       www.gryffindor.com
127.0.0.1       www.slytherin.com

Windows user edit the file C:\WINDOWS\SYSTEM32\DRIVERS\ETC\HOSTS:

127.0.0.1       localhost

127.0.0.1       www.gryffindor.com
127.0.0.1       www.slytherin.com

path + ".%Y%m%d" or
  path + ".%Y%m%d.%H" if rollover-period < 1 day.

"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

element access-log {
  path?
  & path-format?
  & archive-format?
  $amp;auto-flush?
  & auto-flush-time?
  & exclude*
  & format?
  & hostname-dns-lookup?
  & rollover-period?
  & rollover-size?
  & rollover-count?
  & resin:type?
  & init?
}

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">

  <host id="">
    <access-log path='log/access.log'>
      <rollover-period>2W</rollover-period>
    </access-log>
  </host>
</cluster>
</resin>

<resin xmlns="http://caucho.com/ns/resin">

<cluster id="app-tier">

  <host id='foo.com'>

    <access-log>
      <test:MyLog xmlns:test="urn:java:test">
                 path='${resin.root}/foo/error.log'
                 rollover-period='1W'>
          <test:foo>bar</test:foo>
      </test:MyLog>
    </access-log>
    ...
  </host>

</cluster>
</resin>

Specifies ear expansion.

ear-deploy can be used in web-apps to define a subdirectory for ear expansion.

element ear-deploy {
  path
  & archive-directory?
  & ear-default?
  & expand-cleanup-fileset?
  & expand-directory?
  & expand-path?
  & expand-prefix?
  & expand-suffix?
  & lazy-init?
  & redeploy-mode?
  & require-file*
  & url-prefix?
}

<error-page> defines a web page to be displayed when an error occurs outside of a web-app. Note, this is not a default error-page, i.e. if an error occurs inside of a <web-app>, the error-page for that web-app will be used instead.

See webapp: error-page.

<host> configures a virtual host. Virtual hosts must be configured explicitly.

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

<host host-name="www.foo.com">
  <host-alias>foo.com</host-alias>
  <host-alias>web.foo.com</host-alias>

  <root-directory>/opt/www/www.foo.com</root-directory>

  <web-app id="/" document-directory="webapps/ROOT">
    
  </web-app>
  ...
</host>

</cluster>
</resin>

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

<host regexp="([^.]+)\.foo\.com">
  <host-name>${host.regexp[1]}.foo.com</host-name>

  <root-directory>/var/www/hosts/www.${host.regexp[1]}.com</root-directory>

  ...
</host>

</cluster>
</resin>

It is recommended that any <host> using a regexp include a <host-name> to set the canonical name for the host.

<host-alias> defines a URL alias for matching HTTP requests. Any number of <host-alias> can be used for each alias.

The host-alias can be used either in the resin.xml or in a host.xml when use host-deploy together with resin:import.

element host-alias {
  string
}

<resin xmlns="http://caucho.com">
<cluster id="">

  <host id="www.foo.com" root-directory="/var/www/foo.com">
    <host-alias>foo.com</host-alias>

    <web-app id=""/>
  </host>

</cluster>
</resin>

Since the <host-deploy> and <host> tags lets you add a host.xml file to customize configuration, the <host-alias> can also fit in the custom host.xml page.

<host xmlns="http://caucho.com">

  <host-name>www.foo.com</host-name>
  <host-alias>foo.com</host-alias>

  <web-app id="" root-directory="htdocs"/>

</host>

<host-alias-regexp> defines a regular expression for matching URLs for a given virtual host.

element host-alias-regexp {
  string
}

<resin xmlns="http://caucho.com">
<cluster id="">

  <host id="www.foo.com" root-directory="/var/www/foo.com">
    <host-alias-regexp>.*foo.com</host-alias-regexp>

    <web-app id=""/>
  </host>

</cluster>
</resin>

<host-default> configures defaults for a virtual host.

The host-default can contain any of the host configuration tags. It will be used as defaults for any virtual host.

<host-deploy> configures an automatic deployment directory for virtual host.

element host-deploy {
  archive-directory?
  & expand-cleanup-fileset?
  & expand-directory?
  & host-default?
  & host-name?
  & path?
}

The following example configures /var/www/hosts as a host deployment directory. Each virtual host will have a webapps directory for .war deployment. So the directory /var/www/hosts/www.foo.com/webapps/bar/test.jsp would serve the URL http://www.foo.com/bar/test.jsp.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">
    <root-directory>/var/www</root-directory>

    <host-deploy path="hosts">
      <host-default>
        <resin:import path="host.xml" optional="true"/>

        <web-app-deploy path="webapps"/>
      </host-default>
    </host-deploy>
  </cluster>
</resin>

<host-name> defines the canonical name for a virtual host. The <host-name> will be used in Resin's logging, management, and is available in the host's variables.

element host-name {
  string
}

All Resource tags are available to the <host>, for example, resources like <database> or <authenticator>. Resources defined at the host level are available for all web-apps in the host.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">
     <server id="a" .../>

     <host id="www.foo.com">
        <database jndi-name="jdbc/test">
            <driver type="org.postgresql.Driver">
                <url>jdbc:postgresql://localhost/test</url>
                <user>caucho</user>
            </driver>
        </database>

        <web-app-default path="webapps"/>
    </host>
  </cluster>
</resin>

<rewrite-dispatch> defines a set of rewriting rules for dispatching and forwarding URLs. Applications can use these rules to redirect old URLs to their new replacements.

See rewrite-dispatch for more details.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">

    <host host-name="www.foo.com">
      <rewrite-dispatch>
        <redirect regexp="^/foo" target="/index.php?foo="/>
      </rewrite-dispatch>
    </host>

  </cluster>
</resin>

<root-directory> configures the virtual host's filesystem root.

Because the virtual host's root will typically contain non-public files like log files, all web-apps should have a path below the host.

element root-directory {
  string
}

<secure-host-name> sets a host-name or URL to be used for secure redirection. For some security configurations, Resin needs to redirect from an insecure site to a secure one. The <secure-host-name> configures the host to redirect to.

See Resin security.

element secure-host-name {
  string
}

<web-app> configures a web application.

When specified by id, the application will be initialized on server start. When specified by url-regexp, the application will be initialized at the first request. This means that load-on-startup servlets may start later than expected for url-regexp applications.

The following example creates a web-app for /apache using the Apache htdocs directory to serve pages.

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">

<host id=''>
  <web-app id='/apache' root-directory='/usr/local/apache/htdocs'>

  ...

</host>

</cluster>
</resin>

The following example sets the root web-app to the IIS root directory.

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">
<host id=''>

  <web-app id='/' root-directory='C:/inetpub/wwwroot'>

</host>
</cluster>
</resin>

When the web-app is specified with a url-regexp, root-directory can use replacement variables ($2).

In the following, each user gets his or her own independent application using ~user.

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">

  <host id=''>

    <web-app url-regexp='/~([^/]*)'
             root-directory='/home/$1/public_html'>

    ...

    </web-app>

</host>

</cluster>
</resin>

<web-app-default> configures common values for all web applications.

Specifies war expansion.

web-app-deploy can be used in web-apps to define a subdirectory for war expansion. The tutorials in the documentation use web-app-deploy to allow servlet/tutorial/helloworld to be an independent war file.

element web-app-deploy {
  archive-directory?
  & expand-cleanup-fileset?
  & expand-directory?
  & expand-prefix?
  & expand-suffix?
  & path?
  & redeploy-check-interval?
  & redeploy-mode?
  & require-file*
  & startup-mode?
  & url-prefix?
  & versioning?
  & web-app-default*
  & web-app*
}

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">
<host id="">

<web-app-deploy path="webapps">
  <web-app context-path="/wiki"
              document-directory="wiki">
    <context-param database="jdbc/wiki">
  </web-app>
</web-app-deploy>

</host>
</cluster>
</resin>