Caucho Technology
  • resin 4.0
  • 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.



    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
    idThe cluster identifier.required
    access-logAn access-log shared for all virtual hosts.
    cacheProxy cache for HTTP-cacheable results.
    connection-error-pageIIS error page to use when isapi_srun to Resin connection fails
    ear-defaultdefault values for deployed ear files
    error-pageCustom error-page when virtual-hosts fail to match
    hostConfigures a virtual host
    host-defaultConfigures defaults to apply to all virtual hosts
    host-deployAutomatic host deployment based on a deployment directory
    ignore-client-disconnectIgnores socket exceptions thrown because browser clients have prematurely disconnectedfalse
    invocation-cache-sizeSize of the system-wide URL to servlet invocation mapping cache16384
    invocation-cache-max-url-lengthMaximum URL length saved in the invocation cache256
    max-uri-lengthMaximum URI length allowed in request1024
    machineConfiguration for grouping <server> onto physical machines
    pingPeriodic checking of server URLs to verify server activity
    redeploy-mode"automatic" or "manual"automatic
    resin:chooseConditional configuration based on EL expressions
    resin:importImports a custom cluster.xml files for a configuration management
    resin:ifConditional configuration based on EL expressions
    rewrite-dispatchrewrites and dispatches URLs using regular expressions, similar to mod_rewrite
    root-directoryThe root filesystem directory for the cluster${resin.root}
    serverConfigures JVM instances (servers). Each cluster needs at least one server
    server-defaultConfigures defaults for all server instances
    server-headerConfigures the HTTP "Server: Resin/xxx" headerResin/Version
    session-cookieConfigures the servlet cookie nameJSESSIONID
    session-sticky-disableDisables sticky-sessions on the load balancerfalse
    url-character-encodingConfigures the character encoding for URLsutf-8
    url-length-maxConfigures the maximum length of an allowed URL8192
    web-app-defaultConfigures 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="">
        <cluster id="web-tier">
                <http port="8080"/>
            <server id="a" address=""/>
            <server id="b" address=""/>
            <host host-name="">


    child of resin

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

    Example: cluster-default
    <resin xmlns="">
            <cache entries="16384" memory-size="64M"/>
        <cluster id="web-tier">
        <cluster id="app-tier">


    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 {


    <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?
      & resin-data-directory?
      & root-directory?
      & security-manager?
      & security-provider?
      & watchdog-manager?
    Example: minimal resin.xml
    <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

    <resin-data-directory> specifies the location of Resin's administration and data files, including persistent caching, sessions, and administration logs.

    <resin-data-directory> schema
    element resin-data-directory {


    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 {


    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.

    userSpecifies 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
    pathSpecifies the path to an XML file containing users and passwords.None
    logout-on-session-timeoutIf true, the user will be logged out when the session times out.true


    <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 {
    Example: cluster root-directory
    <resin xmlns="">
        <cluster id="app-tier">
            <server id="a" ...>
            <host host-name="">


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


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

    <stat-service> Attributes
    unix-load-avg-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?

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