<document>
<header>
  <product>resin</product>
  <title>resin.xml: Ports, Virtual Hosts, Clustering and Threads</title>
  <version>Resin 3.0</version>

  <description>

  <p>Describes the resin, server, host, and port configuration in the resin.xml.</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.xtp">Web Application</a> configuration for web.xml (Servlet) configuration.</li>
<li>See <a href="config-env.xtp">Environment</a> configuration for resources: classloader, databases, connectors, and resources.</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;cluster>" version="Resin 3.0">
<parents>resin</parents>

<p>&lt;cluster> configures a set of servers used for load-balancing and for
sharing distributed sessions.</p>

<example>
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier"&gt;
    &lt;server id="a" address="192.168.0.1"/>
    &lt;server id="b" address="192.168.0.2"/>

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

<deftable-childtags>
<tr><td>id</td>
    <td>Name of the cluster</td>
    <td>required</td></tr>
</deftable-childtags>

</defun>

<defun title="&lt;min-free-memory>" version="Resin 3.0">
<parents>resin</parents>

<p>For reliability, Resin periodically checks the amount of free
memory available.  When the free memory drops below
&lt;min-free-memory&gt;, even after garbage collection, Resin will force
a JVM restart.</p>

<p>In general, application developers should use a heap profiler
to eliminate memory leaks and OutOfMemoryErrors.  Because an
OutOfMemoryError can cause severe problems with the application, Resin
detects the low memory before those errors can be thrown.</p>

<default>1M</default>

</defun>

<defun title="&lt;resin>" version="Resin 3.0">
      
<p>&lt;resin> is the top-level configuration tag for
the resin.xml file.  The &lt;resin&gt;
tag needs to specify the Resin namespace, to allow for validation
of the configuration file.</p>

<p>The environment of the top-level &lt;resin&gt; is the global classpath.
This environment can be important for &lt;log&gt; configuration
for threads which run with using only the global class loader.
Because the &lt;resin&gt; environment does not have a dynamic class loader,
dynamically loaded classes, like custom jars
in resin/lib are not available.</p>

<example title="resin">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server id="">
      &lt;http address="*" port="8080"/&gt;
    &lt;/server id="">

    &lt;resin:import path="app-default.xml"/&gt;

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

<deftable title="EL variables defined by &lt;resin&gt;">
<tr><th>variable</th>
    <th>corresponding API</th>
    <th/></tr>
<tr><td>resin-home</td>
    <td>CauchoSystem.getResinHome()</td>
    <td/></tr>
<tr><td>server-root</td>
    <td>CauchoSystem.getServerRoot()</td>
    <td/></tr>
</deftable>

</defun>

<defun title="root-directory" version="Resin 3.0">
<parents>server, host</parents>

<p>Specifies the root directory for the &lt;server&gt; and &lt;host&gt;
contexts. All EL-style directory paths are relative to
the root-directory.</p>

</defun>

<defun title="security-manager">
<p>
Enable the use of the security manager for the JVM.
</p>

<example>
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core"&gt;

  ...
  &lt;security-manager/&gt;
  ...
</example>

<p>See also:</p>
<ul>
<li><a href="securitymanager.xtp">Security Manager</a></li>
</ul>
</defun>

<defun title="security-provider">
<p>
Add one or more security providers.  Each entry specifies the name of a
security provider class.  The name is used to instantiate an instance of the
object, which is then passed to 
<a href="javadoc|java.security.Security|addProvider"/>.
</p>

<example>
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core"&gt;

  ...

  &lt;security-provider&gt;
    com.sun.net.ssl.internal.ssl.Provider
  &lt;/security-provider&gt;
  &lt;security-provider&gt;
    example.MyProvider
  &lt;/security-provider&gt;

  ...

</example>

</defun>

<defun title="server" version="Resin 3.0">
<parents>resin</parents>

<p>Main configuration for the server, configuring ports,
threads and virtual hosts.</p>

<ul>
<li>Common resources for all virtual hosts and web-apps.</li>
<li>Thread pooling</li>
<li>HTTP and SRUN/Cluster ports</li>
<li>Caching</li>
<li>virtual host configuration and common web-app-default</li>
</ul>

<p>The &lt;server&gt; will generally contain a &lt;class-loader&gt; configuration
which loads the resin/lib jars dynamically, allowing for system-wide jars
to be dropped into resin/lib.  &lt;server&gt; configures
the main dynamic environment.  Database pools common to all virtual hosts,
for example, should be configured in the &lt;server&gt; block.</p>

<p>The &lt;server&gt; configures the &lt;thread-pool&gt; and a set
of &lt;http&gt; and &lt;srun&gt; ports which share the thread pool.
Requests received on those ports will use worker threads from the
thread pool.</p>

<deftable-childtags>
<tr><td>alternate-session-url-prefix</td>
    <td>a prefix to add the session to the beginning of the URL as a path
        prefix instead of the standard ;jsessionid= suffix. For clients like
        mobile devices with limited memory, this will allow careful web
        designers to minimize the page size.</td>
    <td>null</td></tr>
<tr><td>keepalive-max</td>
    <td>the maximum number of keepalive connections</td>
    <td>512</td></tr>
<tr><td>keepalive-timeout</td>
    <td>the maximum time a connection is maintained in the keepalive state</td>
    <td>120s</td></tr>
</deftable-childtags>

