While this case is rare, it may sometimes be useful to create your own Resin custom authenticator (for example to use a legacy resource as an authentication store). The Resin security framework provides an abtract base class (com.caucho.security.AbstractAuthenticator) that you can extend to do this.

The following is a simple example that you can use a starting point for your application:

<accept-listen-backlog> configures operating system TCP listen queue size for the port.

When a browser connects to a server, the server's operating system handles the TCP initialization before handing the socket to the server's application. The operating system will hold the opened connections in a small queue, until the application is ready to receive them. When the queue fills up, the operating system will start refusing new connections.

<accept-thread-max> configures the maximum number of threads listening for new connections on this port. <accept-thread-max> works with <accept-thread-min> to handle spiky loads without creating and destroying too many threads.

Socket connections are associated with a thread which handles the request. In Resin, a number of threads wait to accept a new connection and then handle the request. <accept-thread-max> specifies the maximum number of threads which are waiting for a new connection.

Larger values handle spiky loads better but require more threads to wait for the connections. Smaller values use less threads, but may be slower handling spikes.

<accept-thread-min> configures the minimum number of threads listening for new connections on this port <accept-thread-min> works with <accept-thread-max> to handle spiky loads without creating and destroying too many threads.

Socket connections are associated with a thread which handles the request. In Resin, a number of threads wait to accept a new connection and then handle the request. <accept-thread-min> specifies the minimum number of threads which are waiting for a new connection. If many connections appear rapidly with a small value of <accept-thread-min>, the application may pause until a new thread is available for the new connection.

Larger values handle spiky loads better but require more threads to wait for the connections. Smaller values use less threads, but may be slower handling spikes.

<access-log> configures the access log file.

As a child of web-app, overrides the definition in the host that the web-app is deployed in. As a child of host, overrides the definition in the server that the host is in.

The default archive format is

path + ".%Y%m%d" or
  path + ".%Y%m%d.%H" if rollover-period < 1 day.

The access log formatting variables follow the Apache variables:

The default format is:

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

resin:type allows for custom logging. Applications can extend a custom class from com.caucho.http.log.AccessLog. Resin-IoC initialization can be used to set bean parameters in the custom class.

<active-wait-time> sets a 503 busy timeout for requests trying to access a restarting web-app. If the timeout expires before the web-app complete initialization, the request will return a 503 Busy HTTP response.

The server <address> defines the IP interface for Resin cluster communication and load balancing. It will be an internal IP address like 192.168.* for a clustered configuration or 127.* for a single-server configuration. No wild cards are allowed because the other cluster servers and load balancer use the address to connect to the server.

The <allow-forward-after-flush> flag configures whether IllegalStateExcdeption is thrown when using forward() method after response has been committed. Flag configures behavior of servlet and jsp.

The <allow-servlet-el> flag configures whether <servlet> tags allow EL expressions in the init-param.

<archive-path> configures the location of the web-app's .war file. In some configurations, the .war expansion might not use the webapps/ directory, but will still want automatic war expantion.

Requires that authenticated users fill the specified role. In Resin's JdbcAuthenticator, normal users are in the "user" role. Think of a role as a group of users.

The roles are defined by the authenticators (see Resin security). When using Resin's <resin:AdminAuthenticator> as a default, the role name is resin-admin. (See Resin management.)

The <authenticator> tag as been replaced by CDI-style authenticator configuration. It exists only for backward compatibility. To upgrade, see the authenticator-specific tags like resin:XmlAuthenticator.

The new name will be the old class="..." name. So class="com.caucho.security.XmlAuthenticator" becomes <resin:XmlAuthenticator>.

The <bean> tag as been replaced by CDI-style configuration. It exists only for backward compatibility.

The new tag name will be the old class="..." name and the XML prefix will be the package. So class="com.mycom.FooBean" becomes <mycom:FooBean xmlns:mycom="urn:com.mycom">.

<cache> configures the proxy cache (requires Resin Professional). The proxy cache improves performance by caching the output of servlets, jsp and php pages. For database-heavy pages, this caching can improve performance and reduce database load by several orders of magnitude.

The proxy cache uses a combination of a memory cache and a disk-based cache to save large amounts of data with little overhead.

Management of the proxy cache uses the ProxyCacheMXBean.

<cache-mapping> specifies max-age and Expires times for cacheable pages.

See caching for more information.

<cache-mapping> is intended to provide Expires times for pages that have ETags or Last-Modified specified, but do not wish to hard-code the max-age timeout in the servlet. For example, Resin's FileServlet relies on cache-mapping to set the expires times for static pages. Using cache-mapping lets cacheable pages be configured in a standard manner.

<cache-mapping> does not automatically make pages cacheable. Your servlets must already set the ETag (or Last-Modified) header to activate <cache-mapping>.

• cache-mapping requires an enabled <cache>. If the cache is disabled, cache-mapping will be ignored.
• cache-mapping does not automatically make a page cacheable. Only cacheable pages are affected by cache-mapping, i.e. pages with an ETag or Last-Modified.

The time intervals default to seconds, but will allow other time intervals.

