cluster: Cluster tag configuration

Overview
Installation
Configuration
Quercus
SOA/IoC
JSP
Servlets and Filters
Admin (JMX)
EJB
Amber
Security
Performance
Hessian
XML and XSLT
Third-party
Troubleshooting/FAQ

tags
Common Tasks
Relax Schema
howto
Config FAQ
Scrapbook
DB Scrapbook

env tags
<resin>
<cluster>
<server>
port tags
<host>
<web-app>
<database>
session tags
rewrite tags
service tags
log
el variables
el control

<resin>

tags

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 the index for a list of all the tags.
See Web Application configuration for web.xml (Servlet) configuration.
See Environment configuration for resources: classloader, databases, connectors, and resources.
See Log configuration for access log configuration, java.util.logging, and stdout/stderr logging.

<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 with the ObjectNameresin:type=ProxyCache.

path	Path to the persistent cache files.	cache/
disk-size	Maximum size of the cache saved on disk.	1024M
enable	Enables the proxy cache.	true
enable-range	Enables support for the HTTP Range header.	true
entries	Maximum number of pages stored in the cache.	8192
max-entry-size	Largest page size allowed in the cache.	1M
memory-size	Maximum heap memory used to cache blocks.	8M
rewrite-vary-as-private	Rewrite Vary headers as Cache-Control: private to avoid browser and proxy-cache bugs (particularly IE).	false

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>

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.

The cluster identifier.

required

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.

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.

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

Environment

child of cluster

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

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>

<host>

child of cluster

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

id	primary host name	none
regexp	Regular expression based host matching	none
host-name	Canonical host name	none
host-alias	Aliases matching the same host	none
secure-host-name	Host to use for a redirect to SSL	none
root-directory	Root directory for host files	parent directory
startup-mode	'automatic', 'lazy', or 'manual', see Startup and Redeploy Mode	automatic

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>

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.

path	path to the deploy directory	required
expand-path	path to the expansion directory	path
host-default	defaults for the expanded host
host-name	the host name to match	\${name}

<ignore-client-disconnect>

child of cluster

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

default true

<invocation-cache-size>

child of cluster

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.

default 8192

<invocation-cache-max-url-length>

child of cluster

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

default 256

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

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

common tags
max-idle-time	How long idle objects are stored	24h
always-load	Always load the value	false
always-save	Always save the value	false

jdbc tags
data-source	The JDBC data source	required
table-name	Database table	persistent_session
blob-type	Schema type to store values	from JDBC meta info

cluster tags
path	Directory to store the sessions	required

file tags
path	Directory to store the sessions	required

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

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>

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>

url	A url to ping.	required
sleep-time	Time to wait between pings. The first ping is always 15m after the server starts, this is for subsequent pings.	15m
try-count	If a ping fails, number of times to retry before giving up and restarting	required
retry-time	time between retries	1s
socket-timeout	time to wait for server to start responding to the tcp connection before giving up	10s

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>[email protected]</mail-to>
      <mail-from>[email protected]</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"/>

<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

<root-directory> configures the root directory for files within the cluster. All paths in the <cluster> will be relative to the root directory.

default The root-directory of the <resin> tag.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>

child of cluster

The <server> tag confgiures 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.

id	unique server identifier	required
address	IP address of the cluster port	127.0.0.1
port	The cluster port	6800

server

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

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

        <server id="c" address="192.168.0.12" server-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.

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

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

server-header

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

default Resin/3.1.x

<session-cookie>

child of cluster

Configures the cookie used for servlet sessions.

default JSESSIONID

<session-url-prefix>

child of cluster

Configures the URL prefix used for session rewriting.

Note Session rewriting is discouraged as a potential security issue.default ;jsessionid=

<ssl-session-cookie>

child of cluster

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

default value of 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

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.

default UTF-8

<web-app-default>

child of cluster

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

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>

<resin>

See Also

Mail notification when ping fails