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


Resin Documentation

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

resin.conf: ports, virtual hosts, clustering and threads

Describes the resin, server, host, and port configuration in the resin.conf.

See Also

  • See the index for a list of all the tags.
  • See Web Application configuration for web.xml (Servlet) configuration.
  • See Environment configuration for resources: classloader, databases, connectors, and resources.
  • See Log configuration for access log configuration, java.util.logging, and stdout/stderr logging.


child of <resin>

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

<resin xmlns="">
  <cluster id="app-tier">
    <server id="a" address=""/>
    <server id="b" address=""/>

    <host id="">
      <web-app-deploy path="webapps"/>
idName of the clusterrequired


child of <resin>

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.

default 1M


<resin> is the top-level configuration tag 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="">
  <cluster id="web-tier">
    <server id="">
      <http address="*" port="8080"/>
    </server id="">

    <resin:import path="app-default.xml"/>

    <host id=""/>
      <web-app id="/"/>
EL variables defined by <resin>


child of <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=""


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=""





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

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 state120s

EL variables and functions

EL variables defined by <server>
EL functions defined by <server>


child of <resin>

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

default 60s


child of <server>

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

thread-maxmaximum number of working threads200
spare-thread-minminimum number of spare working threads5

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


child of <resin>

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.

Common Tags

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.

dirthe starting directoryrequired
includean include patterndo not include all files
excludean exclude patterndo not exclude any files

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"/>

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

MATCH    lib/foo.jar
MATCH    lib/bar.jar
MATCH    lib/baz/foo.jar

Startup and Redeploy Mode

The <startup-mode> 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".

  • automatic - starts the resource on server start (default)
  • lazy - starts the resource on the first use
  • manual - waits for JMX to start the resource

The <redeploy-mode> 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".

  • automatic - restarts the resource when it is modified (web.xml, *.class, *.war, etc).
  • manual - waits for JMX to restart the resource when changes occur.

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, CNET, DZone and many more are powered by Resin.

home company docs 
app server