<example title="alternate-session-url-prefix">
&lt;server&gt;
  ...
  &lt;alternate-session-url-prefix&gt;/~J=&lt;/alternate-session-url-prefix&gt;
  ...
</example>

<s2 name="server-el" title="EL variables and functions">
<deftable title="EL variables defined by &lt;server&gt;">
<tr><th>variable</th>
    <th>corresponding API</th></tr>
<tr><td>serverId</td>
    <td><i>server</i>.getServerId()</td></tr>
<tr><td>root-dir</td>
    <td><i>server</i>.getRootDirectory()</td></tr>
<tr><td>server-root</td><td><i>server</i>.getRootDirectory()</td></tr>
</deftable>

<deftable title="EL functions defined by &lt;server&gt;">
<tr><th>function</th>
    <th>corresponding API</th></tr>
<tr><td>jndi</td>
    <td><a href="javadoc|com.caucho.naming.Jndi|lookup(String)">Jndi.lookup(String)</a></td></tr>
</deftable>

</s2>
</defun> <!-- server -->

<defun title="shutdown-wait-max" version="Resin 3.0">
<parents>resin</parents>

<p>Configures the maximum time Resin will wait for the server to
shutdown gracefully before forcing an exit.</p>

<default>60s</default>

</defun>

<defun title="&lt;thread-pool>" version="Resin 3.0">
<parents>server</parents>

<p>&lt;thread-pool> configures the thread pool shared among all ports.</p>

<deftable-childtags>
<tr><td>thread-max</td>
    <td>maximum number of working threads</td>
    <td>200</td></tr>
<!--
<tr><td>spare-thread-max</td><td>maximum number of spare working threads</td><td>20</td></tr>
-->
<tr><td>spare-thread-min</td><td>minimum number of spare working threads</td><td>5</td></tr>
</deftable-childtags>

<p>&lt;thread-max&gt; is the absolute maximum number of connection worker
threads allowed.  &lt;thread-max&gt; may be limited by OS/JVM
restrictions, especially the stack size.  -Xss and/or ulimit -s may be
required for large numbers of threads, e.g. "ulimit -s 2048" on some
versions of Linux would allow for 1024 total threads in the JVM.</p>

<!--
<p>&lt;spare-thread-max> and &lt;spare-thread-min> configure Resin's
adaptive thread pooling.  Resin tries to keep between &lt;spare-thead-min>
and &lt;spare-thread-max> idle threads available at all time.  Sites
with large spikes in connection loads may need to increase the
&lt;spare-thread-min> value.</p>
-->

<p>&lt;spare-thread-min&gt; configures Resin's
adaptive thread pooling.  Resin tries to keep &lt;spare-thead-min&gt;
idle threads available at all time.  Sites
with large spikes in connection loads may need to increase the
&lt;spare-thread-min&gt; value.</p>

</defun>

<defun title="user-name" version="Resin 3.0">
<parents>resin</parents>

<p>Note: at present, this directive is deprecated because of timing
issues with log file creation and ownership.  It is recommended that
you use some other method to remap port 80 to port 8080.</p>

<p>Configures the Unix setuid user name used after Resin binds the
reserved ports as root.</p>

</defun>

<s1 name="common" title="Common Tags">

<p>There are some conventions for tag names that provide similar functionality.</p>

<s2 title="fileset" version="Resin 3.0.7" type="defun">

<p>&lt;fileset&gt; provides the ability to match a set of files.  It is
modelled after the ant tag by the same name.</p>

<deftable-childtags>
<tr><td>dir</td>
    <td>the starting directory</td>
    <td>required</td></tr>
<tr><td>include</td>
    <td>an include pattern</td>
    <td>do not include all files</td></tr>
<tr><td>exclude</td>
    <td>an exclude pattern</td>
    <td>do not exclude any files</td></tr>
</deftable-childtags>

<p>A pattern can contain two special characters: '*' and '**'.  '*' matches any
part of path, but does not match the path separator.  '**' matches any part of
a path, including the path separator. </p>

<example>
&lt;fileset dir="lib"&gt;
  &lt;include name="*.jar"/&gt;
&lt;/fileset&gt;

MATCH    lib/foo.jar
MATCH    lib/bar.jar
NO MATCH lib/baz/foo.jar
</example>

<example>
&lt;fileset dir="lib"&gt;
  &lt;include name="**/*.jar"/&gt;
&lt;/fileset&gt;

MATCH    lib/foo.jar
MATCH    lib/bar.jar
MATCH    lib/baz/foo.jar
</example>

</s2>

</s1> <!-- common -->

<s1 name="startup-mode" title="Startup and Redeploy Mode">

<p>The <a config-tag="startup-mode"/> is used in a number of places to
determine the behaviour of a resource when the server starts.</p>

<p>The startup-mode has three values: "automatic", "lazy", and "manual".</p>
<ul>
<li>automatic - starts the resource on server start (default)</li>
<li>lazy - starts the resource on the first use</li>
<li>manual - waits for JMX to start the resource</li>
</ul>

<p>The <a config-tag="redeploy-mode"/> is used in a number of places to
determine the behaviour of a resource when it is replaced or modified while the
server is running.</p>

<p>The redeploy-mode has two values: "automatic", and "manual".</p>
<ul>
<li>automatic - restarts the resource when it is modified (web.xml, *.class, *.war, etc).</li>
<li>manual - waits for JMX to restart the resource when changes occur.</li>
</ul>

</s1> <!-- startup-mode -->

</body>
</document>