Reference Guide

Getting Started

Basic Config
Security Config
Log Config
Taglib Config
Misc resin.conf
Host resin.conf
Port resin.conf
App resin.conf
 Web Application Configuration

Port resin.conf

HTTP configuration follows the Servlet 2.2 deployment descriptors. The nesting order is important, but order is generally not important. In the sections that follow, the section header tells where the attribute belongs. For example, an attribute in belongs in a host element which belongs in an http-server element which belongs in the element.

The application configuration can be placed in WEB-INF/web.xml If web.xml exists, Resin will use it to configure the application.

Servlet configuration interacts with the application configuration. In particular, servlet-mapping tells Resin how to map urls to servlets.

access-logSpecifies the access logging
allow-adminAllows administration from the web-app
allow-servlet-elAllows JSP EL expressions in <init-param> for servlets, filters, and the <context-param>
app-dirSpecifies the directory of the application
browser-mappingBrowser-specific configuration
cache-mappingSpecifies Expires times for cacheable pages
case-sensitiveSpecifies whether servlet-mapping and filter-mapping is treated as case-sensitive or case-insensitive
chain-mappingDefines a Servlet filter to transform the output of another servlet based on mime-type
character-encodingSpecifies the default character encoding for form parameters
class-update-intervalInterval in seconds between checking for servlet updates
classpathAdds to the application-specific classpath
config-update-intervalInterval in seconds between checking for configuration updates
context-paramInitializes application variables
cookie-lengthSpecifies the maximum length for the session's generated cookie
directory-servletSpecifies the servlet to use to display directories
ejb-refInstantiates a EJB client bean
env-entryJNDI parameter configuration
error-logSpecifies the file for error logging
error-pageA page to display if the current request fails
invalidate-after-listenerIf true, listeners are called before the session is invalidated
jdbc-storeConfigure sessions to use a JDBC backing store
jndi-linkLinks a foreign JNDI context to the Resin JNDI context
jspJSP configuration
lazy-initMarks the web-app as lazily initialized
login-configConfigures user authentication
mime-mappingMaps url patterns to mime-types
multipart-formEnables multipart-mime for forms and file uploads
path-mappingMaps url patterns to real paths
resource-refDatabase pooling configuration
run-atTimes to execute the servlet automatically
secureRequires that the web-app be only accessed from a secure connection, e
servletDefines a servlet alias for later mapping
servlet-mappingMaps url patterns to servlets
session-configContains session configuration parameters
session-maxSets the maximum number of active sessions
session-timeoutSets the session timeout in minutes
stderr-logConfigures the location for System
stdout-logConfigures the location for System
strict-mappingForces servlet-mapping to follow strict Servlet 2
taglibConfigures a JSP 1
tcp-storeConfigure sessions to use a TCP-ring backing store
temp-dirApplication temp directory
url-patternMatches a set of URLs for servlet-mapping
web-xmlLets applications specify the web
welcome-file-listSets the files to use as index
work-dirApplication work directory



Specifies the access logging. See the host access-log for more details.

By default, uses the host access-log.


Allows administration from the web-app. allow-admin must be specified in the resin.conf for security. In other words, a .war file can't enable admin in its web.xml.

Default: false


Allows JSP EL expressions in <init-param> for servlets, filters, and the <context-param>.

  <init-param greeting="Hello, ${host.url}"/>


Specifies the directory of the application. If unspecified, the application will have the same path as the id. When the web-app is specified with a url-regexp, app-dir can use replacement variables ($2).

When specified by id, the application will be initialized on server start. When specified by url-regexp, the application will be initialized at the first request. This means that load-on-startup servlets may start later than expected for url-regexp applications.

idThe url prefix selecting this application.n/a
url-regexpA regexp to select this application.n/a
app-dirThe root document directory for the application (can use regexp replacement variables.)Same as id or the regexp match

The following example creates a web-app for /apache using the Apache htdocs directory to serve pages.

