<document>
<localtoc/>

- See the index for a list of all the tags.
- See Server tags for JVM-specific configuration like thread-max, JVM settings, ports, etc.
- See Web Application configuration for web.xml (Servlet) configuration.
- See Resource configuration: classloader, databases, connectors, and beans.
- See Log configuration for access log configuration, java.util.logging, and stdout/stderr logging.

<parents>resin</parents>

<cluster> configures a set of servers used for load-balancing and for sharing distributed sessions.

- See <cluster> tags for more details about the cluster contents.
- See <server> tags for more details about the server contents.

<example> <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server id="a" address="192.168.0.1"/> <server id="b" address="192.168.0.2"/> <host id=""> <web-app-deploy path="webapps"/> </host> </cluster> </resin> </example>
Attribute Description Default
id Name of the cluster required
<parents>resin</parents>

<cluster-default> configures common configuration for all clusters.

<default>true</default>

By default, Resin's `System.getProperties()` 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.

element environment-system-properties { r_boolean-Type }

<jmx-service> enables the clustered JMX management.

element jmx-service { enable? }

<log-service> enables persistent storage of warning and critical log messages in the administration.

element log-service { enable? & level? }

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

The <user> configuration is particularly important since it is used as a security measure for the watchdog as well as for remote JMX capabilities.

Attribute Description
jmx-service enables the remote JMX administration (Resin-Pro)
log-service enables persistent log management (Resin-Pro)
path configures the directory for storing management data
user configures system-wide administration accounts
xa-log-service enables XA logging (Resin-Pro)
element management { jmx-service? & log-service? & path & secure? & user* } element user { name & password & disable? }

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

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

The password field is an MD5 hash of the username and password for security. The /resin-admin or `PasswordDigest` can be used to create the hash. See Resin security for more information.

Attribute Description Default
name The user's name required
password An MD5 hash of the username and password. The /resin-admin page provides an easy way of generating the hash. required
disable disable the user from logging in false
element user { name & password & disable? }

<resin> is the top-level configuration tag for the resin.conf file. The <resin> tag needs to specify the Resin namespace, to allow for validation of the configuration file.

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

element resin { env resources & cluster* & cluster-default* & environment-system-properties? & management? & min-free-memory? & root-directory? & security-manager? & security-provider? & watchdog-manager? } <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <root-directory>/var/www</root-directory> <cluster id="web-tier"> <server id=""> <http address="*" port="8080"/> </server> <resin:import path="app-default.xml"/> <host id=""> <web-app id="" root-directory="/var/www/htdocs"/> </host> </cluster> </resin> <parents>resin, cluster, host, web-app</parents>

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"> <database jndi-name="jdbc/test"> <driver type="org.postgresql.Driver"> <url>jdbc:postgresql://localhost/test</url> <user>caucho</user> </driver> </database> <cluster id="app-tier"> ... </cluster> </resin> <parents>resin, cluster, host, web-app</parents>

<root-directory> specifies the base directory for the contexts. All EL-style directory paths are relative to the root-directory.

element root-directory { r_path-Type }

<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 watchdog configuration for alternative methods for securiting the JVM in ISP configurations.

element security-manager { r_boolean-Type } <resin xmlns="http://caucho.com/ns/resin"> ... <security-manager/> ...

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

element security-provider { string } <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> ... <security-provider> com.sun.net.ssl.internal.ssl.Provider </security-provider> <security-provider> example.MyProvider </security-provider> ...
Property Description
version Returns the JDK version from the java.version property
Property Description
address The machine's address as returned by InetAddress
conf The path to the resin.conf
home The --resin-home value, i.e. the location of the Resin installation
homeName The local hostname as returned by InetAddress
id The --serverId command line value (see serverId)
isProfessional() True if Resin professional is installed and licensed
root The --resin-root value, i.e. the site's deployment directory
serverId The --serverId command line value
version The Resin version
versionDate The compilation date of Resin

<stat-service> periodically checks the status of the server, and reports errors as necessary.

Attribute Description Default
cpu-load-exit-threshold CPU load triggering a Resin exit (and restart) 100.0
cpu-load-log-info-threshold CPU load triggering a log message at the info level 1.0
cpu-load-log-warning-threshold CPU load triggering a log message at the warning level 5.0
cpu-load-log-thread-dump-threshold CPU load triggering thread dump to the log 5.0
sample-period how often to sample the statistics 60s
thread-dump-interval minimum time between thread dumps 15m
element stat-service { cpu-load-exit-threshold? & cpu-load-log-info-threshold? & cpu-load-log-warning-threshold? & cpu-load-thread-dump-threshold? & sample-period? & thread-dump-interval? }

The ${system} variable return the `System.getProperties()` value.

<resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <resin:message>${system['foo']}</resin:message> ... </resin>

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

The <watchdog> tag corresponds to the <server> tag in standard resin.conf configurations, and specifies the resin.conf, the root directory and resin-user.

Attribute Description Default
chroot calls chroot before starting the Resin process
group-name setgid value for unix systems
java-exe java executable to use for the Resin instance java
java-home JAVA_HOME value for the Resin instance
open-port list of ports the watchdog should open for the Resin instance, e.g. for ports that require root access
resin-conf Path to the resin.conf file for the Resin instance same as for watchdog
resin-root Root directory for the Resin instance same as for watchdog
element watchdog { attribute id { string } & chroot? & group-name? & java-exe? & java-home? & jvm-arg* & resin-conf? & resin-root? & open-port { address & port }* & user-name? }

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

Attribute Description Default
watchdog Watchdog configuration for a Resin instance, corresponding to a <server> in the resin.conf
watchdog-address The TCP address the watchdog-manager listens for start, stop, status 127.0.0.1
watchdog-default Defaults applied to all watchdog instances
watchdog-jvm-arg JVM arguments for the watchdog-manager when launched
watchdog-port The TCP port the watchdog-manager listens for start, stop, status 6700
element watchdog-manager { watchdog* & watchdog-address? & watchdog-default* & watchdog-jvm-arg* & watchdog-port? }

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

element xa-log-service { enable? }
</document>