Reference Guide

Getting Started

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

Basic Config


RESIN_HOME is the directory containing the Resin binaries and classes. In the default configuration, RESIN_HOME will be the same as SERVER_ROOT, i.e. the document directories and log files are based on RESIN_HOME. A typical location for RESIN_HOME might be /usr/local/resin.

RESIN_HOME is controlled by the command-line and system environment when Resin starts. The heuristic for selecting RESIN_HOME is

  1. -resin-home dir command-line argument
  2. $RESIN_HOME system environment variable
  3. The parent directory of the starting binary. bin/httpd, or bin/ will look at its own directory and then use the parent directory as RESIN_HOME.

The Resin binary will set the Java system property resin.home to the value for RESIN_HOME, e.g. by setting -Dresin.home=$RESIN_HOME. If an application starts the Resin main class directly, it should set the resin. home system property.

Contents of RESIN_HOME
bin/Resin startup binaries
lib/jar files automatically added to the system classpath. Applications may add third-party library .jar files.
libexec/JNI *.so files to be automatically loaded
classes/Optional directory of classes to be added to the system classpath. (Applications should use WEB-INF/classes instead.)
conf/Directory containing configuration files when RESIN_HOME is the same as SERVER_ROOT.
conf/resin.confThe main Resin configuration file when RESIN_HOME is the same as SERVER_ROOT.
doc/Document root when RESIN_HOME is the same as SERVER_ROOT for the default virtual host.
webapps/War expansion directory when RESIN_HOME is the same as SERVER_ROOT for the default virtual host.
log/Log directory when RESIN_HOME is the same as SERVER_ROOT.


SERVER_ROOT is the directory containing the user's configuration, documents, and log files. By default, SERVER_ROOT is the same as RESIN_HOME, but sophisticated users will create a separate directory from the Resin binaries. For example, an ISP might have a separate SERVER_ROOT for each user's JVM. A typical location for SERVER_ROOT might be /usr/local/webroot.

SERVER_ROOT is controlled by the command-line when Resin starts. The heuristic for selecting SERVER_ROOT is:

  1. The value of <root-dir> in the <http-server> section of the resin.conf.
  2. -server-root dir command-line argument
  3. The value of RESIN_HOME.

Contents of SERVER_ROOT
conf/Directory containing the resin.conf configuration file.
conf/resin.confThe main Resin configuration file.
cache/Directory Resin's cache files.
doc/Document root for the default virtual host.
webapps/War expansion directory for the default virtual hosts.
log/Log directory.
WEB-INF/Application classes and jars common to all virtual hosts. directory for a virtual host.

virtual host root-dir

Each virtual host has its own root directory. The root directory contains virtual host's documents, war directory, and logs.

The virtual host's directory is configured in the resin.conf. root-dir configures the virtual host's root. doc-dir configures the virtual host's document directory.

Contents of the virtual host
webapps/war-dir.war expansion directory.
webapps/WEB-INF/war-dirCommon classes for the virtual host
doc/doc-dirdocument directory.
log/access.logaccess-logper-virtual host access logs
log/error.logerror-logper-virtual host error logs
log/stdout.logstdout-logper-virtual host System.out
log/stderr.logstderr-logper-virtual host System.err

webapps (war-dir)

The webapps directory automatically expands .war and .ear files.

Each .war file will be expanded into a web-app as a directory under the webapps directory. webapps/foo.war will expand into webapps/foo. /foo will then be a web-app for the virtual host. So the URL might be

Each .ear file will expand its jars and .war files. The jars will go into webapps/WEB-INF/lib. The .wars will be expanded into webapps.

The resin.conf configures the webapps directory with the war-dir configuration.

Configuring the war-dir
<host id="">

.war file

A .war file is a packaged Servlet application. It's just a renamed .jar file of the web-app directory tree. Resin provides a special webapps directory which will automatically expand .war files, configured by the war-dir attribute in the resin.conf's host configuration.

Placing a foo.war in webapps/foo.war will prompt Resin to expand foo.war into webapps/foo/*. Resin will automatically create a new application browsable at the URL http://localhost:8080/foo

You can also use the < war-dir> for development. Just creating a webapps/bar directory will create an application browsable at http://localhost:8080/bar. A small warning, though, any bar.war placed in webapps will delete and replace your webapps/bar directory.

The special .war file ROOT.war can be used to configure the 'root' web-app, i.e. the web-app with no context path. webapps/ROOT is browsed with http://localhost:8080.

Resin always handles all files in a war, even when Resin is used with another webserver like Apache.

web-app directory

Each web application has its own document directory. The files in that directory are served as static file. The WEB-INF subdirectory contains classes and configuration files for the web-app.

Web applications are either configured implicitly by the webapps directory or explicitly in the resin.conf. Any .war files in the webapps directory will create a web application. foo.war will expand into the web-app directory webapps/foo. The WEB-INF directory is in webapps/foo/WEB-INF.

Web applicatoins configured in the resin.conf can be placed anywhere in the filesystem using the app-dir tag.

Explicit web-app in resin.conf
<host id=''>
  <web-app id='/bar' app-dir='/opt/bar'/>

The web-apps can also be configured using regular expressions. For example, /~ferg may translate into a web-app in /home/ferg/public_html.

Regexp web-app in resin.conf
<host id=''>
  <web-app url-regexp='/~([^/]*)'>

web-app directory contents
test.htmlStatic HTML file served to user
foo.jspJSP file served to user
WEB-INF/Directory for classes and servlets


The WEB-INF contains the classes, jars, and configuration files for the web application. WEB-INF is at the root of the web-app's document directory.

Contents of WEB-INF
classes/Directory containing .class files
lib/Directory containing .jar files
tld/Directory containing tag library configuration files.
sessions/Directory containing persistent sessions.
work/Directory containing Resin's automatically generated java and class files for JSP, XSL, and EJB.
tmp/Temporary directory for the web-app.
web.xmlServlet standard configuration file for the web-app.
resin-web.xmlResin-specific configuration.
foo.ejbResin-specific EJB configuration files.

WEB-INF for hosts and http-server

Hosts and the http-server may also have a WEB-INF directory. The host's WEB-INF will be shared for all web-apps in the virtual host. The http-server's WEB-INF will be shared for all virtual hosts in the server.

The host's WEB-INF directory is in webapps/WEB-INF. The http-server's WEB-INF is in SERVER_ROOT/WEB-INF.

Sites will typically use the host's WEB-INF to share resources, EJB servers, or single-signon authenticators for all applications in a host or in the server.

path-mapping (aliasing)

In the web.xml file, directories and files can be aliased using the path-mapping directive.
aliasing /images to /opt/images

Path Variable expansion

Paths in configuration variables can use path and regular expression variables.

$server-rootThe root of the server instance. Same as the -server-root argument.
$server-docThe document root for the server instance.
$host-rootThe root directory of the enclosing <host>
$host-docThe document directory of the enclosing <host>
$app-dirThe app-dir of the enclosing <web-app>
$host0 ... $host9Regular expression replacement from a host url-regexp.
$app0 ... $app9Regular expression replacement from a web-app url-regexp.
$0 ... $9Regular expression replacement for the containing context (host or web-app)
$fooJava property value from System.getProperty("foo")

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