<host id=''>
  <web-app id='/apache' app-dir='/usr/local/apache/htdocs'>



The following example sets the root application to the IIS root directory. The host and web-app will use the http-server app-dir as a default.

<http-server app-dir='c:\inetpub\wwwroot'>



In the following, each user gets her own independent application using ~user. (Note, since mod_caucho and IIS don't understand regexps, so you may need to manually configure the web server.)

<host id=''>

<web-app url-regexp='/~([^/]*)'




By default, uses the subdiretory under the host app-dir with the application's name.


Browser-specific configuration. Used to deal with broken browsers.

regexpRegular expression to match the User-Agent
force10If set, force HTTP/1.0

No default browser-mappings are defined.


Specifies Expires times for cacheable pages. Uncacheable pages, e.g. pages with sessions, are not affected.

url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the url
expiresA time interval.

The time interval defaults to seconds, but will allow other periods:


<web-app id='/'>

<cache-mapping url-pattern='/*'

<cache-mapping url-pattern='*.gif'


There is no default value.


Specifies whether servlet-mapping and filter-mapping is treated as case-sensitive or case-insensitive.

Default: false on Windows, true on Unix.


Defines a Servlet filter to transform the output of another servlet based on mime-type. By default, the content type x-application/xsl executes com.caucho.jsp.XslFilter.

For example, a servlet could call setContentType("x-application/xsl") to format its XML results using XSL.

mime-typeThe mime-type to match
servlet-nameThe servlet name to execute
Filter XML by an XSL processor
<chain-mapping mime-type='x-application/xsl'

Note: Versions before Resin 1.2.2 use filter-mapping instead of chain-mapping. This has been changed to avoid conflicts with the Servlet 2.3 spec

By default, Resin maps the x-application/xsl to com.caucho.jsp.XslFilter.


Adds to the application-specific classpath. The classpath can also automatically compile java classes when the source attribute is specified.

Note: Each classpath directive must only contain a single class directory. In other words, you need two classpaths to specify "foo.jar:bar.jar".

idSingle class directory or jarrequired
library-dirTo be used as a jar directory like WEB-INF/libfalse
sourceOptional java source directorysame as id
compileEnable automatic compilationtrue
encodingWhen compiling, what character encoding to usejavac default
argsWhen compiling, additional args to javacnone

For example, to automatically compile classes in the WEB-INF/classes directory:

Compile classes in WEB-INF/classes
<classpath id='WEB-INF/classes'

To compile classes into the WEB-INF/classes directory with the source in a home work directory:

<classpath id='WEB-INF/classes'
<classpath id='/home/test/library/classes'/>

By default, WEB-INF/classes is compiled and WEB-INF/lib contains jars.


Interval in seconds between checking for servlet updates. For development, this can be set to 0 or to a small number to pick up new servlet versions quickly. For deployment, class-update-interval can be large to avoid the overhead of checking for updates.

The default value is 2 seconds.


Specifies the default character encoding for form parameters.

<web-app id='/' character-encoding='shift_jis'>



The default value is ISO-8859-1.


Interval in seconds between checking for configuration updates. For development, this can be set to 0 or to a small number to pick up new configuration file versions quickly. For deployment, config-update-interval can be large to avoid the overhead of checking for updates.

The default value is the value of class-update-interval.


Initializes application variables. context-param defines initial values for application.getInitParameter("foo").

The full servlet 2.2 syntax is supported and allows a simple shortcut

<web-app id='/'>

<context-param foo='bar'/>




Specifies the maximum length for the session's generated cookie. Only special situations like WAP devices should use this option. Reducing this value reduces the randomness in the cookie and increases the chance of session collisions.

Defaults to generate the maximum length of the cookie (64 random bits = 12 characters.)


Specifies the servlet to use to display directories. To disable directory listing, set this to 'none'.

<web-app id='/'>



The default is com.caucho.server.http.DirectoryServlet.


Instantiates a EJB client bean. Normally, EJB clients use jndi-link instead. There are EJB configuration examples for some vendors.

ejb-ref-nameJNDI path attribute to store the bean
ejb-ref-typeEJB class type
ejb-ref-factoryFactory for creating an EJB client bean (Resin 1.2)
init-paramParameter for the factory (Resin 1.2)


JNDI parameter configuration. env-entry binds JNDI variables, similar to either: init-param or context param. env-entry is useful for configuring non-servlet-aware classes, like EJBs.

env-entry-nameJNDI path attribute to store the variable. The path is relative to java:comp/env.
env-entry-typeJava type of the variable
env-entry-valueThe variable value.
Example resin.conf fragment
Example test.jsp
<%@ page import="javax.naming.*" %>
Context env = (Context) new InitialContext().lookup("java:comp/env");

Double dValue = (Double) env.lookup("max-price");
double price = dValue.doubleValue();


Specifies the file for error logging. See the host error-log for more details.

The default uses the containing host's error log.


A page to display if the current request fails. The web server plugins use a special case of error-page to handle connection failures.

locationThe error page to display
exception-typeSelect the error page based on a Java exception
error-codeSelect the error page based on an HTTP status code
Catching File Not Found
<web-app id='/'>
    <error-page error-code='404'
Catching Exceptions
<web-app id='/foo'>
      <error-page exception-type='java.lang.NullPointerException'

The following is a special case for the mod_caucho or isapi_srun plugin to redirect to another page if it can't connect to srun. Unlike the other two forms, this must be in http-server web-app as below. It can't be in a specific web-app.

Special can't connect to srun

<error-page exception-type='connection'

By default, Resin returns a 500 Servlet Error and a stack trace for exceptions and a simple 404 File Not Found for error pages.


If true, listeners are called before the session is invalidated. According to the Servlet spec, the session is invalidated before listeners are called. This means the listeners can't call getAttribute methods. For many applications, the spec behavior is not useful.

Default: false


Configure sessions to use a JDBC backing store. The database must be specified using the resource-ref configuration. The database store will automatically create a table to store the sessions.

data-sourcedata source name for the table
table-namedatabase table for the session data
blob-typedatabase type for a blob
timestamp-typedatabase type for a blob
session-timeoutcleanup time
Example configuration
Example table created by session
CREATE TABLE session (
  data BLOB,
  mod_time TIMESTAMP,

By default, Resin does not use JDBC persistent sessions.


Links a foreign JNDI context to the Resin JNDI context. For example, you can use jndi-link to link in client EJBs from a foreign EJB container.

jndi-nameJNDI path attribute to bind the link to use to obtain the Context.
jndi-factoryClass name of an InitialContextFactory used to create the bean.
init-paramProperties to be used to get the initial context.
jndi-lookupJNDI path for the foreign context.
Linking a WebLogic EJB client bean
  <init-param java.naming.provider.url="t3://localhost:7001"/>

By default, Resin does not add any special JNDI links.


JSP configuration.

auto-compileif false, changes in .jsp will not
disable-init-logif true, disables logging of the jsp init and destroyfalse
jsp-update-intervalHow often JSP files should be checked for changes (since Resin 2.1.1)class-update-interval
jsp-maxlimit the number of active JSP pages1024
precompileuse precompiled JSP classes if available.true
require-sourcecheck to see if the *.jsp file has been deletedfalse
recompile-on-errorIf the JSP page throws a java.lang.Error, recompile it. (since Resin 1.2.3)false
recycle-tagsrecycles tags following the JSP 1.2 (since Resin 2.0.2)true
sessionIf "false", disable sessions by default.true
static-encodingallow JSP to precompile character encoding.true force auto-compile.true
velocityallows Velocity-style syntax (since Resin 2.0.3)false


Marks the web-app as lazily initialized. Normally, web-apps are loaded when Resin starts and the load-on-init servlets are run. With lazy-init, the web-app will only be started on the first request.


Configures user authentication. See auth config for more details.

auth-methodAuthentication method
form-login-configConfiguration for form login
authenticatorSelect authenticator class
security-constraintSelect the files to protect.

By default, Resin does not authenticate.


Maps url patterns to mime-types.

extensionurl extension
mime-typethe mime-type

<web-app id='/'>

<mime-mapping extension='.foo'


Resin has a long list of default mime types in com.caucho.server.http.Application.


Enables multipart-mime for forms and file uploads. multipart-mime is disabled by default.

For an uploaded file with a form name of foo, the parameter value contains the path name to a temporary file containing the uploaded file. foo.filename contains the uploaded filename, and foo.content-type contains the content-type of the uploaded file.

enableif set false, this disables multipart-form processing.true
upload-maxmaximum size of an upload request (default in kb).no limit

128128 bytes
128b128 bytes
128k128 kilobytes
128m128 megabytes
128g128 gigabytes

If the upload is larger than the limit or if multipart-form processing is disabled, Resin will not parse the request and will set an error message in the "caucho.multipart.form.error" request attribute. (Resin 2.0.2)

By default, multipart-form is disabled.


Times to execute the servlet automatically. The run-at value in the servlet configuration configures a servlet to be run at certain times of the day.

The value of the run-at is a list of hours or minutes the servlet should be run at. To run the servlet at 3am and at 2:25pm, use:

Run test.Alarm at 3am and 2:25pm
<servlet servlet-name='foo' servlet-class='test.Alarm'>
  <run-at>3:00 14:25</run-at>

To run the servlet at 5 minutes past the hour and at 45 minutes past the our use ":05 :45".

You can also assign a period to the run-at, instead of specifying specific times. This can be useful if the period is something short like every 5 minutes:

Run test.Alarm every 5 minutes
<servlet servlet-name='foo' servlet-class='test.Alarm'>
  <run-at period='5m'/>


Maps url patterns to servlets. servlet-mapping has two children, url-pattern and servlet-name. url-pattern selects the urls which should execute the servlet.

servlet-name can either specify a servlet class directly or it can specify a servlet alias defined by servlet.

The special servlet-name invoker is used to dispatch servlets by class name. For example, /servlets/test.HelloServlet.

url-patternA pattern matching the url: /foo/*, /foo, or *.foon/a
url-regexpA regular expression matching the urln/a
servlet-nameThe servlet name (can use replacement vars like $1)n/a
path-infoPath info rewriting string (can use replacement vars like $1)The standard path-info
servlet-classThe servlet's classuses servlet-name
init-paramInitialization parametersn/a
load-on-startupInitializes the servlet when the server starts.none
run-atTimes to execute the servlet automaticallynone
case-sensitiveIf true, the match is case-sensitivetrue on Unix and false on Windows

<web-app id='/'>

<servlet servlet-name='hello'

<servlet-mapping url-pattern='/hello.html'

<servlet-mapping url-pattern='/servlet/*'

<servlet-mapping url-pattern='*.xtp'


The plugins use servlet-mapping to decide which URLs to send to Resin. The following servlet-name value are special:

plugin_matchThe plugin will send the request to Resin, but Resin will ignore the entry. Use to get around regexp limitations. (Resin 1.2.2)
plugin_ignoreThe plugin will ignore the request. Use this to define a sub-url the web server should handle, not Resin. (Resin 1.2.2)


Defines a servlet alias for later mapping. More details are in the servlet configuration section.

servlet-nameThe servlet's name (alias)
servlet-classThe servlet's class (defaults to servlet-name)
init-paramInitialization parameters
load-on-startupInitializes the servlet when the server starts.
run-atTimes to execute the servlet automatically (Resin 1.1)
initAllows bean-style configuration. See the servlet page (Resin 2.1.3).

The following example defines a servlet alias 'hello'

<web-app id='/'>

<servlet-mapping url-pattern='/hello.html'

<servlet servlet-name='hello'
  <init-param title='Hello, World'/>

<servlet servlet-name='cron'



Contains session configuration parameters.

session-timeoutThe session timeout in minutes30 minutes
session-maxMaximum active sessions4096
enable-cookiesEnable cookies for sessions (resin 1.1)true
enable-url-rewritingEnable URL rewriting for sessions (resin 1.1)true
cookie-versionVersion of the cookie spec for sessions (resin 1.2)1.0
cookie-domainDomain for session cookies (resin 1.2)none
cookie-max-ageMax age for persistent session cookies (resin 2.0)none
cookie-lengthMaximum length of the cookie. (resin 2.1.1)Integer.MAX_VALUE
file-storePersistent sessions using a file store (resin 1.2)none
jdbc-storePersistent sessions using a JDBC store (resin 1.2)none
tcp-storePersistent sessions using a distributed ring (resin 1.2)none
always-load-sessionReload data from the store on every request (resin 1.2)false
always-save-sessionSave session data to the store on every request (resin 1.2)false
save-on-shutdownOnly save session when the application shuts down. (resin 1.2.3)false
reuse-session-idReuse the session id even if the session has timed out. (resin 2.0.4)true
ignore-serialization-errorsWhen persisting a session, ignore any values which don't implement
invalidate-after-listenerCall listeners before the session is invalidfalse

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

<web-app id='/'>




Sets the session timeout in minutes. Sessions idle for longer than session-timeout are purged.

session-timeout must be contained in a session-config tag.

<web-app id='/dir'>

  <session-config session-timeout='120'/>


Defaults to 30 minutes.


Sets the maximum number of active sessions. Sessions are stored in an LRU cache. When the cache fills, the oldest sessions are recovered.

session-max must be contained in a session-config tag.

<web-app id='/dir'>

     <session-timeout id=120/>
     <session-max id=4096/>


Defaults to 4096.


Configures a JSP 1.1 tag library. See the tlb configuration for details.

taglib-uriMatching uri for the tag library
taglib-locationLocation for the tab library definition file.

The location is relative to the class path. In the following example, MyTag.tld should be in WEB-INF/classes/MyTag.tld.

<taglib taglib-uri='/mytag/test'

The JSP file will use the tag library as follows:

<%@ taglib prefix='x' uri='/mytag/test' %>

By default, looks up all WEB-INF/*.tld and META-INF/*.tld.


Configure sessions to use a TCP-ring backing store. All the <srun> servers are arranged in a ring based on their order in the resin.conf. The tcp-store will store the session based on that ring order.

Example Symmetrical configuration
  <http id='a' port='80'/>
  <srun id='a' host='host-a' port='6802'/>

  <http id='b' port='80'/>
  <srun id='b' host='host-b' port='6802'/>

  <host id=''>
  <web-app id=''>



The above example assumes the two hosts use an external load-balancer, like a router load-balancer.

See distributed sessions for more details.

Disabled by default.


Application temp directory. This is the path used in javax.servlet.context.tempdir.

Default: Defaults to WEB-INF/tmp.


Matches a set of URLs for servlet-mapping.

/foo/bar.htmlMatches exactly the /foo/bar.html URL.
/foo/*Matches /foo and any children
*.fooMatches any URL with a .foo extension
/Replaces the default servlet.

/ defines a default handler and /* defines a prefix handler. /* will override extension handlers like *.foo. / will only be used if no other pattern matches.

No default. Either url-pattern or url-regexp is required.


Database pooling configuration. resource-ref puts the DataSource in a JNDI context and also in the ServletContext. Each web-app can configure its own database pool. Resin can also share a common pool by putting the resource-ref outside the http-server.

More details are in the database config page.

The driver can be in WEB-INF/lib or WEB-INF/classes, although it's a better idea to put it in the global classpath or resin-2.0.x/lib.

res-ref-nameJNDI path attribute to store the pool. The path is relative to java:comp/env.
res-typejavax.sql.DataSource or javax.sql.XADataSource for database pools
init-paraminitialization parameters (Resin 1.2)
init-classClass containing init params (Map or Hashtable) (Resin 1.2.4)
bean-nameoptional bean class to be used as a resource (Resin 1.2)

init-param sets bean properties of the data source. You can look at the com.caucho.sql.DBPool JavaDoc for its interface. Unknown parameters are used to set the driver properties. So you can set any driver-specific property in the init-param.

DBPool Init Parameters
driver-nameJDBC driver classrequired
urlJDBC url for the databaserequired
userDatabase user""
passwordDatabase password""
max-connectionsMaximum number of allowed connections20
max-idle-timeMaximum time an idle connection is kept in the pool30 sec
connection-wait-timeHow long to wait for an idle connection (Resin 1.2.3)10 minutes
max-overflow-connectionsHow many "overflow" connection are allowed if the connection wait times out.0
ping-tableThe database table used to "ping", checking that the connection is still live.false
ping-on-reuseTest for live connections before allocating them from the pool.false
ping-on-freeTest for live connections before replacing them in the pool.false
ping-on-idlePeriodically test connections in the poolfalse
any othercalls DBPool.setProperty() to set driver properties.none

Here's a sample minimal resin.conf fragment to bind a DBPool-based database to the JNDI path "java:comp/env/jdbc/test".

Sample resin.conf fragment
  <init-param driver-name=""/>
  <init-param url="jdbc:mysql://localhost:3306/test"/>

The following is a sample design pattern for getting new database connections. The try ... finally block is very important for making database connections reliable.

Sample test.jsp to use database connections
<%@ page import='javax.sql.*, javax.naming.*, java.sql.*' %>
Context env = (Context) new InitialContext().lookup("java:comp/env");

DataSource source = (DataSource) env.lookup("jdbc/test");
Connection conn = source.getConnection();
try {
} finally {


Maps url patterns to real paths. If using a server like IIS, you may need to match the server's path aliases.

url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the url
real-pathThe prefix of the real path. When used with url-regexp, allows substitution variables like $1.

<web-app id='/'>

<path-mapping url-pattern='/resin/*'

<path-mapping url-regexp='/~([^/]*)'



Requires that the web-app be only accessed from a secure connection, e.g. SSL.


Configures the location for System.err for the current web-app. The stdout-log may be put in the <host> or <http-server> context to apply to all web-apps within that context.

  <stdout-log href='$app-dir/WEB-INF/logs/stdout.log'/>

hrefThe location of the file. Path variables may be used.
rollover-periodHow often the log should be rotated.
rollover-sizeThe maximum size of the log before rotation.
timestampTimestamp before each line (Resin 2.0.3)
encodingCharacter encoding


Configures the location for System.out for the current web-app. The stdout-log may be put in the <host> or <http-server> context to apply to all web-apps within that context.

  <stdout-log href='$app-dir/WEB-INF/logs/stdout.log'/>

hrefThe location of the file. Path variables may be used.
rollover-periodHow often the log should be rotated.
rollover-sizeThe maximum size of the log before rotation.
timestampTimestamp before each line (Resin 2.0.3)


Forces servlet-mapping to follow strict Servlet 2.2, disallowing PATH_INFO.

Default: Defaults to false, allowing /foo/bar.jsp/foo.


Sets the files to use as index.jsp pages. According to the spec, each file is in a <welcome-file> element.

<web-app id='/'>

Resin also provides a shortcut where you can just list the files:

<web-app id='/'>
  <welcome-file-list>index.jsp, index.xtp, home.xtp</welcome-file-list>

Default: Defaults to index.xtp, index.jsp, index.html.


Lets applications specify the web.xml file.

Default: Defaults to web.xml.


Application work directory. This is the directory used for generated code like JSP, XSL and EJB classes.

Default: Defaults to WEB-INF/work.

Port resin.conf
Copyright © 1998-2002 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.