<document>
<header>
  <title>&lt;host>: Virtual Host configuration</title>
  <version>Resin 3.1</version>

  <description>

  <p>Describes the virtual host configuration tags.</p>

  </description>
</header>
<body>

<localtoc/>

<s1 title="See Also">

<ul>
<li>See the <a href="index-tags.xtp">index</a> for a list of all the tags.</li>
<li>See <a href="webapp-tags.xtp">Web Application</a> configuration for web.xml (Servlet) configuration.</li>
<li>See <a href="env-tags.xtp">Resource</a> configuration for resources: classloader, databases, JMS, EJB, and IoC beans.</li>
<li>See <a href="config-log.xtp">Log</a> configuration for access log configuration, java.util.logging, and stdout/stderr logging.</li>
</ul>

</s1>

<defun title="&lt;access-log>" version="Resin 2.1">
<parents>cluster, host, web-app</parents>

<p>&lt;access-log> configures the access log file.</p>

<p>As a child of <a config-tag="web-app"/>, overrides the
definition in the <a config-tag="host"/> that the web-app is
deployed in. As a child of <a config-tag="host"/>, overrides the
definition in the <a config-tag="server"/> that the host is
in.</p>

<deftable title="&lt;access-log> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-format</td>
  <td>the format for the archive filename when a rollover occurs,
        see <a href="#rollover">Rollovers</a>.
  </td>
  <td>see below</td>
</tr>
<tr>
  <td>format</td>
  <td>Access log format.</td>
  <td>see below</td>
</tr>
<tr>
  <td>path</td>
  <td>Output path for the log entries,
see <a href="config-log.xtp#path">"Log Paths"</a>.</td>
  <td>required</td>
</tr>
<tr>
  <td>rollover-period</td>
  <td>how often to rollover the log.  Specify in days (15D), weeks (2W), 
        months (1M), or hours (1h). See <a href="#rollover">Rollovers</a>. 
  </td>
  <td>none</td>
</tr>
<tr>
  <td>rollover-size</td>
  <td>maximum size of the file before a rollover occurs, in bytes (50000), 
        kb (128kb), or megabytes (10mb).  
        See <a href="#rollover">Rollovers</a>.
  </td>
  <td>1mb</td>
</tr>
<tr>
  <td>resin:type</td>
  <td>a class extending <a href="javadoc|com.caucho.server.log.AccessLog|"/>
        for custom logging
  </td>
  <td>com.caucho.server.log.AccessLog</td>
</tr>
<tr>
  <td>init</td>
  <td>Resin-IoC initialization for the custom class</td>
  <td>n/a</td>
</tr>
</deftable>

<def title="&lt;access-log> schema">
element access-log {
  auto-flush?
  &amp; archive-format?
  &amp; auto-flush-time?
  &amp; exclude?
  &amp; format?
  &amp; path?
  &amp; rollover-count?
  &amp; rollover-period?
  &amp; rollover-size?
  &amp; init?
}
</def>

<p>The default archive format is
</p><pre>
  <var>path</var> + ".%Y%m%d" or
  <var>path</var> + ".%Y%m%d.%H" if rollover-period &lt; 1 day.
</pre>

<p>The access log formatting variables follow the Apache variables:</p>
<!-- duplicated in config-log.xtp, cluster.xtp, host-tags.xtp -->
<deftable title="format patterns">
<tr>
  <th>Pattern</th>
  <th>Description</th>
</tr>
<tr><td>%b</td>
    <td>result content length</td></tr>
<tr><td>%D</td>
    <td>time taken to complete the request in microseconds (since 3.0.16)</td></tr>
<tr><td>%h</td>
    <td>remote IP addr</td></tr>
<tr><td>%{<var>xxx</var>}i</td>
    <td>request header <var>xxx</var></td></tr>
<tr><td>%{<var>xxx</var>}o</td>
    <td>response header <var>xxx</var></td></tr>
<tr><td>%{<var>xxx</var>}c</td>
    <td>cookie value <var>xxx</var></td></tr>
<tr><td>%n</td>
    <td>request attribute</td></tr>
<tr><td>%r</td>
    <td>request URL</td></tr>
<tr><td>%s</td>
    <td>status code</td></tr>
