Caucho Technology
documentation
examples
changes

overview
quick start
installation
command-line
configuration
admin
amber
clustering
caching
database
deployment
ejb 3.0
embedding
filters
hessian
hmtp
ioc
jsp
logging
messaging
performance
quercus/php
remoting
scheduled tasks
security
server push
servlets
third-party
troubleshooting
virtual hosting
watchdog
webapp
xml and xslt

<cluster>
<database>
<host>
ports
<resin>
resource tags
rewrite
<server>
session
variables
<web-app>
index
relax schema

cluster: cluster tag configuration


Each <cluster> contains a set of virtual hosts served by a collection of <server>s. The cluster provides load-balancing and distributed sessions for scalability and reliability.

See Also

  • See the index for a list of all the tags.
  • See Web Application configuration for web.xml (Servlet) configuration.
  • See Server tags for ports, threads, and JVM configuration.
  • See Resource configuration for resources: classloader, databases, connectors, and resources.
  • See Log configuration for access log configuration, java.util.logging, and stdout/stderr logging.

<access-log>

<access-log> configures a HTTP access log for all virtual hosts in the cluster. See access-log in the <host> tag for more information.

<cache>

child of cluster

<cache> configures the proxy cache (requires Resin Professional). The proxy cache improves performance by caching the output of servlets, jsp and php pages. For database-heavy pages, this caching can improve performance and reduce database load by several orders of magnitude.

The proxy cache uses a combination of a memory cache and a disk-based cache to save large amounts of data with little overhead.

Management of the proxy cache uses the ProxyCacheMXBean.

<cache> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
pathPath to the persistent cache files.cache/
disk-sizeMaximum size of the cache saved on disk.1024M
enableEnables the proxy cache.true
enable-rangeEnables support for the HTTP Range header.true
entriesMaximum number of pages stored in the cache.8192
max-entry-sizeLargest page size allowed in the cache.1M
memory-sizeMaximum heap memory used to cache blocks.8M
rewrite-vary-as-privateRewrite Vary headers as Cache-Control: private to avoid browser and proxy-cache bugs (particularly IE).false
<cache> schema
element cache {
  disk-size?
  & enable?
  & enable-range?
  & entries?
  & path?
  & max-entry-size?
  & memory-size?
  & rewrite-vary-as-private?
}
Example: enabling proxy cache
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <cache entries="16384" disk-size="2G" memory-size="256M"/>

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

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

<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-id on the command line.

<cluster> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
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
machineConfiguration for grouping <server> onto physical machines
persistent-storeConfigures the distributed/persistent store
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*
  & persistent-store?
  & 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>

rewrite-vary-as-private

Because not all browsers understand the Vary header, Resin can rewrite Vary to a Cache-Control: private. This rewriting will cache the page with the Vary in Resin's proxy cache, and also cache the page in the browser. Any other proxy caches, however, will not be able to cache the page.

The underlying issue is a limitation of browsers such as IE. When IE sees a Vary header it doesn't understand, it marks the page as uncacheable. Since IE only understands "Vary: User-Agent", this would mean IE would refuse to cache gzipped pages or "Vary: Cookie" pages.

With the <rewrite-vary-as-private> tag, IE will cache the page since it's rewritten as "Cache-Control: private" with no Vary at all. Resin will continue to cache the page as normal.

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

<connection-error-page>

child of cluster

<connection-error-page> specifies an error page to be used by IIS when it can't contact an app-tier Resin. This directive only applies to IIS.

connection-error-page
element connection-error-page {
  string
}

<ear-default>

child of cluster

<ear-default> configures defaults for .ear resource, i.e. enterprise applications.

<error-page>

child of cluster

<error-page> defines a web page to be displayed when an error occurs outside of a virtual host or web-app. Note, this is not a default error-page, i.e. if an error occurs inside a <host> or <web-app>, the error-page for that host or web-app will be used instead.

See webapp: error-page.

<error-page> schema
element error-page {
  (error-code | exception-type)?
  & location?
}

