Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


home
 

Resin Documentation

home company docs 
app server 		 Resin Server | Application Server (Java EE Certified) and Web Server
 

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.

  1. <access-log>
  2. <cluster>
  3. <cluster-default>
  4. <connection-error-page>
  5. <error-page>
  6. <host>
  7. <host-default>
  8. <host-deploy>
  9. <ignore-client-disconnect>
  10. <invocation-cache-size>
  11. <invocation-cache-max-url-length>
  12. <max-uri-length>
  13. <ping>
  14. <resin:JmxService>
  15. <resin:XaLogService>
  16. <root-directory>
  17. <server>
  18. <server-default>
  19. <server-header>
  20. <session-cookie>
  21. <session-url-prefix>
  22. <ssl-session-cookie>
  23. <url-character-encoding>
  24. <web-app>
  25. <web-app-default>

<access-log>

child of <cluster>,<cluster-default>,<server>,<server-default>,<host>,<host-default>,<web-app>,<web-app-default>

<access-log> configures the access log file.

As a child of <web-app>, overrides the definition in the <host> that the web-app is deployed in. As a child of <host>, overrides the definition in the <server> that the host is in.

The default archive format is 

path + ".%Y%m%d" or
  path + ".%Y%m%d.%H" if rollover-period < 1 day.

The access log formatting variables follow the Apache variables:

format patterns
PATTERNDESCRIPTION
%bresult content length
%Dtime taken to complete the request in microseconds (since 3.0.16)
%hremote IP addr
%{xxx}irequest header xxx
%{xxx}oresponse header xxx
%{xxx}ccookie value xxx
%{xxx}nrequest attribute
%{xxx}prequest parameter
%rrequest URL
%sstatus code
%Srequested session id
%{xxx}trequest date with optional time format string.
%Ttime taken to complete the request in seconds
%uremote user
%Urequest URI
%vname of the virtual host serving the request

The default format is:

default access log format
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

resin:type allows for custom logging. Applications can extend a custom class from com.caucho.http.log.AccessLog. Resin-IoC initialization can be used to set bean parameters in the custom class.

<access-log> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
pathOutput path for the log entries, see "Log Paths".required
path-formatSelects a format for generating path names. The syntax is the same as for archive-format.optional
archive-formatthe format for the archive filename when a rollover occurs, see Rollovers. see below
auto-flushtrue to flush the memory buffer with each request. false
auto-flush-timesets time interval for flushing the memory buffers 60s
excludeaccess logging exclude patterns for request URIs. Access to matching URIs does not get logged.none
formatAccess log format.see above
hostname-dns-lookuplog the dns name instead of the IP address (has a performance hit).false
rollover-periodhow often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See "Rollovers". none
rollover-sizemaximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See "Rollovers". 1gb
rollover-countmaximum number of rollover files before the oldest ones get overwritten. See "Rollovers". none
resin:typea class extending com.caucho.server.log.AccessLog for custom logging com.caucho.server.log.AccessLog
initResin-IoC initialization for the custom classn/a
<access-log> schema
element access-log {
  path?
  & path-format?
  & archive-format?
  $amp;auto-flush?
  & auto-flush-time?
  & exclude*
  & format?
  & hostname-dns-lookup?
  & rollover-period?
  & rollover-size?
  & rollover-count?
  & resin:type?
  & init?
}
Example: <access-log> in host configuration
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">

  <host id="">
    <access-log path='log/access.log'>
      <rollover-period>2W</rollover-period>
    </access-log>
  </host>
</cluster>
</resin>
Example: custom access log
<resin xmlns="http://caucho.com/ns/resin">

<cluster id="app-tier">

  <host id='foo.com'>

    <access-log>
      <test:MyLog xmlns:test="urn:java:test">
                 path='${resin.root}/foo/error.log'
                 rollover-period='1W'>
          <test:foo>bar</test:foo>
      </test:MyLog>
    </access-log>
    ...
  </host>

