Resin Documentation

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

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

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

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

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.

element management {
  jmx-service?
  & log-service?
  & path
  & secure?
  & user*
}

element user {
  name
  & password
  & disable?
}

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>

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>

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

  ...

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

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?
}

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

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.

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?
}