<document>
<header>
  <product>resin</product>
  <title>resin.xml: top-level configuration</title>
  <version>Resin 3.0</version>

  <description>

  <p>The top-level &lt;resin> tag contains any
&lt;<a href="cluster-tags.xtp">cluster</a>&gt; defined for a deployment.
It also provides an <a href="env-tags.xtp">resources</a> for
class-loaders, logging and shared resources.</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="server-tags.xtp">Server tags</a> for JVM-specific configuration like thread-max, JVM settings, ports, etc.</li>
<li>See <a href="webapp-tags.xtp">Web Application</a> configuration for web.xml (Servlet) configuration.</li>
<li>See <a href="config-env.xtp">Resource</a> configuration: classloader, databases, connectors, and 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;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>

<ul>
<li>See <a href="cluster-tags">&lt;cluster> tags</a> for more details
about the cluster contents.</li>
<li>See <a href="server-tags">&lt;server> tags</a> for more details
about the server contents.</li>
</ul>

<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 title="&lt;cluster> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>id</td>
  <td>Name of the cluster</td>
  <td>required</td>
</tr>
</deftable>

</defun>

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

<p>&lt;cluster-default> configures common configuration for all
clusters.</p>
</defun>

<defun title="&lt;environment-system-properties>">
<default>true</default>

<p>By default, Resin's <code>System.getProperties()</code> is
environment-dependent, so the settings in on web-app do not affect the
properties in any other web-app.  Some sites may need to disable
this virtualization capability, when using certain JVM agents.</p>

<def title="&lt;environment-system-properties> schema">
element environment-system-properties {
  r_boolean-Type
}
</def>

</defun>

<defun title="&lt;jmx-service>">

<p>&lt;jmx-service> enables the clustered JMX management.</p>

<def title="&lt;jmx-service> schema">
element jmx-service {
  enable?
}
</def>

</defun>

<defun title="&lt;log-service>">

<p>&lt;log-service> enables persistent storage of warning and critical
log messages in the administration.</p>

<def title="&lt;log-service> schema">
element log-service {
  enable?
  &amp; level?
}
</def>

</defun>

<defun title="&lt;management>" version="Resin 3.0">

<p>&lt;management> controls system-wide management capabilities, like
the clustered JMX reporting, transaction logging, and persistence logging.
It also defines a system-wide administration authenticator, providing a
centralized place to manage administration identity.</p>

<p>The &lt;user> configuration is particularly important since it is used
as a security measure for the <a href="resin-watchdog.xtp">watchdog</a>
as well as for remote JMX capabilities.</p>

<deftable title="&lt;management> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>jmx-service</td>
  <td>enables the remote JMX administration (Resin-Pro)</td>
</tr>
<tr>
  <td>log-service</td>
  <td>enables persistent log management (Resin-Pro)</td>
</tr>
<tr>
  <td>path</td>
  <td>configures the directory for storing management data</td>
</tr>
<tr>
  <td>user</td>
  <td>configures system-wide administration accounts</td>
</tr>
<tr>
  <td>xa-log-service</td>
  <td>enables XA logging (Resin-Pro)</td>
</tr>
</deftable>

<def title="&lt;management> schema">
element management {
  jmx-service?
  &amp; log-service?
  &amp; path
  &amp; secure?
  &amp; user*
}

element user {
  name
  &amp; password
  &amp; disable?
}
</def>

<s2 title="user">

<p>The &lt;user> tags in &lt;management> define Resin administrators for
the /resin-admin service and also add security for JMX remoting and the
watchdog.</p>

<p>Since the authenticator is available to all web-apps, you can
use the &lt;management> login as a simple security authenticator for
the entire site.  The role of the logged-in user is <var>resin-admin</var>,
for configuring security authentication and for the <code>isUserInRole</code>
method.</p>

<p>The password field is an MD5 hash of the username and password for security.
The /resin-admin or <code>PasswordDigest</code> can be used to create the
hash.  See <a href="resin-security.xtp">Resin security</a> for more
information.</p>

<deftable title="&lt;user> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>name</td>
  <td>The user's name</td>
  <td>required</td>
</tr>
<tr>
  <td>password</td>
  <td>An MD5 hash of the username and password.  The /resin-admin page
provides an easy way of generating the hash.</td>
  <td>required</td>
</tr>
<tr>
  <td>disable</td>
  <td>disable the user from logging in</td>
  <td>false</td>