<tr><td>%{<var>xxx</var>}t</td>
    <td>request date with optional time format string.</td></tr>
<tr><td>%T</td>
    <td>time taken to complete the request in seconds</td></tr>
<tr><td>%u</td>
    <td>remote user</td></tr>
<tr><td>%U</td>
    <td>request URI</td></tr>
</deftable>

<p>The default format is:</p>

<def title="default access log format">
"%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\" \"%{User-Agent}i\""
</def>

<p><var>resin:type</var> allows for custom logging.  Applications can
extend a custom class from <a href="javadoc|com.caucho.http.log.AccessLog|"/>.  
<a href="resin-ioc.xtp">Resin-IoC initialization</a> can be used to set bean
parameters in the custom class.</p>

<example title="Example: &lt;access-log> in host configuration">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="app-tier">

  &lt;host id=""&gt;
    &lt;access-log path='log/access.log'&gt;
      &lt;rollover-period&gt;2W&lt;/rollover-period&gt;
    &lt;/access-log&gt;
  &lt;/host>
&lt;/cluster&gt;
&lt;/resin&gt;
</example>

<example title="Example: custom access log">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="app-tier">

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

&lt;/cluster>
&lt;/resin>
</example>

</defun>
    
<defun title="&lt;ear-deploy>">
<parents>host, web-app</parents>

<p>Specifies ear expansion.</p>

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

<deftable title="&lt;ear-deploy> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-path</td>
  <td>The path to the directory containing ear files</td>
  <td>path</td>
</tr>
<tr>
  <td>ear-default</td>
  <td>resin.conf default configuration for all ear files, e.g. configuring
database, JMS or EJB defaults.</td>
  <td></td>
</tr>
<tr>
  <td>expand-cleanup-fileset</td>
  <td>Specifies the files which should be automatically deleted when a
new .ear version is deployed.</td>
  <td></td>
</tr>
<tr>
  <td>expand-directory</td>
  <td>directory where ears should be expanded</td>
  <td>value of <var>path</var></td>
</tr>
<tr>
  <td>expand-prefix</td>
  <td>automatic prefix of the expanded directory</td>
  <td>_ear_</td>
</tr>
<tr>
  <td>expand-suffix</td>
  <td>automatic suffix of the expanded directory</td>
  <td></td>
</tr>
<tr>
  <td>lazy-init</td>
  <td>if true, the ear file is only started on first access</td>
  <td>false</td>
</tr>
<tr>
  <td>path</td>
  <td>The path to the deploy directory</td>
  <td>required</td>
</tr>
<tr>
  <td>redeploy-mode</td>
  <td>"automatic" or "manual".  If automatic, detects new .ear files
automatically and deploys them.</td>
  <td>automatic</td>
</tr>
<tr>
  <td>url-prefix</td>
  <td>optional URL prefix to group deployed .ear files</td>
  <td></td>
</tr>
</deftable>

<def title="&lt;ear-deploy> schema">
element ear-deploy {
  path
  &amp; archive-directory?
  &amp; ear-default?
  &amp; expand-cleanup-fileset?
  &amp; expand-directory?
  &amp; expand-path?
  &amp; expand-prefix?
  &amp; expand-suffix?
  &amp; lazy-init?
  &amp; redeploy-mode?
  &amp; require-file*
  &amp; url-prefix?
}
</def>

</defun>

<defun title="&lt;error-page>" version="Resin 3.1">
<parents>cluster, host, webapp</parents>

<p>&lt;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 &lt;web-app&gt;, the error-page for
that web-app will be used instead.</p>

<p>See <a href="webapp.xtp#error-page">webapp: error-page</a>.</p>

</defun>

<defun title="&lt;host>" version="Resin 3.0">
<parents>cluster</parents>

<p>&lt;host> configures a virtual host.  Virtual hosts must be
configured explicitly.</p>

<deftable title="&lt;host> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr><td>id</td>
    <td>primary host name</td>
    <td>none</td></tr>
<tr><td>regexp</td>
    <td>Regular expression based host matching</td>
    <td>none</td></tr>
<tr><td>host-name</td>
    <td>Canonical host name</td>
    <td>none</td></tr>
<tr><td>host-alias</td>
    <td>Aliases matching the same host</td>
    <td>none</td></tr>
