Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


 

Resin Documentation

home company blog docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

<host>: virtual host configuration


Describes the virtual host configuration tags.

<access-log>

<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
PATTERNDESCRIPTION
%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
ATTRIBUTEDESCRIPTIONDEFAULT
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?
  & path-format?
  & archive-format?
  $amp;auto-flush?
  & 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="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>
Example: custom access log
<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>

<ear-deploy>

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
ATTRIBUTEDESCRIPTIONDEFAULT
archive-directoryThe 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 {
  path
  & archive-directory?
  & ear-default?
  & expand-cleanup-fileset?
  & expand-directory?
  & expand-path?
  & expand-prefix?
  & expand-suffix?
  & lazy-init?
  & redeploy-mode?
  & require-file*
  & url-prefix?
}

<error-page>

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
ATTRIBUTETYPE
javax.servlet.error.status_codejava.lang.Integer
javax.servlet.error.messagejava.lang.String
javax.servlet.error.request_urijava.lang.String
javax.servlet.error.servlet_namejava.lang.String
javax.servlet.error.exceptionjava.lang.Throwable
javax.servlet.error.exception_typejava.lang.Class
<error-page> Attributes
ATTRIBUTEDESCRIPTION
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="http://caucho.com/ns/resin">
  <error-page>
    <error-code>404</error-code>
    <location>/file_not_found.jsp</location>
  </error-page>
</web-app>
Catching Exceptions
<web-app xmlns="http://caucho.com/ns/resin">
   <error-page exception-type="java.lang.NullPointerException"
               location="/nullpointer.jsp"/>
</web-app>
Using request attributes to obtain information about the request that caused the error
<%@ 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>

<host-alias>

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 {
  string
}
Example: host-alias in the resin.xml
<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>
Example: host-alias in a /var/resin/hosts/foo/host.xml
<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>

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 {
  string
}
Example: host-alias-regexp in the resin.xml
<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>

<host-default>

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.

<host-deploy>

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.

<host-deploy> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
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 {
  archive-directory?
  & expand-cleanup-fileset?
  & expand-directory?
  & host-default?
  & host-name?
  & path?
}

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

<host-deploy>
<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>

<host-name>

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

<redeploy-mode>

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

<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 {
  r_path-Type
}
Example: cluster root-directory
<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>

<secure-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 {
  string
}

<startup-mode>

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

<startup-mode> Attributes
MODEDESCRIPTION
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 {
  string
}

<web-app>

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
ATTRIBUTEDESCRIPTIONDEFAULT
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-mode>automatic
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-mode>automatic
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'>

  ...

</host>

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='/~([^/]*)'
           root-directory='/home/$1/public_html'>

    ...

  </web-app>

</host>

<web-app-default>

child of <cluster>

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

Example: web-app-default
<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>

<web-app-deploy>

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
ATTRIBUTEDESCRIPTIONDEFAULT
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 {
  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*
}

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="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>

versioning

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-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.