cluster and network tags reference

This page is a quick reference to all the tags used for Resin clustering and load-balancing including <cluster>, <server>, <host>, <resin:LoadBalance>, <persistence-store> and <use-persistence-store>.

<address>

child of server

default 127.0.0.1

The server <address> defines the IP interface for Resin cluster communication and load balancing. It will be an internal IP address like 192.168.* for a clustered configuration or 127.* for a single-server configuration. No wild cards are allowed because the other cluster servers and load balancer use the address to connect to the server.

server address

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

    <server id="web-a" address="192.168.1.1" port="6800"/>
    <server id="web-b" address="192.168.1.2" port="6800"/>

    ...
  </cluster>

  <cluster id="app-tier">
    <server id="app-a" address="192.168.2.11" port="6800"/>
    <server id="app-b" address="192.168.2.12" port="6800"/>

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

<host>

child of cluster

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

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

<host> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
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-mode	automatic

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

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

<http>

child of server

<http> configures a HTTP or HTTPS port listening for HTTP requests.

When configuring multiple JVMs, each <http> will have a unique <server-id> which allows the -server command-line to select which ports the server should listen to.

Note

The virtual-host attribute overrides the browser's Host directive, specifying the explicit host and port for request.getServerName() and getServerPort(). It is not used in most virtual host configurations. Only IP-based virtual hosts which wish to ignore the browser's Host will use @virtual-host.

<http> Attributes
address/host	IP address of the interface to listen to	*
port	port to listen to	required
tcp-no-delay	sets the NO_DELAY socket parameter	true
read-timeout	timeout waiting to read from idle client	65s
write-timeout	timeout waiting to write to idle client	65s
socket-listen-backlog	The socket factory's listen backlog for receiving sockets	100
virtual-host	forces all requests to this <http> to use the named virtual host	none
openssl	configures the port to use OpenSSL	none
jsse-ssl	configures the port to use JSSE for SSL	none

<http> schema

element http {
  (id | server-id)
  & (address | host )?
  & port?
  & accept-listen-backlog?
  & accept-thread-min?
  & accept-thread-max?
  & connection-max?
  & keepalive-connection-time-max?
  & keepalive-max?
  & keepalive-timeout?
  & secure?
  & socket-timeout?
  & suspend-time-max?
  & tcp-no-delay?
  & throttle-concurrent-max?
  & virtual-host?
  & (openssl | jsse-ssl)?
}

<keepalive-max>

child of server

default 100

<keepalive-max> configures the maximum number of sockets which can be used directly for keepalive connections. In Resin Professional, the select manager allows for a much larger number of keepalive sockets, since it can detach threads from connections. Without the select manager, each connection is associated with a thread.

A value of -1 disables keepalives.

Keepalives are an important TCP technique used with HTTP and Resin's load-balancing to avoid the heavy network cost of creating a new socket. Since an initial HTTP request is usually immediately followed by extra requests to load files like images and stylesheets, it's generally more efficient to keep the socket open for a short time instead of creating a new one. The socket keepalive is even more important for Resin's load balancing, to avoid creating extra sockets between the web-tier and the app-tier and to make distributed sessions more efficient.

Higher values of <keepalive-max> improve network efficiency but increase the number of threads waiting for new client data.

keepalive-thread-max in resin.xml

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

      <thread-max>512</thread-max>

      <keepalive-max>100</keepalive-max>
    </server-default>

    <server id="web-a" address="192.168.0.10"/>
        ...
  </cluster>
</resin>

<keepalive-select-enable>

child of server

default true

<keepalive-select-enable> enables the select manager for keepalives. The select manager is a Resin Professional feature allowing more keepalives by detaching threads from sockets.

Normally, this should be left enabled.

<keepalive-timeout>

child of server

default 10s

<keepalive-timeout> configures how long a keepalive connection should wait for a new request before closing.

Keepalives are used both for HTTP connections and for load-balancing and clustering connections. HTTP connections generally have a single HTML page, followed by a number of image requests. By using keepalives, all the requests can use a single socket. The <keepalive-timeout> should be long enough to catch all the HTTP burst requests, but can close after the burst is complete. A value of 5s or 10s is generally sufficient.

