Caucho Technology
  • resin 4.0
  • <host>: virtual host configuration

    Describes the virtual host configuration tags.



    <access-log> configures the access log file.

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

    The default archive format is

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

    The access log formatting variables follow the Apache variables:

    format patterns
    %bresult content length
    %Dtime taken to complete the request in microseconds (since 3.0.16)
    %hremote IP addr
    %{xxx}irequest header xxx
    %{xxx}oresponse header xxx
    %{xxx}ccookie value xxx
    %nrequest attribute
    %rrequest URL
    %sstatus code
    %Srequested session id
    %{xxx}trequest date with optional time format string.
    %Ttime taken to complete the request in seconds
    %uremote user
    %Urequest URI
    %vname of the virtual host serving the request

    The default format is:

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

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

    <access-log> Attributes
    pathOutput path for the log entries, see "Log Paths".required
    path-formatSelects a format for generating path names. The syntax is the same as for archive-format.optional
    archive-formatthe format for the archive filename when a rollover occurs, see Rollovers. see below
    auto-flushtrue to flush the memory buffer with each request. false
    auto-flush-timesets time interval for flushing the memory buffers 60s
    excludeaccess logging exclude patterns for request URIs. Access to matching URIs does not get logged.none
    formatAccess log format.see above
    hostname-dns-lookuplog the dns name instead of the IP address (has a performance hit).false
    rollover-periodhow often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See "Rollovers". none
    rollover-sizemaximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See "Rollovers". 1mb
    rollover-countmaximum number of rollover files before the oldest ones get overwritten. See "Rollovers". 1mb
    resin:typea class extending com.caucho.server.log.AccessLog for custom logging com.caucho.server.log.AccessLog
    initResin-IoC initialization for the custom classn/a
    <access-log> schema
    element access-log {
      & path-format?
      & archive-format?
      & auto-flush-time?
      & exclude*
      & format?
      & hostname-dns-lookup?
      & rollover-period?
      & rollover-size?
      & rollover-count?
      & resin:type?
      & init?
    Example: <access-log> in host configuration
    <resin xmlns="">
    <cluster id="app-tier">
      <host id="">
        <access-log path='log/access.log'>
    Example: custom access log
    <resin xmlns="">
    <cluster id="app-tier">
      <host id=''>
          <test:MyLog xmlns:test="urn:java:test">


    child of host,web-app

    Specifies ear expansion.

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

    <ear-deploy> Attributes
    archive-pathThe path to the directory containing ear filespath
    ear-defaultresin.xml default configuration for all ear files, e.g. configuring database, JMS or EJB defaults.
    expand-cleanup-filesetSpecifies the files which should be automatically deleted when a new .ear version is deployed.
    expand-directorydirectory where ears should be expandedvalue of path
    expand-prefixautomatic prefix of the expanded directory_ear_
    expand-suffixautomatic suffix of the expanded directory
    lazy-initif true, the ear file is only started on first accessfalse
    pathThe path to the deploy directoryrequired
    redeploy-mode"automatic" or "manual". If automatic, detects new .ear files automatically and deploys them.automatic
    url-prefixoptional URL prefix to group deployed .ear files
    <ear-deploy> schema
    element ear-deploy {
      & archive-directory?
      & ear-default?
      & expand-cleanup-fileset?
      & expand-directory?
      & expand-path?
      & expand-prefix?
      & expand-suffix?
      & lazy-init?
      & redeploy-mode?
      & require-file*
      & url-prefix?


    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.

    Request attributes for error handling
    <error-page> Attributes
    error-codeSelect the error page based on an HTTP status code
    exception-typeSelect the error page based on a Java exception
    locationThe error page to display
    <error-page> schema
    element error-page {
      (error-code | exception-type)?
      & location
    Catching File Not Found
    <web-app xmlns="">
    Catching Exceptions
    <web-app xmlns="">
       <error-page exception-type="java.lang.NullPointerException"
    Using request attributes to obtain information about the request that caused the error
    <%@ page session="false" isErrorPage="true" %>
    <head><title>404 Not Found</title></head>
    <h1>404 Not Found</h1>
    The url <code>${requestScope["javax.servlet.error.request_uri"]}</code> 
    was not found.


    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.

    <host-alias> schema
    element host-alias {
    Example: host-alias in the resin.xml
    <resin xmlns="">
    <cluster id="">
      <host id="" root-directory="/var/www/">
        <web-app id=""/>
    Example: host-alias in a /var/www/hosts/foo/host.xml
    <host xmlns="">
      <web-app id="" root-directory="htdocs"/>


    child of host

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

    <host-alias-regexp> schema
    element host-alias-regexp {
    Example: host-alias-regexp in the resin.xml
    <resin xmlns="">
    <cluster id="">
      <host id="" root-directory="/var/www/">
        <web-app id=""/>


    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 ${}, referring to the name of the host jar file.

    <host-deploy> Attributes
    archive-directorypath to the archive directorypath
    pathpath to the deploy directoryrequired
    expand-cleanup-filesetan ant-style fileset defining which directories to cleanup when an archive is redeployed
    expand-directorypath to the expansion directorypath
    host-defaultdefaults for the expanded host
    host-namethe default hostname, based on the directory${name}
    <host-deploy> schema
    element host-deploy {
      & 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/ would serve the URL

    <resin xmlns="">
      <cluster id="app-tier">
        <host-deploy path="hosts">
            <resin:import path="host.xml" optional="true"/>
            <web-app-deploy path="webapps"/>


    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.

    <host-name> schema
    element host-name {


    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.

    <redeploy-mode> Attributes
    automaticchecks for redeployment and auto-redeploy if modified
    manualdoes not check for redeployment. Only checks if manual (JMX)
    <redeploy-mode> schema
    element redeploy-mode {
      automatic | manual


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

    <root-directory> schema
    element root-directory {
    Example: cluster root-directory
    <resin xmlns="">
        <cluster id="app-tier">
            <server id="a" ...>
            <host host-name="">


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

    <secure-host-name> schema
    element secure-host-name {


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

    <startup-mode> Attributes
    automaticautomatically start when Resin starts
    lazystart only when the first request is received
    manualstart only when JMX administration requests a start
    <startup-mode> schema
    element startup-mode {


    child of host,web-app

    web-app configures a web application.

    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.

    <web-app> Attributes
    active-wait-timehow long a thread should wait for the web-app to initialize before returning a 503-busy.15s
    archive-pathSpecifies the location of the web-app's .war file.n/a
    context-pathSpecifies the URL prefix for the web-app.the id value
    idThe url prefix selecting this application.n/a
    redeploy-mode'automatic' or 'manual', see redeploy-modeautomatic
    redeploy-check-intervalhow often to check the .war archive for redeployment60s
    root-directoryThe root directory for the application, corresponding to a url of /id/. A relative path is relative to the root-directory of the containing host. Can use regexp replacement variables.A relative path constricted with the id or the regexp match
    startup-mode'automatic', 'lazy', or 'manual', see startup-modeautomatic
    startup-priorityspecifies a priority for web-app startup to force an ordering between webapps -1
    url-regexpA regexp to select this application.n/a

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

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

      <web-app id='/' root-directory='C:/inetpub/wwwroot'>

    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.

    <host id=''>
      <web-app url-regexp='/~([^/]*)'


    child of cluster

    <web-app-default> defines default values for any web-app in the cluster.

    Example: web-app-default
    <resin xmlns="">
        <cluster id="app-tier">
                <servlet servlet-name="resin-php"
                <servlet-mapping url-pattern="*.php"
            <host id="">


    child of host,web-app

    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.

    <web-app-deploy> Attributes
    archive-directorydirectory containing the .war filesvalue of path
    dependency-check-intervalHow often to check the .war files for a redeploy60s
    expand-cleanup-filesetdefines the files which should be automatically deleted when an updated .war expandsall files
    expand-directorydirectory where wars should be expandedvalue of path
    expand-prefixprefix string to use when creating the expansion directory, e.g. _war_
    expand-suffixprefix string to use when creating the expansion directory, e.g. .war
    pathThe path to the webapps directoryrequired
    redeploy-mode"automatic" or "manual"automatic
    require-fileadditional files to use for dependency checking for auto restart
    startup-mode"automatic", "lazy" or "manual"automatic
    url-prefixurl-prefix added to all expanded webapps""
    versioningif true, use the web-app's numeric suffix as a versionfalse
    web-app-defaultdefaults to be applied to expaned web-apps
    web-appoverriding configuration for specific web-apps
    <web-app-deploy> schema
    element web-app-deploy {

    Overriding web-app-deploy configuration

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

    Example: resin.xml overriding web.xml
    <resin xmlns="">
    <cluster id="">
    <host id="">
    <web-app-deploy path="webapps">
      <web-app context-path="/wiki"
        <context-param database="jdbc/wiki">


    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.

    Copyright © 1998-2011 Caucho Technology, Inc. All rights reserved.
    Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.