Resin Documentationapp server |
references
Complete reference documentation
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: <web-app xmlns="http://caucho.com/ns/resin" xmlns:foo="urn:java:com.caucho.foo"> ... <foo:MyAuthenticator> <foo:foo>bar</foo:foo> </foo:MyAuthenticator> ... </web-app> package com.foo; import com.caucho.security.AbstractAuthenticator; import com.caucho.security.PasswordUser; public class MyAuthenticator extends AbstractAuthenticator { private PasswordUser _user; public MyAuthenticator() { _user = new PasswordUser("harry", "quidditch", new String[] { "user" }); } public PasswordUser getPasswordUser(String userName) { if (userName.equals(_user.getName())) return _user; else return null; } } <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. child of <cluster>,<cluster-default>,<server>,<server-default>,<host>,<host-default>,<web-app>,<web-app-default>
<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 + ".%Y%m%d" or + ".%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\"" com.caucho.http.log.AccessLog. Resin-IoC initialization can be used to set bean parameters in the custom class. allows for custom logging. Applications can extend a custom class from
element access-log { path? & path-format? & archive-format? $amp;auto-flush? & auto-flush-time? & exclude* & format? & hostname-dns-lookup? & rollover-period? & rollover-size? & rollover-count? & resin:type? & init? } <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <host id=""> <access-log path='log/access.log'> <rollover-period>2W</rollover-period> </access-log> </host> </cluster> </resin> <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <host id='foo.com'> <access-log> <test:MyLog xmlns:test="urn:java:test"> path='${resin.root}/foo/error.log' rollover-period='1W'> <test:foo>bar</test:foo> </test:MyLog> </access-log> ... </host> </cluster> </resin> child of <web-app>
<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. element active-wait-time { r_period-Type } child of <server>
default 127.0.0.1The 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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <http port="80"/> </server-default> <server id="web-a" address="192.168.1.1" port="6800"/> <server id="web-b" address="192.168.1.2" port="6800"/> ... </cluster> <cluster id="app-tier"> <server id="app-a" address="192.168.2.11" port="6800"/> <server id="app-b" address="192.168.2.12" port="6800"/> ... </cluster> </resin> child of <web-app>
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. element allow-forward-after-flush { r_boolean-Type } child of <web-app>
The <allow-servlet-el> flag configures whether <servlet> tags allow EL expressions in the init-param. element allow-servlet-el { r_boolean-Type } child of <web-app>
<archive-path> configures the location of the web-app's .war file. In some configurations, the .war expansion might not use the directory, but will still want automatic war expantion.element archive-path { r_path-Type } <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> <host id=""> <web-app id="/foo" root-directory="/var/resin/foo" archive-path="/var/resin/wars/foo.war"/> </host> </cluster> </resin> child of <security-constraint>
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 . (See Resin management.)
element auth-constraint { description*, role-name* } 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>. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:XmlAuthenticator password-digest="none"> <resin:user name="Harry Potter" password="quidditch" group="user,gryffindor"/> <resin:user name="Draco Malfoy" password="pureblood" group="user,slytherin"/> </resin:XmlAuthenticator> ... </web-app> 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">. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:mypkg="urn:java:com.mycom.mypkg"> ... <mypkg:MyBean resin:Jndi="java:comp/env/my-name"> <my-attribute>my-value</my-attribute> </mypkg:MyBean> ... </web-app> child of <cluster>
<proxy-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.
element proxy-cache { disk-size? & enable? & enable-range? & entries? & path? & max-entry-size? & memory-size? & rewrite-vary-as-private? } <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <proxy-cache entries="16384" disk-size="2G" memory-size="256M"/> <server id="a" address="192.168.0.10"/> <host host-name="www.foo.com"> </cluster> </resin> rewrite-vary-as-privateBecause 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. child of <web-app>
<cache-mapping> specifies and times for cacheable pages.See proxy-cache 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 dynamic (non-static) pages cacheable. Your servlets must already set the (or Last-Modified) header to activate <cache-mapping>. For static resources, Resin's FileServlet sets the header.
The time intervals default to seconds, but will allow other <time intervals>.
element cache-mapping { (url-pattern | url-regexp) & expires? & max-age? & s-max-age? } <web-app xmlns="http://caucho.com/ns/resin"> <cache-mapping url-pattern='/*' max-age='10'/> <cache-mapping url-pattern='*.gif' max-age='15m'/> </web-app> <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. r_case-insensitive = element case-insensitive { r_boolean-Type } <character-encoding> specifies the default character encoding for the environment. r_character-encoding = element character-encoding { string } <resin xmlns="http://caucho.com/ns/resin"> <character-encoding>utf-8</character-encoding> ... </resin> <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.
r_class-loader = element class-loader { r_compiling-loader* & r_library-loader* & r_simple-loader* & r_tree-loader* } <web-app xmlns="http://caucho.com/ns/resin"> <prologue> <class-loader> <compiling-loader path="WEB-INF/classes"/> <library-loader path="WEB-INF/lib"/> </class-loader> </prologue> </web-app> child of <database>
default true<close-dangling-connections> closes open connections at the end of a request and logs a warning and stack trace. child of <resin>
<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 matching the -server on the command line.
element cluster { attribute id { string } & environment resources & access-log? & cache? & connection-error-page? & ear-default* & error-page* & host* & host-default* & host-deploy* & ignore-client-disconnect? & invocation-cache-size? & invocation-cache-max-url-length? & machine* & ping* & redeploy-mode? & resin:choose* & resin:import* & resin:if* & rewrite-dispatch? & root-directory? & server* & server-default* & server-header? & session-cookie? & url-character-encoding? & url-length-max? & web-app-default* } <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <http port="8080"/> </server-default> <server id="a" address="192.168.0.10"/> <server id="b" address="192.168.0.11"/> <host host-name="www.foo.com"> ... </host> </cluster> </resin> child of <resin>
<cluster-default> defines default cluster configuration for all clusters in the <resin> server. <resin xmlns="http://caucho.com/ns/resin"> <cluster-default> <cache entries="16384" memory-size="64M"/> </cluster-default> <cluster id="web-tier"> ... </cluster> <cluster id="app-tier"> ... </cluster> </resin> child of <server>
<cluster-port> configures the cluster and load balancing socket, for load balancing, distributed sessions, and distributed management. When configuring Resin in a load-balanced cluster, each Resin instance will have its own <server> configuration, which Resin uses for distributed session management and for the load balancing itself. When configuring multiple JVMs, each <server> has a unique <server-id> which allows the -server command-line to select which ports the server should listen to.
child of <class-loader>
<compiling-loader> automatically compiles Java code into .class files before loading them.
<web-app xmlns="http://caucho.com/ns/resin"> <prologue> <class-loader> <compiling-loader path="WEB-INF/classes" source="WEB-INF/src"/> </class-loader> </prologue> </web-app> child of <database>
Initialize all java.sql.Connection objects managed by <database>.
element connection { catalog? & read-only? & transaction-isolation? } <web-app xmlns="http://caucho.com/ns/resin"> <database> <driver type="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource"> <url>jdbc:mysql://localhost:3306/test</url> <user></user> <password></password> </driver> <connection> <transaction-isolation>serializable</transaction-isolation> <catalog>my-catalog</catalog> </connection> </database> </web-app> child of <cluster>
<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. element connection-error-page { string } child of <database>
default 30s<connection-wait-time> configures the time a child of <security-constraint>
Defines a custom constraint. Applications can define their own security constraints to handle custom authentication requirements.
element constraint { class & init? } child of <web-app>
Initializes application (ServletContext) variables.
element context-param { (param-name, param-value)* | (attribute * { string })* | (element * { string })* } <web-app xmlns="http://caucho.com/ns/resin"> <context-param> <param-name>baz</param-name> <param-value>value</param-value> </context-param> <!-- shortcut --> <context-param foo="bar"/> </web-app> child of <web-app>
The <cookie-http-only> flag configures the Http-Only attribute for the JSESSIONID cookie generated from the web-app. The Http-Only attribute can add security to a website by not forwarding HTTP cookies to SSL HTTPS requests. element cookie-http-only { r_boolean-Type } <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> <host id="www.foo.com"> <web-app id="" root-directory="/var/resin/foo"> <cookie-http-only>true</cookie-http-only> <web-app id=""> </host> <host id="www.foo.com:443"> <web-app id="" root-directory="/var/resin/foo-secure"> <secure/> <web-app id=""> </host> </cluster> </resin> 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) # | | | | | * * * * *
child of <cluster>
<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.
database = element database { backup-driver* & close-dangling-connections? & commit-on-timeout? & connection? & connection-wait-time? & driver+ & jndi-name? & max-active-time? & max-close-statements? & max-connections? & max-create-connections? & max-idle-count? & max-idle-time? & max-overflow-connections? & max-pool-time? & name? & password? & ping? & ping-interval? & ping-query? & ping-table? & prepared-statement-cache-size? & save-allocation-stack-trace? & spy? & transaction-timeout? & user? & wrap-statements? & xa? & xa-forbid-same-rm? } backup-driver = element backup-driver { class? & url? & element * { * }? } connection = element connection { catalog? & read-only? & transaction-isolation? } driver = element driver { class? & url? & element * { * }? } <web-app xmlns="http://caucho.com/ns/resin"> <database jndi-name='jdbc/test_mysql'> <driver type="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource"> <url>jdbc:mysql://localhost:3306/test</url> <user></user> <password></password> </driver> </database> </web-app> <database-default> defines default database values to be used for any <database> definition, or runtime database creation (see DatabaseManager). element database-default { r_database-Content } <web-app xmlns="http://caucho.com/ns/resin"> <database-default> <max-idle-time>10s</max-idle-time> </database-default> </web-app> <dependency> adds dependent files which should force a reload when changed, like web.xml and resin-web.xml.
element dependency { string } <web-app xmlns="http://caucho.com/ns/resin"> <dependency path="WEB-INF/struts-config.xml"/> ... </web-app> <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. element dependency-check-interval { string } <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <dependency-check-interval>1h<dependency-check-interval> <server id="app-a" .../> <host id=""/> ... </cluster> </resin> child of <database>
<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. element driver { type, * } child of <cluster>
<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.
element ear-deploy { path & archive-directory? & ear-default? & expand-cleanup-fileset? & expand-directory? & expand-path? & expand-prefix? & expand-suffix? & lazy-init? & redeploy-mode? & require-file* & url-prefix? } <ejb-message-bean> configures a bean as a message listener.
The listener can be a simple bean that just implements the
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
element ejb-message-bean { class & init? & (activation-spec? | (destination? & destination-type? & destination-name? & message-consumer-max?) ) } Configures an EJB server.
element ejb-server { auto-compile & create-database-schema & data-source & config-directory & ejb-descriptor & ejb-jar & jndi-prefix & validate-database-schema & jms-connection-factory & xa-data-source } <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. <web-app xmlns="http://caucho.com/ns/resin" xmlns:ee="urn:java:ee" xmlny:mypkg="urn:java:com.mycom.mypkg"> <mypkg:MyBean> <ee:Stateful/> <my-attribute>my-value</my-attribute> </mypkg:MyBean> </web-app> <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. <web-app xmlns="http://caucho.com/ns/resin" xmlns:ee="urn:java:ee" xmlny:mypkg="urn:java:com.mycom.mypkg"> <mypkg:MyBean> <ee:Stateless/> <my-attribute>my-value</my-attribute> </mypkg:MyBean> </web-app> By default, Resin's element environment-system-properties { r_boolean-Type } <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.
element env-entry { description*, env-entry-name, env-entry-type, env-entry-value } The example configuration stores a string in java:comp/env/greeting. Following the J2EE spec, the env-entry-name is relative to java:comp/env. If the env-entry is in the <host> context, it will be visible to all web-apps in the host. <web-app xmlns="http://caucho.com/ns/resin"> <env-entry> <env-entry-name>greeting</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>Hello, World</env-entry-value> </env-entry> <servlet ...> </servlet> </web-app> The following servlet fragment is a typical use in a servlet. The servlet only looks up the variable once and stores it for later use. import java.io.*; import javax.naming.*; import javax.servlet.*; import javax.servlet.http.*; public class TestServlet extends HttpServlet { private String greeting; public void init() throws ServletException { try { Context env = (Context) new InitialContext().lookup("java:comp/env"); greeting = (String) env.lookup("greeting"); } catch (NamingException e) { throw new ServletException(e); } } ... } child of <web-app>
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.
element error-page { (error-code | exception-type)? & location } <web-app xmlns="http://caucho.com/ns/resin"> <error-page> <error-code>404</error-code> <location>/file_not_found.jsp</location> </error-page> </web-app> <web-app xmlns="http://caucho.com/ns/resin"> <error-page exception-type="java.lang.NullPointerException" location="/nullpointer.jsp"/> </web-app> <%@ page session="false" isErrorPage="true" %> <html> <head><title>404 Not Found</title></head> <body> <h1>404 Not Found</h1> The url <code>${requestScope["javax.servlet.error.request_uri"]}</code> was not found. </body> </html> child of <web-app-deploy>
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.
element fileset { dir & exclude* & include* <fileset dir="WEB-INF/lib"> <include name="*.jar"/> </fileset> MATCH lib/foo.jar MATCH lib/bar.jar NO MATCH lib/baz/foo.jar <fileset dir="WEB-INF/tree"> <include name="**/*.jar"/> </fileset> MATCH lib/foo.jar MATCH lib/bar.jar MATCH lib/baz/foo.jar child of <web-app>
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.
element filter { filter-name & filter-class & init* & init-param* } <web-app xmlns="http://caucho.com/ns/resin"> <filter> <filter-name>image</filter-name> <filter-class>test.MyImage</filter-class> <init-param> <param-name>title</param-name> <param-value>Hello, World</param-value> </init-param> </filter> <filter-mapping> <filter-name>image</filter-name> <url-pattern>/images/*</url-pattern> </filter-mapping> </web-app> <web-app id='/'> <filter filter-name='test.HelloWorld'> <init-param foo='bar'/> <init-param> <param-name>baz</param-name> <param-value>value</param-value> </init-param> </servlet> </web-app> child of <web-app>
Maps url patterns to filters. has two children, and . selects the urls which should execute the filter.
element filter-mapping { (url-pattern | url-regexp | servlet-name)+ & filter-name & dispatcher* } <web-app xmlns="http://caucho.com/ns/resin"> <filter> <filter-name>test-filter</filter-name> <filter-class>test.MyFilter</filter-class> </filter> <filter-mapping> <filter-name>test-filter</filter-name> <url-pattern>/hello/*</url-pattern> </filter-mapping> <servlet> <servlet-name>hello</servlet-name> <servlet-class>test.HelloWorld</servlet-class> </servlet> <servlet-mapping> <servlet-name>hello</servlet-name> <url-pattern>/hello</url-pattern> </servlet-mapping> </web-app> child of <login-config>
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 . It must also have the parameters and . Optionally, it can also have and . gives the next page to display when login succeeds. allows Resin to send a persistent cookie to the user to make following login easier.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.
element form-login-config { form-login-page, form-error-page, internal-forward, form-uri-priority } <form action='j_security_check' method='POST'> <table> <tr><td>User:<td><input name='j_username'> <tr><td>Password:<td><input name='j_password'> <tr><td colspan=2>hint: the password is 'quidditch' <tr><td><input type=submit> </table> </form> child of <server>
<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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server-default> <http port="80"/> <user-name>resin</user-name> <group-name>www</group-name> </server-default> <server id="web-a"/> ... </cluster> </resin> child of <cluster>
default 256 headers<header-count-max> sets the maximum number of HTTP headers allowed. For security, Resin has a hard limit on the number of HTTP headers allowed. Resin will reject the HTTP request if this limit is exceeded. If the application requires more headers, this value can be expanded. child of <cluster>
default 16k characters<header-size-max> sets the maximum number characters allowed in the HTTP headers. For security, Resin has a hard limit on the total number characters in the HTTP headers allowed. Resin will reject the HTTP request if this limit is exceeded. If the application requires more headers, this value can be expanded. child of <cluster> javadoc <health:ActionSequence>
Executes a sequence of child health actions in order.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:ActionSequence> <health:DumpThreads/> <health:DumpHeap/> <health:IfHealthCritical time="5m"/> </health:ActionSequence> </cluster> child of <cluster> javadoc <health:And>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:And> <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/> <health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/> </health:And> </health:Restart> </cluster> child of <cluster> javadoc <health:AnomalyAnalyzer>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:JmxMeter> <name>JVM|Thread|JVM Blocked Count</name> <objectName>resin:type=JvmThreads</objectName> <attribute>BlockedCount</attribute> </health:JmxMeter> <health:AnomalyAnalyzer> <meter>JVM|Thread|JVM Blocked Count</meter> <health-event>caucho.thread.anomaly.jvm-blocked</health-event> </health:AnomalyAnalyzer> <health:DumpThreads> <health:IfHealthEvent regexp="caucho.thread"/> <health:IfNotRecent time="15m"/> </health:DumpThreads> </cluster> child of <cluster> javadoc <health:CallJmxOperation>
Executes a JMX MBean operation with parameters. Note: Calling a JMX operation can also be performed on-demand using the command line.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:CallJmxOperation> <objectName>java.lang:type=Threading</objectName> <operation>resetPeakThreadCount</operation> <health:IfNotRecent time='5m'/> </health:CallJmxOperation> </cluster> child of <cluster>
Monitors the health of Resin database connection pools. See <database> for additional information.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:ConnectionPoolHealthCheck/> </cluster> child of <cluster> javadoc <health:CpuHealthCheck>
Monitors CPU usage. On multi-core machines, each CPU is checked individually.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:CpuHealthCheck> <warning-threshold>95</warning-threshold> <critical-threshold>99</critical-threshold> </health:CpuHealthCheck> </cluster> child of <cluster> javadoc <health:DumpHeap>
Create a memory heap dump. The heap dump will be logged to the internal log
database and to the resin log file using
Note: Creating a heap dump can also be performed on-demand using the command line, and from /resin-admin.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:DumpHeap/> </cluster> <cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:DumpHeap> <hprof>true</hprof> <hprof-path-format>${resin.home}/log/dump-%H:%M:%S.%s.hprof</hprof-path-format> <health:OnAbnormalStop/> </health:DumpHeap> </cluster> child of <cluster> javadoc <health:DumpHprofHeap>
Shortcut for <health:DumpHeap hprof='true'/> child of <cluster> javadoc <health:DumpJmx>
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 Note: Creating a JMX dump can also be performed on-demand using the command line.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:DumpJmx/> </cluster> child of <cluster> javadoc <health:DumpThreads>
Create a thread dump. The thread dump will be logged to the internal log
database and log file using Note: Creating a thread dump can also be performed on-demand using the command line.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:DumpThreads> <only-active>false</only-active> </health:DumpThreads> </cluster> child of <cluster> javadoc <health:ExecCommand>
Execute an operating system shell command.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:ExecCommand> <dir>/tmp</dir> <command>remediation.sh</command> <timeout>2s</timeout> <env> <name>resin_home</name> <value>${resin.home}</value> </env> <env> <name>password</name> <value>foo</value> </env> </health:ExecCommand> </cluster> child of <cluster> javadoc <health:ExprHealthCheck>
Evaluates user supplied EL expressions to a boolean.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:ExprHealthCheck> <critical-test>${mbean('java.lang:type=Threading').ThreadCount > 100}</critical-test> </health:ExprHealthCheck> </cluster> child of <cluster> javadoc <health:FailSafeRestart>
A timed restart of Resin, normally used in conjunction with an ActionSequence to gather shutdown information
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:ActionSequence> <health:FailSafeRestart timeout="10m"/> <health:DumpThreads/> <health:DumpHeap/> <health:StartProfiler active-time="5m"/> <health:Restart/> <health:IfHealthCritical time="5m"/> </health:ActionSequence> </cluster> child of <cluster> javadoc <health:HealthSystem>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:HealthSystem> <enabled>true</enabled> <startup-delay>15m</startup-delay> <period>5m</period> <recheck-period>30s</recheck-period> <recheck-max>10</recheck-max> </health:HealthSystem> </cluster> child of <cluster> javadoc <health:HealthSystemHealthCheck>
Monitors the health system itself by using a separate thread to detect if health checking is frozen or taking too long.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:HealthSystemHealthCheck> <thread-check-period>1m</thread-check-period> <freeze-timeout>15m</freeze-timeout> </health:HealthSystemHealthCheck> </cluster> child of <cluster> javadoc <health:HeartbeatHealthCheck>
Monitors for heartbeats from other members of the cluster.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:HeartbeatHealthCheck/> </cluster> child of <cluster> javadoc <health:HttpStatusHealthCheck>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:HttpStatusHealthCheck> <ping-host>localhost</ping-host> <ping-port>8080</ping-port> <url>/custom-test-1.jsp</url> <url>/custom-test-2.jsp</url> <socket-timeout>2s</socket-timeout> <regexp>^2|^3</regexp> </health:HttpStatusHealthCheck> </cluster> In some clustered configurations it may be simpler to use the
<!-- resin.xml --> <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <ping-url>/ping-test.jsp<ping-url> </server-default> ... </cluster> </resin> <!-- health.xml --> <cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:HttpStatusHealthCheck ee:Named="serverHttpPingCheck"> <socket-timeout>5s</socket-timeout> <regexp>200</regexp> </health:HttpStatusHealthCheck> </cluster> child of <cluster> javadoc <health:IfCron>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:IfCron> <enable-at>0 0 * * *</enable-at> <disable-at>5 0 * * *</disable-at> </health:IfCron> </health:Restart> </cluster> child of <cluster> javadoc <health:IfExpr>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:IfExpr> <test>${mbean('java.lang:type=Threading').ThreadCount > 100}</test> </health:IfExpr> </health:Restart> </cluster> child of <cluster> javadoc <health:IfHealthCritical>
Qualifies an action to match if health status is CRITICAL.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/> </health:Restart> </cluster> child of <cluster> javadoc <health:IfHealthEvent>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:JmxMeter> <name>JVM|Thread|JVM Blocked Count</name> <objectName>resin:type=JvmThreads</objectName> <attribute>BlockedCount</attribute> </health:JmxMeter> <health:AnomalyAnalyzer> <meter>JVM|Thread|JVM Blocked Count</meter> <health-event>caucho.thread.anomaly.jvm-blocked</health-event> </health:AnomalyAnalyzer> <health:DumpThreads> <health:IfHealthEvent regexp="caucho.thread"/> <health:IfNotRecent time="15m"/> </health:DumpThreads> </cluster> child of <cluster> javadoc <health:IfHealthFatal>
Qualifies an action to match if health status is FATAL.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:IfHealthFatal health-check="${memoryTenuredHealthCheck}"/> </health:Restart> </cluster> child of <cluster> javadoc <health:IfHealthOk>
Qualifies an action to match if health status is OK.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:Not> <health:IfHealthOk health-check="${memoryTenuredHealthCheck}"/> </health:Not> </health:Restart> </cluster> child of <cluster> javadoc <health:IfHealthUnknown>
Qualifies an action to match if health status is UNKNOWN.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:IfHealthUnknown health-check="${memoryTenuredHealthCheck}"/> </health:Restart> </cluster> child of <cluster> javadoc <health:IfHealthWarning>
Qualifies an action to match if health status is WARNING.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:IfHealthWarning health-check="${memoryTenuredHealthCheck}"/> </health:Restart> </cluster> child of <cluster> javadoc <health:IfMessage>
Qualifies an action to match the health result message to a regular expression.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:IfHealthCritical/> <health:IfMessage health-check="${httpStatusCheck}" regexp="Not Found"/> </health:Restart> </cluster> child of <cluster> javadoc <health:IfNotRecent>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:HttpStatusHealthCheck ee:Named="httpStatusCheck"> <url>http://localhost:8080/test-ping.jsp</url> </health:HttpStatusHealthCheck> <health:DumpHeap> <health:IfHealthCritical healthCheck="${httpStatusCheck}"/> <health:IfNotRecent time='5m'/> </health:DumpHeap> </cluster> child of <cluster> javadoc <health:IfRecovered>
Qualifies an action to match upon recovery. Recovery is defined as the state change from FATAL, CRITICAL, or WARNING to OK.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:SendMail> <to>admin@yourdomain</to> <health:IfRecovered health-check="${cpuHealthCheck}"/> </health:SendMail> </cluster> child of <cluster> javadoc <health:IfRechecked>
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 .
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:IfHealthFatal/> <health:IfRechecked/> </health:Restart> </cluster> child of <cluster> javadoc <health:IfUptime>
Qualifies an action to match an amount of time after startup.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:IfUptime limit="12h"/> </health:Restart> </cluster> child of <cluster> javadoc <health:JmxDeltaMeter>
Creates a meter that graphs the difference between the current and previous values of a numeric JMX MBean attribute.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:JmxDeltaMeter> <name>JVM|Compilation|Compilation Time</name> <object-name>java.lang:type=Compilation</object-name> <attribute>TotalCompilationTime</attribute> </health:JmxDeltaMeter> </cluster> child of <cluster> javadoc <health:JmxMeter>
Creates a meter that graphs the current value of a numeric JMX MBean attribute.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:JmxMeter> <name>OS|Memory|Physical Memory Free</name> <object-name>java.lang:type=OperatingSystem</object-name> <attribute>FreePhysicalMemorySize</attribute> </health:JmxMeter> </cluster> child of <cluster> javadoc <health:JvmDeadlockHealthCheck>
Monitors for deadlocked threads, as determined by the JVM.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:JvmDeadlockHealthCheck/> </cluster> child of <cluster> javadoc <health:LicenseHealthCheck>
Checks for expiring Resin Pro license.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:LicenseHealthCheck> <warning-period>30D</warning-period> </health:LicenseHealthCheck> </cluster> javadoc <health:LogService>
Stores high-priority log messages in a database for resin-admin and PDF reports.
<resin xmlns="http://caucho.com/ns/resin" xmlns:health="urn:java:com.caucho.health"> <health:LogService level="info" expire-timeout="14d"/> ... </resin> child of <cluster>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:MemoryPermGenHealthCheck> <memory-free-min>1m</memory-free-min> <free-warning>0.01</free-warning> </health:MemoryPermGenHealthCheck> </cluster> child of <cluster>
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:
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:MemoryTenuredHealthCheck> <memory-free-min>1m</memory-free-min> <free-warning>0.01</free-warning> </health:MemoryTenuredHealthCheck> </cluster> child of <cluster> javadoc <health:Nand>
Qualifies an action to match if all of the child predicates fail.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:Nand> <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/> <health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/> </health:Nand> </health:Restart> </cluster> child of <cluster> javadoc <health:Nor>
Qualifies an action to match if none of the child predicates match.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:Nor> <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/> <health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/> </health:Nor> </health:Restart> </cluster> child of <cluster> javadoc <health:Not>
Qualifies an action to match if the child predicate is false.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/> <health:Not> <health:IfCron> <enable-at>0 7 * * *</enable-at> <disable-at>0 11 * * *</disable-at> </health:IfCron> </health:Not> </health:Restart> </cluster> child of <cluster> javadoc <health:OnAbnormalStop>
Qualifies an action to match only when Resin is stopping with an non-OK exit code.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:PdfReport snapshot='true'> <health:OnAbnormalStop/> </health:PdfReport </cluster> child of <cluster> javadoc <health:OnRestart>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:SendMail> <to>admin@yourdomain.com</to> <health:OnRestart/> </health:SendMail> </cluster> child of <cluster> javadoc <health:OnStart>
Qualifies an action to match only when Resin is starting.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:SendMail> <to>admin@yourdomain.com</to> <health:OnStart/> </health:SendMail> </cluster> child of <cluster> javadoc <health:OnStop>
Qualifies an action to match only when Resin is stopping.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:SendMail> <to>admin@yourdomain.com</to> <health:OnStop/> </health:SendMail> </cluster> child of <cluster> javadoc <health:Or>
Qualifies an action to match if any of the child predicates match.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart> <health:Or> <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/> <health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/> </health:Or> </health:Restart> </cluster> child of <cluster> javadoc <health:PdfReport>
Health action to generate a PDF report from a PHP script.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:PdfReport> <path>${resin.home}/doc/admin/pdf-gen.php</path> <report>Summary</report> <period>7D</report> <health:IfCron value="0 0 * * 0"/> </health:PdfReport> </cluster> child of <cluster> javadoc <health:Restart>
Restart Resin. Resin will exit with the reason HEALTH.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Restart/> </cluster> child of <cluster> javadoc <health:ScoreboardReport>
Produces a concise thread activity report for groups of related threads. Note: A scoreboard report can also be produced using the command line.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:ScoreboardReport> <health:OnAbnormalStop/> </health:ScoreboardReport> </cluster> child of <cluster> javadoc <health:SetJmxAttribute>
Sets a JMX attribute to a value. Note: Setting a JMX attribute can also be performed on-demand using the command line.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:SetJmxAttribute> <objectName>java.lang:type=ClassLoading</objectName> <attribute>Verbose</attribute> <value>true</value> <health:OnStart/> </health:SetJmxAttribute> </cluster> child of <cluster> javadoc <health:SendMail>
Send an email containing a summary of the current Resin health status.
Without the parameter, the default behaviour for sending mail is to contact an SMTP server at host 127.0.0.1 (the localhost) on port 25. System properties can be used to configure a different SMTP server.<system-property mail.smtp.host="127.0.0.1"/> <system-property mail.smtp.port="25"/> <cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:SendMail> <to>admin@yourdomain.com</to> <to>another_admin@yourdomain.com</to> <from>resin@yourdomain.com</from> <health:SendMail> </cluster> Much more advanced SMTP options can be set by configuring a <mail> resource to use for sending health alerts. <cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <mail name="healthMailer"> <smtp-host>mail.yourdomain.com</smtp-host> <smtp-port>25</smtp-port> <from>resin@yourdomain.com</from> </mail> <health:SendMail mail="${healthMailer}"> <to>admin@yourdomain.com</to> <health:SendMail> </cluster> child of <cluster> javadoc <health:SetJmxAttribute>
Sets a JMX attribute to a value. Note: Setting a JMX attribute can also be performed on-demand using the command line.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:SetJmxAttribute> <objectName>java.lang:type=ClassLoading</objectName> <attribute>Verbose</attribute> <value>true</value> <health:OnStart/> </health:SetJmxAttribute> </cluster> child of <cluster> javadoc <health:Snapshot>
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.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:Snapshot> <health:OnAbnormalStop/> </health:Snapshot> </cluster> child of <cluster> javadoc <health:StartProfiler>
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 command line, and from /resin-admin.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:ActionSequence> <health:FailSafeRestart timeout="10m"/> <health:DumpThreads/> <health:DumpHeap/> <health:StartProfiler active-time="5m"/> <health:Restart/> <health:IfHealthCritical time="5m"/> </health:ActionSequence> </cluster> child of <cluster> javadoc <health:TransactionHealthCheck>
Monitors the Resin transaction manager for commit failures.
<cluster xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:health="urn:java:com.caucho.health" xmlns:ee="urn:java:ee"> <health:TransactionHealthCheck/> </cluster> child of <home-cluster>
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. element home-cluster { string } child of <cluster>
<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 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> <web-app id="/" root-directory="webapps/ROOT"> </web-app> ... </host> <host regexp="([^.]+)\.foo\.com"> <host-name>${host.regexp[1]}.foo.com</host-name> <root-directory>/var/resin/hosts/www.${host.regexp[1]}.com</root-directory> ... </host> child of <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. element host-alias { string } <resin xmlns="http://caucho.com"> <cluster id=""> <host id="www.foo.com" root-directory="/var/resin/foo.com"> <host-alias>foo.com</host-alias> <web-app id=""/> </host> </cluster> </resin> <host xmlns="http://caucho.com"> <host-name>www.foo.com</host-name> <host-alias>foo.com</host-alias> <web-app id="" root-directory="htdocs"/> </host> child of <host>
<host-alias-regexp> defines a regular expression for matching URLs for a given virtual host. element host-alias-regexp { string } <resin xmlns="http://caucho.com"> <cluster id=""> <host id="www.foo.com" root-directory="/var/resin/foo.com"> <host-alias-regexp>.*foo.com</host-alias-regexp> <web-app id=""/> </host> </cluster> </resin> child of <cluster>
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 <cluster>
<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.
element host-deploy { archive-directory? & expand-cleanup-fileset? & expand-directory? & host-default? & host-name? & path? } The following example configures as a host deployment directory. Each virtual host will have a directory for .war deployment. So the directory would serve the URL .<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <root-directory>/var/resin</root-directory> <host-deploy path="hosts"> <host-default> <resin:import path="host.xml" optional="true"/> <web-app-deploy path="webapps"/> </host-default> </host-deploy> </cluster> </resin> child of <host>
<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. element host-name { string } child of <server>
<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 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.
element http { (id | server-id) & (address | host )? & port? & accept-listen-backlog? & accept-thread-idle-timeout? & accept-thread-min? & accept-thread-max? & connection-max? & keepalive-connection-time-max? & keepalive-max? & keepalive-select-enable? & keepalive-select-thread-timeout? & keepalive-timeout? & secure? & socket-timeout? & suspend-reaper-timeout? & suspend-time-max? & tcp-no-delay? & throttle-concurrent-max? & virtual-host? & (openssl | jsse-ssl)? } child of <web-app>
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. element idle-time { r_period-Type } child of <cluster>
default trueignore-client-disconnect configures whether Resin should ignore disconnection exceptions from the client, or if it should send those exceptions to the application. element ignore-client-disconnect { r_boolean-Type } child of <cluster>
default 8192Configures 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. element invocation-cache-size { r_int-Type } child of <cluster>
default 256Configures the longest entry cacheable in the invocation cache. It is used to avoid certain types of denial-of-service attacks. element invocation-cache-max-url-length { r_int-Type } <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:
element javac { args* & compiler & encoding? & max-batch? } <resin xmlns="http://caucho.com/ns/resin"> <javac compiler="internal" args=""/> </resin> <resin xmlns="http://caucho.com/ns/resin"> <javac compiler="javac" args=""/> ... </resin> <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.
element jndi-link { jndi-name & factory? & foreign-name? & init-param* } <web-app xmlns="http://caucho.com/ns/resin"dd> <database jndi-name="jdbc/oracle"> ... </database> <jndi-link jndi-name="java:comp/env/jdbc/gryffindor"> <foreign-name>java:comp/env/jdbc/oracle</foreign-name> </jndi-link> <jndi-link jndi-name="java:comp/env/jdbc/slytherin"> <foreign-name>java:comp/env/jdbc/oracle</foreign-name> </jndi-link> </web-app> <web-app xmlns="http://caucho.com/ns/resin"> <jndi-link jndi-name='java:comp/env/ejb'> <factory>com.caucho.ejb.hessian.HessianContextFactory</factory> <init-param java.naming.provider.url='http://ejb.hogwarts.com:80/hessian'/> </jndi-link> </web-app> <web-app xmlns="http://caucho.com/ns/resin"> <jndi-link jndi-name='java:comp/env/remote-ejb'> <factory>com.caucho.ejb.hessian.HessianContextFactory</factory> <init-param java.naming.provider.url='http://ejb.hogwarts.com:80/hessian'/> </jndi-link> <jndi-link jndi-name="java:comp/env/ejb/Foo"> <foreign-name>java:comp/env/remote-ejb/Foo</foreign-name> </jndi-link> <jndi-link jndi-name="java:comp/env/ejb/Bar"> <foreign-name>java:comp/env/local-ejb/Bar</foreign-name> </jndi-link> </web-app>
element jpa-persistence { create-database-schema? & cache-size? & cache-timeout? & data-source? & jdbc-isolation? & persistence-unit* & persistence-unit-default* & read-data-source? & validate-database-schema? & xa-data-source? } element persistence-unit { name & jta-data-source? & non-jta-data-source? & provider? & transaction-type? & properties? } element persistence-unit-default { & jta-data-source? & non-jta-data-source? & provider? & transaction-type? & properties? } element properties { element property { name & value }* } Replacement for jpa-persistence. child of <web-app>
Configures JSP behavior.
element jsp { auto-compile & deferred-syntax-allowed-as-literal? & dependency-check-interval? & el-ignored? & fast-jstl? & ide-hack? & ignore-el-exception? & is-xml? & page-encoding? & precompile? & print-null-as-blank? & recompile-on-error? & recycle-tags? & require-source? & scripting-invalid? & session? & static-page-generates-class? & tld-dir? & tld-file-set? & trim-directive-whitespaces? & validate-taglib-schema? & velocity-enabled? } <jsp-config> configure standard settings for JSP files.
element jsp-config { taglib*, jsp-property-group* } element jsp-property-group { url-pattern*, deferred-syntax-allowed-as-literal?, el-ignored?, page-encoding? scripting-invalid? trim-directive-whitespaces? is-xml? include-prelude* include-coda* } child of <server>
<jvm-arg> configures JVM arguments to be passed to Resin on the command line, typically -X memory parameters and -D defines. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <jvm-arg>-Xmx512m</jvm-arg> <jvm-arg>-Xss1m</jvm-arg> <jvm-arg>-verbosegc</jvm-arg> </server-default> <server id="app-a" address="192.168.2.10"/> ... </cluster> </resin> child of <server>
<jvm-classpath> adds a classpath entry when starting the JVM. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <jvm-classpath>/tmp/test-classpath</jvm-classpath> </server-default> <server id="app-a" address="192.168.2.10"/> ... </cluster> </resin> child of <server>
default 100<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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <http port="80"/> <thread-max>512</thread-max> <keepalive-max>100</keepalive-max> </server-default> <server id="web-a" address="192.168.0.10"/> ... </cluster> </resin> child of <server>
default true<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. child of <server>
default 1s<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. child of <server>
default 15s<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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <http port="80"/> <thread-max>512</thread-max> <keepalive-max>100</keepalive-max> <keepalive-timeout>15s</keepalive-timeout> </server-default> <server id="web-a" address="192.168.0.10"/> ... </cluster> </resin> <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. element lazy-servlet-validate { r_boolean-Type } child of <class-loader>
<library-loader> configures a jar library, -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 See DirectoryLoader.
element library-loader { fileset | path } element fileset { dir & exclude* & include* } <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.
element listener { listener-class, init? } child of <server>
default 5s<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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server-default> <load-balance-connect-timeout>2s</load-balance-connect-timeout> </server-default> <server id="a" address="192.168.0.10" port="6800"/> <server id="b" address="192.168.0.11" port="6800"/> <host id=""> ... </cluster> </resin> child of <server>
default 15s<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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server-default> <load-balance-recover-time>10s</load-balance-recover-time> </server-default> <server id="a" address="192.168.0.10" port="6800"/> <server id="b" address="192.168.0.11" port="6800"/> <host id=""> ... </cluster> </resin> child of <server>
default keepalive-timeout - 1s<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 cluster-port. value of the targetThe 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. child of <server>
default 60sThe 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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server-default> <load-balance-warmup-time>60s</load-balance-warmup-time> </server-default> <server id="a" address="192.168.0.10" port="6800"/> <server id="b" address="192.168.0.11" port="6800"/> <host id=""> ... </cluster> </resin> child of <server>
default 100load-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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server id="a" address="192.168.0.10" port="6800"/> <server id="b" address="192.168.0.10" port="6800"/> <server id="test" address="192.168.0.100" port="6800"> <load-balance-weight>1</load-balance-weight> </server> <host id=""> ... </cluster> </resin> child of <web-app>
default no authenticationConfigures the login method for authentication, one of BASIC, DIGEST or FORM. See also: Resin security for an overview.
HTTP Authentication is defined in the RFC HTTP Authentication: Basic and Digest. HTTP digest authentication is discussed in Digest Passwords. element login-config { class? & auth-method? & authenticator? & form-login-config? & init? & realm-name? 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.
element log-handler { archive-format? & class? & filter? & format? & formatter? & level? & mbean-name? & name & path? & path-format? & rollover-count? & rollover-period? & rollover-size? & timestamp? & use-parent-handlers? } The following example is a standard log handler writing to a rollover file. Because the handler's level is "all", the <logger> configuration will set the actual logging level. <web-app xmlns="http://caucho.com/ns/resin"> <log-handler name="" level="all" timestamp="[%Y/%m/%d %H:%M:%S.%s] {%{thread}} "/> <logger name="com.caucho" level="info"/> </web-app> <log> configures JDK 1.4 java.util.logger Logger level. The log configuration describes log in detail.
element logger { name & level? & use-parent-handlers? } <resin xmlns="http://caucho.com/ns/resin"> <log name="" level="all" path="log/debug.log"/> <logger name="com.caucho.java" level="fine"/> <cluster id="app-tier"> ... </cluster> </resin> <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:MemoryQueue ee:Named="myQueue"/> <logger name="qa.test"> <resin:JmsLogHandler level="warning"> <target>${myQueue}</target> <resin:TimestampLogFormatter/> </resin:JmsLogHandler> </logger> </web-app> The <log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]" format=" ${log.level} ${log.loggerName} ${log.message}"/>
You can also use the Environment EL variables in your format string: <host ...> <web-app> <log name='' level='all' path='log/debug.log' timestamp="[%H:%M:%S.%s]" format=" [${app.contextPath}] ${log.message}"/> ... </web-app> ... </host> [14:55:10.189] [/foo] `null' returning JNDI java: model for EnvironmentClassLoader[web-app:http://localhost:8080/foo] [14:55:10.189] [/foo] JNDI lookup `java:comp/env/caucho/auth' exception javax.naming.NameNotFoundException: java:comp/env/caucho/auth [14:55:10.199] [/foo] Application[http://localhost:8080/foo] starting The fmt.sprintf() function can space pad the values and make the results look a little nicer: <log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]" format=" ${fmt.sprintf('%-7s %45s %s',log.level,log.loggerName,log.message)}"/> [14:28:08.137] INFO com.caucho.vfs.QJniServerSocket Loaded Socket JNI library. [14:28:08.137] INFO com.caucho.server.port.Port http listening to *:8080 [14:28:08.137] INFO com.caucho.server.resin.ServletServer ServletServer[] starting [14:28:08.307] INFO com.caucho.server.port.Port hmux listening to localhost:6802 [14:28:08.437] INFO com.caucho.server.host.Host Host[] starting fmt.sprintf() and fmt.timestamp() can be used to produce CSV files: <log name='' level='all' path='log/debug.csv' timestamp="" format="${fmt.sprintf('%vs,%d,%d,%vs,%vs',fmt.timestamp('%Y-%m-%d %H:%M:%S.%s'), log.threadID, log.level.intLevel(), log.loggerName, log.message)}"/> "2003-11-17 14:46:14.529",10,800,"com.caucho.vfs.QJniServerSocket", "Loaded Socket JNI library." "2003-11-17 14:46:14.549",10,800,"com.caucho.server.port.Port", "http listening to *:8080" "2003-11-17 14:46:14.549",10,800,"com.caucho.server.resin.ServletServer", "ServletServer[] starting" "2003-11-17 14:46:14.719",10,800,"com.caucho.server.port.Port", "hmux listening to localhost:6802" "2003-11-17 14:46:14.850",10,800,"com.caucho.server.host.Host", "Host[] starting" "2003-11-17 14:46:15.100",10,800,"com.caucho.server.webapp.Application", "Application[http://localhost:8080/freelistbm] starting" <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.
element mail { authenticator? & debug? & from? & host? & imap-host? & imap-port? & imap-user? & init? & jndi-name? & name? & pop3-host? & pop3-port? & pop3-user? & smtp-host? & smtp-port? & smtp-user? & store-protocol? & transport-protocol? & user? } <web-app xmlns="http://caucho.com/ns/resin"> <mail jndi-name="java:comp/env/mail"> <from>noreply@foo.com</from> <smtp-host>localhost</smtp-host> <smtp-port>25</smtp-port> <properties> mail.smtp.starttls.enable=true </properties> </mail> </web-app> child of <database>
default 6h<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. child of <database>
default 256<max-close-statements> configures how many open statements Resin
should save to for the connection close. Since the JDBC
child of <database>
default 1024<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 child of <database>
default 5<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. child of <database>
default 60s<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. child of <database>
default 1024<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. child of <database>
default 24h<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. child of <cluster>
default 1024Sets limit on longest URIs that can be served by Resin. element max-uri-length { r_int-Type } child of <server>
default 1m<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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <thread-max>512</thread-max> <memory-free-min>1m</memory-free-min> </server-default> <server id="web-a" address="192.168.0.10"/> ... </cluster> </resin> child of <web-app>
Maps url patterns to mime-types.
element mime-mapping { extension, mime-type } <web-app xmlns="http://caucho.com/ns/resin"> <mime-mapping> <extension>.foo</extension> <mime-type>text/html</mime-type> </mime-mapping> <!-- resin shortcut syntax --> <mime-mapping extension='.bar' mime-type='text/html'/> </web-app> Resin has a long list of default mime types in child of <web-app>
Enables multipart-mime for forms and file uploads. multipart-mime is disabled by default. For an uploaded file with a form name of , the parameter value contains the path name to a temporary file containing the uploaded file. contains the uploaded filename, and contains the content-type of the uploaded file.
If the upload is larger than the limit or if multipart-form processing is disabled, Resin will not parse the request and will set an error message in the " " request attribute. The " " will contain the attempted upload size.Requests can set the maximum by setting the request attribute " " with an Integer or Long value.By default, multipart-form is disabled. element multipart-form { enable? & upload-max? } <openssl> configures the port to use OpenSSL for SSL support (requires Resin Professional). OpenSSL is a fast C implementation of SSL security used by Apache. Resin's configuration is OpenSSL follows Apache's configuration, so any documentation on installing SSL certificates can use documentation for Apache. The SSL section of the Security documentation provides a comprehensive overview of SSL.
child of <web-app>
Maps url patterns to real paths. If using a server like IIS, you may need to match the server's path aliases.
element path-mapping { (url-pattern | url-regexp) & real-path } <web-app xmlns="http://caucho.com/ns/resin"> <path-mapping url-pattern='/resin/*' real-path='e:\resin'/> <path-mapping url-regexp='/~([^/]*)' real-path='e:\home\$1'/> </web-app> child of <database>
<password> configures the database connection password. Sites requiring additional security for their passwords can use the <mypkg:MyDecryptor/> syntax to configure a password decoder. child of <cluster>
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 xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <cluster id="app-tier"> <ping url="http://localhost/"/> ... </cluster> </resin> <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> ... <cluster id="app-tier"> <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> ... </cluster> </resin> The class that corresponds to <ping> is PingThread. Mail notification when ping failsA refinement of the ping facility sends an email when the server is restarted. <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <cluster id="web-tier"> <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> The default behaviour for sending mail is to contact a SMTP server at host 127.0.0.1 (the localhost) on port 25. System properties are used to configure a different SMTP server. <system-property mail.smtp.host="127.0.0.1"/> <system-property mail.smtp.port="25"/> child of <database>
default false<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>. child of <database>
<ping-table> configures the database table Resin should use to verify if a connection is still valid when returned from the pool. child of <database>
<ping-query> specifies the query to use for validating if a database connection is still valid when returned from the idle pool. child of <database>
default 1s<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. child of <server>
default 6800The 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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server id="app-a" address="192.168.1.11" port="6800"/> <server id="app-b" address="192.168.1.11" port="6801"/> <server id="app-b" address="192.168.2.12" port="6800"/> <server id="app-c" address="192.168.2.12" port="6801"/> ... </cluster> </resin> child of <server>
Defines default port parameters for all <http>, <protocol>, and <cluster-port>. See the description of <http>. for the attributes that can be configured. child of <database>
default 0<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.
element protocol { (class | uri) & init? } child of <web-app>
default 60s<redeploy-check-interval> specifies how often Resin should check if a .war file has been updated or added to a <web-app-deploy> directory. element redeploy-check-interval { r_period-Type } child of <web-app>
default automatic<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.
element redeploy-mode { automatic | manual } <rewrite-real-path> lets you rewrite the URL to physical path mapping, to allow aliasing or for filesystem organization.
element rewrite-real-path { element rewrite { regexp & replacement }* & element rewrite { regexp & target }* } <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-real-path> <real-path regexp="^/foo" target="/bar"/> </rewrite-real-path> </web-app> 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. element root-directory { r_path-Type } <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <root-directory>/var/resin/app-tier</root-directory> <server id="a" ...> <host host-name="www.foo.com"> </cluster> </resin> <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.
element reference { factory & jndi-name & init-param* } <web-app xmlns="http://caucho.com/ns/resin"> <reference> <jndi-name>hessian/hello</jndi-name> <factory>com.caucho.hessian.client.HessianProxyFactory</factory> <init url="http://localhost:8080/ejb/hello"/> type="test.HelloHome"/> </reference> </web-app> <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: , where location is typically a HTTP URL.
element remote-client { (class|uri) & name? & jndi-name? & interface } <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.
element resin {
& cluster*
& cluster-default*
& environment-system-properties?
& management?
& min-free-memory?
& root-directory?
& security-manager?
& security-provider?
& watchdog-manager?
}
<resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <root-directory>/var/resin</root-directory> <cluster id="web-tier"> <server id=""> <http address="*" port="8080"/> </server> <resin:import path="app-default.xml"/> <host id=""> <web-app id="" root-directory="/var/resin/htdocs"/> </host> </cluster> </resin> child of <resin>
<resin-system-auth-key> specifies authorization token for Resin's Security service. element resin-system-auth-key { String } javadoc <resin:AdminAuthenticator>
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.
child of <web-app> javadoc <resin:Allow>
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.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:Allow url-pattern="/*"> <resin:IfUserInRole role="user"/> </resin:Allow> ... </web-app> javadoc <resin:And>
Matches if all children match. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp="" target="/match"> <resin:And> <resin:IfQueryParam name="foo" regexp="foo"/> <resin:IfQueryParam name="bar" regexp="bar"/> </resin:And> </resin:Redirect> </web-app> child of <web-app> javadoc <resin:BasicLogin>
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. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:BasicLogin/> <resin:Allow url-pattern="/foo/*"> <resin:IfUserInRole role="user"/> </resin:Allow> <resin:XmlAuthenticator> ... </resin:XmlAuthenticator> </web-app> javadoc <resin:ByteStreamCache>
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.
element resin:choose { resin:when*, resin:otherwise } element resin:when { attribute test { string },} element resin:otherwise { } <resin:choose> <resin:when test="${expr1}"> ... </resin:when> <resin:when test="${expr2}"> ... </resin:when> <resin:otherwise> ... </resin:otherwise> <resin:choose> javadoc <resin:ClusterCache>
Distributed caching is a useful technique to reduce database load and increase application performance. Resin provides a javax.cache.Cache (JSR-107 JCache) based distributed caching API. Distributed caching in Resin uses the underlying infrastructure used to support load balancing, clustering and session/state replication.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:distcache="urn:java:com.caucho.distcache"> <distcache:ClusterCache ee:Named="myCacheEE"> <name>myCache</name> </distcache:ClusterCache>> </web-app> You may then inject the cache through CDI and use it in your application via the JCache API: import javax.cache.*; import javax.inject.*; public class MyService { @Inject @Named("myCacheEE") private Cache<String,String> _cache; public void test() { _cache.putIfAbsent("foo", "bar"); } } javadoc <resin:ClusterQueue>
Clustered queue. javadoc <resin:ClusterSingleSignon>
Cluster-based single signon. javadoc <resin:DatabaseAuthenticator>
The DatabaseAuthenticator asks a back-end relational database for the password matching a user's name. It uses the DataSource specified by the configured DataSource. attribute. refers to an existing
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <-- Authentication mechanism --> <resin:BasicLogin/> <-- Role-based authorization --> <resin:Allow url-pattern="/foo/*"> <resin:IfUserInRole role="user"/> </resin:Allow> <-- The authenticator --> <resin:DatabaseAuthenticator'> <resin:data-source>test</resin:data-source> <resin:password-query> SELECT password FROM login WHERE username=? </resin:password-query> <resin:cookie-auth-query> SELECT username FROM LOGIN WHERE cookie=? </resin:cookie-auth-query> <resin:cookie-auth-update> UPDATE LOGIN SET cookie=? WHERE username=? </resin:cookie-auth-update> <resin:role-query> SELECT role FROM LOGIN WHERE username=? </resin:role-query> </resin:DatabaseAuthenticator> </web-app> javadoc <resin:Deny>
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.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <!-- protect all .properties files --> <resin:Deny url-pattern="*.properties"/> <!-- protect the config/ subdirectory --> <resin:Deny url-pattern="/config/*"/> ... </web-app> child of <web-app> javadoc <resin:DigestLogin>
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:
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. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:DigestLogin/> ... </web-app> javadoc <resin:Dispatch>
Normal servlet dispatching with optional target rewriting.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Dispatch regexp="\.(jpg|html|txt|gif|png|js|css)$"/> <resin:Dispatch regexp="^" target="/controller"/> </web-app> javadoc <resin:ElasticCloudService>
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. javadoc <resin:FastCgiPort>
FastCGI requests, e.g. from nginx. javadoc <resin:FastCgiProxy>
Proxies the request to a backend server using FastCGI as a proxy protocol.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:FastCgiProxy regexp="\.rb$"> <address>127.0.0.1:12345</address> <address>127.0.0.1:67890</address> </resin:FastCgiProxy> </web-app> javadoc <resin:FileQueue>
Filesystem based queue. javadoc <resin:FileTopic>
Filesystem based topic. javadoc <resin:Forbidden>
Send a HTTP forbidden response.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Forbidden regexp="/foo"> <resin:Not> <resin:IfSecure/> </resin:Not> </resin:Forbidden> </web-app> javadoc <resin:FormLogin>
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 . It must also have the parameters and holding the username and password. Optionally, it can also have and . 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 page regardless of what the originally requested page was. If the attribute is set to false (the default), the page is only used when the originally requested page was the login page itself. allows Resin to send a persistent cookie to the client to make subsequent logins automatic. When 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:
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:FormLogin form-login-page="/login.html" form-error-page="/login_failure.html"/> ... </web-app> <form action='j_security_check' method='POST'> <table> <tr><td>User:<td><input name='j_username'> <tr><td>Password:<td><input name='j_password'> <tr><td colspan=2>hint: the password is 'quidditch' <tr><td><input type=submit> </table> </form> javadoc <resin:Forward>
Forwards to the new URL using RequestDispatcher.forward with the target URL.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Forward regexp='^/foo' target='/bar/'/> </web-app> javadoc <resin:GlobalCache>
JCache-style distributed object cache across the entire Resin system. javadoc <resin:HttpProxy>
Proxies the request to a backend server using HTTP as a proxy protocol.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:HttpProxy regexp="\.cgi$"> <strategy>adaptive</strategy> <backend address="127.0.0.1:12345" weight="100"> <backend address="127.0.0.1:65432" weight="200"> </resin:HttpProxy> </web-app> 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.
element resin:if {
attribute test { string }
}
<resin xmlns="http://caucho.com/ns/resin" xmlns:core="http://caucho.com/ns/resin/core"> <resin:if test="${system['development']}"> <logger name="com.foo" level="finer"/> </resin:if> ... </resin> javadoc <resin:IfAuthType>
Checks for the authentication type, request.getAuthType().
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp='^/user-area' target='/secret'> <resin:IfAuthType value="BASIC"/> </resin:Redirect> <resin:Redirect regexp='^/user-area' target='/login'/> <resin:XmlAuthenticator password-digest='none'> <user name="Aladdin" password="open sesame" group="user"/> </resin:XmlAuthenticator> <resin:BasicLogin realm-name="foobar"/> </web-app> javadoc <resin:IfCookie>
Checks for the presence of a named HTTP cookie from request.getCookies().
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp='^/welcome' target='/user-area'> <resin:IfCookie name="session"/> </resin:Redirect> </web-app> javadoc <resin:IfCron>
Matches if the current time is in an active range configured by cron-style times.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp='^/live-support' target='/hours'> <resin:IfCron> <resin:enable-at>0 17 * * *</resin:enable-at> <resin:disable-at>0 8 * * *</resin:disable-at> </resin:IfCron> </resin:Redirect> </web-app> javadoc <resin:IfFileExists>
Matches if the URL corresponds to an actual file. Has no attributes. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Dispatch> <resin:IfFileExists/> </resin:Dispatch> <resin:Redirect regexp="^" target='/does-not-exist'/> </web-app> javadoc <resin:IfHeader>
Tests for a HTTP header and value match.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp='^/foo' target='/foo-for-example-customers'> <resin:IfHeader name="Referer" value="example.com"/> </resin:Redirect> <resin:Redirect regexp='^/foo' target='/everyone-else'/> </web-app> javadoc <resin:IfLocale>
Tests for a Locale match from the HTTP request (Accept-Language header).
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp='^/your-lang' target='/francais'> <resin:IfLocale value="fr"/> </resin:Redirect> <resin:Redirect regexp='^/your-lang' target='/default'/> </web-app> javadoc <resin:IfLocalPort>
Compares the local port of the request, request.getLocalPort().
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp='^/foo' target='/match-5555'> <resin:IfLocalPort value="5555"/> </resin:Redirect> <resin:Redirect regexp='^/foo' target='/match-6666'> <resin:IfLocalPort value="6666"/> </resin:Redirect> <resin:Redirect regexp='^/foo' target='/no-match'/> </web-app> javadoc <resin:IfMBeanEnabled>
Matches if a MBean is enabled().
The mbean name will be something like: resin:type=IfMBeanEnabled,name=my-name,Host=www.example.com,WebApp=/ The following example redirects URLs to a maintenance page if an mbean is enabled. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp='^/foo' target='/scheduled-maintenance.jsp'> <resin:IfMBeanEnabled name="maintenance" enabled="false"/> </resin:Redirect> </web-app> javadoc <resin:IfMethod>
Compares the HTTP method, request.getMethod().
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp='^/foo' target='/foo/post'> <resin:IfMethod value="POST"/> </resin:Redirect> </web-app> javadoc <resin:IfNetwork>
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.
The <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:Allow url-pattern="/admin/*"> <resin:IfNetwork value="192.168.17.0/24"/> </resin:Allow> ... </web-app> The following example shows how the tag can be used to construct an IP block list: <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:Deny> <resin:IfNetwork> <resin:value>205.11.12.3</resin:value> <resin:value>213.43.62.45</resin:value> <resin:value>123.4.45.6</resin:value> <resin:value>233.15.25.35</resin:value> <resin:value>233.14.87.12</resin:value> </resin:IfNetwork> </resin:Deny> ... </web-app> Be careful with deny - some ISP's (like AOL) use proxies and the IP of many different users may appear to be the same IP to your server. If only javadoc <resin:IfQueryParam>
Tests for a HTTP query parameger, request.getParameter().
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp='^/foo' target='/login'> <resin:IfQueryParam name="area" value="login"/> </resin:Redirect> </web-app> javadoc <resin:IfRemoteUser>
Tests against the remote user, request.getRemoteUser().
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Forbidden regexp="/harry"> <resin:Not> <resin:IfRemoteUser value="harry"/> </resin:Not> </resin:Forbidden> <resin:XmlAuthenticator> <user>harry:H83FykjQaBwvqjGRyIRUHQ==:user</user> </resin:XmlAuthenticator> <resin:BasicLogin realm-name='global'/> </web-app> javadoc <resin:IfSecure>
The <resin:IfSecure> tag restricts access to secure transports, usually SSL.
In the following example, all pages in the web application are enforced to be accessible via SSL only. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" ... <resin:Allow> <resin:IfSecure/> </resin:Allow> ... </web-app> The default behaviour is for Resin to rewrite any URL that starts with "http:" by replacing the "http:" part with "https:", and then send a redirect to the browser because this configuration. If the default rewriting of the host is not appropriate, you can set the <secure-host-name> for the host: <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> ... <host id="..."> <secure-host-name>https://hogwarts.com</secure-host-name> ... </resin> javadoc <resin:IfUserInRole>
The <resin:IfUserInRole> condition enforces role-based security. It requires that authenticated users have a specified role.
The following is an example of how <resin:IfUserInRole> might be used: <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:Allow url-pattern="/webdav/*"> <resin:IfUserInRole role='webdav'/> </resin:Allow> ... </web-app> <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>.
element import { (path | fileset) & optional? } element fileset { dir & exclude* & include* } The following example shows how Resin implements the WEB-INF/web.xml and WEB-INF/resin-web.xml files. Both are simply resin:import in a web-app-default. When Resin configures the web-app, it will process the web-app-default program, and call resin:import for the web.xml file. <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <cluster id="app-tier"> <web-app-default> <resin:import path="WEB-INF/web.xml" optional="true"/> <resin:import path="WEB-INF/resin-web.xml" optional="true"/> </web-app-default> </cluster> </resin> Virtual hosts can use resin:import to add a custom host.xml file. The host.xml can use any <host> attribute, including <host-name> and <host-alias> to customize the virtual host configuration. <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <cluster id="app-tier"> <host-deploy path="/var/resin/hosts"> <host-default> <resin:import path="host.xml" optional="true"/> <web-app-deploy path="webapps"/> </host-default> </web-app-default> </cluster> </resin> Some applications may want to split their configuration into multiple files using the fileset. For example, a Resin-IoC application might want to define beans in WEB-INF/beans/*.xml and give the web-app flexibility in which bean files to create. <web-app xmlns="http://caucho.com/ns/resin" xmlns:core="http://caucho.com/ns/resin/core"> <resin:import> <fileset dir="WEB-INF/beans"> <include>*.xml</include> </fileset> </resin:import> </web-app> javadoc <resin:JaasAuthenticator>
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.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:JaasAuthenticator> <resin:login-module>com.sun.security.auth.module.Krb5LoginModule</resin:login-module> <resin:init-param> <debug>true</debug> </resin:init-param> </resin:JaasAuthenticator> ... </web-app> javadoc <resin:JmsConnectionFactory>
Combined Queue and Topic ConnectionFactory. javadoc <resin:JmxService>
Enables cluster-wide JMX administration. javadoc <resin:LdapAuthenticator>
The LdapAuthenticator uses JNDI to connect to an LDAP (or Active Directory) server for authentication.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:LdapAuthenticator password-digest="none"> <resin:url>ldap://localhost:389</resin:url> <resin:dn-suffix>dc=hogwarts,dc=com</resin:dn-suffix> </resin:LdapAuthenticator> ... </web-app> jndi-env
The following example shows the usage of the <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:LdapAuthenticator password-digest="none"> <resin:jndi-env java.naming.factory.initial="com.sun.jndi.ldap.LdapCtxFactory"/> <resin:jndi-env java.naming.provider.url="ldap://localhost:389"/> <resin:dn-suffix>dc=hogwarts,dc=com</dn-suffix> </resin:LdapAuthenticator> ... <web-app> javadoc <resin:LoadBalance> <resin:LoadBalance> requires Resin Professional
Load balance to a cluster of backend Resin servers.
<resin xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <cluster id='app-tier'> <server id='a' port='6810'/> <server id='b' port='6820'/> ... </cluster> <cluster id='web-tier'> <server id='http' port='80'/> <host id=''> <resin:LoadBalance cluster="app-tier"/> </host> </cluster> </resin> javadoc <resin:MemoryQueue>
Memory based queue. javadoc <resin:MemorySingleSignon>
Memory-based single signon. javadoc <resin:MemoryTopic>
Memory based topic. Logs a message to the given log file. The content of the element is the message. element resin:message { string } <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <resin:message>Starting server ${server.name}</resin:message> </web-app> javadoc <resin:MovedPermanently>
Send an HTTP redirect to a new URL specified by target.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:MovedPermanently regexp='^/([^/]+)/([^/]+)' target='/$2/$1'/> </web-app> javadoc <resin:Not>
Matches if the child does not match. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp="" target="/match"> <resin:Not> <resin:IfQueryParam name="foo" regexp="bar"/> </resin:Not> </resin:Redirect> </web-app> javadoc <resin:NotAnd>
Matches if any child does not match. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp="" target="/match"> <resin:NotAnd> <resin:IfQueryParam name="foo" regexp="foo"/> <resin:IfQueryParam name="bar" regexp="bar"/> </resin:NotAnd> </resin:Redirect> </web-app> javadoc <resin:NotOr>
Matches if all the children do not match. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp="" target="/match"> <resin:NotOr> <resin:IfQueryParam name="foo" regexp="foo"/> <resin:IfQueryParam name="bar" regexp="bar"/> </resin:NotOr> </resin:Redirect> </web-app> javadoc <resin:Or>
Matches if any children match. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp="" target="/match"> <resin:Or> <resin:IfQueryParam name="foo" regexp="foo"/> <resin:IfQueryParam name="foo" regexp="bar"/> </resin:Or> </resin:Redirect> </web-app> child of <resin:choose>
<resin:otherwise> is the catch-all configuration for a <resin:choose> block when none of the <resin:when> items match.
element resin:otherwise {
}
javadoc <resin:Password>
Decrypts a configuraion password. resin:Password allows configuration files to avoid plaintext passwords. The password is generated with the command line: unix> resinctl password-encrypt -password changeme password: {RESIN}DRRIvGLXj/kXSznMYcQxzw== <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" ... <database jndi-name="jdbc/test"> <driver ...> ... <password> <resin:Password value="{RESIN}DRRIvGLXj/kXSznMYcQxzw=="/> </password> </driver> ... ... </web-app> javadoc <resin:PingThread>
Checks status of Resin sutomatically. javadoc <resin:PingMailer>
Mails a notification when a ping check fails. javadoc <resin:PingThread>
Checks status of Resin automatically. javadoc <resin:ProjectJarRepository>
Maven-style library jar management for webapps. javadoc <resin:PropertiesAuthenticator>
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.
The following is an example of in-lining properties with the authenticator. This is useful for extremely simple web-sites maintained by developers as well as testing. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:PropertiesAuthenticator password-digest="none"> harry=quidditch,user,admin draco=mudblood,disabled,user </resin:PropertiesAuthenticator> ... </web-app> Alternatively, external properties files can be used as in the example below. This is useful for a simple site where authentication may be managed by administrators or non-technical users. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" ... <resin:PropertiesAuthenticator path="WEB-INF/users.properties"/> ... </web-app> harry=/Tj/54ylCloUeMi2YQIVCQ===,user,admin As the example indicates, the properties file includes the user as property name while the value is the password (that may be hashed as in the example or may be in plain-text) and any roles that are assigned to the user separated by commas. The password and role values are also separated by a comma. javadoc <resin:Redirect>
Send an HTTP redirect to a new URL specified by target.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:Redirect regexp='^/([^/]+)/([^/]+)' target='/$2/$1'/> </web-app> javadoc <resin:RemoteAdminService>
Enables administration by remote agents, like an eclipse console. javadoc <resin:ScheduledTask>
<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 When specified as an Java Injection bean, the bean task has full IoC capabilities, including injection, @TransactionAttribute aspects, interception and @Observes.
<resin:ScheduledTask> <cron>* * * * *</cron> <task> <example:MyClass xmlns:qa="urn:java:com.example"/> </task> </resin:ScheduledTask> <resin:ScheduledTask url="/saturday-maintenance.jsp"> <cron>* * * * 6</cron> </resin:ScheduledTask> javadoc <resin:SendError>
Send a HTTP error response.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:SendError regexp="/upcoming" code="501" message="Not Implemented"/> </web-app> resin:set adds an EL variable to the current context.
element set { var & value & default & attribute * { string } } <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <resin:set var="root" value="/var/resin"/> <cluster id="app-tier"> <root-directory>${root}</root-directory> ... </cluster> </resin> javadoc <resin:SetHeader>
Sets a response header.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:SetHeader regexp="\.jsp$" name="X-External" value="true"> <resin:Not> <resin:IfNetwork> <resin:value>192.168.1.0/24</resin:value> </resin:IfNetwork> </resin:Not> </resin:SetHeader> </web-app> Sets the character encoding of the request parameters. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:SetRequestCharacterEncoding value="ISO-8859-15"/> </web-app> javadoc <resin:SetRequestSecure>
Marks the request as secure.
If the regular expression is omitted, all URLs will require secure connections. <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:SetRequestSecure> <resin:IfNetwork> <resin:value>192.168.1.0/24</resin:value> </resin:IfNetwork> </resin:SetRequestSecure> </web-app> javadoc <resin:SetVary>
Sets the Vary header.
<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> <resin:SetVary regexp="\.jsp" value="Accept"/> </web-app> child of <resin:choose>
<resin:when> conditionally configures a block within a <resin:choose> block. If the matches, Resin will use the enclosed configuration.
element resin:when {
attribute test { string },
}
javadoc <resin:XaLogService> <resin:XaLogService> requires Resin Professional
Transaction log service. javadoc <resin:XmlAuthenticator>
In a similar vein to the properties authenticator, the XML authenticator allows you to store authentication information in XML - either in-line or in an external file. This authenticator has some of the same use-cases as the properties file authenticator, in a slight more human readable form, especially for a non-technical user.
The following example uses in-line XML for authentication. When configuring the XmlAuthenticator in resin.xml (or resin-web.xml), each adds a new configured user. The user value contains the username, password, and the roles for the user.<web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"> ... <resin:XmlAuthenticator password-digest="none"> <resin:user name="Harry Potter" password="quidditch" group="user,gryffindor"/> <resin:user name="Draco Malfoy" password="pureblood" group="user,slytherin"/> </resin:XmlAuthenticator> ... </web-app> This example shows how to use an external XML file for authentication: <web-app xmlns="http://caucho.com/ns/resin"> ... <resin:XmlAuthenticator path="WEB-INF/users.xml"/> ... </web-app> <users> <user name="harry password="/Tj/54ylCloUeMi2YQIVCQ===" roles="user,admin"/> <users> javadoc <resin:XmlRoleMap>
Role to group permission mapping. javadoc RequestPredicate
Interface for custom request predicates. <resource> is an obsolete synonym for <bean> to define custom singletons. Applications should use the <bean> syntax instead. <resource-ref> declares that the application needs a resouce configuration. resource-ref is not directly used by Resin. It's a servlet configuration item intended to tell GUI tools which resources need configuration. Resource configuration in Resin uses the resource, reference, database, and ejb-server tags. For backwards compatibility, Resin 2.1-style configuration files may still use resource-ref to configure resources, but it's recommended to convert the configuration. element resource-ref { attribute id?, description*, res-ref-name, ref-type, res-auth, res-sharing-scope? } child of <session-config>
<save-mode> configures when Resin should save a persistence session during a request. The values are:
In some situations, like redirects, a fast browser can send a request back to Resin before the session is persisted with the sticky sessions, the load balancer might send the request to a different server, which may not get the updated session. In the situation, either the save-mode should be changed to or sticky sessions should be enabled. save-mode. If the server is configured withoutIf the save-mode is default after-request , the application should take care to make any session changes before sending data to the browser.child of <database>
<save-allocation-stack-trace> helps debugging application with
a missing child of <web-app>
The <scheduled-task> is replaced by bean-style resin:ScheduleTask. <web-app xmlns="http://caucho.com/ns/resin" xmlns:ee="urn:java:ee" xmlns:mypkg="urn:java:com.mycom.mypkg"> <resin:ScheduleTask> <cron>* * 23 * *</cron> <task> <mypkg:MyBean/> </task> </resin:ScheduleTask> </web-app> child of <web-app>
The <secure> flag requires that the web-app only be accessed in a secure/SSL mode. Equivalent to a <security-constraint>. element secure { r_boolean-Type } <secure-host-name> sets a host-name or URL to be used for secure redirection. For some security configurations, Resin needs to redirect from an insecure site to a secure one. The <secure-host-name> configures the host to redirect to. See Resin security. element secure-host-name { string } child of <web-app>
Specifies protected areas of the web site. Sites using authentication as an optional personalization feature will typically not use any security constraints. See Resin security for an overview. Security constraints can also be custom classes. See Resin security for an overview of security issues and configuration.
element security-constraint { auth-constraint* & constraint* & ip-constraint* & role-name* & user-data-constraint* & url-pattern? & web-resource-collection* } <web-app xmlns="http://caucho.com/ns/resin"> <security-constraint> <web-resource-collection> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint role-name='user'> </security-constraint> </web-app> <security-manager> enables the use of the security manager for the JVM. Because the JVM security manager is very slow, we generally do not recommend enabling it for server applications. Instead, see the watchdog configuration for alternative methods for securiting the JVM in ISP configurations. element security-manager { r_boolean-Type } <resin xmlns="http://caucho.com/ns/resin"> ... <security-manager/> ... <security-provider> adds 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 Security.addProvider. element security-provider { string } <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 <cluster>
<server> configures a JVM instance in the cluster. Each <server> is uniquely identified by its attribute. The will match the -server command line argument.The server listens to an internal network address, e.g. 192.168.0.10:6800 for clustering, load balancing, and administration. The current server is managed with a ServerMXBean. The ObjectName is . Peer servers are managed with ServerConnectorMXBean. The ObjectName is .
<resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server id="a" address="192.168.0.10" port="6800"> <http port="8080"/> </server> <server id="b" address="192.168.0.11" server-port="6800"> <http port="8080"/> </server> <server id="c" address="192.168.0.12" server-port="6800"> <http port="8080"/> </server> <host id=""> ... </cluster> </resin> Main configuration for the server, configuring ports, threads and virtual hosts.
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 <server> ports which share the thread pool. Requests received on those ports will use worker threads from the thread pool.
<server> ... <alternate-session-url-prefix>/~J=</alternate-session-url-prefix> ... EL variables and functions
child of <cluster>
<server-default> defines default values for all <server> instances. Since most <server> configuration is identical for all server instances, the shared configuration belongs in a <server-default>. For example, <http> ports, timeouts, JVM arguments, and keepalives are typically identical for all server instances and therefore belong in a server-default. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <thread-max>512</thread-max> <jvm-arg>-Xmx512m -Xss1m</jvm-arg> <http port="8080"/> </server-default> <server id="a" address="192.168.0.10" port="6800"/> <server id="b" address="192.168.0.11" port="6800"/> <server id="c" address="192.168.0.12" port="6800"/> <host id=""> ... </cluster> </resin> child of <cluster>
<server-multi> allows to specify multiple servers in a single tag. The servers are named using id–prefix concatenated with position of server's ip in the address-list.
<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app"> <server-multi id-prefix="app-" address-list="192.168.1.2 192.168.1.3" port="6800"/> ... </cluster> </resin> In the example above server app-0 is bound to ip ending with 1.2, app-1 – 1.3 child of <cluster>
default Resin/4.0.xConfigures the HTTP Server: header which Resin sends back to any HTTP client. element server-header { string } <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-header>MyServer/1.0</server-header> </cluster> </resin> Defines a servlet to process HTTP URL requests. The servlet class can either implement javax.servlet.Servlet to handle the HTTP request directly or it can use a remoting protocol like Hessian to handle remoting requests. Since servlets are full Resin-CanDI beans, they can use dependency injection, EJB aspects like @TransactionAttribute, custom @InterceptorType interceptors, and listen for @Observes events.
element servlet { servlet-name < (servlet-class | jsp-file) < init* < init-param* < load-on-startup? < protocol? < run-as? < run-at? } <web-app xmlns="http://caucho.com/ns"> <servlet> <servlet-name>hello</servlet-name> <servlet-class>test.HelloWorld</servlet-class> <init-param> <param-name>title</param-name> <param-value>Hello, World</param-value> </init-param> </servlet> <!-- using Resin shortcut syntax --> <servlet servlet-name='cron' servlet-class='test.DailyChores'> <init-param title='Daily Chores'/> <load-on-startup/> <run-at>3:00</run-at> </servlet> <!-- mapping a url to use the servlet --> <servlet-mapping url-pattern='/hello.html' servlet-name='hello'/> </web-app> Several configurations might configure the same servlet class with different values. Each will have a separate .<web-app xmlns="http://caucho.com/ns/resin"> <servlet servlet-name='foo-a'> <servlet-class>test.FooServlet</servlet-class> <init-param name='foo-a sample'/> </servlet> <servlet servlet-name='foo-b'> <servlet-class>test.FooServlet</servlet-class> <init-param name='foo-b sample'/> </servlet> </web-app> can specify an (optional) integer value. If the value is 0 or greater, it indicates an order for servlets to be loaded, servlets with higher numbers get loaded after servlets with lower numbers. There are a number of named servlets that are usually available to a Resin application, as defined in .<servlet servlet-name="directory" servlet-class="com.caucho.servlets.DirectoryServlet"/> <servlet servlet-name="file" servlet-class="com.caucho.servlets.FileServlet"/> <servlet servlet-name="jsp" servlet-class="com.caucho.jsp.JspServlet"/> <servlet servlet-name="xtp" servlet-class="com.caucho.jsp.XtpServlet"/> <servlet servlet-name="j_security_check" servlet-class="com.caucho.server.security.FormLoginServlet"/> child of <class-loader>
Use of servlet-hack is discouraged. Using servlet-hack violates the JDK's classloader delegation model and can produce surprising ClassCastExceptions. servlet-hack reverses the normal class loader order. Instead of parent classloaders having priority, child classloaders have priority. element servlet-hack { boolean } Maps url patterns to servlets. has two children, and . selects the urls which should execute the servlet.
element servlet-mapping { init? & protocol? & servlet-class? & servlet-name? < url-pattern* < url-regexp* } <web-app xmlns="http://caucho.com/ns/resin"> <servlet> <servlet-name>hello</servlet-name> <servlet-class>test.HelloWorld</servlet-class> </servlet> <servlet-mapping> <url-pattern>/hello.html</url-pattern> <servlet-name>hello</servlet-name> </servlet-mapping> <!-- resin shortcut syntax --> <servlet-mapping url-pattern='*.xtp' servlet-name='com.caucho.jsp.XtpServlet'/> </web-app> In Resin, the special <web-app xmlns="http://caucho.com/ns/resin"> <!-- used with urls like http://localhost:8080/servlets/test.HelloServlet --> <servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/> </web-app> There are a number of mappings to servlets that are usually available to a Resin application, as defined in .<cluster> <web-app-default> <servlet-mapping url-pattern="*.jsp" servlet-name="jsp"/> <servlet-mapping url-pattern="*.xtp" servlet-name="xtp"/> <servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/> <servlet-mapping url-pattern="/" servlet-name="file"/> </web-app-default> </cluster> The plugins use servlet-mapping to decide which URLs to send to Resin. The following servlet-name values are used by the plugins:
Maps URL by regular expressions to custom servlets. element servlet-regexp { init? & servlet-class? & servlet-name? & url-regexp } <servlet-regexp url-regexp="/([^.]*).do" servlet-class="qa.\${regexp[1]}Servlet"> <init a="b"/> </servlet-regexp> Although extremely rare, it is sometimes useful to create a custom predicate (for example for encapsulating complex custom authorization logic). You can easily do this by extending com.caucho.rewrite.RequestPredicate. This essentially allows you to create your own <IfXXX> rule. The following example demonstrates how to create a custom Resin predicate: <web-app xmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin" xmlns:foo="urn:java:com.foo" ... <resin:Allow url-pattern="/safe/*" <foo:IfMyTest value="abcxyz"/> </resin:Allow url-pattern="/safe/*" ... </web-app> package com.foo; import javax.servlet.http.HttpServletRequest; import com.caucho.security.ServletRequestPredicate; public class IfMyTest extends ServletRequestPredicate { private String value; // Your custom attribute for the tag. public void setValue(String value) { this.value = value; } // Here you must actually determine the match. public boolean isMatch(HttpServletRequest request) { return value.equals(request.getHeader("Foo")); } } child of <cluster>
default JSESSIONIDConfigures the cookie used for servlet sessions. element session-cookie { string } <session-config> configures Resin's session handling, including the cookies Resin sends, the maximum sessions, and session persistence and clustering. See also: Resin clustering for more information about distributed sessions and persistence.
element session-config { always-load-session? & always-save-session? & cookie-append-server-index? & cookie-domain? & cookie-domain-regexp? & cookie-length? & cookie-max-age? & cookie-port? & cookie-secure? & cookie-version? & enable-cookies? & enable-url-rewriting? & ignore-serialization-errors? & invalidate-after-listener? & reuse-session-id? & save-mode? & save-on-shutdown? & serialization-type? & session-max? & session-timeout? & use-persistent-store? } The <web-app id='/dir'> <session-config> <!-- 2 hour timeout --> <session-timeout>120</session-timeout> <session-max>4096</session-max> </session-config> </web-app> is used to limit the maximum length for the session's generated cookie for special situations like WAP devices. Reducing this value reduces the randomness in the cookie and increases the chance of session collisions. defaults to true so that Resin can share the session id amongst different web-apps. The class that corresponds to <session-config> is com.caucho.server.session.SessionManager child of <cluster>
default ;jsessionid=Configures the URL prefix used for session rewriting. Note Session rewriting is discouraged as a potential security issue.element session-cookie { string } child of <server>
<shutdown-wait-max> configures the maximum time the server will wait for the graceful shutdown before forcing an exit. element shutdown-wait-max { r_period-Type } child of <class-loader>
<simple-loader> Configures a simple -style class loader..class files in the specified directory will be loaded without any special compilation steps (in contrast with compiling-loader.)
element simple-loader { path & prefix? } <socket-timeout> is the maximum time a socket load balancer and distributed sessions will wait for a read or write to a cluster socket. Crashed servers may never respond to a read request or accept a write. The socket-timeout lets Resin recover from these kinds of crashes. Lower values can detect crashes more quickly, but too-low values may report bogus failures when the server machine is just a little slow. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server-default> <socket-timeout>60s</socket-timeout> </server-default> <server id="a" address="192.168.0.10" port="6800"/> <server id="b" address="192.168.0.11" port="6800"/> <host id=""> ... </cluster> </resin> child of <database>
default falseThe <spy> tag is a very useful logging tag for debugging database problems. If <spy> is enabled, all database queries will be logged at the "fine" level. Applications can use <spy> to debug unexpected database queries, or to improve query performance. 0.6:setString(1,1) 0.6:executeQuery(select o.DATA from my_bean o where o.ID=?) child of <cluster>
default value of session-cookieDefines an alternative session cookie to be used for a SSL connection. Having two separate cookies increases security. element ssl-session-cookie { string } <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <ssl-session-cookie>SSLJSESSIONID</ssl-session-cookie> ... </cluster> </resin> <startup-mode> configures the virtual-host's behavior on Resin startup, either "automatic", "lazy" or "manual".
element startup-mode { string } <stat-service> periodically checks the status of the server, and reports errors as necessary.
element stat-service { unix-load-avg-exit-threshold? & cpu-load-log-info-threshold? & cpu-load-log-warning-threshold? & cpu-load-thread-dump-threshold? & sample-period? & thread-dump-interval? } <statistics-enable> enables more detailed statistics for the
element statistics-enable { r_boolean-Type } Configures the destination for The log configuration describes stderr-log in detail.
element stderr-log { (path | path-format) & archive-format? & rollover-period? & rollover-size? & rollover-count? & timestamp? } Configures the destination for The log configuration describes stderr-log in detail.
element stdout-log { (path | path-format) & archive-format? & rollover-period? & rollover-size? & rollover-count? & timestamp? } Forces servlet-mapping to follow strict Servlet 2.2, disallowing PATH_INFO. Value is or .element strict-mapping { r_boolean-Type } <web-app xmlns="http://caucho.com/ns/resin"> <strict-mapping>true</strict-mapping> </web-app> Sets a Java system property. The effect is the same as if you had called java.lang.System#setProperty(String,String) before starting Resin. element system-property { attribute * { string }+ } <resin xmlns="http://caucho.com/ns/resin"> <system-property foo="bar"/> </resin> Time intervals are used throughout Resin configuration. To specify the units for a given interval, use the appropriate suffix as shown below.
<temp-dir> configures the application temp directory. This is the path used in .element temp-dir { string } child of <server>
default 10<thread-idle-max> configures the maximum number of idle threads in the thread pool. <thread-idle-max> works with <thread-idle-min> to maintain a steady number of idle threads, avoiding the creation or destruction threads when possible. <thread-idle-max> should be set high enough beyond <thread-idle-min> so a spiky load will avoid creating a thread and then immediately destroying it. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <thread-max>512</thread-max> <thread-idle-min>10</thread-idle-min> <thread-idle-max>20</thread-idle-max> <jvm-arg>-Xss1m -Xmx1024m</jvm-arg> </server-default> <server id="web-a" address="192.168.0.10"/> ... </cluster> </resin> child of <server>
default 5<thread-idle-min> configures the minimum number of idle threads in the thread pool. <thread-idle-min> helps spiky loads, avoiding delays for thread requests by keeping threads ready for future requests. When the number of idle threads drops below <thread-idle-min>, Resin creates a new thread. <thread-idle-min> should be set high enough to deal with load spikes. Since idle threads are relatively inexpensive in modern operating systems, having a number of idle threads is not a major resource hog, especially since these threads are idle, waiting for a new job. <thread-idle-min> works together with <thread-idle-max> to avoid thread allocation thrashing, i.e. avoiding creating a new thread because of <thread-idle-min> and then quickly destroying it because of <thread-idle-max>. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <thread-max>512</thread-max> <thread-idle-min>10</thread-idle-min> <thread-idle-max>20</thread-idle-max> <jvm-arg>-Xss1m -Xmx1024m</jvm-arg> </server-default> <server id="web-a" address="192.168.0.10"/> ... </cluster> </resin> child of <server>
default 8192<thread-max> configures the maximum number of threads managed by Resin's thread pool. Resin's thread pool is used for connection threads, timers, and Resin worker threads for JMS, JCA and EJB. Since Resin's thread pool only manages Resin threads, the actual number of threads in the JVM will be higher. Modern operating systems can handle a fairly large number of threads, so values of 512 or 1024 are often reasonable values for thread-max. The main limitation for thread-max is virtual memory. Since each thread takes up stack space (configured with -Xss), a 32-bit system might have a thread limit based on virtual memory. For example, on Linux the user space is only 2G. If the heap memory is 1024m (-Xmx1024m) and the stack size is 1m (-Xss1m), the maximum number of threads is somewhat less than 1024. In general, JVMs do not handle running out of threads very well, either freezing or throwing out of memory errors. Although it may be necessary to limit the number of threads to avoid running out of memory, <thread-max> should generally be set to a high value. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <thread-max>512</thread-max> <jvm-arg>-Xss1m -Xmx1024m</jvm-arg> </server-default> <server id="web-a" address="192.168.0.10"/> ... </cluster> </resin> child of <database>
default -1<transaction-timeout> configures the maximum time a transaction can be alive before a mandatory rollback. child of <class-loader>
<tree-loader> configures a jar library, <library-loader>, but will also find
element tree-loader { path } child of <cluster>
default UTF-8Defines the character encoding for decoding URLs. The HTTP specification does not define the character-encoding for URLs, so the server must make assumptions about the encoding. element url-character-encoding { string } child of <cache-mapping>,<filter-mapping>,<path-mapping>,<servlet-mapping>,<servlet-regexp>,<web-app>
<url-regexp> matches the portion of the url that
follows the context path. A webapp in child of <security-constraint>
Restricts access to secure transports, such as SSL
element user-data-constraint { transport-guarantee } child of <server>
<user-name> configures the operating system user 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. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server-default> <http port="80"/> <user-name>resin</user-name> </server-default> <server id="web-a"/> ... </cluster> </resin>
The ${system} variable return the <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <resin:message>${system['foo']}</resin:message> ... </resin> The <watchdog> tag is used in ISP-style configurations where the <watchdog-manager> is configured separately from the resin.xml instances, and where the configuration file is generally not readable by the instance users. The <watchdog> tag corresponds to the <server> tag in standard resin.xml configurations, and specifies the resin.xml, the root directory and resin-user.
element watchdog { attribute id { string } & chroot? & group-name? & java-exe? & java-home? & jvm-arg* & resin.xml? & resin-root? & open-port { address & port }* & user-name? } child of <server>
The <watchdog-arg> configures arguments for the watchdog process. The watchdog improves reliability by monitoring the Resin instance, restarting it if necessary. The <watchdog-arg> typically is used to enable jconsole for the watchdog JVM. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server-default> <watchdog-arg>-Dcom.sun.management.jmxremote</watchdog-arg> </server-default> ... </cluster> </resin> For ISP configurations, <watchdog-manager> is used for a separate resin.xml just to configure the watchdog-manager itself. The <watchdog-manager> selects the <user-name>, <resin.xml>, ports, and Resin home directories before giving access to the user's Resin instance.
element watchdog-manager { watchdog* & watchdog-address? & watchdog-default* & watchdog-jvm-arg* & watchdog-port? } child of <server>
default 6700<watchdog-port> configures the administration port for the watchdog JVM. The watchdog launches the server JVM and monitors its health, restarting the JVM when necessary to improve site reliability. The command line arguments use the watchdog-port for the "start" and "stop" commands to tell the watchdog to start and stop the server JVM. The administration also uses the watchdog port for watchdog administration. The watchdog port will use the same <address> as the server, so it will always be an internal network address, never an external internet address. web-app configures a web application. When specified by <url-regexp>, the application will be initialized at the first request. This means that servlets may start later than expected for applications. , the application will be initialized on server start. When specified by
The following example creates a web-app for /apache using the Apache htdocs directory to serve pages. <host id=''> <web-app id='/apache' root-directory='/usr/local/apache/htdocs'> ... </host> The following example sets the root web-app to the IIS root directory. <web-app id='/' root-directory='C:/inetpub/wwwroot'> When the is specified with a , can use replacement variables ( ).In the following, each user gets his or her own independent application using .<host id=''> <web-app url-regexp='/~([^/]*)' root-directory='/home/$1/public_html'> ... </web-app> </host> child of <cluster>
<web-app-default> defines default values for any web-app in the cluster. <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <web-app-default> <servlet servlet-name="resin-php" servlet-class="com.caucho.quercus.servlet.QuercusServlet"/> <servlet-mapping url-pattern="*.php" servlet-name="resin-php"/> </web-app-default> <host id=""> ... </cluster> </resin> Specifies war expansion. web-app-deploy can be used in web-apps to define a subdirectory for war expansion. The tutorials in the documentation use web-app-deploy to allow servlet/tutorial/helloworld to be an independent war file.
element web-app-deploy { archive-directory? expand-cleanup-fileset? expand-directory? expand-prefix? expand-preserve-fileset? expand-suffix? path? redeploy-check-interval? redeploy-mode? require-file* startup-mode? url-prefix? versioning? web-app-default* web-app* } Overriding web-app-deploy configurationThe web-app-deploy can override configuration for an expanded war with a matching <web-app> inside the <web-app-deploy>. The <root-directory> is used to match web-apps. <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> <host id=""> <web-app-deploy path="webapps"> <web-app context-path="/wiki" root-directory="wiki"> <context-param database="jdbc/wiki"> </web-app> </web-app-deploy> </host> </cluster> </resin> versioningThe versioning attribute of the <web-app-deploy> tag improves web-app version updates by enabling a graceful update of sessions. The web-apps are named with numeric suffixes, e.g. foo-10, foo-11, etc, and can be browsed as /foo. When a new version of the web-app is deployed, Resin continues to send current session requests to the previous web-app. New sessions go to the new web-app version. So users will not be aware of the application upgrade. The expand-preserve-fileset attribute lets you keep files for a redeployment, which can improve restart times. Normally, Resin will delete all files for an update, including the compiled files for JSP, which forces Resin to recompile JSP files, even if they haven't changed in the update. If you add the expand-preserve-fileset, Resin will only recompile the JSP files that have changed. child of <security-constraint>
Specifies a collection of areas of the web site for security purposes. See Resin security for an overview.
element web-resource-collection { url-method* & http-method* & web-resource-name? } child of <web-app>
Sets the files to use as when no filename is present in url. According to the spec, each file is in a <welcome-file> element. element welcome-file-list { string | welcome-file* } <web-app xmlns="http://caucho.com/ns/resin"> <welcome-file-list> <welcome-file>index.jsp</welcome-file> <welcome-file>index.xtp</welcome-file> <welcome-file>home.xtp</welcome-file> </welcome-file-list> </web-app> Resin also provides a shortcut where you can just list the files: <web-app xmlns="http://caucho.com/ns/resin"> <welcome-file-list> index.jsp, index.xtp, home.xtp </welcome-file-list> </web-app> default Defaults to <work-dir> configures a work directory for automatically generated code, e.g. for JSP, PHP, and JPA classes. element work-dir { string }
|