The load-balancing and clustering keepalives have a different timeout behavior. Since load-balancing sockets are reused for multiple clients, they can have longer timeouts.

keepalive-thread-max in resin.xml

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

      <thread-max>512</thread-max>

      <keepalive-max>100</keepalive-max>
      <keepalive-timeout>10s</keepalive-timeout>
    </server-default>

    <server id="web-a" address="192.168.0.10"/>
        ...
  </cluster>
</resin>

<resin:LoadBalance>

javadoc <resin:LoadBalance>

<resin:LoadBalance> requires Resin Professional

Load balance to a cluster of backend Resin servers.

<resin:LoadBalance> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
regexp	The regular expression of the URL to match.	None (match all)
cluster	The id of the cluster to which to load balance.	required
strategy	round-robin or adaptive	adaptive

Load Balancing to a backend cluster

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin">
   
  <cluster id='app-tier'>
    <server id='a' port='6810'/>
    <server id='b' port='6820'/>

    ...
  </cluster>

  <cluster id='web-tier'>
    <server id='http' port='80'/>

    <host id=''>
    
      <resin:LoadBalance cluster="app-tier"/>
      
    </host>
  </cluster>
</resin>

<load-balance-weight>

child of server

default 100

load-balance-weight assigns a load-balance weight to a backend server. Servers with higher values get more requests. Servers with lower values get fewer requests.

In some cases, some app-tier servers may be more powerful than others. load-balance-weight lets the load-balancer assign more connections to the more powerful machines.

Test and profiling servers can also use load-balance-weight to receive a small number of connections for profiling purposes.

Larger values tell the load-balancer to assign more requests to the app-tier server.

load-balance-weight

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

        <server id="test" address="192.168.0.100" port="6800">
            <load-balance-weight>1</load-balance-weight>
        </server>

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

<load-balance-connect-timeout>

child of server

default 5s

<load-balance-connect-timeout> configures the maximum time a client connection to a cluster-port should take. The load balance and persistent sessions use load-balance-connect-timeout to connect to backend or peer servers in the cluster.

Lower values detect failed servers more quickly, but a too-low value can timeout too quickly for a live server with some network congestion.

load-balance-connect-timeout

<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <server-default>
          <load-balance-connect-timeout>2s</load-balance-connect-timeout>
        </server-default>

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

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

<load-balance-idle-time>

child of server

default keepalive-timeout - 1s

<load-balance-idle-time> is the maximum time the load balancer and distributed sessions will leave an idle socket before closing it.

The default value is normally sufficient, since it tracks the keepalive of the cluster port.

load-balance-idle-time must be less than the keepalive value of the target cluster-port.

The load balancer and distributed sessions reuse sockets to the cluster peer and app-tier servers to improve TCP performance. The load-balance-idle-time limits the amount of time those sockets can remain idle.

Higher values may improve the socket pooling, but may also increase the chance of connecting to a closed server.

<load-balance-idle-time>

child of server

default keepalive-timeout - 1s

<load-balance-idle-time> is the maximum time the load balancer and distributed sessions will leave an idle socket before closing it.

The default value is normally sufficient, since it tracks the keepalive of the cluster port.

load-balance-idle-time must be less than the keepalive value of the target cluster-port.

Higher values may improve the socket pooling, but may also increase the chance of connecting to a closed server.

<load-balance-warmup-time>

child of server

default 60s

The time the load balancer uses to throttle connections to an app-tier server that's just starting up.

Java web-applications often start slowly while they initialize caches. So a newly-started application will often be slower and consume more resources than a long-running application. The warmup-time increases Resin's reliability by limiting the number of requests to a new app-tier server until the server has warmed up.

Larger values give the application a longer time to warm up.

load-balance-warmup-time

<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <server-default>
          <load-balance-warmup-time>60s</load-balance-warmup-time>
        </server-default>

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

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

<load-balance-recover-time>

child of server

default 15s

<load-balance-recover-time> is the maximum time the load balancer will consider the server dead after a failure before retrying the connection.

