<document>
<header>
  <title>Resin Configuration Overview</title>
  <description>
  <p>
The overview briefly describes much of the interesting Resin configuration
options as an introduction and index to the configuration
documentation.</p>
  </description>
</header>

<body>
<localtoc/>

<s1 title="Introduction">

<p>Many sites will use the default resin.xml with only minimal
configuration changes, e.g. changing the
<a href="port-tags.xtp#http">&lt;http&gt;</a> port, adding
<a href="port-tags.xtp#openssl">&lt;openssl&gt;</a> port, 
new <a href="env-tags.xtp#database">&lt;database&gt;</a> configuration or
<a href="env-tags.xtp#authenticator">&lt;authenticator&gt;</a> for
security.  Those sites can use the default resin.xml as an
sample index into the configuration tags to be customized.</p>

<p>This overview provides an overview of some of the other customizations
available in the resin.xml.  For example some sites have have
more sophisticated requirements, either
adding many <a href="virtual-host.xtp">virtual hosts</a>, 
<a href="cluster-tags.xtp#cache">proxy caching</a>, 
<a href="clustering-overview.xtp">load-balancing</a>, or adding
<a href="sessions.xtp">distributed sessions.</a></p>


</s1>

<s1 title="Minimal resin.xml">

<p>As a starting point to the structure of Resin's configuration, it's
best to look at the minimal usable resin.xml file.  All configuration
in Resin ultimately derives from the top-level resin.xml file, so
understanding and debugging a configuration can start from the resin.xml
and work toward any included files such as <g>resin-web.xml</g>.</p>

<p>The minimal usable resin.xml file listens to HTTP at port 8080
and looks for web-apps in webapps.  So the URL
<var>http://localhost:8080/test.php</var> would look in
$SERVER_ROOT/webapps/ROOT/test.php.</p>

<p>$SERVER_ROOT defaults to $RESIN_HOME, i.e. the resin-3.1.0 directory.
It can also be assigned with a command-line argument
<var>--server-root</var></p>

<example title="minimal resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  &lt;cluster id="app-tier">
    &lt;server id="">
      &lt;http port="8080"/>
    &lt;/server>

    &lt;resin:import path="${resin.home}/conf/app-default.xml"/>

    &lt;host id="">
      &lt;web-app-deploy path="webapps"/>
    &lt;/host>
  &lt;/cluster>
&lt;/resin>
</example>

<p>To start Resin with this minimal resin.xml use the following:</p>

<example>
share> java -jar resin-3.1.0/lib/resin.jar
</example>

<p>Or to start Resin as a daemon use "start":</p>

<example>
share> java -jar resin-3.1.0/lib/resin.jar start
</example>

<s2 title="&lt;resin&gt;">

<p>The <a href="resin-tags.xtp#resin">&lt;resin&gt;</a> tag is a container
for all the Resin configuration.  It will generally contain one or
most &lt;cluster> configuration.  In more complete configuration, it
may also contain <a href="config-log.xtp">logging</a>, <a href="env-tags.xtp#class-loader">class loader</a>,
<a href="env-tags.xtp#system-property">system-property</a> or global
resource definitions.</p>

</s2>

<s2 title="Namespace xmlns=&quot;http://caucho.com/ns/resin&quot;">

<p>The namespace declaration of <var>http://caucho.com/ns/resin</var>
enables Resin's validation of the configuration files.  The validator
will detect syntax errors and provide a summary of the syntax to
help debug resin.xml files.</p>

</s2>

<s2 title="Namespace xmlns:resin=&quot;http://caucho.com/ns/resin/core&quot;">

<p>The namespace declaration of <var>http://caucho.com/ns/resin/core</var>
enables Resin control tags like
<a href="config-control.xtp#resin:import">&lt;resin:import&gt;</a>,
<a href="config-control.xtp#resin:set">&lt;resin:set&gt;</a>, and 
<a href="config-control.xtp#resin:if">&lt;resin:if&gt;</a>.  These control
tags can help organize configuration files, but you should take care not
to overuse them, which might overcomplicate the configuration file.
</p>

</s2>

<s2 title="&lt;cluster&gt;">

<p>The <a href="cluster-tags.xtp#cluster">&lt;cluster&gt;</a> tag
configures clusters of servers.  The cluster consists of a number
of virtual hosts, possibly including a default virtual host.  Each
<a href="server-tags.xtp#server">&lt;server&gt;</a> in
a &lt;cluster> handles the same requests.</p>

<p>A web-site using Resin's <a href="clustering-overview.xtp">load
balancing</a> might have two clusters: a web-tier handling the HTTP requests
and an app-tier handling servlets, PHP and JSP pages.</p>