<tr><td>secure-host-name</td>
    <td>Host to use for a redirect to SSL</td>
    <td>none</td></tr>
<tr><td>root-directory</td>
    <td>Root directory for host files</td>
    <td>parent directory</td></tr>
<tr><td>startup-mode</td>
    <td>'automatic', 'lazy', or 'manual', see <a href="resin-tags.xtp#startup-mode">Startup and Redeploy Mode</a></td>
    <td>automatic</td></tr>
</deftable>

<example title="Example: explicit host in resin.conf">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="">

&lt;host host-name="www.foo.com"&gt;
  &lt;host-alias&gt;foo.com&lt;/host-alias&gt;
  &lt;host-alias&gt;web.foo.com&lt;/host-alias&gt;

  &lt;root-directory&gt;/opt/www/www.foo.com&lt;/root-directory&gt;

  &lt;web-app id="/" document-directory="webapps/ROOT"&gt;
    
  &lt;/web-app&gt;
  ...
&lt;/host&gt;

&lt;/cluster>
&lt;/resin>
</example>

<example title="Example: regexp host in resin.conf">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="">

&lt;host regexp="([^.]+)\.foo\.com"&gt;
  &lt;host-name&gt;${host.regexp[1]}.foo.com&lt;/host-name&gt;

  &lt;root-directory&gt;/var/www/hosts/www.${host.regexp[1]}.com&lt;/root-directory&gt;

  ...
&lt;/host&gt;

&lt;/cluster>
&lt;/resin>
</example>

<p>It is recommended that any &lt;host&gt; using a regexp include
a &lt;host-name&gt; to set the canonical name for the host.</p>

</defun>

<defun title="&lt;host-alias>">

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

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

<def title="&lt;host-alias> schema">
element host-alias {
  string
}
</def>

<example title="Example: host-alias in the resin.conf">
&lt;resin xmlns="http://caucho.com">
&lt;cluster id="">

  &lt;host id="www.foo.com" root-directory="/var/www/foo.com">
    &lt;host-alias>foo.com&lt;/host-alias>

    &lt;web-app id=""/>
  &lt;/host>

&lt;/cluster>
&lt;/resin>
</example>

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

<example title="Example: host-alias in a /var/www/hosts/foo/host.xml">
&lt;host xmlns="http://caucho.com">

  &lt;host-name>www.foo.com&lt;/host-name>
  &lt;host-alias>foo.com&lt;/host-alias>

  &lt;web-app id="" root-directory="htdocs"/>

&lt;/host>
</example>

</defun>

<defun title="&lt;host-alias-regexp>">

<p>&lt;host-alias-regexp> defines a regular expression for matching
URLs for a given virtual host.</p>

<def title="&lt;host-alias-regexp> schema">
element host-alias-regexp {
  string
}
</def>

<example title="Example: host-alias-regexp in the resin.conf">
&lt;resin xmlns="http://caucho.com">
&lt;cluster id="">

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

    &lt;web-app id=""/>
  &lt;/host>

&lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;host-default>" version="Resin 3.0">
<parents>cluster</parents>

<p>&lt;host-default> configures defaults for a virtual host.</p>

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

</defun>

<defun title="&lt;host-deploy>" version="Resin 3.0.4">
<parents>cluster</parents>

<p>&lt;host-deploy> configures an automatic deployment directory
for virtual host.</p>

<deftable title="&lt;host-deploy> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-directory</td>
  <td>path to the archive directory</td>
  <td>path</td>
</tr>
<tr>
  <td>path</td>
  <td>path to the deploy directory</td>
  <td>required</td>
</tr>
<tr>
  <td>expand-cleanup-fileset</td>
  <td>an ant-style fileset defining which directories to cleanup when
an archive is redeployed</td>
  <td></td>
</tr>
<tr>
  <td>expand-directory</td>
  <td>path to the expansion directory</td>
  <td>path</td>
</tr>
<tr>
  <td>host-default</td>
  <td>defaults for the expanded host</td>
  <td></td>
</tr>
<tr>
  <td>host-name</td>
  <td>the default hostname, based on the directory</td>
  <td>${name}</td>
</tr>
</deftable>

<def title="&lt;host-deploy> schema">
element host-deploy {
  archive-directory?
  &amp; expand-cleanup-fileset?
  &amp; expand-directory?
  &amp; host-default?
  &amp; host-name?
  &amp; path?
}
</def>

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