</tr>
</deftable>

<def title="&lt;user> schema">
element user {
  name
  &amp; password
  &amp; disable?
}
</def>
</s2>

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

<def title="&lt;resin> schema">
element resin {
  <var>env resources</var>
  &amp; cluster*
  &amp; cluster-default*
  &amp; environment-system-properties?
  &amp; management?
  &amp; min-free-memory?
  &amp; root-directory?
  &amp; security-manager?
  &amp; security-provider?
  &amp; watchdog-manager?
}
</def>


<example title="Example: minimal resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  &lt;root-directory>/var/www&lt;/root-directory>

  &lt;cluster id="web-tier"&gt;
    &lt;server id="">
      &lt;http address="*" port="8080"/&gt;
    &lt;/server>

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

    &lt;host id="">
      &lt;web-app id="" root-directory="/var/www/htdocs"/&gt;
    &lt;/host&gt;
  &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</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 resin">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &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;cluster id="app-tier"&gt;
     ...
  &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;root-directory>" version="Resin 3.0">
<parents>resin, cluster, host, web-app</parents>

<p>&lt;root-directory> specifies the base directory
for the contexts. All EL-style directory paths are relative to
the root-directory.</p>

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

</defun>

<defun title="&lt;security-manager>">
<p>
&lt;security-manager> enables the use of the security manager for the JVM.
Because the JVM security manager is very slow, we generally do not
recommend enabling it for server applications.  Instead, see the
<a href="resin-watchdog.xtp">watchdog</a> configuration for alternative
methods for securiting the JVM in ISP configurations.
</p>

<def title="&lt;security-manager> schema">
element security-manager {
  r_boolean-Type
}
</def>

<example title="Example: enabling security-manager">
&lt;resin xmlns="http://caucho.com/ns/resin">

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

</defun>

<defun title="&lt;security-provider>">
<p>
&lt;security-provider> adds 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">Security.addProvider</a>.
</p>

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

<example title="Example: adding custom security providers">
&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> <!-- security-provider -->

<defun title="Variables">

<s2 title="java">

<deftable title="java properties">
<tr>
  <th>Property</th>
  <th>Description</th>
</tr>
<tr>
  <td>version</td>
  <td>Returns the JDK version from the java.version property</td>
</tr>
</deftable>

</s2>

<s2 title="resin">

<deftable title="resin properties">
<tr>
  <th>Property</th>
  <th>Description</th>
</tr>
<tr>
  <td>address</td>
  <td>The machine's address as returned by InetAddress</td>
</tr>
<tr>
  <td>conf</td>
  <td>The path to the resin.xml</td>
</tr>
<tr>
  <td>home</td>
  <td>The --resin-home value, i.e. the location of the Resin installation</td>
</tr>
<tr>
  <td>homeName</td>
  <td>The local hostname as returned by InetAddress</td>
</tr>
<tr>
  <td>id</td>
  <td>The --serverId command line value (see serverId)</td>
</tr>
<tr>
  <td>isProfessional()</td>
  <td>True if Resin professional is installed and licensed</td>
</tr>
<tr>
  <td>root</td>
  <td>The --resin-root value, i.e. the site's deployment directory</td>
</tr>
<tr>
  <td>serverId</td>
  <td>The --serverId command line value</td>
</tr>
<tr>
  <td>version</td>
  <td>The Resin version</td>
</tr>
<tr>
  <td>versionDate</td>
  <td>The compilation date of Resin</td>
</tr>
</deftable>

</s2>

<defun title="&lt;stat-service>">

<p>&lt;stat-service> periodically checks the status of the server,
and reports errors as necessary.</p>

<deftable title="&lt;stat-service> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>cpu-load-exit-threshold</td>
  <td>CPU load triggering a Resin exit (and restart)</td>
  <td>100.0</td>
</tr>
<tr>
  <td>cpu-load-log-info-threshold</td>
  <td>CPU load triggering a log message at the info level</td>
  <td>1.0</td>
</tr>
<tr>
  <td>cpu-load-log-warning-threshold</td>
  <td>CPU load triggering a log message at the warning level</td>
  <td>5.0</td>
</tr>
<tr>
  <td>cpu-load-log-thread-dump-threshold</td>
  <td>CPU load triggering thread dump to the log</td>
  <td>5.0</td>
</tr>
<tr>
  <td>sample-period</td>
  <td>how often to sample the statistics</td>
  <td>60s</td>
