![]() | Resin Documentation | home company blog wiki docs app server web server health cloud java ee pro | ![]() |
cluster: cluster tag configurationEach <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.
<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 + ".%Y%m%d" or + ".%Y%m%d.%H" if rollover-period < 1 day. The access log formatting variables follow the Apache variables:
The default format is: default access log format
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""
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> 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>
child of cluster
<cache> configures the proxy cache (requires Resin Professional). The proxy cache improves performance by caching the output of servlets, jsp and php pages. For database-heavy pages, this caching can improve performance and reduce database load by several orders of magnitude. The proxy cache uses a combination of a memory cache and a disk-based cache to save large amounts of data with little overhead. Management of the proxy cache uses the ProxyCacheMXBean.
<cache> schema
element cache {
disk-size?
& enable?
& enable-range?
& entries?
& path?
& max-entry-size?
& memory-size?
& rewrite-vary-as-private?
}
Example: enabling proxy cache
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="web-tier">
<cache entries="16384" disk-size="2G" memory-size="256M"/>
<server id="a" address="192.168.0.10"/>
<host host-name="www.foo.com">
</cluster>
</resin>
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 matching the -server on the command line.
<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>
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>
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
}
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.
<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>
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.
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>
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. 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> schema
element host-deploy {
archive-directory?
& expand-cleanup-fileset?
& expand-directory?
& host-default?
& host-name?
& path?
}
The following example configures as a host deployment directory. Each virtual host will have a directory for .war deployment. So the directory would serve the URL . <host-deploy>
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">
<root-directory>/var/www</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>
child of cluster
default trueignore-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
}
child of cluster
default 8192Configures 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
}
child of cluster
default 256Configures 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
}
child of cluster
default 1024Sets limit on longest URIs that can be served by Resin. <max-uri-length> schema
element max-uri-length {
r_int-Type
}
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.
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 failsA 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"/> javadoc <resin:JmxService>
Enables cluster-wide JMX administration. javadoc <resin:LogService>
Stores high-priority log messages in a database. javadoc <resin:XaLogService> <resin:XaLogService> requires Resin Professional
Transaction log service. <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/www/app-tier</root-directory>
<server id="a" ...>
<host host-name="www.foo.com">
</cluster>
</resin>
child of cluster
<server> configures a JVM instance in the cluster. Each <server> is uniquely identified by its attribute. The 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 . Peer servers are managed with ServerConnectorMXBean. The ObjectName is .
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.
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 <server> ... <alternate-session-url-prefix>/~J=</alternate-session-url-prefix> ... EL variables and functions
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>
child of cluster
default Resin/4.0.xConfigures 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>
child of cluster
default JSESSIONIDConfigures the cookie used for servlet sessions. <session-cookie> schema
element session-cookie {
string
}
child of cluster
default falseDisables sticky sessions from the load balancer. <session-sticky-disable> schema
element session-sticky-disable {
r_boolean-Type
}
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
}
child of cluster
default value of session-cookieDefines 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>
child of cluster
default UTF-8Defines 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 configures a web application. When specified by , 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 servlets may start later than expected for applications.
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 is specified with a , can use replacement variables (). In the following, each user gets his or her own independent application using .
<host id=''>
<web-app url-regexp='/~([^/]*)'
root-directory='/home/$1/public_html'>
...
</web-app>
</host>
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>
|