Configuration for both HTTP and srun. The configuration for both is identical, so running httpd and srun will serve exactly the same pages.

Tag	Meaning	Default
http	Configuration for a HTTP port	none
srun	Configuration for load balancing (used by Apache/IIS plugin)	none
srun-backup	Configuration for backup servers (used by Apache/IIS plugin)	none
srun-index	Session index for this server for load balancing and distributed sessions (Resin 1.2.3)	The position in the srun list.
error-page	Error page for the Apache/IIS plugin to display when it can't connect to srun.	none
caucho-status	Enable the /caucho-status special URL.	false
thread-max	Maximum number of live threads.	200
thread-min	Minimum number of live threads.	5
thread-keepalive	Number of keepalive threads	100
request-timeout	Max time for a request, after this the request will be interrupted.	30 sec
listen	Value of the socket listen parameter	5
accept-buffer-size	Number of sockets in the accept buffer.	256
cache	Create a server cache to improve performance	none
host	Virtual host configuration	"default" host
web-app	Servlet configuration	"default web-app

Defines a HTTP or SSL port for the standalone server.

Attribute	Meaning
id	http identifier name
host	The listening host
port	The listening port
virtual-host	Virtual host to select a host block.
ssl	enable ssl
key-store-type	Type of the key store (default jks)
key-store-file	File containing the certificates
key-store-password	Password to read the certificates
thread-max	Maximum number of live threads.	200
thread-min	Minimum number of live threads.	5
thread-keepalive	Number of keepalive threads	100
request-timeout	Max time for a request, after this the request will be interrupted.	30 sec
listen	Value of the socket listen parameter	5
accept-buffer-size	Number of sockets in the accept buffer.	256

Basic HTTP configuration

<caucho.com> <http-server> <http port='8080'> ... </http-server> </caucho.com>

SSL configuration

<caucho.com> <http-server> <http port='8443'> <ssl>true</ssl> <key-store-type>pkcs12</key-store-type> <key-store-file>keys/server.p12</key-store-file> <key-store-password>changeit</key-store-password> </http> ... </http-server> </caucho.com>

Defines multiple client machines for load balancing. This directive used by the web server (Apache or IIS) and by the Java portion of Resin.

Each srun directive adds a new client to receive load balanced requests. With Resin 1.2, the resin.conf must have at least one <srun> or <http> element.

Attribute	Meaning	Default
id	srun identifier name.	none
host	The host name of the client srun.	all interfaces
port	The port name of the client srun.	none
connect-timeout	How long to wait for a connection from the web server to the Resin srun before giving up.	30 sec
live-time	How long the web-server/srun connection should stay live.	5 sec
dead-time	How long before checking that a srun has come back up.	5 sec
thread-max	Maximum number of live threads.	200
thread-min	Minimum number of live threads.	5
thread-keepalive	Number of keepalive threads	100
request-timeout	Max time for a request, after this the request will be interrupted.	30 sec
listen	Value of the socket listen parameter	5
accept-buffer-size	Number of sockets in the accept buffer.	256

Load balance over three machines

<caucho.com> <http-server> <srun id='a' host='host1.caucho.com' port='6802'> <srun id='b' host='host2.caucho.com' port='6802'> <srun id='c' host='host2.caucho.com' port='6803'> </http-server> </caucho.com>

To start srun 'a' use a command line like

unix> srun.sh -server a Resin 1.2.b2 srun listening to host1.caucho.com:6802

On Unix, when starting a daemon, you'll need to specify a unique pid file.

unix> srun.sh -server a -pid a.pid start

Defines backup client machines for load balancing. This directive is only picked up by the web server (Apache). The Java portion of Resin ignores it.

Attribute	Meaning	Default
id	srun identifier name	none
host	The host name of the client srun	all interfaces
port	The port name of the client srun	none
connect-timeout	How long to wait for a connection from the web server to the Resin srun before giving up.	30 sec
live-time	How long a keepalive connection will remain alive before closing.	5 sec.
dead-time	How long to treat a non-responding srun before trying again.	5 sec.

The url to display if the web server can't connect to Resin. This is a special case of error-page in the web-app configuration.

The Apache and IIS plugins use this special error-page directive to display a custom error page when the web server can't connect to Resin. The location must be an absolute path understandable to the web server.

<caucho.com> <http-server> <error-page exception-type='connection' location='/connection_error.html'/<> </http-server> </caucho.com>

By default, the plugin returns "Can't connect to servlet runner."

Maximum number of request-handling threads.

Defaults to 200.

Number of threads to be used in keepalive requests. When Resin is used in combination with a web server, like Apache or IIS, Resin will reuse the socket connection to that web server if possible. thread-keepalive specifies the number of theads that can be used in these keepalive connections.

Defaults to 100.

Time in seconds for a connection to timeout.

Defaults to 30 sec.

Activates the memory cache with a specified size. Resin's cache acts as a proxy cache. Pages with expires headers will be cached, avoiding expensive Java or Database processing.

To activate caching, you must add a cache directive. By default, caching is disabled.

The cache combines memory and file caching. The most referenced pages are served out of memory and the rest are served from the filesystem.

Attribute	Meaning	Default
dir	File directory to store the cached pages	resin1.2/cache
entries	Number of entries allowed in the memory cache	16386
size	Size in kilobytes of the memory	1024

For example, a page created by several sophisticated and slow database queries may only change every 15 minutes. If that page sets its expires header, Resin can serve the generated page as fast as a static page.

Defines a virtual host. If no hosts are specified, or if a request doesn't match a host, configuration in http-server will be used instead.

