<host>: Virtual Host configuration
Resin 3.1

Documentation
Examples
Changes

Overview
Quick Start
Installation
Command-Line
Configuration
Admin
Amber
Clustering
Caching
Database
Deployment
EJB 3.0
Embedding
Filters
Hessian
HMTP
IoC
JSP
Logging
Messaging
Performance
Quercus/PHP
Remoting
Scheduled Tasks
Security
Server Push
Servlets
Third-party
Troubleshooting
Virtual Hosting
Watchdog
WebApp
XML and XSLT

<cluster>
<database>
<host>
Ports
<resin>
Resource tags
Rewrite
<server>
session
variables
<web-app>
Index
Relax Schema
<database>
Configuration
Ports

Describes the virtual host configuration tags.

See Also

  • See the index for a list of all the tags.
  • See Web Application configuration for web.xml (Servlet) configuration.
  • See Resource configuration for resources: classloader, databases, JMS, EJB, and IoC beans.
  • See Log configuration for access log configuration, java.util.logging, and stdout/stderr logging.
<access-log>
child of cluster, host, web-app

<access-log> configures the access log file.

As a child of , overrides the definition in the that the web-app is deployed in. As a child of , overrides the definition in the that the host is in.

<access-log> Attributes
AttributeDescriptionDefault
archive-formatthe format for the archive filename when a rollover occurs, see Rollovers. see below
formatAccess log format.see below
pathOutput path for the log entries, see "Log Paths".required
rollover-periodhow often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See Rollovers. none
rollover-sizemaximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See Rollovers. 1mb
resin:typea class extending for custom logging com.caucho.server.log.AccessLog
initResin-IoC initialization for the custom classn/a
<access-log> schema
element access-log { auto-flush? & archive-format? & auto-flush-time? & exclude? & format? & path? & rollover-count? & rollover-period? & rollover-size? & init? }

The default archive format is

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

The access log formatting variables follow the Apache variables:

format patterns
PatternDescription
%bresult content length
%Dtime taken to complete the request in microseconds (since 3.0.16)
%hremote IP addr
%{xxx}irequest header xxx
%{xxx}oresponse header xxx
%{xxx}ccookie value xxx
%nrequest attribute
%rrequest URL
%sstatus code
%{xxx}trequest date with optional time format string.
%Ttime taken to complete the request in seconds
%uremote user
%Urequest URI

The default format is:

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

resin:type allows for custom logging. Applications can extend a custom class from . Resin-IoC initialization can be used to set bean parameters in the custom class.

Example: <access-log> in host configuration
<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>
Example: custom access log
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">

  <host id='foo.com'>
    <access-log resin:type='test.MyLog'>
               path='${resin.root}/foo/error.log'
               rollover-period='1W'>
      <init>
        <foo>bar</foo>
      </init>
    </access-log>
    ...
  </host>

</cluster>
</resin>
<ear-deploy>
child of host, web-app

Specifies ear expansion.

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

<ear-deploy> Attributes
AttributeDescriptionDefault
archive-pathThe path to the directory containing ear filespath
ear-defaultresin.conf default configuration for all ear files, e.g. configuring database, JMS or EJB defaults.
expand-cleanup-filesetSpecifies the files which should be automatically deleted when a new .ear version is deployed.
expand-directorydirectory where ears should be expandedvalue of path
expand-prefixautomatic prefix of the expanded directory_ear_
expand-suffixautomatic suffix of the expanded directory
lazy-initif true, the ear file is only started on first accessfalse
pathThe path to the deploy directoryrequired
redeploy-mode"automatic" or "manual". If automatic, detects new .ear files automatically and deploys them.automatic
url-prefixoptional URL prefix to group deployed .ear files
<ear-deploy> schema
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>
child of cluster, host, webapp

<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>
child of cluster

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

<host> Attributes
AttributeDescriptionDefault
idprimary host namenone
regexpRegular expression based host matchingnone
host-nameCanonical host namenone
host-aliasAliases matching the same hostnone
secure-host-nameHost to use for a redirect to SSLnone
root-directoryRoot directory for host filesparent directory
startup-mode'automatic', 'lazy', or 'manual', see Startup and Redeploy Modeautomatic
Example: explicit host in resin.conf
<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>
Example: regexp host in resin.conf
<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>

