<document>
<localtoc/>

- See the index for a list of all the tags.
- See Web Application configuration for web.xml (Servlet) configuration.
- See Resource configuration for resources: classloader, databases, JMS, EJB, and IoC beans.
- See Log configuration for access log configuration, java.util.logging, and stdout/stderr logging.

<parents>cluster, host, web-app</parents>

<access-log> configures the access log file.

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

Attribute Description Default
archive-format the format for the archive filename when a rollover occurs, see Rollovers. see below
format Access log format. see below
path Output path for the log entries, see "Log Paths". required
rollover-period how often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See Rollovers. none
rollover-size maximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See Rollovers. 1mb
resin:type a class extending for custom logging com.caucho.server.log.AccessLog
init Resin-IoC initialization for the custom class n/a
element access-log { auto-flush? & archive-format? & auto-flush-time? & exclude? & format? & path? & rollover-count? & rollover-period? & rollover-size? & init? }

The default archive format is

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

The access log formatting variables follow the Apache variables:

Pattern Description
%b result content length
%D time taken to complete the request in microseconds (since 3.0.16)
%h remote IP addr
%{xxx}i request header xxx
%{xxx}o response header xxx
%{xxx}c cookie value xxx
%n request attribute
%r request URL
%s status code
%{xxx}t request date with optional time format string.
%T time taken to complete the request in seconds
%u remote user
%U request URI

The default format is:

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

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

<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 resin:type='test.MyLog'> path='${resin.root}/foo/error.log' rollover-period='1W'> <init> <foo>bar</foo> </init> </access-log> ... </host> </cluster> </resin> <parents>host, web-app</parents>

Specifies ear expansion.

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

Attribute Description Default
archive-path The path to the directory containing ear files path
ear-default resin.conf default configuration for all ear files, e.g. configuring database, JMS or EJB defaults.
expand-cleanup-fileset Specifies the files which should be automatically deleted when a new .ear version is deployed.
expand-directory directory where ears should be expanded value of path
expand-prefix automatic prefix of the expanded directory _ear_
expand-suffix automatic suffix of the expanded directory
lazy-init if true, the ear file is only started on first access false
path The path to the deploy directory required
redeploy-mode "automatic" or "manual". If automatic, detects new .ear files automatically and deploys them. automatic
url-prefix optional URL prefix to group deployed .ear files
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? } <parents>cluster, host, webapp</parents>

<error-page> defines a web page to be displayed when an error occurs outside of a web-app. Note, this is not a default error-page, i.e. if an error occurs inside of a <web-app>, the error-page for that web-app will be used instead.

See webapp: error-page.

<parents>cluster</parents>

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

Attribute Description Default
id primary host name none
regexp Regular expression based host matching none
host-name Canonical host name none
host-alias Aliases matching the same host none
secure-host-name Host to use for a redirect to SSL none
root-directory Root directory for host files parent directory
startup-mode 'automatic', 'lazy', or 'manual', see Startup and Redeploy Mode automatic
<resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> <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="/" document-directory="webapps/ROOT"> </web-app> ... </host> </cluster> </resin> <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> <host regexp="([^.]+)\.foo\.com"> <host-name>${host.regexp[1]}.foo.com</host-name> <root-directory>/var/www/hosts/www.${host.regexp[1]}.com</root-directory> ... </host> </cluster> </resin>

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

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

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

element host-alias { string } <resin xmlns="http://caucho.com"> <cluster id=""> <host id="www.foo.com" root-directory="/var/www/foo.com"> <host-alias>foo.com</host-alias> <web-app id=""/> </host> </cluster> </resin>

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

<host xmlns="http://caucho.com"> <host-name>www.foo.com</host-name> <host-alias>foo.com</host-alias> <web-app id="" root-directory="htdocs"/> </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/www/foo.com"> <host-alias-regexp>.*foo.com</host-alias-regexp> <web-app id=""/> </host> </cluster> </resin> <parents>cluster</parents>

<host-default> configures 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.

<parents>cluster</parents>

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

Attribute Description Default
archive-directory path to the archive directory path
path path to the deploy directory required
expand-cleanup-fileset an ant-style fileset defining which directories to cleanup when an archive is redeployed
expand-directory path to the expansion directory path
host-default defaults for the expanded host
host-name the default hostname, based on the directory ${name}
element host-deploy { archive-directory? & expand-cleanup-fileset? & expand-directory? & host-default? & host-name? & path? }

The following example configures /var/www/hosts as a host deployment directory. Each virtual host will have a webapps directory for .war deployment. So the directory /var/www/hosts/www.foo.com/webapps/bar/test.jsp would serve the URL http://www.foo.com/bar/test.jsp.