<example title="&lt;host-deploy>">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">
    &lt;root-directory>/var/www&lt;/root-directory>

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

        &lt;web-app-deploy path="webapps"/>
      &lt;/host-default>
    &lt;/host-deploy>
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;host-name>">

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

<def title="&lt;host-host> schema">
element host-name {
  string
}
</def>

</defun>

<defun title="&lt;redeploy-mode>">

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

<deftable title="startup-mode values">
<tr>
  <th>Mode</th>
  <th>Description</th>
</tr>
<tr>
  <td>automatic</td>
  <td>automatically restart when detecting changes</td>
</tr>
<tr>
  <td>manual</td>
  <td>only restart only on a JMX administration request</td>
</tr>
</deftable>

<def title="&lt;restart-mode> schema">
element startup-mode {
  string
}
</def>

</defun>

<defun title="Resources" version="Resin 3.1">
<parents>resin, cluster, host, web-app</parents>

<p>All <a href="env-tags.xtp">Resource tags</a> are
available to the &lt;host&gt;, for example, resources
like &lt;database&gt; or &lt;authenticator>.  Resources defined at
the host level are available for all web-apps in the host.</p>

<example title="Example: shared database in host">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="app-tier"&gt;
     &lt;server id="a" .../>

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

        &lt;web-app-default path="webapps"/>
    &lt;/host&gt;
  &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;rewrite-dispatch>" version="Resin 3.1">
<parents>cluster, host, web-app</parents>

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

<p>See <a href="rewrite-tags.xtp">rewrite-dispatch</a> for more
details.</p>

<example title="rewrite-dispatch">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="app-tier"&gt;

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

  &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;root-directory>" version="Resin 3.1">

<p>&lt;root-directory> configures the virtual host's filesystem root.</p>

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

<def title="&lt;root-directory> schema">
element root-directory {
  string
}
</def>

</defun>

<defun title="&lt;secure-host-name>">

<p>&lt;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 &lt;secure-host-name> configures
the host to redirect to.</p>

<p>See <a href="resin-security.xtp">Resin security</a>.</p>

<def title="&lt;secure-host-name> schema">
element secure-host-name {
  string
}
</def>

</defun>

<defun title="&lt;startup-mode>">

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

<deftable title="startup-mode values">
<tr>
  <th>Mode</th>
  <th>Description</th>
</tr>
<tr>
  <td>automatic</td>
  <td>automatically start when Resin starts</td>
</tr>
<tr>
  <td>lazy</td>
  <td>start only when the first request is received</td>
</tr>
<tr>
  <td>manual</td>
  <td>start only when JMX administration requests a start</td>
</tr>
</deftable>

<def title="&lt;startup-mode> schema">
element startup-mode {
  string
}
</def>

</defun>

<defun title="&lt;web-app>">
<parents>host, web-app</parents>

<p>&lt;web-app> configures a web application.</p>

<deftable title="&lt;web-app> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>id</td>
  <td>The url prefix selecting this application.</td>
  <td>n/a</td>
</tr>
<tr>
  <td>url-regexp</td>
  <td>A regexp to select this application.</td>
  <td>n/a</td>
</tr>
<tr>
  <td>document-directory</td>
  <td>The document directory for
the application, corresponding to a url of <var>/<i>id</i>/</var>. A relative path is relative to the <a config-tag="root-directory"/> of the containing <a config-tag="host"/>.  Can use regexp replacement variables.</td><td>A relative path constricted with the id or the regexp match
</td>
</tr>
<tr>
  <td>startup-mode</td>
  <td>'automatic', 'lazy', or 'manual', see <a href="resin.xtp#startup-mode">Startup and Redeploy Mode</a></td>
  <td>automatic</td>
</tr>
<tr>
  <td>redeploy-mode</td>
  <td>'automatic' or 'manual', see <a href="resin.xtp#startup-mode">Startup and Redeploy Mode</a></td>
  <td>automatic</td>
</tr>
</deftable>

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

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

<example title="Example: custom web-app root" >
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="app-tier">

&lt;host id=''&gt;
  &lt;web-app id='/apache' root-directory='/usr/local/apache/htdocs'&gt;

  ...

