Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


Resin Documentation

home company docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server

resin.conf: top-level configuration

The top-level <resin> tag contains any <cluster> defined for a deployment. It also provides an resources for class-loaders, logging and shared resources.

See Also

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


child of <resin>

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

<resin xmlns="">
  <cluster id="app-tier">
    <server id="a" address=""/>
    <server id="b" address=""/>

    <host id="">
      <web-app-deploy path="webapps"/>
<cluster> Attributes
idName of the clusterrequired


child of <resin>

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


default true

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.

<environment-system-properties> schema
element environment-system-properties {


<jmx-service> enables the clustered JMX management.

<jmx-service> schema
element jmx-service {


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

<log-service> schema
element log-service {
  & 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.

<management> Attributes
jmx-serviceenables the remote JMX administration (Resin-Pro)
log-serviceenables persistent log management (Resin-Pro)
pathconfigures the directory for storing management data
userconfigures system-wide administration accounts
xa-log-serviceenables XA logging (Resin-Pro)
<management> schema
element management {
  & log-service?
  & path
  & secure?
  & user*

element user {
  & 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.

<user> Attributes
nameThe user's namerequired
passwordAn MD5 hash of the username and password. The /resin-admin page provides an easy way of generating the hash.required
disabledisable the user from logging infalse
<user> schema
element user {
  & 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.

<resin> schema
element resin {
  env resources
  & cluster*
  & cluster-default*
  & environment-system-properties?
  & management?
  & min-free-memory?
  & root-directory?
  & security-manager?
  & security-provider?
  & watchdog-manager?
Example: minimal resin.conf
<resin xmlns=""

  <cluster id="web-tier">
    <server id="">
      <http address="*" port="8080"/>

    <resin:import path="app-default.xml"/>

    <host id="">
      <web-app id="" root-directory="/var/www/htdocs"/>


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 resin
<resin xmlns="">
  <database jndi-name="jdbc/test">
    <driver type="org.postgresql.Driver">

  <cluster id="app-tier">


child of <resin>,<cluster>,<host>,<web-app>

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

<root-directory> schema
element root-directory {


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

<security-manager> schema
element security-manager {
Example: enabling security-manager
<resin xmlns="">



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

<security-provider> schema
element security-provider {
Example: adding custom security providers
<resin xmlns=""






java properties
versionReturns the JDK version from the java.version property


resin properties
addressThe machine's address as returned by InetAddress
confThe path to the resin.conf
homeThe --resin-home value, i.e. the location of the Resin installation
homeNameThe local hostname as returned by InetAddress
idThe --serverId command line value (see serverId)
isProfessional()True if Resin professional is installed and licensed
rootThe --resin-root value, i.e. the site's deployment directory
serverIdThe --serverId command line value
versionThe Resin version
versionDateThe compilation date of Resin


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

<stat-service> Attributes
cpu-load-exit-thresholdCPU load triggering a Resin exit (and restart)100.0
cpu-load-log-info-thresholdCPU load triggering a log message at the info level1.0
cpu-load-log-warning-thresholdCPU load triggering a log message at the warning level5.0
cpu-load-log-thread-dump-thresholdCPU load triggering thread dump to the log5.0
sample-periodhow often to sample the statistics60s
thread-dump-intervalminimum time between thread dumps15m
<stat-service> schema
element stat-service {
  & 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.

Example: returning -Dfoo=bar
<resin xmlns=""




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.

<watchdog> Attributes
chrootcalls chroot before starting the Resin process
group-namesetgid value for unix systems
java-exejava executable to use for the Resin instancejava
java-homeJAVA_HOME value for the Resin instance
open-portlist of ports the watchdog should open for the Resin instance, e.g. for ports that require root access
resin-confPath to the resin.conf file for the Resin instancesame as for watchdog
resin-rootRoot directory for the Resin instancesame as for watchdog
<watchdog> schema
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.

<watchdog-manager> Attributes
watchdogWatchdog configuration for a Resin instance, corresponding to a <server> in the resin.conf
watchdog-addressThe TCP address the watchdog-manager listens for start, stop, status127.0.0.1
watchdog-defaultDefaults applied to all watchdog instances
watchdog-jvm-argJVM arguments for the watchdog-manager when launched
watchdog-portThe TCP port the watchdog-manager listens for start, stop, status6700
<watchdog-manager> schema
element watchdog-manager {
  & 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.

<xa-log-service> schema
element xa-log-service {

Copyright © 1998-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).
Leading companies worldwide with demand for reliability and high performance web applications including, CNET, DZone and many more are powered by Resin.

home company docs 
app server