<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <root-directory>/var/www</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>

<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 }

<redeploy-mode> configures the virtual-host's behavior when it detects changes in configuration files or classes. The <dependency-check-interval> controls how often the virtual host will check for updates.

Mode Description
automatic automatically restart when detecting changes
manual only restart only on a JMX administration request
element startup-mode { string } <parents>resin, cluster, host, web-app</parents>

All Resource tags are available to the <host>, for example, resources like <database> or <authenticator>. Resources defined at the host level are available for all web-apps in the host.

<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server id="a" .../> <host id="www.foo.com"> <database jndi-name="jdbc/test"> <driver type="org.postgresql.Driver"> <url>jdbc:postgresql://localhost/test</url> <user>caucho</user> </driver> </database> <web-app-default path="webapps"/> </host> </cluster> </resin> <parents>cluster, host, web-app</parents>

<rewrite-dispatch> defines a set of rewriting rules for dispatching and forwarding URLs. Applications can use these rules to redirect old URLs to their new replacements.

See rewrite-dispatch for more details.

<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <host host-name="www.foo.com"> <rewrite-dispatch> <redirect regexp="^/foo" target="/index.php?foo="/> </rewrite-dispatch> </host> </cluster> </resin>

<root-directory> configures the virtual host's filesystem root.

Because the virtual host's root will typically contain non-public files like log files, all web-apps should have a path below the host.

element root-directory { string }

<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 }

<startup-mode> configures the virtual-host's behavior on Resin startup, either "automatic", "lazy" or "manual".

Mode Description
automatic automatically start when Resin starts
lazy start only when the first request is received
manual start only when JMX administration requests a start
element startup-mode { string } <parents>host, web-app</parents>

<web-app> configures a web application.

Attribute Description Default
id The url prefix selecting this application. n/a
url-regexp A regexp to select this application. n/a
document-directory The document directory for the application, corresponding to a url of /id/. A relative path is relative to the of the containing . Can use regexp replacement variables.A relative path constricted with the id or the regexp match
startup-mode 'automatic', 'lazy', or 'manual', see Startup and Redeploy Mode automatic
redeploy-mode 'automatic' or 'manual', see Startup and Redeploy Mode automatic

When specified by id, the application will be initialized on server start. When specified by url-regexp, the application will be initialized at the first request. This means that load-on-startup servlets may start later than expected for url-regexp applications.

The following example creates a web-app for /apache using the Apache htdocs directory to serve pages.

<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <host id=''> <web-app id='/apache' root-directory='/usr/local/apache/htdocs'> ... </host> </cluster> </resin>

The following example sets the root web-app to the IIS root directory.

<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <host id=''> <web-app id='/' root-directory='C:/inetpub/wwwroot'> </host> </cluster> </resin>

When the web-app is specified with a url-regexp, root-directory can use replacement variables ($2).

In the following, each user gets his or her own independent application using ~user.

<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <host id=''> <web-app url-regexp='/~([^/]*)' root-directory='/home/$1/public_html'> ... </web-app> </host> </cluster> </resin> <parents>cluster, host, web-app</parents>

<web-app-default> configures common values for all web applications.

<parents>host, web-app</parents>

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.

Attribute Description Default
archive-directory directory containing the .war files value of path
expand-cleanup-fileset defines the files which should be automatically deleted when an updated .war expands all files
expand-directory directory where wars should be expanded value of path
expand-prefix prefix string to use when creating the expansion directory, e.g. _war_
expand-suffix prefix string to use when creating the expansion directory, e.g. .war
path The path to the webapps directory required
redeploy-check-interval How often to check the .war files for a redeploy 60s
redeploy-mode "automatic" or "manual" automatic
require-file additional files to use for dependency checking for auto restart
startup-mode "automatic", "lazy" or "manual" automatic
url-prefix url-prefix added to all expanded webapps ""
versioning if true, use the web-app's numeric suffix as a version false
web-app-default defaults to be applied to expaned web-apps
web-app overriding configuration for specific web-apps
element web-app-deploy { archive-directory? & expand-cleanup-fileset? & expand-directory? & expand-prefix? & expand-suffix? & path? & redeploy-check-interval? & redeploy-mode? & require-file* & startup-mode? & url-prefix? & versioning? & web-app-default* & web-app* }

The web-app-deploy can override configuration for an expanded war with a matching <web-app> inside the <web-app-deploy>. The <document-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" document-directory="wiki"> <context-param database="jdbc/wiki"> </web-app> </web-app-deploy> </host> </cluster> </resin>

The 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.

</document>