![]() | ![]() | ![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentation examples changes overview quick start installation command-line configuration admin amber clustering caching database deployment ejb 3.0 embedding filters hessian hmtp ioc jsp logging messaging performance quercus/php remoting scheduled tasks security server push servlets third-party troubleshooting virtual hosting watchdog webapp xml and xslt <cluster> <database> <host> ports <resin> resource tags rewrite <server> session variables <web-app> index relax schema | 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.
<access-log> configures a HTTP access log for all virtual hosts in the cluster. See access-log in the <host> tag for more information. 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> <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-id 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* & 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* } 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> rewrite-vary-as-privateBecause 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. <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> 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 element connection-error-page { string } <ear-default> configures defaults for .ear resource, i.e. enterprise applications. child of cluster<error-page> defines a web page to be displayed when an error occurs outside of a virtual host or web-app. Note, this is not a default error-page, i.e. if an error occurs inside a <host> or <web-app>, the error-page for that host or web-app will be used instead. See webapp: error-page. <error-page> schema element error-page { (error-code | exception-type)? & location? } <host> configures a virtual host. Virtual hosts must be configured explicitly.
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="/" document-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> It is recommended that any <host> using a regexp include a <host-name> to set the canonical name for the host. child of clusterDefaults 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 clusterConfigures a deploy directory for virtual host. The host-deploy will add an EL variable ${name}, referring to the name of the host jar file.
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 } 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 } 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 } 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.
<persistent-store> schema element persistent-store { type & init? } cluster storeThe 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..
cluster schema element persistent-store { type { "cluster "} element init { always-load? & always-save? & max-idle-time? & triplicate? & wait-for-acknowledge? } } Example: cluster store <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> jdbc storeThe JDBC store saves sessions in a JDBC database. Often, this will be a dedicated database to avoid overloading the main database.
Example: jdbc-store <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> file storeThe 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.
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.conf - simple usage of server ping <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <cluster id="app-tier"> <ping url="http://localhost/"/> ... </cluster> </resin> Example: resin.conf - configured usage of server ping <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> ... <cluster id="app-tier"> <ping> <url>http://localhost:8080/index.jsp</url> <url>http://localhost:8080/webapp/index.jsp</url> <url>http://virtualhost/index.jsp</url> <url>http://localhost:443/index.jsp</url> <sleep-time>5m</sleep-time> <try-count>5</try-count> <!-- a very busy server --> <socket-timeout>30s</socket-timeout> </ping> ... </cluster> </resin> 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.conf - mail notification when ping fails <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> ... <cluster id="web-tier"> <ping resin:type="com.caucho.server.admin.PingMailer"> <url>http://localhost:8080/index.jsp</url> <url>http://localhost:8080/webapp/index.jsp</url> <mail-to>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.conf - smtp server configuration <system-property mail.smtp.host="127.0.0.1"/> <system-property mail.smtp.port="25"/> All Environment tags are available to the <cluster>. For example, resources like <database>. Example: cluster environment <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <database jndi-name="jdbc/test"> <driver type="org.postgresql.Driver"> <url>jdbc:postgresql://localhost/test</url> <user>caucho</user> </driver> </database> <server id="a" ...> ... <host host-name="www.foo.com"> ... </cluster> </resin> <rewrite-dispatch> defines a set of rewriting rules for dispatching and forwarding URLs. Applications can use these rules to redirect old URLs to their new replacements. See rewrite-dispatch for more details. rewrite-dispatch <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <rewrite-dispatch> <redirect regexp="^http://www.foo.com" target="http://bar.com/foo"/> </rewrite-dispatch> </cluster> </resin> default The root-directory of the <resin> tag. <root-directory> configures the root directory for files within the cluster. All paths in the <cluster> will be 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> The <server> tag configures a JVM instance in the cluster. Each <server> is uniquely identified by its attribute. The will match the -server-id command line argument.See the full server configuration for more details of the <server> tag and its children. The current server is managed with a ServerMXBean. The ObjectName is . Peer servers are managed with ServerConnectorMXBean. The ObjectName is .
<server> schema 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? } Example: 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" port="6800"> <http port="8080"/> </server> <server id="c" address="192.168.0.12" port="6800"> <http port="8080"/> </server> <host id=""> ... </cluster> </resin> Defines default values for all <server> instances. See <server> configuration for more details. Example: server <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <server-port>6800</server-port> <http port="8080"/> </server-default> <server id="a" address="192.168.0.10"/> <server id="b" address="192.168.0.11"/> <server id="c" address="192.168.0.12"/> <host id=""> ... </cluster> </resin> default Resin/3.1.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> default JSESSIONID Configures the cookie used for servlet sessions. <session-cookie> schema element session-cookie { string } default false Disables sticky sessions from the load balancer. <session-sticky-disable> schema element session-sticky-disable { r_boolean-Type } default ;jsessionid= Configures the URL prefix used for session rewriting. Note Session rewriting is discouraged as a potential security issue.<session-cookie> schema element session-cookie { string } default value of session-cookie Defines an alternative session cookie to be used for a SSL connection. Having two separate cookies increases security. <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> 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-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>
|