resin.conf: Ports, Virtual Hosts, Clustering and ThreadsResin 3.0
Resin 3.0

Features
Installation
Configuration
Web Applications
IOC/AOP
Resources
JSP
Servlets and Filters
Portlets
Databases
Admin (JMX)
CMP
EJB
Amber
EJB 3.0
Security
XML and XSLT
XTP
JMS
Performance
Protocols
Third-party
Troubleshooting/FAQ

index
howto
resin.conf
env
web-app
log
el control
Bean Config
Common Tasks
Relax Schema
Config FAQ
Scrapbook
howto
Configuration
env

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

  1. See Also
  2. resin.conf
    1. access-log
    2. cache
    3. cluster
    4. document-directory
    5. group-name
    6. host
    7. host-default
    8. host-deploy
    9. http
    10. min-free-memory
    11. openssl
    12. persistent-store
    13. ping
      1. Mail notification when ping fails
    14. resin
    15. root-directory
    16. security-manager
    17. security-provider
    18. server
      1. EL variables and functions
    19. srun
    20. thread-pool
    21. user-name
  3. Common Tags
    1. fileset
  4. Startup and Redeploy Mode

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.

resin.conf

access-log

Resin 3.0

child of: server, host

Specifies the access log file.

AttributeMeaningdefault
pathThe access log path.required
formatAccess log format.see below
resin:typeClass implementing AbstractAccessLog for custom logging.
rollover-periodhow often to rollover the log. Normally in days (15D), weeks (2W) or months (1M).none
rollover-sizemax size of the log before a rollover.10 meg
archive-formatformat the name of the archive file.n/a

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:

%bresult content length
%hremote IP addr
%{xxx}irequest header xxx
%{xxx}oresponse header xxx
%{xxx}ccookie value xxx
%nrequest attribute
%rrequest URL
%sstatus code
%{xxx}trequest date with optional time format string.
%Ttime of request in seconds
%uremote user
%Urequest URI

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.

cache

Resin 3.0

child of: server

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.

AttributeMeaningdefault
pathfilesystem location of the cacherequired
enableenables/disables the cachetrue
entriesmax number of entries allowed in the cache1024
memory-sizemax size of the cache saved in memory1M
disk-sizemax size of the cache saved on disk64M

cluster

Resin 3.0

child of: server

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

AttributeMeaningdefault
client-live-timeHow long to keep an idle socket open30s
client-dead-timeHow long to treat a server as dead15s
client-read-timeoutTimeout for client reads60s
client-write-timeoutTimeout for client writes60s

document-directory

Resin 3.0

child of: web-app

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

group-name

Resin 3.0

child of: resin

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.

host

Resin 3.0

child of: server

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

AttributeMeaningdefault
idprimary host namenone
regexpRegular expression based host matchingnone
host-nameCanonical host namenone
host-aliasAliases matching the same hostnone
secure-host-nameHost to use for a redirect to SSLnone
root-directoryRoot directory for host filesparent directory
startup-mode`automatic', `lazy', or `manual', see Startup and Redeploy Mode automatic

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>

  
    
  
  ...
</host>

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

host-default

Resin 3.0

child of: 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.

host-deploy

Resin 3.0.4

child of: server

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.

AttributeMeaningdefault
pathpath to the deploy directoryrequired
expand-pathpath to the expansion directorypath
host-defaultdefaults for the expanded host&td> 
host-namethe host name to match${name}

http

Resin 3.0

child of: server

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.

AttributeMeaningdefault
server-idserver id matching the -server command linenone
hosthostname of the interface to listen to*
portport to listen torequired
tcp-no-delaysets the NO_DELAY socket parametertrue
read-timeouttimeout waiting to read from idle client65s
write-timeouttimeout waiting to write to idle client65s
socket-listen-backlogThe socket factory's listen backlog for receiving sockets100
virtual-hostforces all requests to this <http> to use the named virtual hostnone
opensslconfigures the port to use OpenSSLnone
jsse-sslconfigures the port to use JSSE for SSLnone

min-free-memory

Resin 3.0

child of: resin
default: 1M

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.

openssl

Resin 3.0

child of: http, srun, port

Configures SSL.

AttributeMeaningdefault
certificate-filethe file containing the server's certificaterequired
certificate-key-filethe file containing the server's certificate key, if separate from certificate-filecertificate-file
passwordthe certificate key passwordrequired
certificate-chain-fileA file containing an intermediate (untrusted) and root (trusted) certificate. See Certificate Chains .none
session-cachetrue or false, enables the SSL session cachetrue
session-cache-timeoutsets the SSL session cache timeout in seconds300
verify-clientVerify the client, value is one of `require' (the client has to present a valid certificate), `optional' (the client may present a valid certificate), `optional-no-ca' (the client may present a certificate, it may be unverifiable)no client verification
verify-depththe maximum number of intermediate signers to accept when verifying client certificates-1
ca-certificate-filea file containing a concatenated list of PEM-encoded certificates recognized for client authenticationnone
ca-revocation-filea file containing a concatenated list of PEM-encoded certificates which have been revoked and are no longer validnone
protocola combination of +all, -all, +sslv2, -sslv2, +sslv3, -sslv3, +tlsv1, -tlsv1+all
cipher-suite  