<case-insensitive> specifies whether the environment context is case sensitive or insensitive.

Because some operating systems are case-insensitive, it is important for security reasons for Resin to behave differently for case-sensitive and case-insensitive directories. For example, when case-insensitive is true, url-patterns will match in a case-insensitive manner, so TEST.JSP will work like test.jsp.

<character-encoding> specifies the default character encoding for the environment.

<class-loader> configures a dynamic classloader for the current environment.

Each environment (<cluster>, <host>, <web-app>) etc, can add dynamic classloaders. The environment will inherit the parent classloaders. Each <class-loader> is comprised of several implementing loader items: library-loader for WEB-INF/lib, compiling-loader for WEB-INF/classes.

For web-apps, the classloaders generally belong in a <prologue> section, which ensures that Resin evaluates them first. The evaluation order is particularly important in cases like resin-web.xml vs web.xml, because the resin-web.xml is evaluated after the web.xml.

<close-dangling-connections> closes open connections at the end of a request and logs a warning and stack trace.

<cluster> configures a set of identically-configured servers. The cluster typically configures a set of <server>s, each with some ports, and a set of virtual <host>s.

Only one <cluster> is active in any on server. At runtime, the <cluster> is selected by the <server> with id matching the -server on the command line.

<cluster-default> defines default cluster configuration for all clusters in the <resin> server.

<compiling-loader> automatically compiles Java code into .class files before loading them.

Initialize all java.sql.Connection objects managed by database.

<connection-error-page> specifies an error page to be used by IIS when it can't contact an app-tier Resin. This directive only applies to IIS.

<connection-wait-time> configures the time a getConnection call should wait when then pool is full before trying to create an overflow connection.

Defines a custom constraint. Applications can define their own security constraints to handle custom authentication requirements.

Initializes application (ServletContext) variables. context-param defines initial values for application.getInitParameter("foo"). See also ServletContext.getInitParameter().

The <cookie-http-only> flag configures the Http-Only attribute for all Cookies generated from the web-app. The Http-Only attribute can add security to a website by not forwarding HTTP cookies to SSL HTTPS requests.

A time syntax used in a number of tags. Originally used in the Unix cron program. The wikipedia cron entry contains this descriptive chart:

# +---------------- minute (0 - 59)
# |  +------------- hour (0 - 23)
# |  |  +---------- day of month (1 - 31)
# |  |  |  +------- month (1 - 12)
# |  |  |  |  +---- day of week (0 - 6) (Sunday=0 or 7)
# |  |  |  |  |
  *  *  *  *  *