</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
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
max-uri-lengthMaximum URI length allowed in request1024
machineConfiguration for grouping <server> onto physical machines
pingPeriodic checking of server URLs to verify server activity
redeploy-mode"automatic" or "manual"automatic
resin:chooseConditional configuration based on EL expressions
resin:importImports a custom cluster.xml files for a configuration management
resin:ifConditional configuration based on EL expressions
rewrite-dispatchrewrites and dispatches URLs using regular expressions, similar to mod_rewrite
root-directoryThe root filesystem directory for the cluster${resin.root}
serverConfigures JVM instances (servers). Each cluster needs at least one server
server-defaultConfigures defaults for all server instances
server-headerConfigures the HTTP "Server: Resin/xxx" headerResin/Version
session-cookieConfigures the servlet cookie nameJSESSIONID
url-character-encodingConfigures the character encoding for URLsutf-8
url-length-maxConfigures the maximum length of an allowed URL8192
web-app-defaultConfigures defaults to apply to all web-apps in the cluster
<cluster> schema
element cluster {
  attribute id { string }
  & environment resources
  & access-log?
  & cache?
  & connection-error-page?
  & ear-default*
  & error-page*
  & host*
  & host-default*
  & host-deploy*
  & ignore-client-disconnect?
  & invocation-cache-size?
  & invocation-cache-max-url-length?
  & machine*
  & ping*
  & redeploy-mode?
  & resin:choose*
  & resin:import*
  & resin:if*
  & rewrite-dispatch?
  & root-directory?
  & server*
  & server-default*
  & server-header?
  & session-cookie?
  & 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>

<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> schema
element connection-error-page {
  string
}

<error-page>

child of <web-app>

Allows applications to customize the response generated for errors. By default, Resin returns a 500 Servlet Error and a stack trace for exceptions and a simple 404 File Not Found for error pages. With <error-page>, you may specify a handler page for these errors.

The handler page has several request attributes set so that it may log, display, or otherwise use information about the error that occured. The following table describes the available attributes.

Request attributes for error handling
ATTRIBUTETYPE
javax.servlet.error.status_codejava.lang.Integer
javax.servlet.error.messagejava.lang.String
javax.servlet.error.request_urijava.lang.String
javax.servlet.error.servlet_namejava.lang.String
javax.servlet.error.exceptionjava.lang.Throwable
javax.servlet.error.exception_typejava.lang.Class
<error-page> Attributes
ATTRIBUTEDESCRIPTION
error-codeSelect the error page based on an HTTP status code
exception-typeSelect the error page based on a Java exception
locationThe error page to display
<error-page> schema
element error-page {
  (error-code | exception-type)?
  & location
}
Catching File Not Found
<web-app xmlns="http://caucho.com/ns/resin">
  <error-page>
    <error-code>404</error-code>
    <location>/file_not_found.jsp</location>
  </error-page>
</web-app>
Catching Exceptions
<web-app xmlns="http://caucho.com/ns/resin">
   <error-page exception-type="java.lang.NullPointerException"
               location="/nullpointer.jsp"/>
</web-app>
Using request attributes to obtain information about the request that caused the error
<%@ page session="false" isErrorPage="true" %>

<html>
<head><title>404 Not Found</title></head>
<body>
<h1>404 Not Found</h1>

The url <code>${requestScope["javax.servlet.error.request_uri"]}</code> 
was not found.
</body>
</html>

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

<host-deploy>

child of <cluster>

<host-deploy> configures an automatic deployment directory for virtual hosts.

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

<host-deploy> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
archive-directorypath to the archive directorypath
pathpath to the deploy directoryrequired
expand-cleanup-filesetan ant-style fileset defining which directories to cleanup when an archive is redeployed
expand-directorypath to the expansion directorypath
host-defaultdefaults for the expanded host
host-namethe default hostname, based on the directory${name}
<host-deploy> schema
element host-deploy {
  archive-directory?
  & expand-cleanup-fileset?
  & expand-directory?
  & host-default?
  & host-name?
  & path?
}

The following example configures /var/resin/hosts as a host deployment directory. Each virtual host will have a webapps directory for .war deployment. So the directory /var/resin/hosts/www.foo.com/webapps/bar/test.jsp would serve the URL http://www.foo.com/bar/test.jsp.

<host-deploy>
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">
    <root-directory>/var/resin</root-directory>

    <host-deploy path="hosts">
      <host-default>
        <resin:import path="host.xml" optional="true"/>

        <web-app-deploy path="webapps"/>
      </host-default>
    </host-deploy>
  </cluster>
</resin>

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

<max-uri-length>

child of <cluster>
default 1024

Sets limit on longest URIs that can be served by Resin.

<max-uri-length> schema
element max-uri-length {
  r_int-Type
}

<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
freeze-timeoutTime with no response to detect a frozen jvm.15m
retry-timetime between retries1s
socket-timeouttime to wait for server to start responding to the tcp connection before giving up10s
Example: resin.xml - 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.xml - 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.xml - mail notification when ping fails
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin">
  ...
  <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.xml - smtp server configuration
  <system-property mail.smtp.host="127.0.0.1"/>
  <system-property mail.smtp.port="25"/>

<resin:JmxService>

javadoc <resin:JmxService>

Enables cluster-wide JMX administration.

<resin:XaLogService>

javadoc <resin:XaLogService>
<resin:XaLogService> requires Resin Professional

Transaction log service.

<root-directory>

child of <resin>,<cluster>,<host>,<web-app>

<root-directory> specifies the base directory for the contexts. All EL-style directory paths are relative to the root-directory.

<root-directory> schema
element root-directory {
  r_path-Type
}
Example: cluster root-directory
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <root-directory>/var/resin/app-tier</root-directory>

        <server id="a" ...>

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

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

<server> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
idunique server identifierrequired
addressIP address of the cluster port127.0.0.1
portThe cluster port6800
allow-non-reserved-ipallows non-private IP address be used for cluster portfalse
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.

<server> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
alternate-session-url-prefixa 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-maxthe maximum number of keepalive connections512
keepalive-timeoutthe maximum time a connection is maintained in the keepalive state15s
alternate-session-url-prefix
<server>
  ...
  <alternate-session-url-prefix>/~J=</alternate-session-url-prefix>
  ...

EL variables and functions

EL variables defined by <server>
VARIABLECORRESPONDING API
serverIdserver.getServerId()
root-dirserver.getRootDirectory()
server-rootserver.getRootDirectory()
EL functions defined by <server>
FUNCTIONCORRESPONDING API
jndiJndi.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>

<server-header>

child of <cluster>
default Resin/4.0.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-url-prefix>

child of <cluster>
default ;jsessionid=

Configures the URL prefix used for session rewriting.

note
Note
Session rewriting is discouraged as a potential security issue.
<session-url-prefix> 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.

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

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
ATTRIBUTEDESCRIPTIONDEFAULT
active-wait-timehow long a thread should wait for the web-app to initialize before returning a 503-busy.15s
archive-pathSpecifies the location of the web-app's .war file.n/a
context-pathSpecifies the URL prefix for the web-app.the id value
idThe url prefix selecting this application.n/a
redeploy-mode'automatic' or 'manual', see <redeploy-mode>automatic
redeploy-check-intervalhow often to check the .war archive for redeployment60s
root-directoryThe 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-priorityspecifies a priority for web-app startup to force an ordering between webapps -1
url-regexpA 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>
Copyright © 1998-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).
Leading companies worldwide with demand for reliability and high performance web applications including SalesForce.com, CNET, DZone and many more are powered by Resin.

home company docs 
app server