<host>

child of cluster

<host> configures a virtual host. Virtual hosts must be configured explicitly.

<host> attributes
ATTRIBUTEDESCRIPTIONDEFAULT
idprimary host namenone
regexpRegular expression based host matchingnone
host-nameCanonical host namenone
host-aliasAliases matching the same hostnone
secure-host-nameHost to use for a redirect to SSLnone
root-directoryRoot directory for host filesparent directory
startup-mode'automatic', 'lazy', or 'manual', see Startup and Redeploy Modeautomatic
Example: explicit host
<host host-name="www.foo.com">
  <host-alias>foo.com</host-alias>
  <host-alias>web.foo.com</host-alias>

  <root-directory>/opt/www/www.foo.com</root-directory>

  <web-app id="/" document-directory="webapps/ROOT">
    
  </web-app>
  ...
</host>
Example: regexp host
<host regexp="([^.]+)\.foo\.com">
  <host-name>${host.regexp[1]}.foo.com</host-name>

  <root-directory>/var/www/hosts/www.${host.regexp[1]}.com</root-directory>

  ...
</host>

It is recommended that any <host> using a regexp include a <host-name> to set the canonical name for the host.

<host-default>

child of cluster

Defaults for a virtual host.

The host-default can contain any of the host configuration tags. It will be used as defaults for any virtual host.

<host-deploy>

child of cluster

Configures a deploy directory for virtual host.

The host-deploy will add an EL variable ${name}, referring to the name of the host jar file.

ATTRIBUTEDESCRIPTIONDEFAULT
pathpath to the deploy directoryrequired
expand-pathpath to the expansion directorypath
host-defaultdefaults for the expanded host
host-namethe host name to match${name}

<ignore-client-disconnect>

child of cluster
default true

ignore-client-disconnect configures whether Resin should ignore disconnection exceptions from the client, or if it should send those exceptions to the application.

<ignore-client-disconnect> schema
element ignore-client-disconnect {
  r_boolean-Type
}

<invocation-cache-size>

child of cluster
default 8192

Configures the number of entries in the invocation cache. The invocation cache is used to store pre-calculated servlet and filter chains from the URLs. It's also used as the basis for proxy caching.

<invocation-cache-size> schema
element invocation-cache-size {
  r_int-Type
}

<invocation-cache-max-url-length>

child of cluster
default 256

Configures the longest entry cacheable in the invocation cache. It is used to avoid certain types of denial-of-service attacks.

<invocation-cache-max-url-length> schema
element invocation-cache-max-url-length {
  r_int-Type
}

<persistent-store>

child of cluster

Defines the cluster-aware persistent store used for sharing distributed sessions. The allowed types are "jdbc", "cluster" and "file". The "file" type is only recommended in single-server configurations.

The <persistent-store> configuration is in the <server> level because it needs to share update information across the active cluster and the <cluster> definition is at the <server> level. Sessions activate the persistent store with the <use-persistent-store> tag of the <session-config>.

See Persistent sessions for more details.

<persistent-store> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
initinitialization parameters for the persistent-store
typecluster, jdbc, or filerequired
<persistent-store> schema
element persistent-store {
  type
  & init?
}

cluster store

The cluster store shares copies of the sessions on multiple servers. The original server is used as the primary, and is always more efficient than the backup servers. In general, the cluster store is preferred because it is more scalable, and with the "triplicate" attribute, the most reliable..

cluster tags
ATTRIBUTEDESCRIPTIONDEFAULT
always-loadAlways load the valuefalse
always-saveAlways save the valuefalse
max-idle-timeHow long idle objects are stored (session-timeout will invalidate items earlier)24h
pathDirectory to store the objectsrequired
triplicateSaves three copies of all distributed objects.false
wait-for-acknowledgeRequires the sending server to wait for all acks.false
cluster schema
element persistent-store {
  type { "cluster "}

  element init {
    always-load?
    & always-save?
    & max-idle-time?
    & triplicate?
    & wait-for-acknowledge?
  }
}
Example: cluster store
<resin xmlns="http://caucho.com/ns/resin">
<cluster>
  <server id="a" address="192.168.0.1" port="6800"/>
  <server id="b" address="192.168.0.2" port="6800"/>

  <persistent-store type="cluster">
    <init>
      <triplicate>true</triplicate>
    </init>
  </persistent-store>

  <web-app-default>
    <session-config use-persistent-store="true"/>
  </web-app-default>
