<cluster> configures a set of servers used for load-balancing and for sharing distributed sessions.

For reliability, Resin periodically checks the amount of free memory available. When the free memory drops below <min-free-memory>, even after garbage collection, Resin will force a JVM restart.

In general, application developers should use a heap profiler to eliminate memory leaks and OutOfMemoryErrors. Because an OutOfMemoryError can cause severe problems with the application, Resin detects the low memory before those errors can be thrown.

<resin> is the top-level configuration tag for the resin.xml file. The <resin> tag needs to specify the Resin namespace, to allow for validation of the configuration file.

The environment of the top-level <resin> is the global classpath. This environment can be important for <log> configuration for threads which run with using only the global class loader. Because the <resin> environment does not have a dynamic class loader, dynamically loaded classes, like custom jars in resin/lib are not available.

Specifies the root directory for the <server> and <host> contexts. All EL-style directory paths are relative to the root-directory.

Enable the use of the security manager for the JVM.

See also:

• Security Manager

Add one or more security providers. Each entry specifies the name of a security provider class. The name is used to instantiate an instance of the object, which is then passed to .

Configures the maximum time Resin will wait for the server to shutdown gracefully before forcing an exit.

<thread-pool> configures the thread pool shared among all ports.

<thread-max> is the absolute maximum number of connection worker threads allowed. <thread-max> may be limited by OS/JVM restrictions, especially the stack size. -Xss and/or ulimit -s may be required for large numbers of threads, e.g. "ulimit -s 2048" on some versions of Linux would allow for 1024 total threads in the JVM.

<spare-thread-min> configures Resin's adaptive thread pooling. Resin tries to keep <spare-thead-min> idle threads available at all time. Sites with large spikes in connection loads may need to increase the <spare-thread-min> value.

Note: at present, this directive is deprecated because of timing issues with log file creation and ownership. It is recommended that you use some other method to remap port 80 to port 8080.

Configures the Unix setuid user name used after Resin binds the reserved ports as root.

<accept-listen-backlog> configures operating system TCP listen queue size for the port.

When a browser connects to a server, the server's operating system handles the TCP initialization before handing the socket to the server's application. The operating system will hold the opened connections in a small queue, until the application is ready to receive them. When the queue fills up, the operating system will start refusing new connections.

<accept-thread-max> configures the maximum number of threads listening for new connections on this port. <accept-thread-max> works with <accept-thread-min> to handle spiky loads without creating and destroying too many threads.

Socket connections are associated with a thread which handles the request. In Resin, a number of threads wait to accept a new connection and then handle the request. <accept-thread-max> specifies the maximum number of threads which are waiting for a new connection.

Larger values handle spiky loads better but require more threads to wait for the connections. Smaller values use less threads, but may be slower handling spikes.

<accept-thread-min> configures the minimum number of threads listening for new connections on this port <accept-thread-min> works with <accept-thread-max> to handle spiky loads without creating and destroying too many threads.

Socket connections are associated with a thread which handles the request. In Resin, a number of threads wait to accept a new connection and then handle the request. <accept-thread-min> specifies the minimum number of threads which are waiting for a new connection. If many connections appear rapidly with a small value of <accept-thread-min>, the application may pause until a new thread is available for the new connection.

Larger values handle spiky loads better but require more threads to wait for the connections. Smaller values use less threads, but may be slower handling spikes.

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.

<cluster-port> configures the cluster and load balancing socket, for load balancing, distributed sessions, and distributed management.

When configuring Resin in a load-balanced cluster, each Resin instance will have its own <server> configuration, which Resin uses for distributed session management and for the load balancing itself.

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

<group-name> configures the operating system group Resin should run as. Since the HTTP port 80 is protected in Unix, the web server needs to start as root to bind to port 80. For security, Resin should switch to a non-root user after binding to port 80.

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

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.

<jvm-arg> configures JVM arguments to be passed to Resin on the command line, typically -X memory parameters and -D defines.

<jvm-classpath> adds a classpath entry when starting the JVM.

<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-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-select-thread-timeout> is a short timeout allowing the select manager to wait for a keepalive before detaching the thread. This value would not normally be changed.d wou

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

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

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