Resin uses the load-balance-recover-time to avoid wasting time trying to connect to an unavailable app-tier server.

Lower values let the load balancer use a restarted app-tier server faster, but lower values also increase the overhead of trying to contact unavailable servers.

load-balance-recover-time

<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <server-default>
          <load-balance-recover-time>10s</load-balance-recover-time>
        </server-default>

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

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

<port>

child of server

default 6800

The server <port> defines the TCP port for Resin cluster communication and load balancing. Most server instances will use a common port like 6800, while machines with multiple servers may use multiple ports like 6800 and 6801.

multiple servers on a machine

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">
    <server id="app-a" address="192.168.1.11" port="6800"/>
    <server id="app-b" address="192.168.1.11" port="6801"/>

    <server id="app-b" address="192.168.2.12" port="6800"/>
    <server id="app-c" address="192.168.2.12" port="6801"/>

    ...
  </cluster>
</resin>

<port-default>

child of server

Defines default port parameters for all <http>, <protocol>, and <cluster-port>.

<server>

child of cluster

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

The server listens to an internal network address, e.g. 192.168.0.10:6800 for clustering, load balancing, and administration.

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

Main configuration for the server, configuring ports, threads and virtual hosts.

Common resources for all virtual hosts and web-apps.
Thread pooling
HTTP and Server/Cluster ports
Caching
virtual host configuration and common web-app-default

The <server> will generally contain a <class-loader> configuration which loads the resin/lib jars dynamically, allowing for system-wide jars to be dropped into resin/lib. <server> configures the main dynamic environment. Database pools common to all virtual hosts, for example, should be configured in the <server> block.

The <server> configures the <thread-pool> and a set of <http> and <server> ports which share the thread pool. Requests received on those ports will use worker threads from the thread pool.

alternate-session-url-prefix	a prefix to add the session to the beginning of the URL as a path prefix instead of the standard ;jsessionid= suffix. For clients like mobile devices with limited memory, this will allow careful web designers to minimize the page size.	null
keepalive-max	the maximum number of keepalive connections	512
keepalive-thread-timeout	the maximum time a connection is maintained in the keepalive state	120s

alternate-session-url-prefix

<server>
  ...
  <alternate-session-url-prefix>/~J=</alternate-session-url-prefix>
  ...

EL variables and functions

EL variables defined by <server>
VARIABLE	CORRESPONDING API
serverId	server.getServerId()
root-dir	server.getRootDirectory()
server-root	server.getRootDirectory()

EL functions defined by <server>
FUNCTION	CORRESPONDING API
jndi	Jndi.lookup(String)

<server-default>

child of cluster

<server-default> defines default values for all <server> instances. Since most <server> configuration is identical for all server instances, the shared configuration belongs in a <server-default>. For example, <http> ports, timeouts, JVM arguments, and keepalives are typically identical for all server instances and therefore belong in a server-default.

server

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

           <jvm-arg>-Xmx512m -Xss1m</jvm-arg>

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

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

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

<session-config>

<session-config> configures Resin's session handling, including the cookies Resin sends, the maximum sessions, and session persistence and clustering.

See also: Resin clustering for more information about distributed sessions and persistence.

<session-config> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
always-load-session	Reload data from the store on every request	false
always-save-session	Save session data to the store on every request	false
enable-cookies	Enable cookies for sessions	true
enable-url-rewriting	Enable URL rewriting for sessions	true
cookie-version	Version of the cookie spec for sessions	1.0
cookie-domain	Domain for session cookies	none
cookie-max-age	Max age for persistent session cookies	none
cookie-length	Maximum length of the cookie
ignore-serialization-errors	When persisting a session, ignore any values which don't implement java.io.Serializable	false
invalidate-after-listener	If true, invalidate the sessions after the session listeners have been called
reuse-session-id	Reuse the session id even if the session has timed out. A value of false defeats single signon capabilities. (resin 2.0.4)	true
session-max	Maximum active sessions	4096
session-timeout	The session timeout in minutes, 0 means never timeout.	30 minutes
serialization-type	Use one of "java" or "hessian" for serialization, hessian is significantly faster and smaller (resin 3.1.2)	java
serialize-collection-type	For hessian serialization, ignore the collection type when serializing lists (disable for some Hibernate lists)	true
save-mode	When to save sessions, one of "before-headers", "after-request", or "on-shutdown"	after-request
use-persistent-store	Uses the current persistent-store to save sessions. (resin 3.0.8)	none

