Describes the resin, server, host, and port configuration in the resin.conf.
- See the index for a list of all the tags.
- See Web Application configuration for web.xml (Servlet) configuration.
- See Environment configuration for resources: classloader, databases, connectors, and resources.
- See Log configuration for access log configuration, java.util.logging, and stdout/stderr logging.
child of: server, host
Specifies the access log file.
Attribute | Meaning | default |
path | The access log path. | required
|
format | Access log format. | see below
|
resin:type | 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 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
|
%n | request attribute
|
%r | request URL
|
%s | status code
|
%{xxx}t | request 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\""
|
<server>
<access-log id='log/access.log'>
<rollover-period>2W</rollover-period>
</access-log>
...
</server>
|
If the web-app doesn't specify an access-log, it will use the host's
access-log.
child of: server
Configures Resin's internal HTTP proxy cache.
Resin's cache can dramatically improve performance by avoiding re-evaluation
of slowly changing database-backed changes. We strongly
recommend using the proxy caching when possible for a simple,
standards-based performance boost.
Using the proxy cache is described more fully
in the caching documentation.
Attribute | Meaning | default |
path | filesystem location of the cache | required
|
enable | enables/disables the cache | true
|
entries | max number of entries allowed in the cache | 1024
|
memory-size | max size of the cache saved in memory | 1M
|
disk-size | max size of the cache saved on disk | 64M
|
child of: server
Defines the cluster of Resin JVMs used for load-balancing and for
sharing distributed sessions.
<cluster>
<client-live-time>30s</client-live-time>
<srun id="a" host="192.168.0.1" port="6802" index="1"/>
<srun id="b" host="192.168.0.2" port="6802" index="2"/>
</cluster>
|
Attribute | Meaning | default |
client-live-time | How long to keep an idle socket open | 30s
|
client-dead-time | How long to treat a server as dead | 15s
|
client-read-timeout | Timeout for client reads | 60s
|
client-write-timeout | Timeout for client writes | 60s
|
document-directory | Resin 3.0 |
child of: web-app
Configures the directory where web pages will be placed when
using webserver-style deployment instead of war-based deployment.
child of: resin
Configures the Unix setuid group name used after Resin binds the
reserved ports as root.
Note, Linux requires the new thread package (e.g. RedHat 9.0 or
later) to support group-name.
child of: server
Configures a virtual host. Virtual hosts must be
configured explicitly.
Attribute | Meaning | default |
id | primary host name | none
|
regexp | Regular expression based host matching | none
|
host-name | Canonical host name | none
|
host-alias | Aliases matching the same host | none
|
secure-host-name | Host to use for a redirect to SSL | none
|
root-directory | Root directory for host files | parent directory
|
startup-mode | `automatic', `lazy', or `manual', see Startup and Redeploy Mode | automatic
|
explicit host
<host host-name="www.foo.com">
<host-alias>foo.com</host-alias>
<host-alias>web.foo.com</host-alias>
<root-directory>/opt/www/www.foo.com</root-directory>
...
</host>
|
regexp host
<host regexp="([^.]+)\.foo\.com">
<host-name>${host.regexp[1]}.foo.com</host-name>
<root-directory>/opt/www/www.${host.regexp[1]}.com</root-directory>
...
</host>
|
It is recommended that any <host> using a regexp include
a <host-name> to set the canonical name for the host.
child of: server, host-deploy
Defaults for a virtual host.
The host-default can contain any of the host configuration tags.
It will be used as defaults for any virtual host.
child of: server
Configures a deploy directory for virtual host.
The host-deploy will add an EL variable ${name}, referring to
the name of the host jar file.
Attribute | Meaning | default |
path | path to the deploy directory | required
|
expand-path | path to the expansion directory | path
|
host-default | defaults for the expanded host&td>
|
host-name | the host name to match | ${name}
|
child of: server
Configures a HTTP port listening for HTTP requests.
When configuring multiple JVMs, each <http> will have a
unique <server-id> which allows the -server command-line to select
which ports the server should listen to.
Attribute | Meaning | default |
server-id | server id matching the -server command line | none
|
host | hostname of the interface to listen to | *
|
port | port to listen to | required
|
tcp-no-delay | sets the NO_DELAY socket parameter | true
|
read-timeout | timeout waiting to read from idle client | 65s
|
write-timeout | timeout waiting to write to idle client | 65s
|
socket-listen-backlog | The socket factory's listen backlog for receiving sockets | 100
|
virtual-host | forces all requests to this <http> to use the named virtual host | none
|
openssl | configures the port to use OpenSSL | none
|
jsse-ssl | configures the port to use JSSE for SSL | none
|
child of: resin default: 1M
For reliability, Resin periodically checks the amount of free
memory available. When the free memory drops below
<min-free-memory>, even after garbage collection, Resin will force
a JVM restart.
In general, application developers should use a heap profiler
to eliminate memory leaks and OutOfMemoryErrors. Because an
OutOfMemoryError can cause severe problems with the application, Resin
detects the low memory before those errors can be thrown.
child of: http, srun, port
Configures SSL.
Attribute | Meaning | default |
certificate-file | the file containing the server's certificate | required
|
certificate-key-file | the file containing the server's certificate key, if separate from certificate-file | certificate-file
|
password | the certificate key password | required
|
certificate-chain-file | A file containing an intermediate (untrusted) and root (trusted) certificate. See Certificate Chains . | none
|
session-cache | true or false, enables the SSL session cache | true
|
session-cache-timeout | sets the SSL session cache timeout in seconds | 300
|
verify-client | Verify the client, value is one of `require' (the client has to present a valid certificate), `optional' (the client may present a valid certificate), `optional-no-ca' (the client may present a certificate, it may be unverifiable) | no client verification
|
verify-depth | the maximum number of intermediate signers to accept when verifying client certificates | -1
|
ca-certificate-file | a file containing a concatenated list of PEM-encoded certificates recognized for client authentication | none
|
ca-revocation-file | a file containing a concatenated list of PEM-encoded certificates which have been revoked and are no longer valid | none
|
protocol | a combination of +all, -all, +sslv2, -sslv2, +sslv3, -sslv3, +tlsv1, -tlsv1 | +all
|
cipher-suite | |
|
More documentation is available in the Security
section.
The mod_ssl documentation
for Apache is a good source of information on OpenSSL.
The class that corresponds to <openssl> is
class com.caucho.vfs.OpenSSLFactory .
persistent-store | Resin 3.0.8 |
child of: server
Defines the cluster-aware persistent store used for
sharing distributed sessions. The allowed types are "jdbc", "cluster"
and "file". The "file" type is only recommended in single-server
configurations.
The <persistent-store> configuration is in the <server> level
because it needs to share update information across the
active cluster and the <cluster> definition is at the <server> level.
Sessions activate the persistent store with the <use-persistent-store>
tag of the <session-config>.
See Persistent sessions for more details.
<server>
<cluster>
<srun id="a" host="192.168.0.1" port="6802" index="1"/>
<srun id="b" host="192.168.0.2" port="6802" index="2"/>
</cluster>
<persistent-store type="jdbc">
<init>
<data-source>jdbc/session</data-source>
<max-idle-time>24h</max-idle-time>
</init>
</persistent-store>
<web-app-default>
<session-config use-persistent-store="true"/>
</web-app-default>
</server>
|
common tags
Attribute | Meaning | default |
max-idle-time | How long idle objects are stored | 24h
|
always-load | Always load the value | false
|
always-save | Always save the value | false
|
jdbc tags
Attribute | Meaning | default |
data-source | The JDBC data source | required
|
table-name | Database table | persistent_session
|
blob-type | Schema type to store values | from JDBC meta info
|
cluster tags
Attribute | Meaning | default |
path | Directory to store the sessions | required
|
file tags
Attribute | Meaning | default |
path | Directory to store the sessions | required
|
child of: server
Starts a thread that periodically makes a request to the server, and
restarts Resin if it fails. This facility is used to increase server
reliability - if there is a problem with the server (perhaps from a deadlock or
an exhaustion of resources), the server is restarted.
A failure occurs if a request to the url returns an HTTP status that is
not 200.
Since the local process is restarted, it does not make sense to specify a
url that does not get serviced by the instance of Resin that has the ping
configuration. Most configurations use url's that specify `localhost' as
the host.
This pinging only catches some problems because it's running in the
same process as Resin itself. If the entire JDK freezes, this
thread will freeze as well. Assuming the JDK doesn't freeze, the
PingThread will catch errors like deadlocks.
resin.conf - simple usage of server ping
<resin xmlns="http://caucho.com/ns/resin"
xmlns:resin="http://caucho.com/ns/resin/core">
...
<server>
<ping url="http://localhost/"/>
...
</server>
</resin>
|
resin.conf - configured usage of server ping
<resin xmlns="http://caucho.com/ns/resin"
xmlns:resin="http://caucho.com/ns/resin/core">
...
<server>
<ping>
<url>http://localhost:8080/index.jsp</url>
<url>http://localhost:8080/webapp/index.jsp</url>
<url>http://virtualhost/index.jsp</url>
<url>http://localhost:443/index.jsp</url>
<sleep-time>5m</sleep-time>
<try-count>5</try-count>
<!-- a very busy server -->
<socket-timeout>30s</socket-timeout>
</ping>
...
</server>
</resin>
|
Attribute | Meaning | default |
url | A url to ping. | required
|
sleep-time | Time to wait between pings. The first ping is always 15m after the server starts, this is for subsequent pings. | 15m
|
try-count | If a ping fails, number of times to retry before giving up and restarting | required
|
retry-time | time between retries | 1s
|
socket-timeout | time to wait for server to satrt responding to the tcp connection before giving up | 10s
|
The class that corresponds to <ping> is
class com.caucho.server.admin.PingThread .
A refinement of the ping facility sends an email when the server is
restarted.
resin.conf - mail notification when ping fails
<resin xmlns="http://caucho.com/ns/resin"
xmlns:resin="http://caucho.com/ns/resin/core">
...
<server>
<ping resin:type="com.caucho.server.admin.PingMailer">
<url>http://localhost:8080/index.jsp</url>
<url>http://localhost:8080/webapp/index.jsp</url>
<mail-to>fred@hogwarts.com</mail-to>
<mail-from>resin@hogwarts.com</mail-from>
<mail-subject>Resin ping has failed for server ${server.name}</mail-subject>
</ping>
...
</server>
</resin>
|
Top-level configuration for the resin.conf file. The <resin>
tag needs to specify the Resin namespace, to allow for validation
of the configuration file.
The environment of the top-level <resin> is the global classpath.
This environment can be important for <log> configuration
for threads which run with using only the global class loader.
Because the <resin> environment does not have a dynamic class loader,
dynamically loaded classes, like custom jars
in resin/lib are not available.
resin
<resin xmlns="http://caucho.com/ns/resin">
<server>
<http id='' host='*' port='8080'/>
<resin:import path="app-default.xml"/>
<host id=""/>
<web-app id="/"/>
</host>
</server>
</resin>
|
EL variables defined by <resin>
variable | corresponding API |
|
resin-home | CauchoSystem.getResinHome() |
|
server-root | CauchoSystem.getServerRoot() |
|
The class that corresponds to this tag is class com.caucho.server.resin.ResinServer
child of: server, host
Specifies the root directory for the <server> and <host>
contexts. All EL-style directory paths are relative to
the root-directory.
security-manager
Enable the use of the security manager for the JVM.
<resin xmlns="http://caucho.com/ns/resin"
xmlns:resin="http://caucho.com/ns/resin/core">
...
<security-manager/>
...
|
See also:
security-provider
Add one or more security providers. Each entry specifies the name of a
security provider class. The name is used to instantiate an instance of the
object, which is then passed to
method Security.addProvider .
<resin xmlns="http://caucho.com/ns/resin"
xmlns:resin="http://caucho.com/ns/resin/core">
...
<security-provider>com.sun.net.ssl.internal.ssl.Provider</security-provider>
<security-provider>example.MyProvider</security-provider>
...
|
child of: resin
Main configuration for the server, configuring ports,
threads and virtual hosts.
- Common resources for all virtual hosts and web-apps.
- Thread pooling
- HTTP and SRUN/Cluster ports
- Caching
- virtual host configuration and common web-app-default
The <server> will generally contain a <class-loader> configuration
which loads the resin/lib jars dynamically, allowing for system-wide jars
to be dropped into resin/lib. <server> configures
the main dynamic environment. Database pools common to all virtual hosts,
for example, should be configured in the <server> block.
The <server> configures the <thread-pool> and a set
of <http> and <srun> ports which share the thread pool.
Requests received on those ports will use worker threads from the
thread pool.
Attribute | Meaning | default |
alternate-session-url-prefix
| a prefix to 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.
| null
|
keepalive-max
| the maximum number of keepalive connections
| 512
|
keepalive-timeout
| the maximum time a connection is maintained in the keepalive state
| 120s
|
alternate-session-url-prefix
<server>
...
<alternate-session-url-prefix>/~J=</alternate-session-url-prefix>
...
|
The class that corresponds to <server> is class com.caucho.server.resin.ServletServer
EL variables defined by <server>
variable | corresponding API
|
serverId | server.getServerId()
|
root-dir | server.getRootDirectory()
|
server-root | server.getRootDirectory()
|
child of: cluster
Configures a clustered HMUX listener.
When configuring Resin in a load-balanced cluster, each Resin instance
will have its own <srun> configuration, which Resin uses for distributed
session management and for the load balancing itself.
When configuring multiple JVMs, each <srun> will have a
unique <server-id> which allows the -server command-line to select
which ports the server should listen to.
Attribute | Meaning | default |
backup | If true, the server is generally used as a backup | false
|
host | hostname of the interface to listen to | *
|
index | Session index of the srun | required
|
jsse-ssl | configures the port to use JSSE for SSL | none
|
openssl | configures the port to use OpenSSL | none
|
port | port to listen to | required
|
protocol | configures the Srun protocol | hmux
|
read-timeout | timeout waiting to read from idle client | 65s
|
write-timeout | timeout waiting to write to idle client | 65s
|
server-id | server id matching the -server command line | none
|
socket-listen-backlog | The socket factory's listen backlog for receiving sockets | 100
|
tcp-no-delay | sets the NO_DELAY socket parameter | true
|
The class that corresponds to <srun> is class com.caucho.server.cluster.ClusterPort
child of: server
Configures the thread pool shared among all ports.
Attribute | Meaning | default |
thread-max | maximum number of working threads | 200
|
spare-thread-min | minimum number of spare working threads | 5
|
<thread-max> is the absolute maximum number of connection worker
threads allowed. <thread-max> may be limited by OS/JVM
restrictions, especially the stack size. -Xss and/or ulimit -s may be
required for large numbers of threads, e.g. "ulimit -s 2048" on some
versions of Linux would allow for 1024 total threads in the JVM.
<spare-thread-min> configures Resin's
adaptive thread pooling. Resin tries to keep <spare-thead-min>
idle threads available at all time. Sites
with large spikes in connection loads may need to increase the
<spare-thread-min> value.
child of: resin
Configures the Unix setuid user name used after Resin binds the
reserved ports as root.
Note, Linux requires the new thread package (e.g. RedHat 9.0 or
later) to support user-name.
There are some conventions for tag names that provide similar functionality.
<fileset> provides the ability to match a set of files. It is
modelled after the ant tag by the same name.
Attribute | Meaning | default |
dir | the starting directory | required
|
include | an include pattern | do not include all files
|
exclude | an exclude pattern | do not exclude any files
|
A pattern can contain two special characters: '*' and '**'. '*' matches any
part of path, but does not match the path separator. '**' matches any part of
a path, including the path separator.
<fileset dir="lib">
<include name="*.jar"/>
</fileset>
MATCH lib/foo.jar
MATCH lib/bar.jar
NO MATCH lib/baz/foo.jar
|
<fileset dir="lib">
<include name="**/*.jar"/>
</fileset>
MATCH lib/foo.jar
MATCH lib/bar.jar
MATCH lib/baz/foo.jar
|
The class that corresponds to <fileset> is
class com.caucho.config.types.FileSetType .
The class that corresponds to the <include> and <exclude> patterns
is class com.caucho.config.types.PathPatternType
The <startup-mode> is used in a number of places to
determine the behaviour of a resource when the server starts.
The startup-mode has three values: "automatic", "lazy", and "manual".
- automatic - starts the resource on server start (default)
- lazy - starts the resource on the first use
- manual - waits for JMX to start the resource.
The <redeploy-mode> is used in a number of places to
determine the behaviour of a resource when it is replaced or modified while the
server is running.
The redeploy-mode has two values: "automatic", and "manual".
- automatic - restarts the resource when it is modified (web.xml, *.class, *.war, etc).
- manual - waits for JMX to restart the resource when changes occur.
Copyright © 1998-2005 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark,
and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc. | |
|