<memory-free-min> improves server reliability by detecting low-memory situations caused by memory leaks and forcing a clean server restart. Since Resin's watchdog service reliably restarts the server, a website can improve stability by forcing a restart before memory becomes a major problem. The memory-free-min restart will also log a warning, notifying the developers that a potential memory leak needs to be resolved.

When free heap memory gets very low, the garbage collector can run continually trying to free up extra memory. This continual garbage collection can send the CPU time to 100%, cause the site to become completely unresponsive, and yet take a long time before finally failing to an out of memory error (forcing an unclean restart). To avoid this situation, Resin will detect the low-memory condition and gracefully restart the server when free memory becomes too low.

The ultimate solution to any memory leak issues is to get a memory profiler, find the leaking memory and fix it. <memory-free-min> is just a temporary bandage to keep the site running reliably until the memory leak can be found and fixed.

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.

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

<protocol> configures custom socket protocols using Resin's thread and connection management.

The custom protocol will extend from com.caucho.server.port.Protocol.

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

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

<shutdown-wait-max> configures the maximum time the server will wait for the graceful shutdown before forcing an exit.

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

<thread-idle-max> configures the maximum number of idle threads in the thread pool. <thread-idle-max> works with <thread-idle-min> to maintain a steady number of idle threads, avoiding the creation or destruction threads when possible.

<thread-idle-max> should be set high enough beyond <thread-idle-min> so a spiky load will avoid creating a thread and then immediately destroying it.

<thread-idle-min> configures the minimum number of idle threads in the thread pool. <thread-idle-min> helps spiky loads, avoiding delays for thread requests by keeping threads ready for future requests. When the number of idle threads drops below <thread-idle-min>, Resin creates a new thread.

<thread-idle-min> should be set high enough to deal with load spikes. Since idle threads are relatively inexpensive in modern operating systems, having a number of idle threads is not a major resource hog, especially since these threads are idle, waiting for a new job.

<thread-idle-min> works together with <thread-idle-max> to avoid thread allocation thrashing, i.e. avoiding creating a new thread because of <thread-idle-min> and then quickly destroying it because of <thread-idle-max>.

<thread-max> configures the maximum number of threads managed by Resin's thread pool. Resin's thread pool is used for connection threads, timers, and Resin worker threads for JMS, JCA and EJB. Since Resin's thread pool only manages Resin threads, the actual number of threads in the JVM will be higher.

Modern operating systems can handle a fairly large number of threads, so values of 512 or 1024 are often reasonable values for thread-max. The main limitation for thread-max is virtual memory. Since each thread takes up stack space (configured with -Xss), a 32-bit system might have a thread limit based on virtual memory.

For example, on Linux the user space is only 2G. If the heap memory is 1024m (-Xmx1024m) and the stack size is 1m (-Xss1m), the maximum number of threads is somewhat less than 1024.

In general, JVMs do not handle running out of threads very well, either freezing or throwing out of memory errors. Although it may be necessary to limit the number of threads to avoid running out of memory, <thread-max> should generally be set to a high value.

<user-name> configures the operating system user Resin should run as. Since the HTTP port 80 is protected in Unix, the web server needs to start as root to bind to port 80. For security, Resin should switch to a non-root user after binding to port 80.

The <watchdog-arg> configures arguments for the watchdog process. The watchdog improves reliability by monitoring the Resin instance, restarting it if necessary.

The <watchdog-arg> typically is used to enable jconsole for the watchdog JVM.

<watchdog-port> configures the administration port for the watchdog JVM. The watchdog launches the server JVM and monitors its health, restarting the JVM when necessary to improve site reliability. The command line arguments use the watchdog-port for the "start" and "stop" commands to tell the watchdog to start and stop the server JVM. The administration also uses the watchdog port for watchdog administration.

The watchdog port will use the same <address> as the server, so it will always be an internal network address, never an external internet address.

<cookie-domain> configures the host domain to use for sessions, i.e. value of the Domain cookie attributes.

