<document>
<localtoc/>

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

<parents>cluster</parents>

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

Attribute Description Default
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
element cache { disk-size? & enable? & enable-range? & entries? & path? & max-entry-size? & memory-size? & rewrite-vary-as-private? } <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> <parents>resin</parents>

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

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
machine Configuration for grouping <server> onto physical machines
persistent-store Configures the distributed/persistent store
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
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* } <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>

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.

<parents>resin</parents>

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

<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> <parents>cluster</parents>

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

element connection-error-page { string } <parents>cluster</parents>

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

<parents>cluster</parents>

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

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

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

- See host tags for configuration details.

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 and Redeploy Mode automatic
<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> <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.

<parents>cluster</parents>

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.

<parents>cluster</parents>

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.

Attribute Description Default
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}
<parents>cluster</parents> <default>true</default>

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

element ignore-client-disconnect { r_boolean-Type } <parents>cluster</parents> <default>8192</default>

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.

element invocation-cache-size { r_int-Type } <parents>cluster</parents> <default>256</default>

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

element invocation-cache-max-url-length { r_int-Type } <parents>cluster</parents>

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.

Attribute Description Default
init initialization parameters for the persistent-store
type cluster, jdbc, or file required
element persistent-store { type & init? }

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

Attribute Description Default
always-load Always load the value false
always-save Always save the value false
max-idle-time How long idle objects are stored (session-timeout will invalidate items earlier) 24h
path Directory to store the objects required
triplicate Saves three copies of all distributed objects. false
wait-for-acknowledge Requires the sending server to wait for all acks. false
element persistent-store { type { "cluster "} element init { always-load? & always-save? & max-idle-time? & triplicate? & wait-for-acknowledge? } } <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>

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

Attribute Description Default
always-load Always load the value false
always-save Always save the value false
blob-type Schema type to store values from JDBC meta info
data-source The JDBC data source required
table-name Database table persistent_session
max-idle-time How long idle objects are stored 24h
<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>

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.

Attribute Description Default
always-load Always load the value false
always-save Always save the value false
max-idle-time How long idle objects are stored 24h
path Directory to store the sessions required
<parents>cluster</parents>

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.

Attribute Description Default
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
<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 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.

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

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

<system-property mail.smtp.host="127.0.0.1"/> <system-property mail.smtp.port="25"/> <parents>cluster</parents>

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

<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> <parents>cluster</parents>

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

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

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

element root-directory { r_path-Type } <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> <parents>cluster</parents>

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 <g>ObjectName</g> is resin:type=Server.

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

Attribute Description Default
address IP address of the cluster port 127.0.0.1
bind-ports-after-start If true, listen to the ports only after all initialization has completed, allowing load-balance failover. true
cluster-port Configures the cluster port in detail, allowing for customization of timeouts, etc.
group-name Used by the watchdog to switch setgid before starting the Resin JVM instance for security.
http Adds a HTTP port (see port tags)
id Unique server identifier required
java-exe The specific Java executable for the watchdog to launch the JVM java
jvm-arg Adds a JVM argument when the watchdog launches Resin.
jvm-classpath Adds a JVM classpath when the watchdog launches Resin.
keepalive-connection-time-max The total time a connection can be used for requests and keepalives 10min
keepalive-max The maximum keepalives enabled at one time. 128
keepalive-select-enable Enables epoll/select for keepalive requests to reduce threads (unix only) true
keepalive-timeout Timeout for a keepalive to wait for a new request 15s
load-balance-connect-timeout How long the load-balancer should wait for a connection to this server 5s
load-balance-idle-time How long the load balancer can keep an idle socket open to this server (see keepalive-timeout) keepalive-time - 2s
load-balance-recover-time How long the load balancer should treat this server as dead after a failure before retrying 15s
load-balance-socket-timeout timeout for the load balancer reading/writing to this server 65s
load-balance-warmup-time Warmup time for the load-balancer to throttle requests before sending the full load 60s
load-balance-weight relative weight used by the load balancer to send traffic to this server 100
memory-free-min minimum memory allowed for the JVM before Resin forces a restart 1M
ping Configures a periodic ping of the server to force restarts when non-responsive
port Configures the cluster port (shortcut for <cluster-port>) 6800
protocol Adds a custom socket protocol, e.g. for IIOP or SNMP.
shutdown-wait-max The maximum of time to wait for a graceful Resin shutdown before forcing a close 60s
socket-timeout The read/write timeout for the socket 65s
thread-max The maximum number of threads managed by Resin (JVM threads will be larger because of non-Resin threads) 4096
thread-executor-thread-max Limits the threads allocated to application ScheduledExecutors from Resin
thread-idle-max Maximum number of idle threads in the thread pool 10
thread-idle-min Minimum number of idle threads in the thread pool 5
user-name The setuid user-name for the watchdog when launching Resin for Unix security.
watchdog-jvm-arg Additional JVM arguments when launching the watchdog manager
watchdog-port The port for the watchdog-manager to listen for start/stop/status requests 6700
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? } <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> <parents>cluster</parents>

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

<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> <parents>cluster</parents> <default>Resin/3.1.x</default>

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

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

Configures the cookie used for servlet sessions.

element session-cookie { string } <parents>cluster</parents> <default>false</default>

Disables sticky sessions from the load balancer.

element session-sticky-disable { r_boolean-Type } <parents>cluster</parents> <default>;jsessionid=</default>

Configures the URL prefix used for session rewriting.

<note>Session rewriting is discouraged as a potential security issue.</note> element session-cookie { string } <parents>cluster</parents> <default>value of session-cookie</default>

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

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

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.

element url-character-encoding { string } <parents>cluster</parents>

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

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