<session-config> schema

element session-config {
  always-load-session?
  & always-save-session?
  & cookie-append-server-index?
  & cookie-domain?
  & cookie-length?
  & cookie-max-age?
  & cookie-port?
  & cookie-secure?
  & cookie-version?
  & enable-cookies?
  & enable-url-rewriting?
  & ignore-serialization-errors?
  & invalidate-after-listener?
  & reuse-session-id?
  & save-mode?
  & save-on-shutdown?
  & serialization-type?
  & session-max?
  & session-timeout?
  & use-persistent-store?
}

The session-timeout and session-max are usually used together to control the number of sessions. Sessions are stored in an LRU cache. When the number of sessions in the cache fills up past session-max, the oldest sessions are recovered. In addition, sessions idle for longer than session-timeout are purged.

using session-config and session-timeout to control the number of sessions

<web-app id='/dir'>

  <session-config>
     <!-- 2 hour timeout -->
     <session-timeout>120</session-timeout>
     <session-max>4096</session-max>
  </session-config>

</web-app>

cookie-length is used to limit the maximum length for the session's generated cookie for special situations like WAP devices. Reducing this value reduces the randomness in the cookie and increases the chance of session collisions.

reuse-session-id defaults to true so that Resin can share the session id amongst different web-apps.

The class that corresponds to <session-config> is com.caucho.server.session.SessionManager

<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-url-prefix> schema

element session-cookie {
  string
}

<socket-timeout>

child of http,cluster-port,protocol,server

default 60s

<socket-timeout> is the maximum time a socket load balancer and distributed sessions will wait for a read or write to a cluster socket.

Crashed servers may never respond to a read request or accept a write. The socket-timeout lets Resin recover from these kinds of crashes.

Lower values can detect crashes more quickly, but too-low values may report bogus failures when the server machine is just a little slow.

socket-timeout

<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <server-default>
          <socket-timeout>60s</socket-timeout>
        </server-default>

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

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

<web-app>

child of host,web-app

web-app configures a web application.

When specified by id, the application will be initialized on server start. When specified by url-regexp, the application will be initialized at the first request. This means that load-on-startup servlets may start later than expected for url-regexp applications.

<web-app> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
active-wait-time	how long a thread should wait for the web-app to initialize before returning a 503-busy.	15s
archive-path	Specifies the location of the web-app's .war file.	n/a
context-path	Specifies the URL prefix for the web-app.	the id value
id	The url prefix selecting this application.	n/a
redeploy-mode	'automatic' or 'manual', see redeploy-mode	automatic
redeploy-check-interval	how often to check the .war archive for redeployment	60s
root-directory	The root directory for the application, corresponding to a url of /id/. A relative path is relative to the root-directory of the containing host. Can use regexp replacement variables.	A relative path constricted with the id or the regexp match
startup-mode	'automatic', 'lazy', or 'manual', see startup-mode	automatic
startup-priority	specifies a priority for web-app startup to force an ordering between webapps	-1
url-regexp	A regexp to select this application.	n/a

The following example creates a web-app for /apache using the Apache htdocs directory to serve pages.

<host id=''>
  <web-app id='/apache' root-directory='/usr/local/apache/htdocs'>

  ...

</host>

The following example sets the root web-app to the IIS root directory.

  <web-app id='/' root-directory='C:/inetpub/wwwroot'>

When the web-app is specified with a url-regexp, root-directory can use replacement variables ($2).

In the following, each user gets his or her own independent application using ~user.

<host id=''>

  <web-app url-regexp='/~([^/]*)'
           root-directory='/home/$1/public_html'>

    ...

  </web-app>

</host>

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