More documentation is available in the Security section.

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

mod_ssl equivalents to Resin OpenSSL configuration
Resinmod_ssl
certificate-file SSLCertificateFile
certificate-key-file SSLCertificateKeyFile
certificate-chain-file SSLCertificateChainFile
session-cache SSLSessionCache
session-cache-timeout SSLSessionCacheTimeout
verify-client SSLVerifyClient
verify-depth SSLVerifyDepth
ca-certificate-file SSLCACertificateFile
ca-revocation-file SSLCARevocationFile
protocol SSLProtocol
cipher-suite SSLCipherSuite

The class that corresponds to <openssl> is class com.caucho.vfs.OpenSSLFactory .

persistent-store

Resin 3.0.8

child of: server

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="192.168.0.1" port="6802" index="1"/>
    <srun id="b" host="192.168.0.2" 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>

common tags
AttributeMeaningdefault
max-idle-timeHow long idle objects are stored24h
always-loadAlways load the valuefalse
always-saveAlways save the valuefalse

jdbc tags
AttributeMeaningdefault
data-sourceThe JDBC data sourcerequired
table-nameDatabase tablepersistent_session
blob-typeSchema type to store valuesfrom JDBC meta info

cluster tags
AttributeMeaningdefault
pathDirectory to store the sessionsrequired

file tags
AttributeMeaningdefault
pathDirectory to store the sessionsrequired

ping

Resin 3.0

child of: 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.conf - simple usage of server ping
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  ...
  <server>
    <ping url="http://localhost/"/>
    ...
  </server>
</resin>

resin.conf - configured usage of server ping
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  ...
  <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>

AttributeMeaningdefault
urlA url to ping.required
sleep-timeTime to wait between pings. The first ping is always 15m after the server starts, this is for subsequent pings.15m
try-countIf a ping fails, number of times to retry before giving up and restarting required
retry-timetime between retries1s
socket-timeouttime to wait for server to satrt responding to the tcp connection before giving up10s

The class that corresponds to <ping> is class com.caucho.server.admin.PingThread .

Mail notification when ping fails

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

resin

Resin 3.0

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
<resin xmlns="http://caucho.com/ns/resin">
  <server>
    <http id='' host='*' port='8080'/>

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

    <host id=""/>
      <web-app id="/"/>
    </host>
  </server>
</resin>

EL variables defined by <resin>
variablecorresponding API 
resin-homeCauchoSystem.getResinHome() 
server-rootCauchoSystem.getServerRoot() 

The class that corresponds to this tag is class com.caucho.server.resin.ResinServer

root-directory

Resin 3.0

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.

security-manager

Enable the use of the security manager for the JVM.

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">

  ...
  <security-manager/>
  ...

See also:

security-provider

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 method Security.addProvider .

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">

  ...

  <security-provider>com.sun.net.ssl.internal.ssl.Provider</security-provider>
  <security-provider>example.MyProvider</security-provider>

  ...

server

Resin 3.0

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.

AttributeMeaningdefault
alternate-session-url-prefix a 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-max the maximum number of keepalive connections 512
keepalive-timeout the maximum time a connection is maintained in the keepalive state 120s

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

The class that corresponds to <server> is class com.caucho.server.resin.ServletServer

EL variables and functions

EL variables defined by <server>
variablecorresponding API
serverIdserver.getServerId()
root-dirserver.getRootDirectory()
server-rootserver.getRootDirectory()

EL functions defined by <server>
functioncorresponding API
jndi:lookupmethod Jndi.lookup(String)

srun

Resin 3.0

child of: cluster

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.

AttributeMeaningdefault
backupIf true, the server is generally used as a backupfalse
hosthostname of the interface to listen to*
indexSession index of the srunrequired
jsse-sslconfigures the port to use JSSE for SSLnone
opensslconfigures the port to use OpenSSLnone
portport to listen torequired
protocolconfigures the Srun protocolhmux
read-timeouttimeout waiting to read from idle client65s
write-timeouttimeout waiting to write to idle client65s
server-idserver id matching the -server command linenone
socket-listen-backlogThe socket factory's listen backlog for receiving sockets100
tcp-no-delaysets the NO_DELAY socket parametertrue

The class that corresponds to <srun> is class com.caucho.server.cluster.ClusterPort

thread-pool

Resin 3.0

child of: server

Configures the thread pool shared among all ports.

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

user-name

Resin 3.0

child of: resin

Configures the Unix setuid user 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 user-name.

Common Tags

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

fileset

Resin 3.0.7

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

AttributeMeaningdefault
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"/>
</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 class com.caucho.config.types.FileSetType . The class that corresponds to the <include> and <exclude> patterns is class com.caucho.config.types.PathPatternType

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.

howto
Configuration
env
Copyright © 1998-2005 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.