</tr>
<tr>
  <td>thread-dump-interval</td>
  <td>minimum time between thread dumps</td>
  <td>15m</td>
</tr>
</deftable>

<def title="&lt;stat-service> schema">
element stat-service {
  cpu-load-exit-threshold?
  &amp; cpu-load-log-info-threshold?
  &amp; cpu-load-log-warning-threshold?
  &amp; cpu-load-thread-dump-threshold?
  &amp; sample-period?
  &amp; thread-dump-interval?
}
</def>

</defun>

<s2 title="system">

<p>The ${system} variable return the <code>System.getProperties()</code>
value.</p>

<example title="Example: returning -Dfoo=bar">
&lt;resin xmlns="http://caucho.com/ns/resin"
      xmlns:resin="http://caucho.com/ns/resin/core">

  &lt;resin:message>${system['foo']}&lt;/resin:message>

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

</s2>

</defun>

<defun title="watchdog">

<p>The &lt;watchdog> tag is used in ISP-style
configurations where the &lt;watchdog-manager> is configured separately
from the resin.xml instances, and where the configuration file is generally
not readable by the instance users.</p>

<p>The &lt;watchdog> tag corresponds to the &lt;server> tag in standard
resin.xml configurations, and specifies the resin.xml, the root directory
and resin-user.</p>

<deftable title="&lt;watchdog> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>chroot</td>
  <td>calls chroot before starting the Resin process</td>
  <td></td>
</tr>
<tr>
  <td>group-name</td>
  <td>setgid value for unix systems</td>
  <td></td>
</tr>
<tr>
  <td>java-exe</td>
  <td>java executable to use for the Resin instance</td>
  <td>java</td>
</tr>
<tr>
  <td>java-home</td>
  <td>JAVA_HOME value for the Resin instance</td>
  <td></td>
</tr>
<tr>
  <td>open-port</td>
  <td>list of ports the watchdog should open for the Resin instance, e.g.
for ports that require root access</td>
  <td></td>
</tr>
<tr>
  <td>resin.xml</td>
  <td>Path to the resin.xml file for the Resin instance</td>
  <td>same as for watchdog</td>
</tr>
<tr>
  <td>resin-root</td>
  <td>Root directory for the Resin instance</td>
  <td>same as for watchdog</td>
</tr>
</deftable>

<def title="&lt;watchdog> schema">
element watchdog {
  attribute id { string }
  &amp; chroot?
  &amp; group-name?
  &amp; java-exe?
  &amp; java-home?
  &amp; jvm-arg*
  &amp; resin.xml?
  &amp; resin-root?
  &amp; open-port { address &amp; port }*
  &amp; user-name?
}
</def>

</defun>
<defun title="watchdog-manager">

<p>For ISP configurations, &lt;watchdog-manager> is used for a separate
resin.xml just to configure the watchdog-manager itself.  The
&lt;watchdog-manager> selects the &lt;user-name>, &lt;resin.xml>,
ports, and Resin home directories before giving access to the user's
Resin instance.</p>

<deftable title="&lt;watchdog-manager> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>watchdog</td>
  <td>Watchdog configuration for a Resin instance, corresponding to a &lt;server> in the resin.xml</td>
  <td></td>
</tr>
<tr>
  <td>watchdog-address</td>
  <td>The TCP address the watchdog-manager listens for start, stop, status</td>
  <td>127.0.0.1</td>
</tr>
<tr>
  <td>watchdog-default</td>
  <td>Defaults applied to all watchdog instances</td>
  <td></td>
</tr>
<tr>
  <td>watchdog-jvm-arg</td>
  <td>JVM arguments for the watchdog-manager when launched</td>
  <td></td>
</tr>
<tr>
  <td>watchdog-port</td>
  <td>The TCP port the watchdog-manager listens for start, stop, status</td>
  <td>6700</td>
</tr>
</deftable>

<def title="&lt;watchdog-manager> schema">
element watchdog-manager {
  watchdog*
  &amp; watchdog-address?
  &amp; watchdog-default*
  &amp; watchdog-jvm-arg*
  &amp; watchdog-port?
}
</def>

</defun>

<defun title="xa-log-service">

<p>&lt;xa-log-service> enables the transaction-manager logging.  The XA log
enables Resin to recover from server crashes and complete XA commits.</p>

<def title="&lt;xa-log-service> schema">
element xa-log-service {
  enable?
}
</def>
</defun>

</body>
</document>
