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


 

Resin Documentation

home company blog wiki docs 
app server web server 
health cloud java ee pro 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

<host>: virtual host configuration


Describes the virtual host configuration tags.

See Also

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

<access-log>

child of cluster,host,web-app

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

<access-log> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
archive-formatthe format for the archive filename when a rollover occurs, see Rollovers. see below
formatAccess log format.see below
pathOutput path for the log entries, see "Log Paths".required
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
resin:typea class extending for custom logging com.caucho.server.log.AccessLog
initResin-IoC initialization for the custom classn/a
<access-log> schema
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:

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
%{xxx}trequest date with optional time format string.
%Ttime taken to complete the request in seconds
%uremote user
%Urequest URI

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 . Resin-IoC initialization can be used to set bean parameters in the custom class.

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 resin:type='test.MyLog'>
               path='${resin.root}/foo/error.log'
               rollover-period='1W'>
      <init>
        <foo>bar</foo>
      </init>
    </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-pathThe path to the directory containing ear filespath
ear-defaultresin.conf 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 cluster,host,webapp

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

<host>

child of cluster

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

<host> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
idprimary host namenone
regexpRegular expression based host matchingnone
host-nameCanonical host namenone
host-aliasAliases matching the same hostnone
secure-host-nameHost to use for a redirect to SSLnone
root-directoryRoot directory for host filesparent directory
startup-mode'automatic', 'lazy', or 'manual', see Startup and Redeploy Modeautomatic
Example: explicit host in resin.conf
<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>
Example: regexp host in resin.conf
<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>

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

<host-alias> schema
element host-alias {
  string
}
Example: host-alias in the resin.conf
<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.

Example: host-alias in a /var/www/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>

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

<host-default>

child of cluster

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

<host-deploy>

child of cluster

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

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

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

<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-host> schema
element host-name {
  string
}

<redeploy-mode>

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

startup-mode values
MODEDESCRIPTION
automaticautomatically restart when detecting changes
manualonly restart only on a JMX administration request
<restart-mode> schema
element startup-mode {
  string
}

Resources

child of resin,cluster,host,web-app

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.

Example: shared database in 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>

<rewrite-dispatch>

child of cluster,host,web-app

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

rewrite-dispatch
<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>

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

<root-directory> schema
element root-directory {
  string
}

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

<web-app> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
idThe url prefix selecting this application.n/a
url-regexpA regexp to select this application.n/a
document-directoryThe document 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 and Redeploy Modeautomatic
redeploy-mode'automatic' or 'manual', see Startup and Redeploy Modeautomatic

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.

Example: custom web-app root
<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.

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

Example: web-app root based on regexps
<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>

<web-app-default>

child of cluster,host,web-app

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

<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
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-check-intervalHow often to check the .war files for a redeploy60s
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 <document-directory> is used to match web-apps.

Example: resin.conf overriding web.xml
<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>

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

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).
Leading companies worldwide with demand for reliability and high performance web applications including SalesForce.com, CNET, DZone and many more are powered by Resin.

home company blog wiki docs 
app server web server 
health cloud java ee pro