&lt;/host&gt;

&lt;/cluster>
&lt;/resin>
</example>

<p>The following example sets the root web-app to the IIS
root directory. </p>

<example title="Example: IIS root directory">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="app-tier">
&lt;host id=''&gt;

  &lt;web-app id='/' root-directory='C:/inetpub/wwwroot'&gt;

&lt;/host>
&lt;/cluster>
&lt;/resin>
</example>

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

<p>In the following, each user gets his or her own independent
application using <var>~user</var>.</p>

<example title="Example: web-app root based on regexps">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="app-tier">

  &lt;host id=''&gt;

    &lt;web-app url-regexp='/~([^/]*)'
             root-directory='/home/$1/public_html'&gt;

    ...

    &lt;/web-app&gt;

&lt;/host&gt;

&lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;web-app-default>">
<parents>cluster, host, web-app</parents>

<p>&lt;web-app-default> configures common values for all web applications.</p>
</defun>

<defun title="&lt;web-app-deploy>" type="defun">
<parents>host, web-app</parents>

<p>Specifies war expansion.</p>

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

<deftable title="&lt;web-app-deploy> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-directory</td>
  <td>directory containing the .war files</td>
  <td>value of <var>path</var></td>
</tr>
<tr>
  <td>expand-cleanup-fileset</td>
  <td>defines the files which should be automatically deleted
when an updated .war expands</td>
  <td>all files</td>
</tr>
<tr>
  <td>expand-directory</td>
  <td>directory where wars should be expanded</td>
  <td>value of <var>path</var></td>
</tr>
<tr>
  <td>expand-prefix</td>
  <td>prefix string to use when creating the expansion directory, e.g. _war_</td>
  <td></td>
</tr>
<tr>
  <td>expand-suffix</td>
  <td>prefix string to use when creating the expansion directory, e.g. .war</td>
  <td></td>
</tr>
<tr>
  <td>path</td>
  <td>The path to the webapps directory</td>
  <td>required</td>
</tr>
<tr>
  <td>redeploy-check-interval</td>
  <td>How often to check the .war files for a redeploy</td>
  <td>60s</td>
</tr>
<tr>
  <td>redeploy-mode</td>
  <td>"automatic" or "manual"</td>
  <td>automatic</td>
</tr>
<tr>
  <td>require-file</td>
  <td>additional files to use for dependency checking for auto restart</td>
  <td></td>
</tr>
<tr>
  <td>startup-mode</td>
  <td>"automatic", "lazy" or "manual"</td>
  <td>automatic</td>
</tr>
<tr>
  <td>url-prefix</td>
  <td>url-prefix added to all expanded webapps</td>
  <td>""</td>
</tr>
<tr>
  <td>versioning</td>
  <td>if true, use the web-app's numeric suffix as a version</td>
  <td>false</td>
</tr>
<tr>
  <td>web-app-default</td>
  <td>defaults to be applied to expaned web-apps</td>
  <td></td>
</tr>
<tr>
  <td>web-app</td>
  <td>overriding configuration for specific web-apps</td>
  <td></td>
</tr>
</deftable>

<def title="&lt;web-app-deploy> schema">
element web-app-deploy {
  archive-directory?
  &amp; expand-cleanup-fileset?
  &amp; expand-directory?
  &amp; expand-prefix?
  &amp; expand-suffix?
  &amp; path?
  &amp; redeploy-check-interval?
  &amp; redeploy-mode?
  &amp; require-file*
  &amp; startup-mode?
  &amp; url-prefix?
  &amp; versioning?
  &amp; web-app-default*
  &amp; web-app*
}
</def>

<s2 title="Overriding web-app-deploy configuration">

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

<example title="Example: resin.conf overriding web.xml">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="">
&lt;host id="">

&lt;web-app-deploy path="webapps"&gt;
  &lt;web-app context-path="/wiki"
              document-directory="wiki"&gt;
    &lt;context-param database="jdbc/wiki"&gt;
  &lt;/web-app&gt;
&lt;/web-app-deploy&gt;

&lt;/host>
&lt;/cluster>
&lt;/resin>
</example>

</s2>

<s2 title="versioning">

<p>The versioning attribute of the &lt;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.</p>

</s2>

</defun>

</body>
</document>
