HTTP and Srun configuration is identical except for load balancing (
and .)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
configuration in looks like:
<caucho.com> <http-server> <host id=''> <web-app id='/'> <servlet-mapping url-pattern='/test' .../> </web-app> </host> </http-server></caucho.com> |
Most of the interesting configuration belongs in web-app. For example, belongs in a element, but belongs in the top-level element.
The server contains a number of
elements and each contains elements. Each configures a virtual host and each configures an application.
<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> |
access-log | Specifies the access log file |
alternate-session-url-prefix | Configures an alternate URL prefix to be used for /~J=xxx/test |
cache | Activates the memory cache with a specified size |
doc-dir | Specifies the document directory for the <host> or <http-server> |
error-log | Specifies the file for error logging |
error-page | The url to display if the web server can't connect to Resin |
forbid-host | Selects a list of IPs that are forbidden |
global-system-properties | Determines if system-properties are classloader specific or global |
host | Defines a virtual host |
http | Defines a HTTP or SSL port for the standalone server |
http-server | Configuration for the servlet engine |
ignore-client-disconnect | Ignores ClientDisconnectionExceptions thrown when the browser disconnects |
ping | Specifies a list of URLs to test to check the webserver's uptime |
root-dir | Specifies the root directory for the <host> or <http-server> |
server-listener | Specifies the classname for a listener when the server starts and shuts down |
server-name | Defines the canonical url for the host |
servlet-classloader-hack | Enables the Servlet specification classloader hack |
session-cookie | Configures session cookie |
session-url-prefix | Configures the URL prefix to be used for url-rewriting |
srun | Defines multiple client machines for load balancing |
srun-backup | Defines backup client machines for load balancing |
sticky-sessions | Enables or disables sticky-session load balancing |
thread-keepalive | Number of threads to be used in keepalive requests |
thread-max | Maximum number of request-handling threads |
url-character-encoding | Defines the character encoding to be used for decoding the URL |
url-length-max | Specifies the maximum length allowed in a HTTP URL |
war-dir | Specifies a special directory to place war files |
war-expand-dir | Specifies the destination of war expansion |
web-app | Specifies an application |
http-server |
http-server
Configuration for the servlet engine.
Any <resource-ref> resource configured in <http-server> is shared for all virtual hosts and web-apps in the server. So a database or EJB server configured in the <http-server> will be shared for all virtual hosts.
Default application tags like <servlet-mapping> may appear in the <http-server> section. These tags will be defaults for the contained <web-app> and <host>.
alternate-session-url-prefix | Resin 2.0.5 |
Configures an alternate URL prefix to be used for /~J=xxx/test.jsp style url-rewriting. There is no default.
If alternate-session-url-prefix is configured, URL rewriting will 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.
...<http-server> <alternate-session-url-prefix>/~J=</alternate-session-url-prefix> ... |
cache | Resin 1.1 |
Activates the memory cache with a specified size. Resin's cache acts as a proxy cache. Pages with
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 |
enable | true or false to disable | true |
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.
Default: by default, cache is disabled.
error-log
Specifies the file for error logging. The log is relative to $RESIN_HOME. You can use the special path
to make the log relative to the host, e.g. .
<caucho.com><http-server error-log='log/error.log'><host id='foo.com' error-log='log/foo.log'> ...</host></http-server></caucho.com> |
Attribute | Meaning | Default |
---|---|---|
encoding | character encoding | The JVM's default |
href | The log's filename | required |
rollover-period | How often the log should be rotated | never |
rollover-size | How large the log can be before rotating | infinite |
timestamp | Format for a timestamp before each entry | none |
Default: By default, a host's error log will use an error-log defined in http-server.
error-page
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> |
forbid-host | Resin 2.0.3 |
Selects a list of IPs that are forbidden.
<http-server> <forbid-host>192.168.0.1</forbid-host> <forbid-host>192.168.0.2</forbid-host> ...</http-server> |
forbid-host is implemented by com.caucho.http.security.ForbidHost. It is stored in JNDI as java:comp/env/caucho/forbid-host. An intelligent log might detect a denial of service attack and dynamically forbid the host.
ignore-client-disconnect | Resin 1.2.3 |
Ignores ClientDisconnectionExceptions thrown when the browser disconnects.
<caucho.com> <http-server> <ignore-client-disconnect>false</ignore-client-disconnect> ... </http-server></caucho.com> |
False by default, throws exceptions on disconnects.
global-system-properties | Resin 2.0.5 |
Determines if system-properties are classloader specific or global.
By default, Resin's web-apps and hosts have isolated system properties. So System.getProperty("test") in host foo.com might return a different value from System.getProperty("test") in host bar.com. Usually, this is the correct solution to prevents hosts and web-apps from affecting each other. Specialized applications may want to disable this feature however.
...<http-server> <global-system-properties>true</global-system-properties> ...</http-server> |
Default: The default value is false.
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.
The id may contain a list of hosts. Any host in the list will match.
See application configuration for servlet configuration.
Hosts can use
instead of 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 |
Any <resource-ref> resource configured in <http-server> is shared for all virtual hosts and web-apps in the server. So a database or EJB server configured in the <http-server> will be shared for all virtual hosts.
Default application tags like <servlet-mapping> may appear in the <http-server> section. These tags will be defaults for the contained <web-app> and <host>.
<caucho.com><http-server><host id='www.foobar.com, 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.
Default: If the
attribute is null or '*', the <host> will be used as the default configuration for any virtual host that doesn't match a specific <host> block.
http | Resin 1.2 |
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 | JSSE Type of the key store (default jks) | |
key-store-file | JSSE File containing the certificates | |
key-store-password | JSSE Password to read the certificates | |
key-manager-factory | JSSE key manager factory type | |
ssl-context | JSSE ssl context type | |
certificate-file | OpenSSL certificate (Resin 2.0.5) | |
certificate-key-file | OpenSSL key certificate (Resin 2.0.5) | |
certificate-key-password | OpenSSL key password (Resin 2.1.1) | |
crypto-device | OpenSSL engine (Resin 2.0.5) | |
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 |
shutdown-wait-time | How long to wait for connections to finish before exiting. | 10 sec. |
<caucho.com> <http-server> <http port='8080'> ... </http-server></caucho.com> |
<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> |
ping
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 |
class-name | specify a custom ping class (Resin 2.0.3) | com.caucho.http.admin.PingThread |
socket-timeout | how long the socket should wait for a response before timing out. | 10s |
<caucho.com><http-server> <ping> <sleep-time>1m</sleep-time> <retry-count>3</retry-count> <retry-time>1s</retry-time> <url>http://localhost:8080/test.jsp</url> </ping> ...</http-server></caucho.com> |
Custom ping classes must extend com.caucho.http.admin.PingThread. For example, the PingMailer will mail when the PingThread fails.
Attribute | Meaning | Default |
---|---|---|
mail-to | Recipient of the warning mail | required |
mail-from | Sender of the mail | the user of the Resin process |
mail-subject | The subject of the mail | "Resin ping has failed" |
<ping> <class-name>com.caucho.http.admin.PingMailer</class-name> <sleep-time>1m</sleep-time> <retry-count>3</retry-count> <retry-time>1s</retry-time> <url>http://localhost:8080/test.jsp</url> <mail-to>webmaster@localhost</mail-to></ping> |
No default.
srun | Resin 1.1 |
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
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. | 10 sec |
dead-time | How long before checking that a srun has come back up. | 5 sec |
timeout | How long the load balancing server should wait for a response. | 30 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 |
shutdown-wait-time | How long to wait for connections to finish before exiting. | 10 sec. |
<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> Resin 2.1.0srun listening to host1.caucho.com:6802 |
On Unix, when starting a daemon, you'll need to specify a unique pid file.
unix> |
srun-backup | Resin 1.1 |
Defines backup client machines for load balancing. This directive is only picked up by the load balancer. The Java portion of Resin treats a <srun-backup> like any other srun. Normally, <srun-backup> is only used when each web server has a primary <srun> in preference to other <srun> JVMs. See the load-balancing section for more information.
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. |
shutdown-wait-time | How long to wait for connections to finish before exiting. | 10 sec. |
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.
specifies the number of theads that can be used in these keepalive connections.Defaults to 100.
thread-max
Maximum number of request-handling threads.
Defaults to 200.
host |
access-log
Specifies the access log file. The log is relative to $RESIN_HOME. You can use the special path
to make the log relative to the host, e.g. .
Attribute | Description | Default |
---|---|---|
id | The access log path. | required |
format | Access log format. | see below |
class-name | Class implementing AbstractAccessLog for custom logging. | |
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. | 10 meg |
archive-format | format the name of the archive file. | n/a |
The
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 |
%{ | }irequest header |
%{ | }oresponse header |
%{ | }ccookie value |
%n | request attribute |
%r | request URL |
%s | status code |
%{ | }trequest date with optional time format string. |
%T | time of request in seconds |
%u | remote user |
%U | request URI |
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.
doc-dir | Resin 2.1 |
Specifies the document directory for the <host> or <http-server>.
<doc-dir> values may use use system properties, like
or or even .
<host id=''> <doc-dir>/opt/web/default_host</doc-dir> ...</host> |
Default: Defaults to <root-dir> if specified. Otherwise <host> defaults to the document directory of the <http-server> <http-server> defaults to the server-root.
root-dir | Resin 2.1 |
Specifies the root directory for the <host> or <http-server>. Non-document data like log files and war directories are based off the root directory.
<root-dir> values may use use system properties, like
or or even .
<host id=''> <root-dir>/opt/web/default_host</root-dir> <doc-dir>doc</doc-dir> ...</host> |
Default: Hosts defaults to the <root-dir> of the <http-server>. <http-server> defaults to the server-root.
session-cookie | Resin 2.1.2 |
Configures session cookie. The default is "JSESSIONID".
session-url-prefix | Resin 2.0 |
Configures the URL prefix to be used for url-rewriting. The default is ";jsessionid=".
server-name | Resin 2.0.4 |
Defines the canonical url for the host. In some cases, the specific URL that's used for a virtual host might be different from the <host id='...'> name. <server-name> lets you specify the exact URL to be added when using a sendRedirect.
...<host id='foo.com'> <server-name>http://foo.com</server-name> ...</host>... |
server-listener | Resin 2.0.3 |
Specifies the classname for a listener when the server starts and shuts down. The class must be in the system classpath because it's called before the dynamic classpaths have been created and after they've been destroyed.
The server listener class must extend com.caucho.http.admin.AbstractServerListener.
<http-server> <server-listener> <class-name>test.MyListener</class-name> </server-listener> ... |
servlet-classloader-hack | Resin 2.0.3 |
Enables the Servlet specification classloader hack. The Servlet 2.3 classloader order violates the JDK classloader specification. By default, therefore, Resin follows the JDK requirements. Those application which need to violate the JDK spec may enable the servlet-classloader-hack.
By default, the hack is disabled.
sticky-sessions | Resin 2.0 |
Enables or disables sticky-session load balancing.
The default is true to enable sticky sessions.
url-character-encoding
Defines the character encoding to be used for decoding the URL. Because the HTTP protocol does not specify the encoding to be used, the server must specify the encoding beforehand.
Default: utf-8
url-length-max
Specifies the maximum length allowed in a HTTP URL. Requests with longer lengths will receive an error.
Default: 8192
war-dir
Specifies a special 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
, 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
. So browsing will give the top-level contents.Generally, war files use
for configuration. The syntax is the same as for other application configuration.No war-dir is defined by default.
war-expand-dir | Resin 1.2.3 |
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
lets you define the root web-app.Generally, war files use
for configuration. The syntax is the same as for other application configuration.Default: Defaults to the value of <war-dir>.
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
similar to the document root. By default, it's just the same as the relative path.Beneath the
root, a special directory contains servlet classes and beans. contains Java source files and Java classes. 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 |
<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
configuration allows for dynamic applications, for example, creating a new application for each user.
<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
. Classes belong in .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.
Trackback: http://tb.blog.csdn.net/TrackBack.aspx?PostId=1555396