</cluster>
</resin>

jdbc store

The JDBC store saves sessions in a JDBC database. Often, this will be a dedicated database to avoid overloading the main database.

jdbc store Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
always-loadAlways load the valuefalse
always-saveAlways save the valuefalse
blob-typeSchema type to store valuesfrom JDBC meta info
data-sourceThe JDBC data sourcerequired
table-nameDatabase tablepersistent_session
max-idle-timeHow long idle objects are stored24h
Example: jdbc-store
<resin xmlns="http://caucho.com/ns/resin">
<cluster>
  <server id="a" address="192.168.0.1" port="6800"/>
  <server id="b" address="192.168.0.2" port="6800"/>

  <persistent-store type="jdbc">
    <init>
      <data-source>jdbc/session</data-source>

      <max-idle-time>24h</max-idle-time>
    </init>
  </persistent-store>

  <web-app-default>
    <session-config use-persistent-store="true"/>
  </web-app-default>
</cluster>
</resin>

file store

The file store is a persistent store for development and testing or for single servers. Since it is not aware of the clusters, it cannot implement true distributed objects.

file tags
ATTRIBUTEDESCRIPTIONDEFAULT
always-loadAlways load the valuefalse
always-saveAlways save the valuefalse
max-idle-timeHow long idle objects are stored24h
pathDirectory to store the sessionsrequired

<ping>

child of cluster

Starts a thread that periodically makes a request to the server, and restarts Resin if it fails. This facility is used to increase server reliability - if there is a problem with the server (perhaps from a deadlock or an exhaustion of resources), the server is restarted.

A failure occurs if a request to the url returns an HTTP status that is not 200.

Since the local process is restarted, it does not make sense to specify a url that does not get serviced by the instance of Resin that has the ping configuration. Most configurations use url's that specify 'localhost' as the host.

This pinging only catches some problems because it's running in the same process as Resin itself. If the entire JDK freezes, this thread will freeze as well. Assuming the JDK doesn't freeze, the PingThread will catch errors like deadlocks.

<ping> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
urlA url to ping.required
sleep-timeTime to wait between pings. The first ping is always 15m after the server starts, this is for subsequent pings.15m
try-countIf a ping fails, number of times to retry before giving up and restartingrequired
retry-timetime between retries1s
socket-timeouttime to wait for server to start responding to the tcp connection before giving up10s
Example: resin.conf - simple usage of server ping
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
    <cluster id="app-tier">
        <ping url="http://localhost/"/>
        ...
    </cluster>
</resin>
Example: resin.conf - configured usage of server ping
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
    ...
    <cluster id="app-tier">
        <ping>
            <url>http://localhost:8080/index.jsp</url>
            <url>http://localhost:8080/webapp/index.jsp</url>
            <url>http://virtualhost/index.jsp</url>
            <url>http://localhost:443/index.jsp</url>

            <sleep-time>5m</sleep-time>
            <try-count>5</try-count>
    
            <!-- a very busy server -->
            <socket-timeout>30s</socket-timeout>
        </ping>
      ...
    </cluster>
</resin>

The class that corresponds to <ping> is PingThread.

Mail notification when ping fails

A refinement of the ping facility sends an email when the server is restarted.

