caucho
Resin 1.1
FAQ
Reference
JavaDoc
Demo
Java Tutorial

Getting Started
Configuration
Servlet
JSP
XTP/XSL
JavaScript
JS Library

Resin Config
HTTP Config
App Config
Servlet Config
Login Config
Taglib Config
Virtual Hosts
Caching
 HTTP/Srun Configuration

HTTP and Srun configuration is identical except for load balancing (srun-host and srun-backup.)

HTTP configuration follows the Servlet 2.2 deployment descriptors. The nesting depth is important, but order is generally not important. In the sections that follow, the section header tells where the attribute belongs. For example, the servlet-mapping configuration in caucho.com/http-server/host/web-app looks like:

<caucho.com>
  <http-server>
    <host id=''>
      <web-app id='/'>
        <servlet-mapping url-pattern='/test' .../>
      </web-app>
    </host>
  </http-server>
</caucho.com>

Because most sites only have a single host and a single web-app, that example can be shortened. The resin1.1/conf/samples/deploy.conf sample is a good starting point. The following is more typical for most sites:

<caucho.com>
  <http-server>
    <servlet-mapping url-pattern='/test' .../>
  </http-server>
</caucho.com>

Most of the interesting configuration belongs in web-app. For example, servlet-mapping belongs in a web-app element, but thread-max belongs in the top-level http-server element.

The server contains a number of host elements and each host contains web-app elements. Each host configures a virtual host and each web-app configures an application.

Simple configurations can omit the host and web-app tags. If you omit the host and web-app, the configuration belongs to the default host and default application. A simple configuration can ignore host and web-app and just put all the web-app configuration in the http-server element.

Full Configuration
<caucho.com>
<http-server>
  <host id='gryffindor.caucho.com' app-dir='gryffindor'>
    <web-app id='/'>
      <servlet-mapping .../>
      ...
    </web-app>
    
    <web-app id='/test' app-dir='/usr/local/test'>
      ...
    </web-app>
  </host>
  
  <host id='slytherin.caucho.com' app-dir='slytherin'>
    ...
  </host>

  ...
</http-server>
</caucho.com>
Simple Configuration
<caucho.com>
<http-server app-dir='/usr/local/web'>
  <servlet-mapping .../>
  ...
</http-server>
</caucho.com>

caucho.com/http-server
http-server Configuration for both HTTP and srun.
httpd-host Sets the interface the HTTP server should listen to.
httpd-port Sets the TCP/IP port the HTTP server should listen to.
srun-host Sets the Servlet Runner TCP/IP interface.
srun-port Sets the Servlet Runner TCP/IP port.
srun Defines multiple client machines for load balancing.
srun-backup Defines backup client machines for load balancing.
user-name Sets Unix user.
group-name Sets Unix group.
error-page The url to display if the web server can't connect to Resin.
thread-min Minimum number of request-handling threads.
thread-max Maximum number of request-handling threads.
thread-keepalive Number of threads to be used in keepalive requests.
request-timeout Time in seconds for the server to reclaim an idle thread.
timeout-interval Time in seconds for the server check timeouts, including session timeouts.
cache Activates the memory cache with a specified size.
host Defines a virtual host.

caucho.com/http-server/host
error-log Specifies the file for error logging.
access-log Specifies the access log file.
web-app Specifies an application.

caucho.com/http-server

http-server

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

httpd-host The interface the HTTP server should listen to
httpd-port The interface the HTTP server should listen to
srun-host The interface the srun server should listen to
srun-port The port the srun server should listen to
srun Configuration for load balancing (used by Apache/IIS plugin)
srun-backup Configuration for backup servers (used by Apache/IIS plugin)
error-page Error page for the Apache/IIS plugin to display when it can't connect to srun.
caucho-status Enable the /caucho-status special URL.
user-name For unix, the user to run as once root binds to 80.
group-name For unix, the group to run as once root binds to 80.
thread-min Minimum number of live threads
thread-max Maximum number of live threads
thread-keepalive Number of keepalive threads
request-timeout Max time for a request, after this the request will be interrupted.
cache Create a server cache to improve performance
host Virtual host configuration
web-app Servlet configuration