See application configuration for servlet configuration.

Hosts can use regexp instead of id to dynamically create new hosts.

Attribute	Meaning	Default
id	The host name	required
regexp	A regular expression matching hosts.	none
app-dir	The root directory of the host (can use replacement vars)	use http-server app-dir

<caucho.com> <http-server> <host id='www.foobar.com' app-dir='foobar/docs'> <web-app id='/'> <servlet-mapping url-pattern='/servlets/*' servlet-name='invoker'/> </web-app> </host> <host regexp='([^.]*).users.com' app-dir='/home/$1/public_html'> ... </host> </http-server> </caucho.com>

Note: Only the Resin Java process understands regexps. Because mod_caucho, isapi_srun and the other web server plugins don't understand the regexps, you may need to do additional work to make the web server send the request to Resin.

By default, match any host.

Specifies the file for error logging. The log is relative to $RESIN_HOME. You can use the special path $app-dir to make the log relative to the host, e.g. $app-dir/WEB-INF/log/access.log.

<caucho.com> <http-server error-log='log/error.log'> <host id='foo.com' error-log='log/foo.log'> ... </host> </http-server> </caucho.com>

By default, a host's error log will use an error-log defined in http-server.

Specifies the access log file. The log is relative to $RESIN_HOME. You can use the special path $app-dir to make the log relative to the host, e.g. $app-dir/WEB-INF/log/access.log.

Attribute	Description	Default
id	The access log path.	required
format	Access log format.	see below
rollover-period	how often to rollover the log. Normally in days (15D), weeks (2W) or months (1M).	none
rollover-size	max size of the log before a rollover.	1 meg

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:

%b	result content length
%h	remote IP addr
%{xxx}i	request header xxx
%{xxx}o	response header xxx
%{xxx}c	cookie value xxx
%r	request URI
%s	status code
%t	request time
%u	remote user

The default format is:

"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

<host id=''> <access-log id='log/access.log'> <rollover-period>2W</rollover-period> </access-log> ... </host>

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

Specifies a list of URLs to test to check the webserver's uptime. Ping adds reliability to a web site. It launches a separate thread to check if a list of URLs return valid results, i.e. HTTP status 200. If the URLs fail after repeated attempts, Resin will exit. The parent process, either wrapper.pl or the NT service, will automatically restart Resin.

Because the ping thread is in the same JVM as the web server, ping cannot detect all failure types. In particular, if the JDK itself freezes, ping can do nothing. It can detect problems like deadlocks or database connection overflows or memory leaks.

The URLs listed in the <ping> should exercise the important operations in the application. For example, it should at least access the database.

Attribute	Meaning	Default
url	URL to test for failure	required
sleep-time	time to sleep between pings.	15 min
retry-count	how many times to retry failures before restarting.	3
retry-time	how long to sleep between failures.	1 sec

<caucho.com> <http-server> <ping> <sleep-time>1m</sleep-time> <retry-count>3</retry-count> <retry-time>1s</retry-time> </ping> ... </http-server> </caucho.com>

No default.

Specifies an application. Applications are self-contained subtrees of the web site. They have distinct Application objects, sessions, and servlet mappings. Applications can even be deployed entirely from .jar files.

The full application configuration is described in a separate page.

Applications have a root app-dir similar to the document root. By default, it's just the same as the relative path.

Beneath the app-dir root, a special directory WEB-INF contains servlet classes and beans. WEB-INF/classes contains Java source files and Java classes. WEB-INF/lib contains additional jar files for the application.

Attribute	Meaning	Default
id	The url prefix of the application.	required
url-regexp	A regular expression matching a url prefix.	none
app-dir	The application's root directory.	The subdirectory of the host's app-dir named by id

<host id='foo.com'> <web-app id='example/tictactoe' app-dir='c:\work\ttt'> <servlet-mapping url-pattern='*.foo' servlet-name='com.caucho.jsp.XtpServlet'/> </web-app> </host>

The url-regexp configuration allows for dynamic applications, for example, creating a new application for each user.

Per-user Servlet Directory

<host> <web-app url-regexp='^/~([^/]+)' app-dir='/home/$1/public_html'> ... </web-app> </host>

In the above example, users will put their own web.xml in /home/user/public_html/WEB-INF/web.xml. Classes belong in public_html/WEB-INF/classes.

Note: Only the Resin Java process understands regexps. Because mod_caucho, isapi_srun and the other web server plugins don't understand the regexps, you may need to do additional work to make the web server send the request to Resin.

Specifies a special .war directory to place .war files. Any .war (web-application resource) file placed in the war directory will be automatically expanded and installed. The .war file will be expanded into war-expand-dir, if specified.

The war-dir is relative to $RESIN_HOME, not to the virtual host's app-dir.

<host id='www.foo.com'> <war-dir>foo-apps</war-dir> </host>

Given the above example, if you put foo.war in resin1.2/foo-apps, Resin will automatically expand it and install it with the prefix /foo. So browsing http://localhost:8080/foo will give the top-level contents.

Generally, war files use WEB-INF/web.xml for configuration. The syntax is the same as for other application configuration.

No war-dir is defined by default.

Specifies the destination of .war expansion. Any .war (web-application resource) file placed in the war-dir directory will be automatically expanded into war-expand-dir. You can also create a web-app by creating a directory in war-expand-dir.

The war-dir is relative to $RESIN_HOME, not to the virtual host's app-dir.

The special directory ROOT lets you define the root web-app.

Generally, war files use WEB-INF/web.xml for configuration. The syntax is the same as for other application configuration.

Defaults to war-dir is defined by default.