By default, browsers only send cookies back to the exact host which sent them. In some virtual host cases, it makes sense to share the same cookie value for multiple virtual hosts in the same domain. For example, caucho.com might want a single cookie to be used for both gryffindor.caucho.com and slytherin.caucho.com. In this case the cookie-domain would be set to caucho.com.

<cookie-domain-regexp> configures the host domain to use for sessions, i.e. value of the Domain cookie attributes.

This setting serves a case when a single web-app is accessed via a number of domains while session cookie must belong to the domain at requested URI. e.g. domains www.foo.com zoo.xyz.foo.com must have cookie set to foo.com while domains www.1-foo.com zoo.xyz.1-foo.com must have cookie set to 1-foo.com

<cookie-length> sets the length of the generated cookie value. In some rare cases, the cookie-length might need to be shortened or the cookie-length might be extended to add randomness to the cookie value. For the most part, this value should be left alone.

<cookie-max-age> sets how long the browser should keep the session cookie.

By default, browsers keep cookies as long as they are open. When the browser is restarted, the cookies are dropped. cookie-max-age tells the browser to keep the cookie for a certain time period. Applications can make this time "infinite" by setting a large number.

<cookie-version> sets the version of the cookie spec for sessions.

<ignore-serialization-errors> is used with persistent sessions in certain rare cases where some session data is serializable and other data is not serializable. <ignore-serialization-errors> simply skips session values which do not implement java.io.Serializable when serializing the session.

Session configuration parameters.

Resin adds a number of session-config tags.

By default, both enable-cookies and enable-url-rewriting are true. To force url rewriting, you would create a configuration like:

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.

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

<accept-listen-backlog> configures operating system TCP listen queue size for the port.

<accept-thread-max> configures the maximum number of threads listening for new connections on this port.

<accept-thread-min> configures the minimum number of threads listening for new connections on this port.

The <address> defines the IP interface for a port. A value of '*' binds to all ports. Because the <address> is specific to a server, it should only be defined in a <server> tag, not a <server-default>.

<ca-certificate-file> configures the path to a CA certificate file for intermediate CA support.

<ca-certificate-path> configures the path to a CA certificate directory for intermediate CA support.

<ca-revocation-file> configures the path to a list of revoked CA certificates.

<ca-revocation-path> configures the path to a list of revoked CA certificates.

<certificate-file> configures the path to the server's SSL certificate.

<certificate-chain-file> configures the path to the server's SSL certificate for OpenSSL.

<certificate-key-file> configures the path to the server's SSL private key certificate for OpenSSL.

<cipher-suite> configures the path to the server's SSL cryptographic ciphers.

<cluster-port> configures the cluster and load balancing socket, for load balancing, distributed sessions, and distributed management.

When configuring Resin in a load-balanced cluster, each Resin instance will have its own <server> configuration, which Resin uses for distributed session management and for the load balancing itself.

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

<connection-max> configures the maximum number of concurrent connections on this port.

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

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.

<jsse-ssl> configures the port to use JSSE for SSL support.

The SSL section of the Security documentation provides a comprehensive overview of SSL.

<keepalive-max> configures the maximum number of keepalives on this port.

<openssl> configures the port to use OpenSSL for SSL support (requires Resin Professional). OpenSSL is a fast C implementation of SSL security used by Apache. Resin's configuration is OpenSSL follows Apache's configuration, so any documentation on installing SSL certificates can use documentation for Apache.

The SSL section of the Security documentation provides a comprehensive overview of SSL.

<password> configures the SSL private key certificate password.

The <port> defines the TCP port the HTTP or protocol should bind to.

<protocol> configures custom socket protocols using Resin's thread and connection management.

The custom protocol will extend from com.caucho.server.port.Protocol.

<protocol> configures the SSL allowed protocols.

<session-cache> configures the SSL session cache.

<session-cache> configures the SSL session cache timeout.

<socket-timeout> overrides the socket timeout from the <server>.

Sets the tcp-no-delay parameter.

<unclean-shutdown> configures the OpenSSL unclean shutdown on connection close.

<verify-client> sets the client certificate configuration. If the certificate is available, it will be put in the javax.servlet.request.X509Certificate request attribute.

<verify-depth> configures the OpenSSL client verification depth.