</s2>

<s2 title="&lt;server&gt;">

<p>A <a href="server-tags.xtp#server">&lt;server&gt;</a> configures a
single JVM instance running Resin. There may be multiple servers in a
<a href="cluster-tags.xtp#cluster">&lt;cluster&gt;</a> and there may also
be multiple servers on a machine.</p>

<p>The &lt;server> will have a unique <var>id</var> which matches the
<var>-server</var> command-line argument.</p>

<p>The &lt;server> will also configure any
<a href="port-tags.xtp#http">&lt;http&gt;</a> ports, any setuid
<a href="server-tags.xtp#user-name">&lt;user-name&gt;</a> changes
and any
<a href="server-tags.xtp#thread-max">&lt;thread-max&gt;</a>, 
<a href="server-tags.xtp#socket-timeout">&lt;socket-timeout&gt;</a>, or
<a href="server-tags.xtp#keepalive-max">&lt;keepalive-max&gt;</a> values.</p>

<p>Typically, common configuration for multiple servers
like &lt;http> and &lt;thread-max&gt; will be put in a
<a href="server-tags.xtp#server-default">&lt;server-default&gt;</a> tag to
simplify the configuration.</p>

</s2>

<s2 title="&lt;http&gt;">

<p>The <a href="port-tags.xtp#http">&lt;http&gt;</a> tag configures
HTTP ports.  It may contain <a href="port-tags.xtp#openssl">&lt;openssl&gt;
</a> tags for SSL support.</p>

<p>The &lt;http> tags are often put in a &lt;server-default> tag, sharing
the configuration for all servers in a cluster.</p>

</s2>

<s2 title="&lt;resin:import&gt;">

<p>The <a href="config-control.xtp#resin:import">&lt;resin:import&gt;</a> can
import other configuration files to help organize complicated
configurations.  The <var>app-default.xml</var> file in the example
defines the usual servlets that applications expect, like the
JSP servlet, the <a href="../quercus/index.xtp">PHP/Quercus</a> servlet,
and default configuration like <g>resin-web.xml</g> and <g>web.xml</g>.</p>

</s2>

<s2 title="\${resin.home}">

<p>Resin's configuration files can use <a href="jsp-el.xtp">EL</a>
expressions, including predefined variables like
<a href="el-var.xtp#resin">${resin}</a>, 
<a href="el-var.xtp#cluster">${cluster}</a>, 
<a href="el-var.xtp#host">${host}</a>, and
<a href="el-var.xtp#webApp">${webApp}</a>.</p>

</s2>

<s2 title="&lt;host&gt;">

<p>The <a href="host-tags.xtp#host">&lt;host&gt;</a> tags configure
<a href="virtual-host.xtp">virtual host</a>.  In this minimal example,
the host is the default virtual host; it will match any host which other
&lt;host&gt; tags do not match.</p>

<p>More complicated sites with many virtual hosts will
often use a <a href="host-tags.xtp#host-deploy">host-deploy</a> tag
to automatically deploy virtual hosts in a <var>hosts</var> deployment
directory, and use <a href="host-tags.xtp#host-default">host-default</a>
to share common virtual host configuration.</p>

</s2>

<s2 title="&lt;web-app-deploy&gt;">

<p>The <a href="webapp-tags.xtp#web-app">&lt;web-app&gt;</a> and
 <a href="webapp-tags.xtp#web-app-deploy">&lt;web-app-deploy&gt;</a>
tags configure web-applications.  Web applications are mini-virtual hosts,
i.e. sections of the web site that are conceptually distinct from
each other.  Many sites will only have a single root web-application.</p>

<p>The &lt;web-app-deploy&gt; tag defines a <var>webapps</var> directory
which automatically deploys web-applications.  The <var>ROOT</var>
web-app is a special name which matches the root URL.</p>

</s2>

</s1>

<s1 title="Virtual Hosts">

<p>Adding a <a href="virtual-host.xtp">virtual host</a> with Resin can be
as simple as creating new directories and adding content.  The default
virtual host has
a <a href="host-tags.xtp#host-deploy">&lt;host-deploy&gt;</a> tag which
defines a <var>hosts</var> deployment directory.  For example, a
virtual host <var>www.foo.com</var> might be browsable as
<var>http://www.foo.com/test.php</var>.  Assuming the server-root is
<var>/var/www</var>, you can create a new virtual host by adding a file in:</p>

<example>
/var/www/hosts/www.foo.com/webapps/ROOT/test.php
</example>