httpd-host

Sets the interface the HTTP server should listen to. Useful primarily for multihomed hosts.

The following example will only accept connections from the localhost interface.

<caucho.com>
  <http-server httpd-host=localhost httpd-port=8000/>
</caucho.com>

httpd-port

Sets the TCP/IP port the HTTP server should listen to.

<caucho.com>
  <http-server httpd-port=8000/>
</caucho.com>

srun-host

Sets the Servlet Runner TCP/IP interface.

<caucho.com>
  <http-server srun-host=localhost srun-port=8001/>
</caucho.com>

srun-port

Sets the Servlet Runner TCP/IP port.

The Caucho Servlet Engine listens to srun-port, waiting for requests from the web server.

<caucho.com>
  <http-server srun-port=8001/>
</caucho.com>

srun

Resin 1.1

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

Each srun directive adds a new client to receive load balanced requests.

host The host name of the client srun
port The port name of the client srun
Load balance over three machines
<caucho.com>
  <http-server>
    <srun host='host1.caucho.com' port='6802'>
    <srun host='host2.caucho.com' port='6802'>
    <srun host='host2.caucho.com' port='6803'>
  </http-server>
</caucho.com>

srun-backup

Resin 1.1

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.

host The host name of the client srun
port The port name of the client srun

user-name

Sets Unix user. To listen to port 80, Unix systems require Resin to start as root. user-name lets the server change to a safer user after listening to port 80.

<caucho.com>
  <http-server httpd-port=80 user-name='httpd' group-name='daemon'/>
</caucho.com>

group-name

Sets Unix group. To listen to port 80, Unix systems require Resin to start as root. group-name lets the server change to a safer user after listening to port 80.

<caucho.com>
  <http-server httpd-port=80 user-name='httpd' group-name='daemon'/>
</caucho.com>

error-page

The url to display if the web server can't connect to Resin.

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>

thread-min

Minimum number of request-handling threads.

thread-max

Maximum number of request-handling threads.

thread-keepalive

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.

request-timeout

Time in seconds for the server to reclaim an idle thread. By default, Resin does not kill threads. Setting request-timeout will interrupt a thread frozen for longer than the given number of seconds.

Some care should be taken when using request-timeout because some libraries, like some database drivers, do not properly handle interrupts.

timeout-interval

Time in seconds for the server check timeouts, including session timeouts.

<caucho.com>
<http-server thread-min=5
             thread-max=10
             request-timeout=120
             timeout-interval=15>

  ...

</http-server>
</caucho.com>

cache

Resin 1.1

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.

dir File directory to store the cached pages
entries Number of entries allowed in the memory cache
size Size in kilobytes of the memory

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.

host

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.

id The host name
regexp A regular expression matching hosts.
app-dir The root directory of the hose (can use replacement vars)

<caucho.com>
<http-server>

<host id='www.foobar.com'
      app-dir='foobar/docs'>
  <servlet-mapping url-pattern='/servlets/*'
                   servlet-name='invoker'/> 
</host>

<host regexp='([^.]*).users.com'
      app-dir='/home/$1/public_html'>
  ...
</host>


</http-server>
</caucho.com>

caucho.com/http-server/host

error-log

Specifies the file for error logging.

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

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

</http-server>
</caucho.com>

access-log

Specifies the access log file.

<caucho.com>
<http-server access-log='log/access.log'>

 ...

</http-server>
</caucho.com>

web-app

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.

id The url prefix of the application
url-regexp A regular expression matching a url prefix.
app-dir The application's root directory

<caucho.com>
<http-server>

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

</http-server>
</caucho.com>

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

<caucho.com>
<http-server>

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

</http-server>
</caucho.com>

Resin Config   App Config
Copyright © 1998-2000 Caucho Technology. All rights reserved.
Last modified: Fri, 24 Mar 2000 13:44:13 -0800 (PST)