resin.conf - mail notification when ping fails
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  ...
  <cluster id="web-tier">
    <ping resin:type="com.caucho.server.admin.PingMailer">
      <url>http://localhost:8080/index.jsp</url>
      <url>http://localhost:8080/webapp/index.jsp</url>

      <mail-to>fred@hogwarts.com</mail-to>
      <mail-from>resin@hogwarts.com</mail-from>
      <mail-subject>Resin ping has failed for server ${'${'}server.name}</mail-subject>
    </ping>
    ...
  </server>
</resin>

The default behaviour for sending mail is to contact a SMTP server at host 127.0.0.1 (the localhost) on port 25. System properties are used to configure a different SMTP server.

resin.conf - smtp server configuration
  <system-property mail.smtp.host="127.0.0.1"/>
  <system-property mail.smtp.port="25"/>

Resource Tags

child of cluster

All Environment tags are available to the <cluster>. For example, resources like <database>.

Example: cluster environment
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <database jndi-name="jdbc/test">
            <driver type="org.postgresql.Driver">
                <url>jdbc:postgresql://localhost/test</url>
                <user>caucho</user>
            </driver>
        </database>

        <server id="a" ...>
          ...

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

<rewrite-dispatch>

child of cluster

<rewrite-dispatch> defines a set of rewriting rules for dispatching and forwarding URLs. Applications can use these rules to redirect old URLs to their new replacements.

See rewrite-dispatch for more details.

rewrite-dispatch
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">

        <rewrite-dispatch>
            <redirect regexp="^http://www.foo.com"
                      target="http://bar.com/foo"/>
        </rewrite-dispatch>
  
    </cluster>
</resin>

<root-directory>

child of cluster
default The root-directory of the <resin> tag.

<root-directory> configures the root directory for files within the cluster. All paths in the <cluster> will be 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>

<server>

child of cluster

The <server> tag configures a JVM instance in the cluster. Each <server> is uniquely identified by its id attribute. The id will match the -server-id command line argument.

See the full server configuration for more details of the <server> tag and its children.

The current server is managed with a ServerMXBean. The ObjectName is resin:type=Server.

Peer servers are managed with ServerConnectorMXBean. The ObjectName is resin:type=ServerConnector,name=server-id.

<server> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
addressIP address of the cluster port127.0.0.1
bind-ports-after-startIf true, listen to the ports only after all initialization has completed, allowing load-balance failover.true
cluster-portConfigures the cluster port in detail, allowing for customization of timeouts, etc.
group-nameUsed by the watchdog to switch setgid before starting the Resin JVM instance for security.
httpAdds a HTTP port (see port tags)
idUnique server identifierrequired
java-exeThe specific Java executable for the watchdog to launch the JVMjava
jvm-argAdds a JVM argument when the watchdog launches Resin.
jvm-classpathAdds a JVM classpath when the watchdog launches Resin.
keepalive-connection-time-maxThe total time a connection can be used for requests and keepalives10min
keepalive-maxThe maximum keepalives enabled at one time.128
keepalive-select-enableEnables epoll/select for keepalive requests to reduce threads (unix only)true
keepalive-timeoutTimeout for a keepalive to wait for a new request15s
load-balance-connect-timeoutHow long the load-balancer should wait for a connection to this server5s
load-balance-idle-timeHow long the load balancer can keep an idle socket open to this server (see keepalive-timeout)keepalive-time - 2s
load-balance-recover-timeHow long the load balancer should treat this server as dead after a failure before retrying15s
load-balance-socket-timeouttimeout for the load balancer reading/writing to this server65s
load-balance-warmup-timeWarmup time for the load-balancer to throttle requests before sending the full load60s
load-balance-weightrelative weight used by the load balancer to send traffic to this server100
memory-free-minminimum memory allowed for the JVM before Resin forces a restart1M
pingConfigures a periodic ping of the server to force restarts when non-responsive
portConfigures the cluster port (shortcut for <cluster-port>)6800
protocolAdds a custom socket protocol, e.g. for IIOP or SNMP.
shutdown-wait-maxThe maximum of time to wait for a graceful Resin shutdown before forcing a close60s
socket-timeoutThe read/write timeout for the socket65s
thread-maxThe maximum number of threads managed by Resin (JVM threads will be larger because of non-Resin threads)4096
thread-executor-thread-maxLimits the threads allocated to application ScheduledExecutors from Resin
thread-idle-maxMaximum number of idle threads in the thread pool10
thread-idle-minMinimum number of idle threads in the thread pool5
user-nameThe setuid user-name for the watchdog when launching Resin for Unix security.
watchdog-jvm-argAdditional JVM arguments when launching the watchdog manager
watchdog-portThe port for the watchdog-manager to listen for start/stop/status requests6700
<server> schema
element server {
  attribute id { string }
  & address?
  & bind-ports-after-start?
  & cluster-port*
  & group-name?
  & http*
  & java-exe?
  & jvm-arg?
  & jvm-classpath?
  & keepalive-connection-time-max?
  & keepalive-max?
  & keepalive-select-enable?
  & keepalive-timeout?
  & load-balance-connect-timeout?
  & load-balance-idle-time?
  & load-balance-recover-time?
  & load-balance-socket-timeout?
  & load-balance-warmup-time?
  & load-balance-weight?
  & memory-free-min?
  & ping?
  & port?
  & protocol?
  & shutdown-wait-max?
  & socket-timeout?
  & thread-max?
  & thread-executor-task-max?
  & thread-idle-max?
  & thread-idle-min?
  & user-name?
  & watchdog-jvm-arg*
  & watchdog-port?
}
Example: server
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <server id="a" address="192.168.0.10" port="6800">
          <http port="8080"/>
        </server>

        <server id="b" address="192.168.0.11" port="6800">
          <http port="8080"/>
        </server>

        <server id="c" address="192.168.0.12" port="6800">
          <http port="8080"/>
        </server>

        <host id="">
          ...
    </cluster>