<p>Of course, Resin's virtual host's can be configured in other directory
configurations.  The <a href="host-tags.xtp#host">&lt;host&gt;</a>,
<a href="host-tags.xtp#host-deploy">&lt;host-deploy&gt;</a>, and
<a href="host-tags.xtp#host-default">&lt;host-default&gt;</a> tags
let sites choose where to put their virtual hosts.</p>

<p>The following example shows both the &lt;host> and &lt;host-deploy>
methods of configuring virtual hosts.  The &lt;host&gt;
for <var>www.foo.com</var> directly configures the foo.com site in
the resin.xml.  The &lt;host-deploy&gt; for <var>hosts</var> configures
a host deployment directory.  Any directory added to <var>hosts</var> will
automatically create a new virtual host.  Finally, the &lt;host> with
<var>id=""</var> defines the "default" virtual host. Any request not matching
any other host will use the virtual host.</p>

<example title="resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">
    &lt;root-directory>/var/www&lt;/root-directory>

    &lt;server ... />

    &lt;host-default>
      &lt;web-app-deploy path="webapps"/>

      &lt;resin:import path="host.xml" optional="true"/>
    &lt;/host-default>

    &lt;host id="www.foo.com">
      &lt;host-alias>foo.com&lt;/host-alias>

      &lt;root-directory>foo.com&lt;/root-directory>
    &lt;/host>

    &lt;host id="">
      &lt;root-directory>default-host&lt;/root-directory>
    &lt;/host>

    &lt;host-deploy path="hosts"/>
  &lt;/cluster>
&lt;/resin>
</example>

<p>The above example also introduces the &lt;host-default> tag.  The
&lt;host-default> defines configuration common to all hosts following the
&lt;host-default>.   In this case, we define an optional host
configuration file <var>host.xml</var> and a standard <var>webapps</var>
deployment directory.  The &lt;host-default> are processed as macros
in configuration-file order.  So a configuration tag later in the file
can override the defaults.</p>

</s1>

<s1 title="Clustering">

<p>In Resin, adding servers to a cluster is just adding
a <a href="server-tags.xtp#server">&lt;server></a> tag to
a <a href="cluster-tags.xtp#cluster">&lt;cluster></a> block.
Each &lt;server> has an <var>id</var> which is unique in the
resin.xml file.  The server will also have a
unique <var>address</var> and <var>port</var> which allows
the servers in the cluster to communicate with each other.</p>

<p>Clustering is used for <a href="clustering-overview.xtp">load-balancing</a>,
<a href="sessions.xtp">distributed sessions</a> and remote
administration.  Adding servers to a cluster lets sites handle more traffic
and improves reliability by providing redundant servers.</p>

<example title="resin.xml for hardware load balancing">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">

    &lt;server-default>
      &lt;http port="80"/>

      &lt;user-name>resin&lt;/user-name>
    &lt;/server-default>

    &lt;server id="app-a" address="192.168.2.10" port="6800"/>
    &lt;server id="app-b" address="192.168.2.11" port="6800"/>
    &lt;server id="app-c" address="192.168.2.12" port="6800"/>

    &lt;host id="">
       ...
    &lt;/host>
  &lt;/cluster>
&lt;/resin>
</example>

<p>In the previous example, each server listens to port 80 as defined
in the &lt;server-default>.  The unique <var>id</var> and <var>address</var>
are internal IP addresses.  (The server <var>address</var> should never be
external.)  Because the example is listening to port 80, the
<a href="server-tags.xtp#user-name">&lt;user-name></a> switches from root to
a safer runtime uid.</p>

<p>The resin.xml can define multiple &lt;cluster> tags in the same
resin.xml.  Resin's load-balancing will typically use two clusters,
a web-tier for the HTTP servers and an app-tier for the servlets,
PHP and JSP files.  A sample load balancing configuration might look like:</p>

<example title="resin.xml for resin load balancing">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="web-tier">
    &lt;server-default>
      &lt;http port="80"/>
    &lt;/server-default>

    &lt;server id="web-a" address="192.168.1.10" port="6800"/>

    &lt;cache memory-size="64M"/>

    &lt;host id="">
      &lt;web-app id="">

        &lt;rewrite-dispatch>
          &lt;load-balance regexp="" cluster="app-tier"/>
        &lt;/rewrite-dispatch>
      &lt;/web-app>
    &lt;/host>
  &lt;/cluster>

  &lt;cluster id="web-tier">
    &lt;server id="app-a" address="192.168.2.10" port="6800"/>
    &lt;server id="app-b" address="192.168.2.11" port="6800"/>
    &lt;server id="app-c" address="192.168.2.12" port="6800"/>

    &lt;host id="www.foo.com">
       ...
    &lt;/host>
  &lt;/cluster>
&lt;/resin>
</example>

</s1>

