resin.xml: top-level configuration

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

<cluster>
<cluster-default>
<environment-system-properties>
<resin>
<resin-system-auth-key>
<resin:AdminAuthenticator>
<root-directory>
<security-manager>
<security-provider>
<stat-service>

<cluster>

child of resin

<cluster> configures a set of identically-configured servers. The cluster typically configures a set of <server>s, each with some ports, and a set of virtual <host>s.

Only one <cluster> is active in any on server. At runtime, the <cluster> is selected by the <server> with id matching the -server on the command line.

<cluster> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
id	The cluster identifier.	required
access-log	An access-log shared for all virtual hosts.
cache	Proxy cache for HTTP-cacheable results.
connection-error-page	IIS error page to use when isapi_srun to Resin connection fails
ear-default	default values for deployed ear files
error-page	Custom error-page when virtual-hosts fail to match
host	Configures a virtual host
host-default	Configures defaults to apply to all virtual hosts
host-deploy	Automatic host deployment based on a deployment directory
ignore-client-disconnect	Ignores socket exceptions thrown because browser clients have prematurely disconnected	false
invocation-cache-size	Size of the system-wide URL to servlet invocation mapping cache	16384
invocation-cache-max-url-length	Maximum URL length saved in the invocation cache	256
max-uri-length	Maximum URI length allowed in request	1024
machine	Configuration for grouping <server> onto physical machines
ping	Periodic checking of server URLs to verify server activity
redeploy-mode	"automatic" or "manual"	automatic
resin:choose	Conditional configuration based on EL expressions
resin:import	Imports a custom cluster.xml files for a configuration management
resin:if	Conditional configuration based on EL expressions
rewrite-dispatch	rewrites and dispatches URLs using regular expressions, similar to mod_rewrite
root-directory	The root filesystem directory for the cluster	${resin.root}
server	Configures JVM instances (servers). Each cluster needs at least one server
server-default	Configures defaults for all server instances
server-header	Configures the HTTP "Server: Resin/xxx" header	Resin/Version
session-cookie	Configures the servlet cookie name	JSESSIONID
session-sticky-disable	Disables sticky-sessions on the load balancer	false
url-character-encoding	Configures the character encoding for URLs	utf-8
url-length-max	Configures the maximum length of an allowed URL	8192
web-app-default	Configures defaults to apply to all web-apps in the cluster

<cluster> schema

element cluster {
  attribute id { string }
  & environment resources
  & access-log?
  & cache?
  & connection-error-page?
  & ear-default*
  & error-page*
  & host*
  & host-default*
  & host-deploy*
  & ignore-client-disconnect?
  & invocation-cache-size?
  & invocation-cache-max-url-length?
  & machine*
  & ping*
  & redeploy-mode?
  & resin:choose*
  & resin:import*
  & resin:if*
  & rewrite-dispatch?
  & root-directory?
  & server*
  & server-default*
  & server-header?
  & session-cookie?
  & session-sticky-disable?
  & url-character-encoding?
  & url-length-max?
  & web-app-default*
}

Example: cluster-default

<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <server-default>
            <http port="8080"/>
        </server-default>

        <server id="a" address="192.168.0.10"/>
        <server id="b" address="192.168.0.11"/>

        <host host-name="www.foo.com">
          ...
        </host>
    </cluster>
</resin>

<cluster-default>

child of resin

<cluster-default> defines default cluster configuration for all clusters in the <resin> server.

Example: cluster-default

<resin xmlns="http://caucho.com/ns/resin">
    <cluster-default>
        <cache entries="16384" memory-size="64M"/>
    </cluster-default>

    <cluster id="web-tier">
        ...
    </cluster>

    <cluster id="app-tier">
        ...
    </cluster>
</resin>

<environment-system-properties>

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 {
  r_boolean-Type
}

<resin>

<resin> is the top-level configuration tag for the resin.xml 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.xml

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

<resin-system-auth-key>

child of resin

<resin-system-auth-key> specifies authorization token for Resin's Security service.

<resin-system-auth-key> schema

element resin-system-auth-key {
  String
}

<resin:AdminAuthenticator>

javadoc <resin:AdminAuthenticator>

Authenticator used by Resin for administration purposes such as the /resin-admin application. Also used by the watchdog and clustering code to authenticate servers, so changing principals or passwords in this authenticator requires a shutdown and restart of the watchdog and Resin instances.

Uses the same syntax as XmlAuthenticator.

<resin:AdminAuthenticator> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
user	Specifies a user authentication record. There maybe zero, one or more records.	None
password-digest	Specifies the digest algorithm and format used to secure the password (see following section in this document for details).	md5-base64
path	Specifies the path to an XML file containing users and passwords.	None
logout-on-session-timeout	If true, the user will be logged out when the session times out.	true

<root-directory>

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 {
  r_path-Type
}

Example: cluster root-directory

<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <root-directory>/var/www/app-tier</root-directory>

        <server id="a" ...>

        <host host-name="www.foo.com">
    </cluster>
</resin>

<security-manager>

<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 {
  r_boolean-Type
}

Example: enabling security-manager

<resin xmlns="http://caucho.com/ns/resin">

  ...
  <security-manager/>
  ...

<security-provider>

<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 {
  string
}

Example: adding custom security providers

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

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

<stat-service> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
unix-load-avg-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

<stat-service> schema

element stat-service {
  unix-load-avg-exit-threshold?
  & cpu-load-log-info-threshold?
  & cpu-load-log-warning-threshold?
  & cpu-load-thread-dump-threshold?
  & sample-period?
  & thread-dump-interval?
}