The rollover-period variable controls how often the access log will be rotated. When the time runs out, Resin will move the old log file to a timestamped one, e.g. access.log20001114. Rollovers happen at midnight in the local time if the time period is a day or longer.

The access log formatting variables follow the Apache variables:

The default format is:

"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" <server> <access-log id='log/access.log'> <rollover-period>2W</rollover-period> </access-log> ... </server>

If the web-app doesn't specify an access-log, it will use the host's access-log.


Configures Resin's internal HTTP proxy cache. Resin's cache can dramatically improve performance by avoiding re-evaluation of slowly changing database-backed changes. We strongly recommend using the proxy caching when possible for a simple, standards-based performance boost.

Using the proxy cache is described more fully in the caching documentation.


Defines the cluster of Resin JVMs used for load-balancing and for sharing distributed sessions.

<cluster> <client-live-time>30s</client-live-time> <srun id="a" host="" port="6802" index="1"/> <srun id="b" host="" port="6802" index="2"/> </cluster>

Configures the directory where web pages will be placed when using webserver-style deployment instead of war-based deployment.


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

Note, Linux requires the new thread package (e.g. RedHat 9.0 or later) to support group-name.


Configures a virtual host. Virtual hosts must be configured explicitly.

<host host-name=""> <host-alias></host-alias> <host-alias></host-alias> <root-directory>/opt/www/</root-directory> ... </host> <host regexp="([^.]+)\.foo\.com"> <host-name>${host.regexp[1]}</host-name> <root-directory>/opt/www/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.

server, host-deploy

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.


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.


Configures a HTTP 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.


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.

http, srun, port

Configures SSL.

More documentation is available in the Security section.

The mod_ssl documentation for Apache is a good source of information on OpenSSL.

The class that corresponds to <openssl> is .


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.

<server> <cluster> <srun id="a" host="" port="6802" index="1"/> <srun id="b" host="" port="6802" index="2"/> </cluster> <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> </server> server

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.

<resin xmlns="" xmlns:resin=""> ... <server> <ping url="http://localhost/"/> ... </server> </resin> <resin xmlns="" xmlns:resin=""> ... <server> <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> ... </server> </resin>

The class that corresponds to <ping> is .

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

<resin xmlns="" xmlns:resin=""> ... <server> <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></mail-to> <mail-from></mail-from> <mail-subject>Resin ping has failed for server ${}</mail-subject> </ping> ... </server> </resin>

The port tag allows for custom protocols using Resin's thread and connection management.

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

<server> <port id="" host="localhost" port="8888"> <protocol resin:type="example.Magic8BallProtocol"/> </port> </server>

Top-level configuration for the resin.conf 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.

<resin xmlns=""> <server> <http id='' host='*' port='8080'/> <resin:import path="app-default.xml"/> <host id=""/> <web-app id="/"/> </host> </server> </resin>

The class that corresponds to this tag is

server, host

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.

<resin xmlns="" xmlns:resin=""> ... <security-manager/> ...

See also:

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 .

<resin xmlns="" xmlns:resin=""> ... <security-provider></security-provider> <security-provider>example.MyProvider</security-provider> ...

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 <srun> ports which share the thread pool. Requests received on those ports will use worker threads from the thread pool.

<server> ... <alternate-session-url-prefix>/~J=</alternate-session-url-prefix> ...

The class that corresponds to <server> is


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


Configures a clustered HMUX listener.

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

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

The class that corresponds to <srun> is


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.

There are some conventions for tag names that provide similar functionality.

<fileset> provides the ability to match a set of files. It is modelled after the ant tag by the same name.

A pattern can contain two special characters: '*' and '**'. '*' matches any part of path, but does not match the path separator. '**' matches any part of a path, including the path separator.

<fileset dir="lib"> <include name="*.jar"/> </fileset> MATCH lib/foo.jar MATCH lib/bar.jar NO MATCH lib/baz/foo.jar <fileset dir="lib"> <include name="**/*.jar"/> </fileset> MATCH lib/foo.jar MATCH lib/bar.jar MATCH lib/baz/foo.jar

The class that corresponds to <fileset> is . The class that corresponds to the <include> and <exclude> patterns is

The is used in a number of places to determine the behaviour of a resource when the server starts.

The startup-mode has three values: "automatic", "lazy", and "manual".

The is used in a number of places to determine the behaviour of a resource when it is replaced or modified while the server is running.

The redeploy-mode has two values: "automatic", and "manual".

Copyright (c) 1998-2009 Caucho Technology, Inc. All rights reserved.
caucho® , resin® and quercus® are registered trademarks of Caucho Technology, Inc.