<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.conf or in a host.xml when use host-deploy together with resin:import.

<host-alias> schema
element host-alias { string }
Example: host-alias in the resin.conf
<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.

Example: host-alias in a /var/www/hosts/foo/host.xml
<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>

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

<host-alias-regexp> schema
element host-alias-regexp { string }
Example: host-alias-regexp in the resin.conf
<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>
child of cluster

<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>
child of cluster

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

<host-deploy> Attributes
AttributeDescriptionDefault
archive-directorypath to the archive directorypath
pathpath to the deploy directoryrequired
expand-cleanup-filesetan ant-style fileset defining which directories to cleanup when an archive is redeployed
expand-directorypath to the expansion directorypath
host-defaultdefaults for the expanded host
host-namethe default hostname, based on the directory${name}
<host-deploy> schema
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.

<host-deploy>
<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>

<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.

<host-host> schema
element host-name { string }
<redeploy-mode>

<redeploy-mode> configures the virtual-host's behavior when it detects changes in configuration files or classes. The <dependency-check-interval> controls how often the virtual host will check for updates.

startup-mode values
ModeDescription
automaticautomatically restart when detecting changes
manualonly restart only on a JMX administration request
<restart-mode> schema
element startup-mode { string }
Resources
child of resin, cluster, host, web-app

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.

Example: shared database in 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>
child of cluster, host, web-app

<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.

rewrite-dispatch
<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>

<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.

<root-directory> schema
element root-directory { string }
<secure-host-name>

<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.

<secure-host-name> schema
element secure-host-name { string }
<startup-mode>

<startup-mode> configures the virtual-host's behavior on Resin startup, either "automatic", "lazy" or "manual".

startup-mode values
ModeDescription
automaticautomatically start when Resin starts
lazystart only when the first request is received
manualstart only when JMX administration requests a start
<startup-mode> schema
element startup-mode { string }
<web-app>
child of host, web-app

<web-app> configures a web application.

<web-app> Attributes
AttributeDescriptionDefault
idThe url prefix selecting this application.n/a
url-regexpA regexp to select this application.n/a
document-directoryThe document directory for the application, corresponding to a url of /id/. A relative path is relative to the of the containing . Can use regexp replacement variables.A relative path constricted with the id or the regexp match
startup-mode'automatic', 'lazy', or 'manual', see Startup and Redeploy Modeautomatic
redeploy-mode'automatic' or 'manual', see Startup and Redeploy Modeautomatic

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.

Example: custom web-app root
<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.

Example: 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.

Example: web-app root based on regexps
<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>
child of cluster, host, web-app

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

<web-app-deploy>
child of host, web-app

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.

<web-app-deploy> Attributes
AttributeDescriptionDefault
archive-directorydirectory containing the .war filesvalue of path
expand-cleanup-filesetdefines the files which should be automatically deleted when an updated .war expandsall files
expand-directorydirectory where wars should be expandedvalue of path
expand-prefixprefix string to use when creating the expansion directory, e.g. _war_
expand-suffixprefix string to use when creating the expansion directory, e.g. .war
pathThe path to the webapps directoryrequired
redeploy-check-intervalHow often to check the .war files for a redeploy60s
redeploy-mode"automatic" or "manual"automatic
require-fileadditional files to use for dependency checking for auto restart
startup-mode"automatic", "lazy" or "manual"automatic
url-prefixurl-prefix added to all expanded webapps""
versioningif true, use the web-app's numeric suffix as a versionfalse
web-app-defaultdefaults to be applied to expaned web-apps
web-appoverriding configuration for specific web-apps
<web-app-deploy> schema
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* }

Overriding web-app-deploy configuration

The web-app-deploy can override configuration for an expanded war with a matching <web-app> inside the <web-app-deploy>. The <document-directory> is used to match web-apps.

Example: resin.conf overriding web.xml
<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>

versioning

The versioning attribute of the <web-app-deploy> tag improves web-app version updates by enabling a graceful update of sessions. The web-apps are named with numeric suffixes, e.g. foo-10, foo-11, etc, and can be browsed as /foo. When a new version of the web-app is deployed, Resin continues to send current session requests to the previous web-app. New sessions go to the new web-app version. So users will not be aware of the application upgrade.


<database>
Configuration
Ports
Copyright © 1998-2006 Caucho Technology, Inc. All rights reserved.
Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.