<development-mode-error-page> enables browser error reporting with extra information. Because it can expose internal data, it is not generally recommended in production systems. (The information is generally copied to the log.

<database> defines a database (i.e. DataSource) resource.

The database configuration section has more details on the configuration.

<database-default> defines default database values to be used for any <database> definition, or runtime database creation (see DatabaseManager).

<dependency> adds dependent files which should force a reload when changed, like web.xml and resin-web.xml.

<dependency-check-interval> Configures how often the environment context should be checked for changes. The default value is set low for development purposes, deployments should use something larger like 5m or 1h.

Resin automatically checks each environment for updates, generally class or configuration updates. Because these checks can take a considerable amount of time, deployment servers should use high values like 60s or more while development machines will want low values like 2s.

The interval defaults to the parent's interval. So the web-app will default to the host's value.

<driver> configures a database driver for a connection pool. The individual driver information is available from the driver vendor or on the Caucho Wiki.

The content of the driver tag configures bean properties of the driver class, e.g. url, user, password.

<ear-default> configures defaults for .ear resource, i.e. enterprise applications.

Specifies ear expansion.

ear-deploy can be used in web-apps to define a subdirectory for ear expansion.

<ejb-message-bean> configures a bean as a message listener. The listener can be a simple bean that just implements the javax.jms.MessageListener interface. No other packaging or complications are necessary. Resin will retrieve messages from a configured queue and pass them to the listener as they arrive. The listeners are typically pooled.

The bean has full access to Resin-IoC capabilities, including dependency injection, transaction attributes, and aspect interception.

The message bean can plug into custom messaging systems. The application will need to define a ResourceAdapter and an ActivationSpec.

Configures an EJB server.

<ejb-stateful-bean> is deprecated and replaced by CDI-style configuration. EJB stateful beans are now either scanned automatically if configured with the @Stateful annotation or can be configured as CDI beans with the <ee:Stateful> tag.

<ejb-stateless-bean> is deprecated and replaced by CDI-style configuration. EJB stateless beans are now either scanned automatically if configured with the @Stateless annotation or can be configured as CDI beans with the <ee:Stateless> tag.

By default, Resin's System.getProperties() is environment-dependent, so the settings in on web-app do not affect the properties in any other web-app. Some sites may need to disable this virtualization capability, when using certain JVM agents.

<env-entry> configures a JNDI scalar value for JNDI-based application configuration.

Some application beans prefer to retrieve configuration data from JNDI, including String, Integer, and Double constants. env-entry configures that data in the current context.

The value can not use JSP-EL expressions, because the env-entry is part of the JavaEE spec. To set EL expressions, use resin:set instead.

Allows applications to customize the response generated for errors. By default, Resin returns a 500 Servlet Error and a stack trace for exceptions and a simple 404 File Not Found for error pages. With <error-page>, you may specify a handler page for these errors.

The handler page has several request attributes set so that it may log, display, or otherwise use information about the error that occured. The following table describes the available attributes.

The expand-cleanup-fileset tag lets you configure which files are to be kept on a .war redeploy. By default, Resin deletes the entire .war directory on a restart.

<fileset> provides the ability to match a set of files. It is modelled after the ant tag by the same name. The fileset matches files from a base directory defined by 'dir'. Files can be included by patterns defined by <include> tags or excluded by patterns defined in <exclude> tags.

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.

Defines a filter name for later mapping. Because Filters are fully integrated with Resin CanDI, they can use dependency-injection, transactional aspects, custom interception with @InterceptorType, and event handling with @Observes.

Maps url patterns to filters. filter-mapping has two children, url-pattern and filter-name. url-pattern selects the urls which should execute the filter.

filter-name can either specify a filter class directly or it can specify a filter alias defined by filter.

Configures authentication using forms. The login form has specific parameters that the servlet engine's login form processing understands. If the login succeeds, the user will see the original page. If it fails, she will see the error page.

The form itself must have the action j_security_check. It must also have the parameters j_username and j_password. Optionally, it can also have j_uri and j_use_cookie_auth. j_uri gives the next page to display when login succeeds. j_use_cookie_auth allows Resin to send a persistent cookie to the user to make following login easier.

j_use_cookie_auth gives control to the user whether to generate a persistent cookie. It lets you implement the "remember me" button. By default, the authentication only lasts for a single session.

<group-name> configures the operating system group Resin should run as. Since the HTTP port 80 is protected in Unix, the web server needs to start as root to bind to port 80. For security, Resin should switch to a non-root user after binding to port 80.

Executes a sequence of child health actions in order.

Qualifies an action to match if all of the child predicates match.

Note: <health:And> is implied and thus not strictly necessary except when used in conjunction with more complex combining conditions.

AnomalyAnalyzer examines a meter value, checking for deviations from the average value. So unusual changes like a spike in blocked threads can be detected, logged, and trigger health actions.

Executes a JMX MBean operation with parameters.

Note: Calling a JMX operation can also be performed on-demand using the jmx-call command line.

Monitors the health of Resin database connection pools. See <database> for additional information.

Monitors CPU usage. On multi-core machines, each CPU is checked individually.

Create a memory heap dump. The heap dump will be logged to the internal log database and to the resin log file using com.caucho.health.action.DumpHeap as the class at info level.

Note: Creating a heap dump can also be performed on-demand using the heap-dump command line, and from /resin-admin.

Shortcut for <health:DumpHeap hprof='true'/>

Health action to create a dump of all JMX attributes and values. The JMX dump will be logged to the internal log database and to the resin log file using com.caucho.health.action.DumpJmx as the class at info level.

Note: Creating a JMX dump can also be performed on-demand using the jmx-dump command line.

Create a thread dump. The thread dump will be logged to the internal log database and log file using com.caucho.health.action.DumpThreads as the class at info level.

Note: Creating a thread dump can also be performed on-demand using the thread-dump command line.

Execute an operating system shell command.

Evaluates user supplied EL expressions to a boolean.

A timed restart of Resin, normally used in conjunction with an ActionSequence to gather shutdown information

Configures overall health checking frequency and recheck rules. This element is present in health.xml for clarity, but is not strictly required since it will be created upon startup with default values.

Monitors the health system itself by using a separate thread to detect if health checking is frozen or taking too long.

Monitors for heartbeats from other members of the cluster.

Monitors one or more URLs on the current Resin instance by making an HTTP GET request and comparing the returned HTTP status code to a pattern.

Qualify an action to execute if the current time is in an active range configured by cron-style times. This can be used both to schedule regular actions or to prevent restarts or other actions during critical times.

Qualifies an action to execute based on the evaluation of an JSP EL expression. Expression can include references to system properties, config properties, and JMX mbean attributes.

Qualifies an action to match if health status is CRITICAL.

Causes an action to fire in response to a matching health event. This is usually used in combination with AnomalyAnalyzer with a <health-event> attribute.

Qualifies an action to match if health status is FATAL.

Qualifies an action to match if health status is OK.

Qualifies an action to match if health status is UNKNOWN.

Qualifies an action to match if health status is WARNING.

Qualifies an action to match the health result message to a regular expression.

Qualifies an action to match at most an amount of time after the last execution. This is usefull to prevent unecessary frequent execution of an action.

Qualifies an action to match upon recovery. Recovery is defined as the state change from FATAL, CRITICAL, or WARNING to OK.

Qualifies an action to match only after the required number of rechecks have been performed. Since rechecking is not a health check specific condition, this predicate simply matches when recheck cycle count matches the HealthSystem parameter recheck-max.

Qualifies an action to match an amount of time after startup.

Creates a meter that graphs the difference between the current and previous values of a numeric JMX MBean attribute.

Creates a meter that graphs the current value of a numeric JMX MBean attribute.

Monitors for deadlocked threads, as determined by the JVM.

Checks for expiring Resin Pro license.

Monitors the amount of free memory in the JVM PermGen memory pool. Requests a garbage collection if memory falls too low.

Note: This check does not apply to all JVM vendor implementations, and will report UNKNOWN if there is no PermGen pool.

Monitors the amount of free memory in the JVM Tenured memory pool. Requests a garbage collection if memory falls too low. This check will monitor heap memory on JVMs where there is no tenured pool.

Note: memory-free-min will default to the value of <server> <memory-free-min> if present in resin.xml.

Qualifies an action to match if all of the child predicates fail.

Qualifies an action to match if none of the child predicates match.

Qualifies an action to match if the child predicate is false.

Qualifies an action to match only when Resin is stopping with an non-OK exit code.

Qualifies an action to match only when Resin is restarted by the watchdog. This generally only occurs during an error condition. OnStart will fire during this event also.

Qualifies an action to match only when Resin is starting.

Qualifies an action to match only when Resin is stopping.

Qualifies an action to match if any of the child predicates match.

Health action to generate a PDF report from a PHP script.

Restart Resin. Resin will exit with the reason HEALTH.

Produces a concise thread activity report for groups of related threads.

Note: A scoreboard report can also be produced using the scoreboard command line.

Sets a JMX attribute to a value.

Note: Setting a JMX attribute can also be performed on-demand using the jmx-set command line.

Send an email containing a summary of the current Resin health status.

Sets a JMX attribute to a value.

Note: Setting a JMX attribute can also be performed on-demand using the jmx-set command line.

A specific sequence of health actions: thread dump, heap dump, jmx dump, and pdf report. This is intended to generate a permanent representation, or "snapshot" of the system at a point in time that includes all the information necessary to debug server issues. It is usually intended to run in response to a unexpected issue.

Starts a profiler session. Results are logged to the internal database and the Resin log file at INFO level.

Note: Starting the profiler can also be performed on-demand using the profile command line, and from /resin-admin.

Monitors the Resin transaction manager for commit failures.

The <home-cluster> specifies the default --cluster value for dynamic servers. When Resin starts and elastic server, it looks for a <home-cluster> if the --cluster option is missing. The home cluster will be cluster that the Resin server tries to join.

<host> configures a virtual host. Virtual hosts must be configured explicitly.

It is recommended that any <host> using a regexp include a <host-name> to set the canonical name for the host.

<host-alias> defines a URL alias for matching HTTP requests. Any number of <host-alias> can be used for each alias.

The host-alias can be used either in the resin.xml or in a host.xml when use host-deploy together with resin:import.

Since the <host-deploy> and <host> tags lets you add a host.xml file to customize configuration, the <host-alias> can also fit in the custom host.xml page.

<host-alias-regexp> defines a regular expression for matching URLs for a given virtual host.

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.

<host-deploy> configures an automatic deployment directory for virtual hosts.

The host-deploy will add an EL variable ${host.name}, referring to the name of the host jar file.

<host-name> defines the canonical name for a virtual host. The <host-name> will be used in Resin's logging, management, and is available in the host's variables.

<http> configures a HTTP or HTTPS 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.

Note

The virtual-host attribute overrides the browser's Host directive, specifying the explicit host and port for request.getServerName() and getServerPort(). It is not used in most virtual host configurations. Only IP-based virtual hosts which wish to ignore the browser's Host will use @virtual-host.

The <idle-time> specifies the timeout for lazy-idle web-apps. In some configurations, web-apps are created only on demand and are closed when no requests access the web-app. The idle-time configures when those web-apps should be freed.

For example, the resin-doc web-app uses idle-time for its child web-apps because there are a large number of sub-web-apps for the individual tutorials.

ignore-client-disconnect configures whether Resin should ignore disconnection exceptions from the client, or if it should send those exceptions to the application.

Configures the number of entries in the invocation cache. The invocation cache is used to store pre-calculated servlet and filter chains from the URLs. It's also used as the basis for proxy caching.

Configures the longest entry cacheable in the invocation cache. It is used to avoid certain types of denial-of-service attacks.

<javac> configures the Java compiler for automatically compiled files.

The javac configuration is used for JSP, PHP, EJB and compiling-loader configuration. Thus you can deploy JSPs to Resin and it will use the compiler to generate classes at runtime. In other words, you do not need to precompile your JSPs, Java files, et al. to deploy them on Resin.

The internal compiler (recommended) requires tools.jar from the JDK installation, so a JDK must be used (not a JRE). Sometimes the internal compiler causes errors, creating exceptions or simply hanging and taking up a thread. The solution is to change the compiler to use an external compiler.

The javac compiler is included with the JDK. It performs the same function as the internal compiler, however it is executed as an external process and is less prone to the problems described for the internal compiler. In resin.xml with the javac configuration option:

<jndi-link> creates a symbolic link from one jndi name to another, or links to a foreign JNDI context.

Resin's JNDI can link to foreign JNDI contexts. For example, third-party EJB servers will often expose their EJB beans through a JNDI context. jndi-link will create the appropriate InitialContextFactory, configure it, and lookup the foreign JNDI objects.

Replacement for jpa-persistence.

Configures JSP behavior.

<jsp-config> configure standard settings for JSP files.

<jvm-arg> configures JVM arguments to be passed to Resin on the command line, typically -X memory parameters and -D defines.

<jvm-classpath> adds a classpath entry when starting the JVM.

<keepalive-max> configures the maximum number of sockets which can be used directly for keepalive connections. In Resin Professional, the select manager allows for a much larger number of keepalive sockets, since it can detach threads from connections. Without the select manager, each connection is associated with a thread.

A value of -1 disables keepalives.

Keepalives are an important TCP technique used with HTTP and Resin's load-balancing to avoid the heavy network cost of creating a new socket. Since an initial HTTP request is usually immediately followed by extra requests to load files like images and stylesheets, it's generally more efficient to keep the socket open for a short time instead of creating a new one. The socket keepalive is even more important for Resin's load balancing, to avoid creating extra sockets between the web-tier and the app-tier and to make distributed sessions more efficient.

Higher values of <keepalive-max> improve network efficiency but increase the number of threads waiting for new client data.

<keepalive-select-enable> enables the select manager for keepalives. The select manager is a Resin Professional feature allowing more keepalives by detaching threads from sockets.

Normally, this should be left enabled.

<keepalive-select-thread-timeout> is a short timeout allowing the select manager to wait for a keepalive before detaching the thread. This value would not normally be changed.

<keepalive-timeout> configures how long a keepalive connection should wait for a new request before closing.

Keepalives are used both for HTTP connections and for load-balancing and clustering connections. HTTP connections generally have a single HTML page, followed by a number of image requests. By using keepalives, all the requests can use a single socket. The <keepalive-timeout> should be long enough to catch all the HTTP burst requests, but can close after the burst is complete. A value of 5s or 15s is generally sufficient.

The load-balancing and clustering keepalives have a different timeout behavior. Since load-balancing sockets are reused for multiple clients, they can have longer timeouts.

<lazy-servlet-validate> defers validation of servlet classes until the servlet is used. Some servlet libraries are bundled with web.xml files which include servlets with no available classes. Since Resin will normally send an error in this situation, <lazy-servlet-validate> lets you turn the validation off.

<library-loader> configures a jar library, WEB-INF/lib-style class loader.

The library-loader will add jar files in its path to the current classpath. Jar files are recognized wihen they have a filename extension of .jar or .zip.

See DirectoryLoader.

<listener> configures servlet event listeners. The listeners are registered based on interfaces they implement. The listener instances are fully Resin-IoC aware, including dependency injection, observing events, and supporting aspects.

<load-balance-connect-timeout> configures the maximum time a client connection to a cluster-port should take. The load balance and persistent sessions use load-balance-connect-timeout to connect to backend or peer servers in the cluster.

Lower values detect failed servers more quickly, but a too-low value can timeout too quickly for a live server with some network congestion.

<load-balance-recover-time> is the maximum time the load balancer will consider the server dead after a failure before retrying the connection.

Resin uses the load-balance-recover-time to avoid wasting time trying to connect to an unavailable app-tier server.

Lower values let the load balancer use a restarted app-tier server faster, but lower values also increase the overhead of trying to contact unavailable servers.

<load-balance-idle-time> is the maximum time the load balancer and distributed sessions will leave an idle socket before closing it.

The default value is normally sufficient, since it tracks the keepalive of the cluster port.

load-balance-idle-time must be less than the keepalive value of the target cluster-port.

The load balancer and distributed sessions reuse sockets to the cluster peer and app-tier servers to improve TCP performance. The load-balance-idle-time limits the amount of time those sockets can remain idle.

Higher values may improve the socket pooling, but may also increase the chance of connecting to a closed server.

The time the load balancer uses to throttle connections to an app-tier server that's just starting up.

Java web-applications often start slowly while they initialize caches. So a newly-started application will often be slower and consume more resources than a long-running application. The warmup-time increases Resin's reliability by limiting the number of requests to a new app-tier server until the server has warmed up.

Larger values give the application a longer time to warm up.

load-balance-weight assigns a load-balance weight to a backend server. Servers with higher values get more requests. Servers with lower values get fewer requests.

In some cases, some app-tier servers may be more powerful than others. load-balance-weight lets the load-balancer assign more connections to the more powerful machines.

Test and profiling servers can also use load-balance-weight to receive a small number of connections for profiling purposes.

Larger values tell the load-balancer to assign more requests to the app-tier server.

Configures the login method for authentication, one of BASIC, DIGEST or FORM.

See also: Resin security for an overview.

Configure a log handler for the JDK java.util.logging.* API. java.util.logging has two steps: configure a set of log handlers, and configure the levels for each logger. The <log-handler> creates a destination for logs, sets a minimum logging level for the handler, and attaches the handler to a logging name.

In addition to configuring custom handlers, <log-handler> has the most common configuration build-in: logging to a rotating file. Most of the configuration attributes are used for the rotating file and are shared with the other logging configuration.

The format for log tags is used to specify a format string for each log message. format recognizes EL-expressions. The EL variable log is a com.caucho.log.ELFormatter.ELFormatterLogRecord object.

<mail> configures a javax.mail.Session object and makes it available in Resin-IoC/WebBeans. Mail properties can be configured using the properties attribute. Some of the most common properties can be configured directly on the <mail> tag.

<max-active-time> configures the maximum time a connection can be active before Resin will automatically close it. Normally, the max-active-time should not be configured, since Resin will also automatically close a connection at the end of a request.

Sites should generally leave max-active-time at the default.

<max-close-statements> configures how many open statements Resin should save to for the connection close. Since the JDBC Connection.close() call automatically closes any open statements, Resin's database pool needs to keep track of any open statements to close them in case the application has forgotten. The <max-close-statements> is primarily needed for older database drivers implementing the java.sql.Driver interface.

<max-connections> configures the maximum number of open connections allowed for Resin's database pool. Sites can use <max-connections> to throttle the number of database connections for an overloaded server. When max-connections is reached and an application calls getConnection, Resin will wait connection-wait-time or until a connection is freed before allocating a new connection.

<max-create-connections> configures the maximum number of simultaneous connection creations. Since connection creation is slow and database access can be spiky, Resin's pool limits the number of new connections to the database at any time. Once a connection has succeeded, a new connection can proceed.

<max-idle-time> configures the maximum time a connection can remain idle before Resin automatically closes it. Since idle databases tie up resources, Resin will slowly close idle connections that are no longer needed.

Higher values of <max-idle-time> will connections to remain in the idle pool for a longer time. Lower values will close idle connections more quickly.

<max-overflow-connections> extends <connection-max> temporarily in case of overflow. After the <connection-wait-time> expires, Resin can create an overflow connection to handle unforseen load spikes.

<max-pool-time> configures the maximum time the connection can remain open. A connection could theoretically remain open, switching between active and idle, for an indefinite time. The <max-pool-time> allows a site to limit to total time of that connection.

Most sites will leave <max-pool-time> at the default.

Sets limit on longest URIs that can be served by Resin.

<memory-free-min> improves server reliability by detecting low-memory situations caused by memory leaks and forcing a clean server restart. Since Resin's watchdog service reliably restarts the server, a website can improve stability by forcing a restart before memory becomes a major problem. The memory-free-min restart will also log a warning, notifying the developers that a potential memory leak needs to be resolved.

When free heap memory gets very low, the garbage collector can run continually trying to free up extra memory. This continual garbage collection can send the CPU time to 100%, cause the site to become completely unresponsive, and yet take a long time before finally failing to an out of memory error (forcing an unclean restart). To avoid this situation, Resin will detect the low-memory condition and gracefully restart the server when free memory becomes too low.

The ultimate solution to any memory leak issues is to get a memory profiler, find the leaking memory and fix it. <memory-free-min> is just a temporary bandage to keep the site running reliably until the memory leak can be found and fixed.

Maps url patterns to mime-types.

Enables multipart-mime for forms and file uploads. multipart-mime is disabled by default.

For an uploaded file with a form name of foo, the parameter value contains the path name to a temporary file containing the uploaded file. foo.filename contains the uploaded filename, and foo.content-type contains the content-type of the uploaded file.

Maps url patterns to real paths. If using a server like IIS, you may need to match the server's path aliases.

<password> configures the database connection password. Sites requiring additional security for their passwords can use the <mypkg:MyDecryptor/> syntax to configure a password decoder.

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.

<ping> enables connection validation. When <ping> is enabled, Resin will test the connection with <ping-query> or <ping-table> before returning a connection to the user. If the connection fails the test, Resin will close it and return a new connection.

For efficiency, Resin will only validate the connection if it has been idle for longer than <ping-interval>.

<ping-table> configures the database table Resin should use to verify if a connection is still valid when returned from the pool.

<ping-query> specifies the query to use for validating if a database connection is still valid when returned from the idle pool.

<ping-interval> configures when Resin should validate an idle connection. Connections which have been idle for less than <ping-interval> are assumed to be still valid without validation. Connections idle for longer than <ping-interval> are validated.

Sites can force a validation by setting <ping-interval> to 0.

The server <port> defines the TCP port for Resin cluster communication and load balancing. Most server instances will use a common port like 6800, while machines with multiple servers may use multiple ports like 6800 and 6801.

Defines default port parameters for all <http>, <protocol>, and <cluster-port>.

<prepared-statement-cache-size> configures how many prepared statements Resin should cache for each connection. Caching prepared statement can improve performance for some database drivers by avoiding repeated parsing of the query SQL.

<protocol> configures a remoting protocol for a Java bean. The bean is configured with the <servlet> and <servlet-mapping> tags, since it will process HTTP URL requests.

Protocol drivers extend the com.caucho.remote.server.AbstractProtocolServletFactory interface and can register a URI alias to simplify configuration.

<redeploy-check-interval> specifies how often Resin should check if a .war file has been updated or added to a <web-app-deploy> directory.

<redeploy-mode> specifies how Resin handles updates to web-apps and .war files. By default, Resin restarts web-apps when classes or configuration files change.

<rewrite-real-path> lets you rewrite the URL to physical path mapping, to allow aliasing or for filesystem organization.

Because not all browsers understand the Vary header, Resin can rewrite Vary to a Cache-Control: private. This rewriting will cache the page with the Vary in Resin's proxy cache, and also cache the page in the browser. Any other proxy caches, however, will not be able to cache the page.

The underlying issue is a limitation of browsers such as IE. When IE sees a Vary header it doesn't understand, it marks the page as uncacheable. Since IE only understands "Vary: User-Agent", this would mean IE would refuse to cache gzipped pages or "Vary: Cookie" pages.

With the <rewrite-vary-as-private> tag, IE will cache the page since it's rewritten as "Cache-Control: private" with no Vary at all. Resin will continue to cache the page as normal.

<root-directory> specifies the base directory for the contexts. All EL-style directory paths are relative to the root-directory.

<reference> configures a JNDI ObjectFactory. Some legacy resources are configured using an ObjectFactory syntax. The <reference> tag provides a compatible way to configure those objects. More modern resources should use <bean> or <component> for IoC configuration.

JNDI ObjectFactories are used to create objects from JNDI references. The <reference> tag configures the ObjectFactory and stores it in JNDI.

<remote-client> configures a proxy to a web-service. It uses a Java interface and a URI to select the web-service.

The URI is defined as: protocol:url=location, where location is typically a HTTP URL.

• See Resin remoting for more information, including how to write an adapter for Resin remoting.

<resin> is the top-level configuration tag for the resin.xml 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-system-auth-key> specifies authorization token for Resin's Security service.

Authenticator used by Resin for administration purposes such as the /resin-admin application. Also used by the watchdog and clustering code to authenticate servers, so changing principals or passwords in this authenticator requires a shutdown and restart of the watchdog and Resin instances.

Uses the same syntax as XmlAuthenticator.

The <resin:Allow> tag is used to secure a particular URL pattern. Because it is affirmative, it must always include a nested condition expressing an authorization constraint. All access attempts that do not satisfy the authorization rule are denied access. This tag is the most common type of top level authorization tag.

Matches if all children match.

As the name implies, HTTP basic authentication is the simplest mechanism for gathering login data for web applications. When a web page is secured through HTTP basic authentication, the brower renders a simple dialog box for the user to enter login information. This information is then sent to the server in clear-text using well-defined HTTP headers. This authentication mechanism can be convenient for quick protection of internal pages or administration when writing a form isn't necessary. If you use basic authentication for applications outside the fire-wall, it is highly recommended that you secure the transport layer using SSL. The <resin:BasicLogin> tag is used to configure basic authentication.

Distributed cache of InputStream/OutputStream byte streams across a cluster pod.

resin:choose implements an if, elsif, else.

The <resin:choose> schema is context-dependent. A <resin:choose> in a <web-app> will have <web-app> content, while a <resin:choose> in a <host> will have <host> content.

JCache-style distributed object cache across a cluster pod (java.util.Map).

Clustered queue.

Cluster-based single signon.

The DatabaseAuthenticator asks a back-end relational database for the password matching a user's name. It uses the DataSource specified by the data-source attribute. data-source refers to an existing configured DataSource.

The <resin:Deny> tag is the opposite of the top level <resin:Allow>. It restricts access to a particular URL pattern based on any nested conditions. Access attempts that match the condition are denied access. If no conditions are specified, all access to a URL pattern is restricted.

The HTTP protocol includes a method to indicate to the client that it should digest the password before sending it to the server. This is basically a more secure variant of HTTP basic authentication. The browser submits a digest to Resin instead of submitting a clear-text password. HTTP digest authentication protects the password in transmission.

When using the HTTP digest, Resin will respond to the browser when a secure URL is accessed and ask it to calculate a digest. The steps involved are:

• Resin provides the client a realm and some other information.
• The client obtains a user-name and password (usually through a dialog box with a web browser).
• The client calculates a digest using the user-name, realm, password, and other information supplied by Resin.
• The client submits the digest to Resin.
• Resin does the same digest calculation as the client did.
• Resin compares the submitted digest and the digest it calculated. If they match, the user is authenticated.

The advantage of this method is that the clear-text password is protected in transmission, it cannot be determined from the digest that is submitted by the client to the server. The <resin:DigestLogin> tag is used to configure digest login.

Normal servlet dispatching with optional target rewriting.

Enables dynamic servers. When dynamic servers are enable, a new Resin server can join a cluster by contacting the hub triad without needing an explicit server configuration in the resin.properties or resin.xml.

FastCGI requests, e.g. from nginx.

Proxies the request to a backend server using FastCGI as a proxy protocol.

Filesystem based queue.

Filesystem based topic.

Send a HTTP forbidden response.

Form-based login is the most common way collecting login information. Using this login mechanism, you can plug-in a custom login page with a form storing login information (usually two input text fields for user-name and password). This custom login page can then be used with the Resin security framework. This allows for a much more seamless login mechanism integrated closely with your application, especially in terms of look and feel.

When a URL is secured via form based login, the custom login form page is used to collect authentication information. If authentication succeeds, the user is redirected to the originally requested page. Otherwise, the user is forwarded to an error page (that can also be configured).

A login page can be anything that renders a valid login form such as HTML, Servlet, JSP or JSF. A valid login form must have the action j_security_check. It must also have the parameters j_username and j_password holding the username and password. Optionally, it can also have j_uri and j_use_cookie_auth. j_uri gives the next page to display when login succeeds. If the form-uri-priority is set to true, the user will be forwarded to the j_uri page regardless of what the originally requested page was. If the attribute is set to false (the default), the j_uri page is only used when the originally requested page was the login page itself. j_use_cookie_auth allows Resin to send a persistent cookie to the client to make subsequent logins automatic. When j_use_cookie_auth is set, Resin will store a persistent cookie on the client's machine after authentication succeeds. On all subsequent access, Resin detects the persistent cookie and automatically logs the user in instead of prompting for authentication. This essentially lets you implement "remember me" functionality common in many web-sites. By default, the authentication only lasts for a single session and no persistent login cookie is sent to the client.

The following table outlines all the login parameters recognized by Resin:

Forwards to the new URL using RequestDispatcher.forward with the target URL.

JCache-style distributed object cache across the entire Resin system.

Proxies the request to a backend server using HTTP as a proxy protocol.

resin:if executes part of the configuration file conditionally. resin:if can be particularly useful in combination with Java command-line properties like -Dfoo=bar to enable development mode or testing configuration.

The resin:if schema is context-dependent. For example, resin:if in a <web-app> will have web-app content while resin:if in a <host> will have host content.

Checks for the authentication type, request.getAuthType().

Checks for the presence of a named HTTP cookie from request.getCookies().

Matches if the current time is in an active range configured by cron-style times.

Matches if the URL corresponds to an actual file. Has no attributes.

Tests for a HTTP header and value match.

Tests for a Locale match from the HTTP request (Accept-Language header).

Compares the local port of the request, request.getLocalPort().

Matches if a MBean is enabled().

Compares the HTTP method, request.getMethod().

The <resin:IfNetwork> tag allows or denies requests based on the IP address of the client. IP-constraint is very useful for protecting administration resources to an internal network. It can also be useful for denying service to known problem IPs.

Tests for a HTTP query parameger, request.getParameter().

Tests against the remote user, request.getRemoteUser().

The <resin:IfSecure> tag restricts access to secure transports, usually SSL.

The resin:IfUserInRole condition enforces role-based security. It requires that authenticated users have a specified role.

<resin:import> reads configuration from another file or set of files. For example, the WEB-INF/web.xml and WEB-INF/resin-web.xml files are implemented as <resin:import> in the app-default.xml.

The target file is validated by the schema of the including context. So a resin:import in <web-app-default> will have a target with a top-level of <web-app>, and a resin:import in <cluster> will have a top-level tag of <cluster>.

The JaasAuthenticator uses a JAAS LoginModule for authentication. A common use of the JaasAuthenticator is to serve as an adapter for the large number of JAAS LoginModule's included in the Sun JDK for authentication purposes. However, the JAAS authenticator can be used with any valid JAAS login module.

Combined Queue and Topic ConnectionFactory.

Enables cluster-wide JMX administration.

The LdapAuthenticator uses JNDI to connect to an LDAP (or Active Directory) server for authentication.

Load balance to a cluster of backend Resin servers.

Stores high-priority log messages in a database.

Memory based queue.

Memory-based single signon.

Memory based topic.

Logs a message to the given log file. The content of the element is the message.

Send an HTTP redirect to a new URL specified by target.

Matches if the child does not match.

Matches if any child does not match.

Matches if all the children do not match.

Matches if any children match.

Mails a notification when a ping check fails.

Checks status of Resin sutomatically.

Maven-style library jar management for webapps.

The PropertiesAuthenticator allows you to use Java properties to store authentication information. This is very useful for a variety of applications such as very small sites, developement, unit testing or integration testing. You can either specify properties in-line in XML or via an external properties file.

Send an HTTP redirect to a new URL specified by target.

Enables administration by remote agents, like an eclipse console.

<resin:ScheduledTask> schedules a job to be executed at specific times or after specific delays. The times can be specified by a cron syntax or by a simple delay parameter. The job can be either a Runnable bean, a method specified by an EL expression, or a URL.

When specified as an Java Injection bean, the bean task has full IoC capabilities, including injection, @TransactionAttribute aspects, interception and @Observes.

Send a HTTP error response.

resin:set adds an EL variable to the current context.

Sets a response header.

Marks the request as secure.

Sets the Vary header.

Gathers timed runtime status of Resin for graphing.

<resin:when> conditionally configures a block within a <resin:choose> block. If the test matches, Resin will use the enclosed configuration.

Transaction log service.