</resin>

<server-default>

child of cluster

Defines default values for all <server> instances. See <server> configuration for more details.

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

            <http port="8080"/>
        </server-default>

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

        <host id="">
          ...
    </cluster>
</resin>

<server-header>

child of cluster
default Resin/3.1.x

Configures the HTTP Server: header which Resin sends back to any HTTP client.

<server-header> schema
element server-header {
  string
}
server-header
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <server-header>MyServer/1.0</server-header>
    </cluster>
</resin>

<session-cookie>

child of cluster
default JSESSIONID

Configures the cookie used for servlet sessions.

<session-cookie> schema
element session-cookie {
  string
}

<session-sticky-disable>

child of cluster
default false

Disables sticky sessions from the load balancer.

<session-sticky-disable> schema
element session-sticky-disable {
  r_boolean-Type
}

<session-url-prefix>

child of cluster
default ;jsessionid=

Configures the URL prefix used for session rewriting.

Note Session rewriting is discouraged as a potential security issue.
<session-cookie> schema
element session-cookie {
  string
}

<ssl-session-cookie>

child of cluster
default value of session-cookie

Defines an alternative session cookie to be used for a SSL connection. Having two separate cookies increases security.

<session-cookie> schema
element ssl-session-cookie {
  string
}
Example: ssl-session-cookie
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <ssl-session-cookie>SSLJSESSIONID</ssl-session-cookie>
        ...
    </cluster>
</resin>

<url-character-encoding>

child of cluster
default UTF-8

Defines the character encoding for decoding URLs.

The HTTP specification does not define the character-encoding for URLs, so the server must make assumptions about the encoding.

<url-character-encoding> schema
element url-character-encoding {
  string
}

<web-app-default>

child of cluster

<web-app-default> defines default values for any web-app in the cluster.

Example: web-app-default
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">

        <web-app-default>
            <servlet servlet-name="resin-php"
                     servlet-class="com.caucho.quercus.servlet.QuercusServlet"/>

            <servlet-mapping url-pattern="*.php"
                             servlet-name="resin-php"/>
        </web-app-default>

        <host id="">
          ...
    </cluster>
</resin>

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