<s1 title="URL rewriting and dispatching">

<p>Resin includes a <a href="rewrite-tags.xtp">&lt;rewrite-dispatch&gt;</a>
tag for general URL rewriting and dispatching similar to Apache's mod_rewrite.
&lt;rewrite-dispatch> can forward to a new location when a site moves content,
it can convert host urls into paths, and rewrite "pretty" URLs into
PHP pages, load-balance to a cluster, and dispatch to normal servlets.</p>

<p>The following example rewrites "pretty" URLs like /wiki/Load-balance to
actual urls like <var>/wiki/index.php/Load-balance</var></p>

<example title="resin-web.xml rewrite for Mediawiki">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;rewrite-dispatch>
    &lt;dispatch regexp="\.(php|gif|css|jpg|png)"/>

    &lt;forward regexp="" target="/index.php"/>
  &lt;/rewrite-dispatch>

&lt;/web-app>
</example>

<s2 title="Redirecting changed hosts">

<example title="resin.xml redirect">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="">
    ...

    &lt;rewrite-dispatch>
      &lt;redirect regexp="^http://www.foo.com" target="http://test.com/"/>
  &lt;/rewrite-dispatch>

  &lt;/cluster>
&lt;/resin>
</example>

</s2>

<s2 title="Load balancing">

<example title="resin.xml load balancing">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="web-tier">
    &lt;server id="web-a">
       &lt;http port="80"/>
    &lt;/server>

    &lt;host id="">
      &lt;web-app id="/">
        &lt;rewrite-dispatch>
          &lt;load-balance regexp="" cluster="app-tier"/>
        &lt;/rewrite-dispatch>
      &lt;/web-app>
    &lt;/host>
  &lt;/cluster>

  &lt;cluster id="app-tier">
     &lt;server id="app-a" server="192.168.2.10"/>
     &lt;server id="app-b" server="192.168.2.11"/>

     ...
  &lt;/cluster>
&lt;/resin>
</example>

</s2>

</s1>

<s1 title="Web Services: REST, Hessian, SOAP">

<p>With Resin 3.1, applications can deploy
<a href="../tutorial/rest-flickr/index.xtp">REST</a>, 
<a href="hessian.xtp">Hessian</a>, and SOAP using the
same instance class.  A good introductary example
is the <a href="soa|tutorial/soa-hello-world/index.xtp">SOA Hello, World tutorial.</a></p>

<s2 title="Web Service configuration">

<p>The <a href="soa-tags.xtp#web-service">&lt;web-service&gt;</a>
tag configures the web service.  The service is a Java object which
exposes a JAX-WS interface and receives and sends Java objects
encoded with JAXB.  The service object itself is configured
using JAXB-style IoC, i.e. standard bean-style property
initialization.</p>

<example title="resin-web.xml web-service">
&lt;web-app xmlns="http://caucho.com/ns/resin">

&lt;web-service class="example.HelloServiceImpl">
  &lt;jndi-name>service/HelloService&lt;/jndi-name>

  &lt;init>
    &lt;greeting>Hello, World&lt;/greeting>
  &lt;/init>

  &lt;hessian>
    &lt;url-pattern>/hello/hessian/*&lt;/url-pattern>
  &lt;/hessian>

  &lt;rest>
    &lt;url-pattern>/hello/rest/*&lt;/url-pattern>
  &lt;/rest>

  &lt;soap>
    &lt;url-pattern>/hello/soap/*&lt;/url-pattern>
  &lt;/soap>
&lt;/web-service>

&lt;/web-app>
</example>

</s2>

<s2 title="Web Service Client configuration">

<p>The web service client configuration makes a Java proxy
available to servlets and PHP pages through JNDI, or through a
@Resource injection.  The client can be SOAP, Hessian, or REST.
A <a href="soa|tutorial/soa-flickr/index.xtp">REST tutorial</a> shows
how to obtain a proxy to the Flickr REST service.</p>

<p>The <a href="soa-tags.xtp#web-service-client">&lt;web-service-client></a>
tag configures the client proxy.  It provides a Java interface and
a URL for the service.  The URL specifies the encoding and the protocol,
e.g. REST over HTTP or Hessian over HTTP.  The client will typically
have a <var>jndi-name</var> to store the client proxy.</p>

<example title="web-service-client in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;web-service-client jndi-name="rest/flickr">
    &lt;url>rest:http://foo.com/flickr/rest/&lt;/url>

    &lt;interface>example.FlickrAPI&lt;/interface>

    &lt;jaxb-package>example.data&lt;/jaxb-package>
  &lt;/web-service-client>

&lt;/web-app>
</example>

</s2>

</s1>

</body>
</document>
