Resin Installation

From Resin 3.0

(Difference between revisions)
Jump to: navigation, search
(New page: <document> <header> <product>resin</product> <version>Resin 4.0</version> <title>Resin Installation</title> <description> <p><b><em>Resin Step-by-Step Installation...)
 
 
(One intermediate revision by one user not shown)
Line 1,180: Line 1,180:
  
  
 +
</body>
 +
</document>
 +
 +
<document>
 +
  <header>
 +
    <product>resin</product>
 +
    <title>Resin with Apache</title>
 +
    <description>
 +
      <p>Resin provides a fast servlet runner for Apache 1.3 or greater,
 +
        allowing Apache to run servlets and JSP files.
 +
      </p>
 +
 +
    </description>
 +
  </header>
 +
 +
<body>
 +
 +
<s1>
 +
<p>If you have not yet done so, we suggest you use the <a href="resin-web-server.xtp">Resin standalone web server</a> option
 +
      first.</p>
 +
</s1>
 +
 +
<localtoc/>
 +
 +
<s1 name="standalone" title="Before you integrate Resin with Apache">
 +
<p>
 +
Before integrating Resin with Apache, it is valuable to configure Resin as a
 +
<a href="resin-web-server.xtp">standalone server</a>, especially with more
 +
complicated setups such as those involving virtual hosts.  Doing so isolates
 +
the steps and makes troubleshooting easier.
 +
</p>
 +
 +
<p>
 +
Many users find that the performance, flexibility, and features of Resin
 +
make Resin a desirable replacement for Apache.
 +
</p>
 +
</s1>
 +
 +
<s1 name="dispatch" title="How Resin integrates with Apache">
 +
 +
<p>When used with Apache, Resin serves JSPs and Servlets and Apache serves
 +
static content like html and images.  Apache is a frontend server, it handles
 +
the request from the browser. Resin's <code>mod_caucho</code> plugin integrates
 +
with Apache, it dispatches requests for JSPs and Servlets to one or more
 +
backend Resin servers.</p>
 +
 +
<figure src="apache_srun.gif"/>
 +
 +
<p>
 +
mod_caucho queries the backend server to distinguish the URLs going to Resin
 +
from the URLs handled by Apache.  The backend server uses the
 +
&lt;servlet-mapping&gt; directives to decide which URLs to send.  Also, any *.war
 +
file automatically gets all its URLs.  Other URLs stay with Apache.
 +
</p>
 +
 +
<p>
 +
There's a more complete discussion of the URL dispatching in the
 +
<a href="plugin-dispatch.xtp">How the Plugins Dispatch to Resin</a> page.
 +
</p>
 +
 +
</s1> <!-- dispatch -->
 +
 +
<s1 name="unix" title="Unix Installation">
 +
 +
<p>Resin needs Apache 1.3.x or greater and DSO support.</p>
 +
 +
<p>To configure Resin with Apache, you must follow the following steps:</p>
 +
<ol>
 +
<li>Compile Apache
 +
</li><li>Compile mod_caucho.so
 +
</li><li>Configure Apache
 +
</li><li>Set up environment
 +
</li><li>Configure resin.xml
 +
</li><li>Restart Apache and start the backend Resin server
 +
</li></ol>
 +
 +
<s2 title="Compiling Apache">
 +
 +
<p>You need a version of Apache with DSO support enabled. Apache has
 +
full documentation at <a href="http://httpd.apache.org/docs/dso.html">their website</a>.
 +
To check if your apache has DSO support, you can check for
 +
<var>mod_so.c</var> in your your httpd
 +
 +
<example title="checking apache httpd for mod_so.c">
 +
unix&gt; /usr/local/apache/bin/httpd -l
 +
Compiled-in modules:
 +
  ...
 +
  mod_so.c
 +
  ...
 +
</example>
 +
 +
</p><p>Many distributions, e.g. Red Hat Linux, will have Apache preinstalled.
 +
However, because the standard distribution has files all over the
 +
place, some people prefer to recompile Apache from scratch.</p>
 +
 +
<p>Once you untar Apache, build it like:</p>
 +
 +
<example>
 +
unix&gt; ./configure --prefix=/usr/local/apache --enable-module=so
 +
unix&gt; make
 +
unix&gt; make install
 +
</example>
 +
 +
<p>Solaris versions of Apache may need additional flags, otherwise
 +
you'll get some linking errors when trying to load Resin.  You may need
 +
to refer to the Apache documentation if you get linking errors.  Here's an
 +
example configuration on Solaris:</p>
 +
 +
<example>
 +
unix&gt; ./configure --prefix=/usr/local/apache \
 +
                  --enable-rule=SHARED_CORE \
 +
                  --enable-rule=SHARED_CHAIN \
 +
                  --enable-module=so \
 +
                  --enable-module=most \
 +
                  --enable-shared=max
 +
</example>
 +
 +
</s2>
 +
 +
<s2 title="Compiling mod_caucho.so">
 +
 +
<p>To compile and install <var>mod_caucho</var> on Unix, you'll need to run
 +
Resin's <code>configure</code> and then make.  This step will create
 +
mod_caucho.so and put it in the Apache module directory.  Usually,
 +
mod_caucho.so will end up in /usr/local/apache/libexec/mod_caucho.so.</p>
 +
 +
<p>If you know where your <var>apxs</var> executable is, you can use --with-apxs.
 +
<var>apxs</var> is a little Perl script that the Apache configuration
 +
makes.  It lets modules like Resin know how all the Apache directories
 +
are configured.  It is generally in /usr/local/apache/bin/apxs or
 +
/usr/sbin/apxs.  It's usually easiest to use --with-apxs so you don't
 +
need to worry where all the Apache directories are.</p>
 +
 +
<example>
 +
unix&gt; ./configure --with-apxs=/usr/local/apache/bin/apxs
 +
unix&gt; make
 +
</example>
 +
 +
<p>Even if you don't know where <var>apxs</var> is, the configure script
 +
can often find it:</p>
 +
 +
<example>
 +
unix&gt; ./configure --with-apxs
 +
unix&gt; make
 +
</example>
 +
 +
<p>As an alternative to --with-apxs, if you've compiled Apache yourself,
 +
or if you have a simple configuration, you can generally just point to
 +
the Apache directory:</p>
 +
 +
<example>
 +
unix&gt; ./configure --with-apache=/usr/local/apache
 +
unix&gt; make
 +
unix&gt; make install
 +
</example>
 +
 +
<p>The previous --with-apxs or --with-apache should cover most
 +
configurations.  For some unusual configurations, you can have finer control
 +
over each directory with the following arguments to ./configure.
 +
In general, you should use --with-apache or --with-apxs, but the other
 +
variables are there if you know what you're doing.</p>
 +
 +
<deftable>
 +
<tr><td>--with-apache=dir</td><td>The Apache root directory.
 +
</td></tr><tr><td>--with-apxs=apxs</td><td>Pointer to the Apache extension script
 +
</td></tr><tr><td>--with-apache-include=dir</td><td>The Apache include directory
 +
</td></tr><tr><td>--with-apache-libexec=dir</td><td>The Apache module directory
 +
</td></tr><tr><td>--with-apache-conf=httpd.conf</td><td>The Apache config file
 +
</td></tr></deftable>
 +
 +
</s2>
 +
 +
<s2 title="Configure the Environment">
 +
 +
<p>If you don't already have Java installed, you'll need to download a
 +
JDK and set some environment variables.</p>
 +
 +
<p>Here's a typical environment that you might put in ~/.profile or
 +
/etc/profile</p>
 +
 +
<example>
 +
# Java Location
 +
JAVA_HOME=/&lt;installdir&gt;/jdk1.4
 +
export JAVA_HOME
 +
 +
# Resin location (optional).  Usually Resin can figure this out.
 +
RESIN_HOME=/&lt;installdir&gt;/resin-3.2.2
 +
export RESIN_HOME
 +
 +
# If you're using additional class libraries, you'll need to put them
 +
# in the classpath.
 +
CLASSPATH=
 +
</example>
 +
 +
</s2>
 +
 +
</s1> <!-- unix -->
 +
 +
<s1 name="windows" title="Windows Installation">
 +
<p>
 +
The <code>setup.exe</code> program installs the mod_caucho.dll
 +
plugin for any Apache it finds, and modifies the Apache httpd.conf file.
 +
</p>
 +
 +
<p>
 +
The httpd.conf file is also easily modified manually:
 +
</p>
 +
 +
<example title="httpd.conf">
 +
LoadModule caucho_module \
 +
    &lt;installdir&gt;/resin-3.2.x/win32/apache-2.0/mod_caucho.dll
 +
 +
ResinConfigServer localhost 6800
 +
&lt;Location /caucho-status&gt;
 +
  SetHandler caucho-status
 +
&lt;/Location&gt;
 +
</example>
 +
 +
</s1> <!-- windows -->
 +
 +
 +
<s1 title="Configuring resin.xml">
 +
 +
<p>
 +
The communication between <code>mod_caucho</code> and the backend Resin
 +
server takes place using a <var>server</var> port.
 +
</p>
 +
 +
<p>
 +
The <code>resin.xml</code> for the backend server contains
 +
a <code>server</code> to enable the port.  The default <code>resin.xml</code>
 +
has an server listener on port 6800.
 +
</p>
 +
 +
<example title="resin.xml">
 +
&lt;resin xmlns="http://caucho.com/ns/resin"
 +
      xmlns:resin="http://caucho.com/ns/resin/core"&gt;
 +
 +
  ...
 +
 +
 +
  &lt;cluster id="app-tier"&gt;
 +
 +
    ...
 +
 +
    <b>&lt;server id="" address="127.0.0.1" port="6800"/&gt;</b>
 +
 +
    ...
 +
 +
</example>
 +
 +
 +
<p>
 +
The resin.xml and the layout of your webapps should match the
 +
layout that Apache expects.  The mapping of urls to filesystem locations
 +
should be consistent between Apache and the backend Resin server.
 +
</p>
 +
 +
 +
<p>The default resin.xml looks in
 +
<code>resin-3.2.x/webapps/ROOT</code>
 +
for JSP files and
 +
<code>resin-3.2.x/webapps/ROOT/WEB-INF/classes</code>
 +
for servlets and java source files.  To tell Resin
 +
to use Apache's document area, you configure an explicit
 +
<var>web-app</var> with the appropriate document-directory:
 +
</p>
 +
 +
<example title="resin.xml">
 +
&lt;resin xmlns="http://caucho.com/ns/resin"
 +
      xmlns:resin="http://caucho.com/ns/resin/core"&gt;
 +
 +
  ...
 +
 +
  &lt;server&gt;
 +
 +
    ...
 +
 +
    &lt;host id=""&gt;
 +
 +
      &lt;web-app id='/' document-directory="/usr/local/apache/htdocs"/&gt;
 +
 +
    &lt;/host&gt;
 +
 +
    ...
 +
 +
  &lt;/server&gt;
 +
&lt;/resin&gt;
 +
</example>
 +
 +
</s1>
 +
 +
<s1 title="Starting the app-tier Resin server">
 +
 +
<p>Now you need to start the app-tier Resin server.  Starting Resin is the same
 +
with Apache or standalone.  See the <a href="resin-web-server.xtp#deploy">Resin Web Server</a> page
 +
for a detailed description.</p>
 +
 +
<example>
 +
unix&gt; java -jar $RESIN_HOME/lib/resin.jar
 +
 +
unix&gt; bin/resin.sh
 +
 +
win&gt; resin.exe
 +
</example>
 +
 +
<results>
 +
Resin 3.2.2 (built Mon Aug  4 09:26:44 PDT 2006)
 +
Copyright(c) 1998-2006 Caucho Technology.  All rights reserved.
 +
 +
Starting Resin on Mon, 04 Aug 2006 09:43:39 -0700 (PDT)
 +
[09:43:40.664] Loaded Socket JNI library.
 +
[09:43:40.664] http listening to *:8080
 +
[09:43:40.664] ServletServer[] starting
 +
[09:43:40.879] hmux listening to *:6800
 +
[09:43:41.073] Host[] starting
 +
[09:43:41.446] Application[http://localhost:8080/resin-doc] starting
 +
[09:43:41.496] Application[http://localhost:8080] starting
 +
</results>
 +
 +
<p>
 +
Resin will print every port it's listening to.  In the above example,
 +
Resin has an http listener on port 8080 and an server listener on port 6800
 +
(using its custom 'hmux' protocol).  mod_caucho establishes connections  to
 +
Resin using port 6800, and a web browser can connect using port 8080.  Usually
 +
the 8080 port will be unused, because web browsers will make requests to Apache,
 +
these requests get dispatched to Resin as needed by mod_caucho.  A Resin
 +
configured http listener on port 8080 is a useful debugging tool, it allows you
 +
to bypass Apache and make a request straight to Resin.
 +
</p>
 +
 +
<p>The following snippet shows the
 +
&lt;<a href="port-tags.xtp#http">http</a>&gt;
 +
and &lt;<a href="server-tags.xtp#server">server</a>&gt;
 +
configuration for the above example.</p>
 +
 +
<example>
 +
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
 +
  &lt;cluster id="app-tier"&gt;
 +
    &lt;server-default&gt;
 +
      &lt;http address="*" port="8080"/&gt;
 +
    &lt;/server-default&gt;
 +
 +
    &lt;server id="" address="192.168.2.10" port="6800"/&gt;
 +
 +
    ...
 +
  &lt;/cluster&gt;
 +
&lt;/resin&gt;
 +
</example>
 +
 +
</s1>
 +
 +
<s1 title="Testing the servlet engine">
 +
 +
<p>Create a test file '/usr/local/apache/htdocs/test.jsp'</p>
 +
 +
<example>
 +
2 + 2 = &lt;%= 2 + 2 %&gt;
 +
</example>
 +
 +
<p>Browse http://localhost/test.jsp again.  You should now get</p>
 +
 +
<results>
 +
2 + 2 = 4
 +
</results>
 +
 +
</s1>
 +
 +
<s1 name="httpd.conf" title="Configuring Apache httpd.conf">
 +
 +
<p>
 +
The installation process above automatically changes the httpd.conf file.
 +
You can also configure the httpd.conf file manually, or modify the
 +
default configuration created by the installation process.
 +
</p>
 +
 +
<example title="Unix - httpd.conf">
 +
LoadModule caucho_module libexec/mod_caucho.so
 +
 +
ResinConfigServer localhost 6800
 +
&lt;Location /caucho-status&gt;
 +
  SetHandler caucho-status
 +
&lt;/Location&gt;
 +
</example>
 +
 +
<example title="Windows - httpd.conf">
 +
LoadModule caucho_module \
 +
    &lt;installdir&gt;/resin-3.2.x/libexec/apache-2.0/mod_caucho.dll
 +
 +
ResinConfigServer localhost 6800
 +
&lt;Location /caucho-status&gt;
 +
  SetHandler caucho-status
 +
&lt;/Location&gt;
 +
</example>
 +
 +
<p>
 +
The <code>ResinConfigServer</code> is used to tell mod_caucho how to contact
 +
the backend Resin server.  The backend Resin server tell's mod_caucho which urls
 +
should be dispatched.
 +
</p>
 +
 +
<deftable>
 +
<tr><th>Apache Command</th><th>Meaning
 +
</th></tr><tr><td>ResinConfigServer <var>host</var> <var>port</var></td><td>Specifies the Resin JVM at <var>host:port</var> as a configuration server.
 +
</td></tr></deftable>
 +
 +
<s2 name="caucho-status" title="caucho-status">
 +
 +
<p>
 +
<code>caucho-status</code> is optional and probably should be avoided in
 +
a production site.  It lets you ask the Caucho Apache module about it's
 +
configuration, and the status of the backend server(s), valuable for
 +
debugging.
 +
</p>
 +
 +
<p>After any change to httpd.conf, restart Apache.  Now browse
 +
http://localhost/caucho-status.</p>
 +
 +
</s2>
 +
 +
<s2 name="manual-dispatch" title="Manual configuration of dispatching">
 +
 +
<p>
 +
You can also dispatch to Resin directly from the httpd.conf.  Instead of
 +
relying on the ResinConfigServer directive to determine which url's to dispatch
 +
to the backend server, Apache handler's are used to specify the url's to
 +
dispatch.
 +
</p>
 +
 +
<example>
 +
CauchoHost 127.0.0.1 6800
 +
 +
&lt;Location /foo/*&gt;
 +
  SetHandler caucho-request
 +
&lt;/Location&gt;
 +
</example>
 +
 +
<deftable>
 +
<tr>
 +
  <th width="30%">Apache Command</th>
 +
  <th>Meaning</th>
 +
</tr>
 +
<tr>
 +
  <td>CauchoHost <var>host</var> <var>port</var></td>
 +
  <td>Alternative to <var>ResinConfigServer</var>, adds the Resin JVM with an server port at host:port as a backend server.</td>
 +
</tr>
 +
<tr>
 +
  <td>CauchoBackup <var>host</var> <var>port</var></td>
 +
  <td>Alternative to <var>ResinConfigServer</var>, adds the Resin JVM with
 +
  a server port at host:port as a backup backend server.
 +
</td>
 +
</tr>
 +
</deftable>
 +
 +
<deftable>
 +
<tr>
 +
  <th width="30%">Apache Handler</th>
 +
  <th>Meaning</th>
 +
</tr>
 +
<tr>
 +
  <td>caucho-status</td>
 +
  <td>Handler to display /caucho-status</td>
 +
</tr>
 +
<tr>
 +
  <td>caucho-request</td>
 +
  <td>Dispatch a request to Resin</td>
 +
</tr>
 +
</deftable>
 +
 +
<p>
 +
Requests dispatched directly from the Apache httpd.conf will not
 +
appear in /caucho-status.
 +
</p>
 +
 +
</s2>  <!-- manual-dispatch -->
 +
 +
</s1>  <!-- httpd.conf -->
 +
 +
 +
<s1 name="vhosts" title="Virtual Hosts">
 +
 +
<p>
 +
The <a href="virtual-host.xtp">virtual host</a> topic describes virtual
 +
hosts in detail.  If you're using a single JVM, you only need to configure
 +
the resin.xml.
 +
</p>
 +
 +
<example title="httpd.conf">
 +
LoadModule caucho_module libexec/mod_caucho.so
 +
 +
ResinConfigServer 192.168.0.1 6800
 +
&lt;Location /caucho-status&gt;
 +
  SetHandler caucho-status
 +
&lt;/Location&gt;
 +
</example>
 +
 +
<example title="resin.xml">
 +
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
 +
&lt;cluster id="app-tier"&gt;
 +
 +
  &lt;server id="" address="192.168.0.1" port="6800"/&gt;
 +
 +
  &lt;host id='www.gryffindor.com'&gt;
 +
    &lt;host-alias&gt;gryffindor.com&lt;/host-alias&gt;
 +
    ...
 +
  &lt;/host&gt;
 +
 +
  &lt;host id='www.slytherin.com'&gt;
 +
    &lt;host-alias&gt;slytherin.com&lt;/host-alias&gt;
 +
    ...
 +
  &lt;/host&gt;
 +
&lt;/cluster&gt;
 +
&lt;/resin&gt;
 +
</example>
 +
 +
<s2 name="vhostperjvm" title="Virtual Host per JVM">
 +
 +
<p>
 +
If you want a different JVM for each virtual host, your
 +
httpd.conf can specify a different server port for each host.
 +
</p>
 +
 +
<example title="httpd.conf">
 +
&lt;VirtualHost gryffindor.com&gt;
 +
ServerName gryffindor.com
 +
ServerAlias www.gryffindor.com
 +
ResinConfigServer 192.168.0.1 6800
 +
&lt;/VirtualHost&gt;
 +
 +
&lt;VirtualHost slytherin.com&gt;
 +
ServerName slytherin.com
 +
ServerAlias www.slytherin.com
 +
ResinConfigServer 192.168.0.1 6801
 +
&lt;/VirtualHost&gt;
 +
</example>
 +
 +
<example title="gryffindor.conf">
 +
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
 +
&lt;cluster id=""&gt;
 +
 +
  &lt;server id="" address="192.168.0.1" port="6800"/&gt;
 +
 +
  &lt;host id=""&gt;
 +
    ...
 +
  &lt;/host&gt;
 +
&lt;/cluster&gt;
 +
&lt;/resin&gt;
 +
</example>
 +
 +
<example title="slytherin.conf">
 +
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
 +
&lt;cluster&gt;
 +
 +
  &lt;server id="" address="192.168.0.1" port="6801"/&gt;
 +
 +
  &lt;host id=""&gt;
 +
    ...
 +
  &lt;/host&gt;
 +
&lt;/cluster&gt;
 +
&lt;/resin&gt;
 +
</example>
 +
 +
<example>
 +
$ bin/resin.sh -pid gryffindor.pid -conf conf/gryffindor.conf start
 +
$ bin/resin.sh -pid slytherin.pid -conf conf/slytherin.conf start
 +
 +
...
 +
 +
$ bin/resin.sh -pid gryffindor.pid stop
 +
 +
</example>
 +
 +
</s2> <!-- vhostperjvm -->
 +
 +
</s1>  <!-- vhosts -->
 +
 +
 +
<s1 name="balance" title="Load Balancing">
 +
 +
<p>The <a href="resin-clustering.xtp">Reliability and Load Balancing</a>
 +
section provides an introduction to the concepts of load balancing.</p>
 +
 +
<p>mod_caucho recognizes cluster configurations for load balancing.
 +
Requests are distributed to all machines in the cluster, all
 +
requests in a session will go to the same host, and if one host goes down,
 +
Resin will send the request to the next available machine.
 +
Optional backup machines only receive requests if all of the primaries are
 +
down.</p>
 +
 +
<example title="resin.xml">
 +
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
 +
  &lt;cluster id="app-tier"&gt;
 +
    &lt;server id="a" address="192.168.0.11" port="6800" index="1"/&gt;
 +
    &lt;server id="b" address="192.168.0.11" port="6801" index="2"
 +
            backup="true"/&gt;
 +
    &lt;server id="c" address="192.168.0.12" port="6800" index="3"/&gt;
 +
    &lt;server id="d" address="192.168.0.12" port="6801" index="4"
 +
            backup="true"/&gt;
 +
    ...
 +
  &lt;/cluster&gt;
 +
&lt;/resin&gt;
 +
</example>
 +
 +
<p>
 +
mod_caucho only needs to know about one of the backend servers. It will query
 +
that backend server, and learn about all of the other members of the cluster.
 +
</p>
 +
 +
<example>
 +
ResinConfigServer 192.168.0.11 6800
 +
</example>
 +
 +
<p>
 +
mod_caucho keeps a local cache of the configuration information, so if the
 +
backend server becomes unavailable then the cached configuration will be used
 +
until the backend server becomes available again.
 +
</p>
 +
 +
<p>
 +
The httpd.conf file can also specify more than one backend server, when
 +
mod_caucho checks for configuration updates, it will check each in turn, and
 +
only if none of them are available will it use the local cached copy.
 +
</p>
 +
 +
<example>
 +
ResinConfigServer 192.168.0.11 6800
 +
ResinConfigServer 192.168.0.12 6801
 +
</example>
 +
 +
<s2 name="manual-dispatch-balance" title="Manual configuration of load balanced dispatching">
 +
<p>
 +
Manual dispatching in httpd.conf can also specify the backend hosts and the backend backup hosts, as an alternative to using <code>ResinConfigServer</code>.
 +
</p>
 +
 +
<example>
 +
CauchoHost 192.168.0.11 6800
 +
CauchoBackup 192.168.0.11 6801
 +
CauchoHost 192.168.0.12 6800
 +
CauchoBackup 192.168.0.12 6801
 +
 +
&lt;Location /foo/*&gt;
 +
  SetHandler caucho-request
 +
&lt;/Location&gt;
 +
</example>
 +
 +
</s2> <!-- manual-dispatch-balance -->
 +
 +
<s2 name="manual-dispatch-location" title="Manual configuration of location based dispatching">
 +
 +
<example>
 +
&lt;Location /applicationA/*&gt;
 +
  ResinConfigServer 192.168.0.11 6800
 +
&lt;/Location&gt;
 +
 +
&lt;Location /applicationB/*&gt;
 +
  ResinConfigServer 192.168.0.12 6800
 +
&lt;/Location&gt;
 +
</example>
 +
 +
</s2> <!-- manual-dispatch-location -->
 +
 +
</s1> <!-- balance -->
 +
 +
<s1 title="Troubleshooting">
 +
 +
<ol>
 +
<li>First, check your configuration with Resin standalone.sh.
 +
In other words, add a &lt;http port='8080'/&gt; and check port 8080.</li>
 +
<li>Check http://localhost/caucho-status.  That will tell if
 +
mod_caucho has properly connected to the backend Resin server.
 +
</li>
 +
<li>Each server should be green and the mappings should
 +
match your resin.xml.
 +
</li>
 +
<li>If caucho-status fails entirely, the problem is in the mod_caucho
 +
installation and the Apache httpd.conf.
 +
</li>
 +
<li>If caucho-status shows the wrong mappings, there's something wrong
 +
with the resin.xml or the pointer to the backend server in httpd.conf.
 +
</li>
 +
<li>If caucho-status shows a red servlet runner, then Resin hasn't
 +
properly started.
 +
</li>
 +
<li>If you get a "cannot connect to servlet engine", caucho-status
 +
will show red, and Resin hasn't started properly.
 +
</li>
 +
<li>If Resin doesn't start properly, you should look at the logs
 +
in resin-3.2.x/log.  You should start <var>resin.sh -verbose</var> or
 +
<var>resin.exe -verbose</var> to get more information.
 +
</li>
 +
<li>If Resin never shows a "hmux listening to *:6800" line,
 +
it's not listening for connections from mod_caucho.
 +
You'll need to add a &lt;server&gt; line.
 +
</li>
 +
<li>If you get Resin's "file not found", the Apache configuration
 +
is good but the resin.xml probably points to the wrong directories.
 +
</li>
 +
</ol>
 +
 +
</s1>
 +
  </body>
 +
</document>
 +
 +
<document>
 +
  <header>
 +
    <product>resin</product>
 +
    <title>Resin with IIS</title>
 +
 +
    <description>
 +
      <p>For sites requiring the use of IIS, Resin provides a fast servlet
 +
runner, allowing IIS to run servlets and JSP files.</p>
 +
 +
    </description>
 +
  </header>
 +
 +
  <body>
 +
 +
<s1>
 +
      <figure src="iis_srun.gif"/>
 +
 +
      <p>If you have not yet done so, we suggest you
 +
consider the <a href="resin-web-server.xtp">Resin
 +
web server</a> option first, either as a standalone web server or as
 +
a web-tier server load-balancing to Resin app-tier servers.
 +
Resin's Java web server provides management, clustering,
 +
and load-balancing with failover.
 +
</p>
 +
</s1>
 +
 +
    <localtoc/>
 +
 +
<s1 title="Prerequisites and Environment Variables">
 +
 +
<p>Resin requires a 1.5 JDK.  You can download one from Sun and install it.</p>
 +
 +
<p>The Control Panel is used to configure two environment variables:</p>
 +
<example>
 +
JAVA_HOME=C:\jdk1.5.0
 +
RESIN_HOME=C:\resin-4.0
 +
</example>
 +
</s1>
 +
 +
<s1 title="Configuring IIS/PWS">
 +
 +
<p>To configure Resin with IIS, you must follow the following steps:</p>
 +
<ol>
 +
<li>Configure IIS/PWS
 +
</li><li>Configure resin.xml
 +
</li><li>Start resin.exe
 +
</li></ol>
 +
 +
 +
<s2 title="ISAPI Filter">
 +
 +
<p>You should run <code>RESIN_HOME/setup.exe</code> to setup your
 +
configuration.  If setup.exe is not used, or it fails, the steps in <a href="#Manual-Configuration">Manual Configuration</a> are necessary.</p>
 +
 +
</s2>
 +
 +
<s2 title="ISAPI Filter Priority">
 +
 +
<p>isapi_srun.dll installs itself as the default priority.  Some users may need
 +
to set the priority to a higher level, e.g. to override IIS's DAV support.
 +
</p>
 +
 +
<example title="resin.ini">
 +
ResinConfigServer localhost 6802
 +
CauchoStatus yes
 +
IISPriority high
 +
</example>
 +
 +
</s2>
 +
 +
<s2 title="Configuring resin.xml">
 +
 +
<p>resin.xml should mirror the configuration of IIS.  In other words, you
 +
need to configure the document root and any directory aliases.</p>
 +
 +
<p>For many users, the only need to change needed in Resin is to change the
 +
<a config-tag="document-directory"/> attribute from 'webapps/ROOT' to something
 +
like 'C:/inetpub/wwwroot'.  The mapping of url paths from the browser to real
 +
files on the disk must be the same for Resin as they are for IIS. For more
 +
complicated configurations that use mappings in IIS, you'll need to add <a href="webapp-tags.xtp">path-mapping</a> attributes
 +
to match.</p>
 +
 +
<example title="Example: resin.xml" language="xml">
 +
&lt;resin xmlns="http://caucho.com/ns/resin">
 +
&lt;cluster id="">
 +
 +
  &lt;!-- configures the default host, matching any host name --&gt;
 +
  &lt;host id=""&gt;
 +
 +
  &lt;!-- configures the root web-app --&gt;
 +
  &lt;web-app id='/'&gt;
 +
    &lt;root-directory&gt;C:/inetpub/wwwroot&lt;/root-directory&gt;
 +
    &lt;!-- adds xsl to the search path --&gt;
 +
    &lt;class-loader&gt;
 +
      &lt;simple-loader path="$host-root/xsl"/&gt;
 +
    &lt;/class-loader&gt;
 +
  &lt;/web-app&gt;
 +
&lt;/host&gt;
 +
 +
&lt;/cluster&gt;
 +
&lt;/cluster&gt;
 +
</example>
 +
 +
</s2>
 +
 +
<s2 title="Testing the servlet engine">
 +
 +
<p>From a <code>cmd</code> shell run <code>RESIN_HOME/resin.exe</code> to start the
 +
servlet runner.</p>
 +
 +
<example title="Run resin.exe">
 +
C:\&gt; cd %RESIN_HOME%
 +
C:\resin-3.2&gt; resin.exe
 +
</example>
 +
 +
<p>Now browse http://localhost/test.jsp.  You should get a 'file not
 +
found' message.</p>
 +
 +
<p>Create a test file 'd:\inetpub\wwwroot\test.jsp'</p>
 +
 +
<example>
 +
2 + 2 = &lt;%= 2 + 2 %&gt;
 +
</example>
 +
 +
<p>Browse http://localhost/test.jsp again.  You should now get</p>
 +
 +
<results>
 +
2 + 2 = 4
 +
</results>
 +
</s2>
 +
 +
</s1>
 +
 +
<s1 title="Command line arguments">
 +
 +
<p>The following configuration line arguments are recognized by resin.exe.
 +
When command line arguments are used along with <code>-install</code> to
 +
install as a service, the arguments are used each time the service starts.</p>
 +
 +
<deftable>
 +
<tr><th>Argument</th><th>Meaning
 +
</th></tr><tr><td>-verbose</td><td>Write more verbose information to the log file
 +
</td></tr><tr><td>-resin_home &lt;path&gt;</td><td>Sets the location of Resin
 +
</td></tr><tr><td>-java_home &lt;path&gt;</td><td>Specify the JDK location
 +
</td></tr><tr><td>-msjava</td><td>Use Microsoft's JVM
 +
</td></tr><tr><td>-nojit</td><td>Disable JIT compilation to help debugging
 +
</td></tr><tr><td>-classpath &lt;cp&gt;</td><td>Add to the classpath
 +
</td></tr><tr><td>-J&lt;arg&gt;</td><td>Set a Java command line argument, e.g. -J-nojit.
 +
</td></tr><tr><td>-X&lt;arg&gt;</td><td>Set a Java -X command line argument, e.g. -Xms128m.
 +
</td></tr><tr><td>-D&lt;foo=bar&gt;</td><td>Set a Java variable, e.g. -Dresin.home=here.
 +
</td></tr><tr><td>-install</td><td>Install as an NT service
 +
</td></tr><tr><td>-install-as &lt;name&gt;</td><td>Install as an NT service with the specific name.
 +
</td></tr><tr><td>-remove</td><td>Remove as an NT service
 +
</td></tr><tr><td>-remove-as &lt;name&gt;</td><td>Remove as an NT service with the specific name.
 +
</td></tr></deftable>
 +
 +
<s2 title="Memory Configuration">
 +
 +
<p>Memory configuration is part of the JVM's arguments.  For most JVMs,
 +
you can find the full list by starting "java -X".</p>
 +
 +
<deftable title="Memory Configuration">
 +
<tr><th>Argument</th><th>Meaning
 +
</th></tr><tr><td>-Xms&lt;size&gt;</td><td>Initial Java heap size, e.g. -Xms32m
 +
</td></tr><tr><td>-Xmx&lt;size&gt;</td><td>Maximum Java heap size, e.g. -Xmx128m
 +
</td></tr><tr><td>-Xms&lt;size&gt;</td><td>the size of the heap for the young generation
 +
</td></tr></deftable>
 +
 +
<p>See <a href="jvm-tuning.xtp#memory">Performance : JVM Tuning : Memory</a> for more information on JVM memory usage.</p>
 +
 +
</s2>
 +
 +
</s1>
 +
 +
<s1 title="Deploying as an NT Service">
 +
 +
<p>Once you're comfortable with using Resin with IIS, you can install it
 +
as an NT service.  As a service, Resin will automatically start when
 +
NT reboots.  The service will also automatically restart Resin if it
 +
unexpectedly exits.</p>
 +
 +
<p>To install the service, use</p>
 +
 +
<example>
 +
win&gt; resin-3.2.x/resin.exe -install
 +
</example>
 +
 +
<p>To remove the service, use</p>
 +
 +
<example>
 +
win&gt; resin-3.2.x/resin.exe -remove
 +
</example>
 +
 +
<p>You will either need to reboot the machine or start the service
 +
from the Control&#160;Panel/Services panel to start the server.  On a
 +
machine reboot, NT will automatically start the servlet runner.</p><p/>
 +
 +
<note>There is a bug in many JDKs which cause the JDK to exit when the
 +
administrator logs out.  JDK 1.4 and later can avoid that bug if the
 +
JDK is started with -Xrs. </note>
 +
 +
<example>
 +
win&gt; resin-3.2.x/resin.exe -install -Xrs
 +
</example>
 +
 +
</s1>
 +
 +
<s1 name="balance" title="Load Balancing">
 +
 +
<p>With Resin, you can distribute requests to multiple machines.  All
 +
requests with the same session will go to the same host.  In addition, if one
 +
host goes down, the IIS filter will send the request to the next
 +
available machine.</p>
 +
 +
<p>In addition, you can specify backup machines.  The backup only will serve
 +
requests if all primaries are down.</p>
 +
 +
<p>See the <a href="cluster.xtp">Resin config</a> section for more
 +
details.</p>
 +
 +
<example title="resin.xml">
 +
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
 +
&lt;cluster id="app-tier"&gt;
 +
 +
    &lt;server id="a" address="host1" port="6802" index="1"/&gt;
 +
    &lt;server id="b" address="host2" port="6802" index="2"/&gt;
 +
    &lt;server id="c" address="backup" port="6802" index="3" backup="true"/&gt;
 +
  ...
 +
&lt;/cluster&gt;
 +
&lt;/resin&gt;
 +
</example>
 +
 +
<example title="installing multiple servlet runners as services">
 +
win&gt; resin-3.2.x/resin.exe -install-as "Resin-A" -server a -Xrs
 +
win&gt; resin-3.2.x/resin.exe -install-as "Resin-B" -server b -Xrs
 +
win&gt; resin-3.2.x/resin.exe -install-as "Resin-C" -server c -Xrs
 +
</example>
 +
</s1>
 +
 +
<s1 title="Manual Configuration">
 +
 +
<p>Experts may want to configure Resin/IIS by hand instead
 +
of using the setup program.  The steps involved are:</p>
 +
 +
<ol>
 +
<li>Make sure resin.exe works
 +
</li><li>Copy isapi_srun.dll to the IIS scripts directory, <var>d:\inetpub\scripts</var>.
 +
You may need to run <var>net stop w3svc</var> to get permission to overwrite the file.
 +
</li><li>If you have a virtual site (virtual hosts), you must configure IIS to have
 +
the virtual directory <var>/scripts</var> point to <var>d:\inetpub\scripts</var> for
 +
each virtual site.
 +
 +
</li><li>(optional) Create a resin.ini in <var>d:\inetpub\scripts</var> pointing to the ResinConfigServer
 +
</li><li>(optional) Add a "CauchoStatus yes" line to the resin.ini for debugging
 +
</li><li>Configure IIS to load isapi_srun.dll as an ISAPI filter.
 +
</li><li>Restart IIS (control panel/services) or <var>net stop w3svc</var> followed
 +
by <var>net start w3svc</var>.
 +
</li><li>Browse /servlet/Hello and /foo.jsp.
 +
You should see a "cannot connect" error.
 +
</li><li>Start resin.exe
 +
</li><li>Browse /servlet/Hello and /foo.jsp.  You should now see the servlet.
 +
</li></ol>
 +
 +
<p>Copying isapi_srun.dll to <var>inetpub/scripts</var> directory is relatively
 +
straightforward.  If you're upgrading to a new version of Resin, you
 +
may need to stop IIS (control panel/services) to get permission to
 +
overwrite isapi_srun.dll.</p>
 +
 +
<p>The resin.ini is an optional file in <var>inetpub/scripts</var> to
 +
override the automatic registry $RESIN_HOME/conf/resin.xml configuration
 +
file.  If you only have one Resin server, you should not create a resin.ini
 +
and let isapi_srun.dll use the registry value set by the setup.exe program.</p>
 +
 +
<p>resin.ini is only needed if you have multiple Resin configuration
 +
files for different IIS virtual hosts.</p>
 +
 +
<p>The resin.ini should contain the following line:</p>
 +
<example>
 +
ResinConfigServer localhost 6802
 +
</example>
 +
 +
<p>You can change the host from <var>localhost</var> to a backend server.
 +
You can also add multiple <var>ResinConfigServer</var> items to cluster the
 +
configuration.</p>
 +
 +
<p>For debugging, you can add a "CauchoStatus yes" line to the resin.ini:</p>
 +
 +
<example>
 +
ResinConfigServer localhost 6802
 +
CauchoStatus yes
 +
</example>
 +
 +
<p>For security purposes, the default value of CauchoStatus is "no" when
 +
you have a resin.ini.</p>
 +
 +
<p>Adding an ISAPI filter is accomplished in the IIS manager.</p>
 +
 +
<s2 title="IIS and Resin on different machines">
 +
 +
<p>When Resin and IIS are on different machines, you'll change
 +
the ResinConfigServer from "localhost" to the IP address of the
 +
Resin server.</p>
 +
 +
<example>
 +
ResinConfigServer 192.168.0.10 6802
 +
CauchoStatus yes
 +
</example>
 +
 +
</s2>
 +
 +
</s1>
 +
 +
<s1 title="Virtual Sites (Virtual Hosts)">
 +
 +
<p>If IIS is managing multiple virtual sites (everyone else calls them virtual
 +
hosts), then you need to configure IIS to use the isapi_srun.dll filter for
 +
each virtual site.  Configure IIS to have the virtual directory <var>/scripts</var>
 +
for each virtual site point to <var>d:\inetpub\scripts</var>, so that each virtual site uses the isapiu_srun.dll.</p>
 +
 +
<p>Resin is configured to recognize virtual hosts with the <var>id</var> attribute
 +
of <a config-tag="host"/>. </p>
 +
 +
<example title="resin.xml with virtual hosts">
 +
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
 +
  ...
 +
  &lt;server&gt;
 +
    ...
 +
 +
    &lt;host id="foo.com"&gt;
 +
      ...
 +
    &lt;/host&gt;
 +
 +
    &lt;host id="bar.com"&gt;
 +
      ...
 +
    &lt;/host&gt;
 +
 +
    &lt;host id="baz.com"&gt;
 +
      ...
 +
    &lt;/host&gt;
 +
 +
  &lt;/server&gt;
 +
&lt;/resin&gt;
 +
</example>
 +
 +
<p>Resin recognizes which host to use by examing the url.  With the above
 +
example, a url of <code>http://foo.com/some/path</code> will use host
 +
<code>id="foo.com"</code> and a url of <code>http://bar.com/some/path</code>
 +
will use host <code>id="bar.com"</code>.</p>
 +
 +
</s1>
 +
 +
<s1 title="Virtual Sites with different JVM's">
 +
 +
<p>If a seperate JVM for each virtual site is desired, a seperate
 +
<code>resin.ini</code> is used for each virtual site.  The resin.ini file is placed
 +
in the <code>scripts</code> directory.</p>
 +
 +
<example title="resin-foo.xml">
 +
<!-- for foo.com jvm -->
 +
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
 +
&lt;cluster id=""&gt;
 +
 +
  &lt;server port="6800"/&gt;
 +
 +
  ...
 +
  &lt;host id="*"&gt;
 +
    ...
 +
  &lt;/host&gt;
 +
 
 +
&lt;/cluster&gt;
 +
&lt;/resin&gt;
 +
</example>
 +
 +
<example title="resin-bar.xml">
 +
<!-- for bar.com jvm -->
 +
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
 +
&lt;cluster id=""&gt;
 +
 +
  &lt;server port="6801"/&gt;
 +
 +
  ...
 +
  &lt;host id="*"&gt;
 +
    ...
 +
  &lt;/host&gt;
 +
&lt;/cluster&gt;
 +
&lt;/resin&gt;
 +
</example>
 +
 +
<example title="installing a servlet runner for each virtual site">
 +
win&gt; resin-3.2.x/resin.exe -install-as "Resin-foo" \
 +
    -conf resin-foo.xml -Xrs
 +
win&gt; resin-3.2.x/resin.exe -install-as "Resin-bar" \
 +
    -conf resin-bar.xml -Xrs
 +
</example>
 +
 +
<example title="resin.ini for IIS virtual site foo.com">
 +
ResinConfigServer localhost 6802
 +
</example>
 +
 +
<example title="resin.ini for IIS virtual site bar.com">
 +
ResinConfigServer localhost 6803
 +
</example>
 +
 +
<p>The ResinConfigServer tells the isapi_srun.dll the port number to use to
 +
connect to the Resin instance.  You can change the host from <var>localhost</var>
 +
to a backend server.  You can also add multiple <var>ResinConfigServer</var> items
 +
to cluster the configuration.</p>
 +
 +
<p>resin-foo.xml and resin-bar.xml contain a &lt;host id="*"&gt;, you do not
 +
need to specify the host name because each conf/JVM is only going to
 +
receive requests from a particular virtual site (because of the unique
 +
resin.ini files).</p>
 +
 +
</s1>
 +
 +
<s1 title="Troubleshooting">
 +
 +
<ol>
 +
<li>Check your configuration with the standalone web server.
 +
In other words, add a &lt;http port='8080'/&gt; block and
 +
browse http://localhost:8080.
 +
</li><li>Check <var>http://localhost/caucho-status</var>.  That will tell if
 +
the ISAPI filter/extension is properly installed.
 +
</li><li>Each server should be green and the mappings should
 +
match your resin.xml.
 +
</li><li>If caucho-status fails entirely, the problem is in the <var>isapi_srun</var>
 +
installation.  Try
 +
<var>http://localhost/scripts/isapi_srun.dll/caucho-status</var> directly
 +
(bypassing the filter).  If this fails, IIS can't find isapi_srun.dll.
 +
<ul>
 +
<li>Check that isapi_srun.dll is in <var>c:\inetpub\scripts.</var>
 +
</li><li>Make sure that both IIS and the underlying NTFS file system have permissions set appropriately for isapi_srun.dll.
 +
</li><li>Make sure that your IIS host has a mapping from <var>/scripts</var>
 +
to <var>c:\inetpub\scripts</var> and that the <var>/scripts</var> has execute
 +
permissions.
 +
</li><li>IIS 6 users may need to take <a href="#iis6">additional steps</a>.
 +
</li></ul>
 +
</li><li>If you've created a new
 +
IIS web site, you need to create a virtual directory <var>/scripts</var> pointing
 +
to the <var>d:\inetpub\scripts</var> directory.
 +
</li><li>If caucho-status shows the wrong mappings, there's something wrong
 +
with the resin.xml.
 +
</li><li>If caucho-status shows a red servlet runner, then resin.exe hasn't
 +
properly started.
 +
</li><li>If you get a "cannot connect to servlet engine", caucho-status
 +
will show red, and resin.exe hasn't started properly.
 +
</li><li>If resin.exe doesn't start properly, you should look at the logs
 +
in resin3.2/log.  You should start <var>resin.exe -verbose</var> to get
 +
more information.
 +
</li><li>If you get Resin's file not found, the IIS configuration
 +
is good but the resin.xml probably points to the wrong directories.
 +
</li></ol>
 +
 +
<s2 name="iis6" title="Troubleshooting IIS 6">
 +
<p>
 +
IIS 6/Windows 2003 users may need to perform additional steps.
 +
</p>
 +
 +
<ul>
 +
 +
<li>Make sure that the System account has suffiicient privleges to
 +
read the <code>C:\InetPub</code> and <code>C:\InetPub\Scripts</code> directory
 +
and the <code>isapi_srun.dll</code>.
 +
 +
</li><li>Check the `Web Service Extensions' listed in the `Internet Service Manager'
 +
to make sure that Resin is listed as a Web Service Extension and has a status
 +
of "enabled". You may need to click "add a new web service extension...",
 +
under Extension name add .jsp or whatever your file extension is,
 +
click Add and browse to the isapi_srun.dll, check the "Set extension status
 +
to allowed box", click OK.
 +
 +
 +
</li><li>Check that the user specified as the
 +
"application pool identity" for Resin has read/write
 +
permission to the Resin installation directory.
 +
In the Internet Service Manager, open the Properties dialog for
 +
"Application Pools".  Find the User on the "Identity" tab, it may
 +
be the user named "Network Service" in the drop-down list associated
 +
with the radio button labeled "predefined".
 +
Then check physical file permissions on the Resin installation
 +
directory and all its subdirectories and subfiles, to ensure that
 +
that user has read/write permission status is "Enabled".
 +
 +
</li></ul>
 +
 +
</s2>
 +
</s1>
 
</body>
 
</body>
 
</document>
 
</document>

Latest revision as of 10:06, 17 December 2009

<document> 

 <header>
   <product>resin</product>
   <version>Resin 4.0</version>
   <title>Resin Installation</title>

   <description>

Resin Step-by-Step Installation Guide If you've decided that you're ready to deploy Resin for production, this page will guide you through the steps to install this powerful application server system-wide. You'll see where we recommend installing the various components of Resin as well as some basic production tuning tips. 

   </description>
 </header>

 <body>

   <localtoc/>

<s1 title="Resin Server Installation">

This page is for you if you:

  • Are evaluating Resin
  • Want to do local application development with Resin
  • Have evaluated Resin and are ready to install system-wide

This page leads you step-by-step through the installation of Resin. After going through these steps, you'll have a full Java and PHP Application Server able to serve even the most demanding web sites.

You'll learn:

  • How to install Resin system-wide
  • The recommended installation locations for Resin
  • How to run the Resin administration application

<s2 title="Preparing for installation">

  1. Install JDK 1.5 or later. You'll need to set the JAVA_HOME variable in your shell or link /usr/java to the Java home directory.
  2. Download the latest version of Resin 4 from the <a href="http://www.caucho.com/download">Resin download page</a>. Grab the Professional version if:
    • You have purchased a Resin Professional license.
    • You have obtained an evaluation Resin Professional license.
    • You are considering purchasing Resin Professional (without a license, Resin Professional simply downgrades to the open source functionality). This will make it easier to upgrade in the future.
  3. Unzip or untar the Resin download. If you downloaded Resin Professional, it will unzip into resin-pro-4.x.x/, otherwise it will download into resin-4.x.x/.

</s2>

<s2 title="Installing Resin on Unix or Mac OS X">

If you're installing Resin on Windows, you can skip to the next section. If you're installing Resin on Ubuntu or Debian and want to use the .deb packaged version of Resin, skip to the end of this section.

<s3 title="Configuring the build process for Resin">

Next we'll change into the Resin directory we just unpacked to configure and build the server. The Java portions of Resin are already compiled, but this step will build additional C-based components of Resin that provide additional functionality such as:

  • A faster IO library, including massive keepalive support *
  • Support for OpenSSL *
  • The ability to run as a non-priviledged user for security
  • Connector modules for Apache

(* only available in Resin Professional)

The following command installs Resin and its files into the recommended locations on the file system:

<example> ./configure --prefix=/usr/local/resin \ 

           --with-resin-root=/var/www \
           --with-resin-log=/var/log/resin \
           --with-resin-conf=/etc/resin

</example>

This will configure Resin to install in /usr/local/resin, with support for OpenSSL if it was detected, but without support for Apache. If you want to use Apache or another 3rd party HTTP server in front of Resin (unrecommended), please take a look at our <a href="install-3rd-party.xtp">third-party HTTP server setup documentation</a>. If you need to configure other options with Resin, now is the time to do it. Please consult the <a href="configure.xtp">reference to all the configuration options</a>.

Once you've run the configuration successfully, the configure script will display a summary like the following:

<example> Resin Configuration summary: 

 RESIN_HOME: /usr/local/resin
     root: /var/www
     conf: /etc/resin/conf
     log : /var/log/resin
     init: /etc/init.d/resin

 + epoll() for keepalives
 + OpenSSL 0.9.8g 19 Oct 2007
     OpenSSL include: /usr/include
     OpenSSL lib: /usr/lib
     OpenSSL libraries:  -lssl -lcrypto

 JAVA_HOME: /usr/lib/jvm/java-6-sun
   + 32-bit JNI in -I/usr/lib/jvm/java-6-sun/include \
                   -I/usr/lib/jvm/java-6-sun/include/linux
     JNI CFLAGS: -g -O2 -DPOLL -DEPOLL -D_POSIX_PTHREAD_SEMANTICS \
                 -DHAS_SOCK_TIMEOUT -DHAS_JVMTI

</example> </s3>

<s3 title="Building and Installing Resin">

Now that you've configured the Resin build process, all you need to do is build and install! To build, just run

<example> make </example>

If this step went well, you'll now need to install the Resin files as the root user:

<example> sudo make install </example>

Where ever you install Resin to, we'll refer to that directory as resin.home.

If you have a license file for Resin, save it in /usr/local/resin/licenses

</s3>

<s3 title="Installing Resin using the .deb package on Ubuntu and Debian">

We provide a Debian packaged version of Resin that Debian and Ubuntu users can take advantage of. It performs all of the installation steps above for you and creates all the recommended server and content directories. Simply download from the <a href="http://caucho.com/download">Resin download page</a> and install using dpkg.

Alternatively, you can add Caucho's Debian repository to your system's repositories to use automated update tools like Synaptic and apt-get. To do this, add the following line to your /etc/apt/sources.list

<example> deb http://caucho.com/download/debian/ unstable universe deb http://caucho.com/download/debian/ unstable multiverse </example>

After adding this line, update your local repository cache by running:

<example> apt-get update </example>

Finally, install Resin Professional using the following:

<example> apt-get install resin-pro </example>

If you have a license file for Resin, save it in /usr/local/resin/licenses

Or install Resin Open Source with this command:

<example> apt-get install resin </example> </s3> </s2>

<s2 title="Installing Resin on Windows">

The native libraries that are included with Resin are precompiled for Windows in both 32-bit and 64-bit mode. These libraries provide:

  • A faster IO library, including massive keepalive support *
  • Support for OpenSSL *
  • Connector modules for Apache/IIS

(* only available in Resin Professional)

  1. Download the latest version of Resin 4 from the <a href="http://www.caucho.com/download">Resin download page</a>. Grab the Professional version if:
    • You have purchased a Resin Professional license.
    • You have obtained an evaluation Resin Professional license.
    • You are considering purchasing Resin Professional (without a license, Resin Professional simply downgrades to the open source functionality). This will make it easier to upgrade in the future.
  2. Unzip or untar the Resin download. If you downloaded Resin Professional, it will unzip into resin-pro-4.x.x\, otherwise it will download into resin-4.x.x\.
  3. Move the directory from the previous step to C:\Resin
  4. Run C:\Resin\setup.exe
  5. If you have a license file for Resin, save it in C:\Resin\licenses

</s2> </s1>

<s1 title="Resin Content Installation">

Once your have the Resin server installed, you can start installing your content.

<s2 title="Content from the top down">

Resin and JavaEE organize content into "web applications" or webapps. As an administrator, your developers have probably provided you with a webapp in the form of a .war file or a webapp directory. In the Resin root directory is a special subdirectory named webapps which is a webapp deploy directory. Deploying applications in Resin is as easy as copying a .war file or web application directory to one of these webapp deploy directories. Resin detects the applications and deploys them automatically.

<figure src="content-directories.png"/>

In the directory structure above, notice the special webapp directories named "ROOT". These will map to the "/" (root) application. Other webapps will map to their name. For example, "wordpress" will map to "http://www.example.com/wordpress".

</s2>

<s2 title="Permanent content locations">

Resin is configured to use the content directory structure show above by default. In the examples, the Resin root directory is /var/www. This directory is also the recommended content root for Unix. For Windows, the recommended content root is C:\www. To specify the root directory to Resin, you pass it on the command line when starting the server. For example:

<example> java -jar ${resin.home}/lib/resin.jar --root-directory /var/www start </example>

If you use the Unix startup scripts mentioned in the next section, they automatically specify the root and log directories.

</s2> </s1>

<s1 title="Starting Resin"> <s2 title="Creating Unix startup scripts for Resin">

When you installed using the .deb package or when you ran "make install" earlier, the installer created a file named /etc/init.d/resin which contains a standard Unix init.d startup file. This file will start Resin when invoked as:

<example> /etc/init.d/resin start </example>

Use the tools that came with your system to execute the script on startup.

</s2> <s2 title="Installing Resin as a Windows Service">

Resin can install itself as a Windows Service by executing the resin.exe with the -install command line option. If you pass other options to resin.exe along with the -install option, such as specifying a server or content directory, these will be used when the service is started. To install Resin as a Windows Service using the default options, simply run:

<example> C:\Resin\resin.exe -install </example>

You can also install Resin using a specific service name or install multiple Resin services using the -install-as option:

<example> C:\Resin\resin.exe -install-as ResinA </example> <s3 title="Running resin.exe on Windows Vista and Windows Server 2008">

Note: the command prompt i.e. cmd.exe on Windows Vista and Windows Server 2008 will need to be run with administrative priviliges by choosing "Run As Administrator" from the context menu(given by Windows on right click). The cmd.exe locations for Windows Vista and Windows Server 2008 are %WINDIR%/system32 and %WINDIR%/sytemwow64 respectively.

</s3> </s2> </s1>

<s1 title="Creating a password for the Resin Administration Console">

One of the most useful tools provided with Resin is the built-in, web-based administration console. This tool provides detailed information about the operation of the server, a feature that is very useful to administrators, but one which must be kept secure from unauthorized users.

If you are deploying Resin to a production machine, it's likely that you won't be running your browser on the same system as the server. In this case, you'll need to configure Resin to allow you to access the server remotely.

  1. Edit /etc/resin/resin.xml
  2. Change the line: <example> <resin:set var="resin_admin_external" value="false"/> </example>

    to

       <example>

    <resin:set var="resin_admin_external" value="true"/> 

       </example>
  3. Save /etc/resin/resin.xml and restart the server.
  4. Replace "localhost" with the name of your host in the URLs below.

Now that you're able to access the administration application, you have to set up a password and install it. In order to prove that you have access to the machine on which Resin is running, the only way to change the password is to create a file with the authentication information on that machine.

  1. Browse to http://localhost:8080/resin-admin/

  2. Enter a username and password in the lower half of the page, then click "Create Configuration File". The recommended username is "admin". <figure src="admin-password-create.png"/>
  3. After going to the next page, a new "admin-users.xml.generated" file has been created for you in the same directory as your resin.xml file is located. (If you followed the directions above, this should be in /etc/resin for Unix and C:\Resin\conf for Windows.) Just rename this file to admin-users.xml and Resin will use it to <figure src="admin-password-save.png"/>
  4. Browse back to http://localhost:8080/resin-admin/. The change you made should force Resin to restart and return a 503 error. Just hit refresh in a few moments to bring up the page again.
  5. You should now be able to login using the username and password that you gave above.

</s1>

<s1 title="Troubleshooting">

If something went wrong above, the first place to check for problems is the log.

  • If you are using Unix, look in /var/log/resin/jvm_default.log
  • If you are using Windows, look in C:\Resin\log\jvm_default.log

Hopefully, the log message will be clear enough for you to figure out the problem. If not, you have a number of resources available to you to help you figure out what's going wrong:

</s1>

</body> </document>

<document> 

 <header>
   <product>resin</product>
   <title>Resin with Apache and IIS</title>
   <description>

Resin provides a fast servlet runner for Apache 2.2, and IIS allowing these HTTP servers to dispatch requests to Resin. 

   </description>
 </header>

<body>

<localtoc/>

<s1 name="standalone" title="Before you integrate Resin with Apache or IIS">

Before integrating Resin with Apache, it is valuable to configure Resin as a <a href="install.xtp">standalone server</a>, especially with more complicated setups such as those involving virtual hosts. Doing so isolates the steps and makes troubleshooting easier.

Many users find that the performance, flexibility, and features of Resin make it a desirable replacement for Apache and IIS. These 3rd party HTTP servers add overhead to Resin's operation, therefore you should have a specific reason to run one of them with Resin.

</s1>

<s1 name="apache" title="Using Resin with Apache"> <s2 name="dispatch" title="How Resin integrates with Apache">

When used with Apache, Resin serves JSPs and Servlets and Apache serves static content like html and images. Apache is a frontend server, it handles the request from the browser. Resin's mod_caucho plugin integrates with Apache, it dispatches requests for JSPs and Servlets to one or more backend Resin servers.

<figure src="apache_srun.gif"/>

mod_caucho queries the backend server to distinguish the URLs going to Resin from the URLs handled by Apache. The backend server uses the <servlet-mapping> directives to decide which URLs to send. Also, any *.war file automatically gets all its URLs. Other URLs stay with Apache.

There's a more complete discussion of the URL dispatching in the <a href="../doc/plugin-dispatch.xtp">How the Plugins Dispatch to Resin</a> page.

</s2>

<s2 name="unix" title="Unix Installation">

Resin needs Apache 2.x or greater and DSO support. You probably have DSO support, but if you're not sure, you can check for mod_so.c when running httpd -l:

<example title="checking apache httpd for mod_so.c"> unix> /usr/local/apache/bin/httpd -l Compiled-in modules: 

 ...
 mod_so.c
 ...

</example>

If you don't have DSO support, you can recompile Apache or install another package from your operating system vendor. Check their documentation for more details.

<s3 title="Compiling mod_caucho.so">

Compiling mod_caucho on Unix is usually as easy as changing the way that you configure Resin during installation:

  1. Locate the apxs program that is included with Apache.
  2. Follow the <a href="install.xtp">Resin installation instructions</a>. In addition to any other configure script options, add the --with-apxs option. Assuming that your apxs program is in /usr/sbin/apxs, you might run configure in the following way: <example> unix> ./configure --with-apxs=/usr/sbin/apxs --prefix=/usr/local/resin </example>
  3. Run make and make install as specified in the installation instructions. In addition to building the normal Resin native libraries, these steps will also build mod_caucho, install it, and add some directives to the end of your httpd.conf file configuring mod_caucho.

</s3>


</s2>

<s2 name="windows" title="Windows Installation">

The setup.exe program installs the mod_caucho.dll plugin for any Apache it finds, and modifies the Apache httpd.conf file.

The httpd.conf file is also easily modified manually:

<example title="httpd.conf"> LoadModule caucho_module \ 

   <resin.home>/win32/apache-2.0/mod_caucho.dll

ResinConfigServer localhost 6800 <Location /caucho-status> 

 SetHandler caucho-status

</Location> </example>

Replace win32 with win64 above if you're using a 64-bit version of Apache.

</s2>


<s2 title="Configuring resin.xml">

The communication between mod_caucho and the backend Resin server takes place using a server port.

The resin.xml for the backend server contains a server to enable the port. The default resin.xml has an server listener on port 6800.

<example title="resin.xml"> <resin xmlns="http://caucho.com/ns/resin" 

      xmlns:resin="urn:java:com.caucho.resin">
 ...
 <cluster id="app-tier">
   ...
   <server id="" address="127.0.0.1" port="6800"/>
   ...

</example>


The resin.xml and the layout of your webapps should match the layout that Apache expects. The mapping of urls to filesystem locations should be consistent between Apache and the backend Resin server.


The default resin.xml looks in <resin.root>/webapps/ROOT for JSP files and <resin.root>/webapps/ROOT/WEB-INF/classes for servlets and java source files. To tell Resin to use Apache's document area, you configure an explicit web-app with the appropriate document-directory:

<example title="resin.xml"> <resin xmlns="http://caucho.com/ns/resin" 

      xmlns:resin="urn:java:com.caucho.resin">
 ...
 <cluster id="">
   ...
   <host id="">
     <web-app id='/' document-directory="/usr/local/apache/htdocs"/>
   </host>
   ...
 </cluster>

</resin> </example>

</s2>

<s2 name="httpd.conf" title="Configuring Apache httpd.conf">

The ResinConfigServer is used to tell mod_caucho how to contact the backend Resin server. The backend Resin server tell's mod_caucho which urls should be dispatched.

<deftable> <tr><th>Apache Command</th><th>Meaning </th></tr><tr><td>ResinConfigServer host port</td><td>Specifies the Resin JVM at host:port as a configuration server. </td></tr></deftable>

The caucho-status handler is optional and probably should be avoided in a production site. It lets you ask the Caucho Apache module about it's configuration, and the status of the backend server(s), valuable for debugging.

After any change to httpd.conf, restart Apache. Now browse http://localhost/caucho-status.

<s3 name="manual-dispatch" title="Manual configuration of dispatching">

You can also dispatch to Resin directly from the httpd.conf. Instead of relying on the ResinConfigServer directive to determine which url's to dispatch to the backend server, Apache handler's are used to specify the url's to dispatch.

<example> CauchoHost 127.0.0.1 6800

<Location /foo/*> 

 SetHandler caucho-request

</Location> </example>

<deftable> <tr> 

 <th width="30%">Apache Command</th>
 <th>Meaning</th>

</tr> <tr> 

 <td>CauchoHost host port</td>
 <td>Alternative to ResinConfigServer, adds the Resin JVM with an server port at host:port as a backend server.</td>

</tr> <tr> 

 <td>CauchoBackup host port</td>
 <td>Alternative to ResinConfigServer, adds the Resin JVM with
 a server port at host:port as a backup backend server.

</td> </tr> </deftable>

<deftable> <tr> 

 <th width="30%">Apache Handler</th>
 <th>Meaning</th>

</tr> <tr> 

 <td>caucho-status</td>
 <td>Handler to display /caucho-status</td>

</tr> <tr> 

 <td>caucho-request</td>
 <td>Dispatch a request to Resin</td>

</tr> </deftable>

Requests dispatched directly from the Apache httpd.conf will not appear in /caucho-status.

</s3>

</s2>


<s2 name="balance" title="Load Balancing">

The <a href="../admin/load-balancing.xtp">Load Balancing</a> section provides an introduction to the concepts of load balancing.

mod_caucho recognizes cluster configurations for load balancing. Requests are distributed to all machines in the cluster, all requests in a session will go to the same host, and if one host goes down, Resin will send the request to the next available machine. Optional backup machines only receive requests if all of the primaries are down.

mod_caucho only needs to know about one of the backend servers. It will query that backend server, and learn about all of the other members of the cluster. mod_caucho keeps a local cache of the configuration information, so if the backend server becomes unavailable then the cached configuration will be used until the backend server becomes available again.

The httpd.conf file can also specify more than one backend server, when mod_caucho checks for configuration updates, it will check each in turn, and only if none of them are available will it use the local cached copy.

<example> ResinConfigServer 192.168.0.11 6800 ResinConfigServer 192.168.0.12 6801 </example>

<s3 name="manual-dispatch-balance" title="Manual configuration of load balanced dispatching">

Manual dispatching in httpd.conf can also specify the backend hosts and the backend backup hosts, as an alternative to using ResinConfigServer.

<example> CauchoHost 192.168.0.11 6800 CauchoBackup 192.168.0.11 6801 CauchoHost 192.168.0.12 6800 CauchoBackup 192.168.0.12 6801

<Location /foo/*> 

 SetHandler caucho-request

</Location> </example>

</s3>

<s3 name="manual-dispatch-location" title="Manual configuration of location based dispatching">

<example> <Location /applicationA/*> 

 ResinConfigServer 192.168.0.11 6800

</Location>

<Location /applicationB/*> 

 ResinConfigServer 192.168.0.12 6800

</Location> </example>

</s3>

</s2>

<s2 title="Troubleshooting">

  1. Check your configuration with Resin standalone. In other words, add a <http port='8080'/> and check port 8080.
  2. Check http://localhost/caucho-status. That will tell if mod_caucho has properly connected to the backend Resin server. Each server should be green and the mappings should match your resin.xml.
  3. If caucho-status fails entirely, the problem is in the mod_caucho installation and the Apache httpd.conf.
  4. If caucho-status shows the wrong mappings, there's something wrong with the resin.xml or the pointer to the backend server in httpd.conf.
  5. If caucho-status shows a red servlet runner, then Resin hasn't properly started.
  6. If you get a "cannot connect to servlet engine", caucho-status will show red, then Resin hasn't started properly.
  7. If Resin doesn't start properly, you should look at the logs in <resin.log>/log. You should start java -jar <resin.home>/lib/resin.jar -verbose or resin.exe -verbose to get more information.
  8. If Resin never logs a "hmux listening to *:6800" line, it's not listening for connections from mod_caucho. You'll need to add a <server> line.
  9. If you get Resin's "file not found", the Apache configuration is functional but the resin.xml probably points to the wrong directories.

</s2> </s1>

<s1 title="IIS"> 

     <figure src="iis_srun.gif"/>

<s2 title="Environment Variables">

Configure the following two environment variables in the Control Panel:

<example> JAVA_HOME=C:\jdk1.5.0 RESIN_HOME=C:\Resin </example>

Of course, adjust these to the correct directories for Java and Resin if they differ from your own.

</s2>

<s2 title="Configuring IIS/PWS">

To configure Resin with IIS, you must follow the following steps:

  1. Configure IIS/PWS
  2. Configure resin.xml
  3. Start resin.exe


<s3 title="ISAPI Filter">

You should run RESIN_HOME/setup.exe to setup your configuration. If setup.exe is not used, or it fails, the steps in <a href="#Manual-Configuration">Manual Configuration</a> are necessary.

</s3>

<s3 title="ISAPI Filter Priority">

isapi_srun.dll installs itself as the default priority. Some users may need to set the priority to a higher level, e.g. to override IIS's DAV support.

<example title="resin.ini"> ResinConfigServer localhost 6802 CauchoStatus yes IISPriority high </example>

</s3>

<s3 title="Configuring resin.xml">

resin.xml should mirror the configuration of IIS. In other words, you need to configure the document root and any directory aliases.

For many users, the only need to change needed in Resin is to change the <a config-tag="document-directory"/> attribute from 'webapps/ROOT' to something like 'C:/inetpub/wwwroot'. The mapping of url paths from the browser to real files on the disk must be the same for Resin as they are for IIS. For more complicated configurations that use mappings in IIS, you'll need to add <a href="webapp-tags.xtp">path-mapping</a> attributes to match.

<example title="Example: resin.xml" language="xml"> <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> 

 <!-- configures the default host, matching any host name -->
 <host id="">

 <!-- configures the root web-app -->
 <web-app id='/'>
   <root-directory>C:/inetpub/wwwroot</root-directory>
   <!-- adds xsl to the search path -->
   <class-loader>
     <simple-loader path="$host-root/xsl"/>
   </class-loader>
 </web-app>

</host>

</cluster> </cluster> </example>

</s3>

</s2>

<s2 name="iis-balance" title="Load Balancing">

Resin's IIS plugin supports load balancing in much the same way as mod_caucho does for Apache. Consult the <a href="#balance">mod_caucho load balancing section</a> for more details.

</s2>

<s2 title="Manual Configuration">

Experts may want to configure Resin/IIS by hand instead of using the setup program. The steps involved are:

  1. Make sure resin.exe works
  2. Copy isapi_srun.dll to the IIS scripts directory, d:\inetpub\scripts.

    You may need to run net stop w3svc to get permission to overwrite the file.

  3. If you have a virtual site (virtual hosts), you must configure IIS to have

    the virtual directory /scripts point to d:\inetpub\scripts for each virtual site.

  4. (optional) Create a resin.ini in d:\inetpub\scripts pointing to the ResinConfigServer
  5. (optional) Add a "CauchoStatus yes" line to the resin.ini for debugging
  6. Configure IIS to load isapi_srun.dll as an ISAPI filter.
  7. Restart IIS (control panel/services) or net stop w3svc followed

    by net start w3svc.

  8. Browse /servlet/Hello and /foo.jsp.

    You should see a "cannot connect" error.

  9. Start resin.exe
  10. Browse /servlet/Hello and /foo.jsp. You should now see the servlet.

Copying isapi_srun.dll to inetpub/scripts directory is relatively straightforward. If you're upgrading to a new version of Resin, you may need to stop IIS (control panel/services) to get permission to overwrite isapi_srun.dll.

The resin.ini is an optional file in inetpub/scripts to override the automatic registry $RESIN_HOME/conf/resin.xml configuration file. If you only have one Resin server, you should not create a resin.ini and let isapi_srun.dll use the registry value set by the setup.exe program.

resin.ini is only needed if you have multiple Resin configuration files for different IIS virtual hosts.

The resin.ini should contain the following line:

<example> ResinConfigServer localhost 6802 </example>

You can change the host from localhost to a backend server. You can also add multiple ResinConfigServer items to cluster the configuration.

For debugging, you can add a "CauchoStatus yes" line to the resin.ini:

<example> ResinConfigServer localhost 6802 CauchoStatus yes </example>

For security purposes, the default value of CauchoStatus is "no" when you have a resin.ini.

Adding an ISAPI filter is accomplished in the IIS manager.

<s3 title="IIS and Resin on different machines">

When Resin and IIS are on different machines, you'll change the ResinConfigServer from "localhost" to the IP address of the Resin server.

<example> ResinConfigServer 192.168.0.10 6802 CauchoStatus yes </example>

</s3>

</s2>

<s2 title="Virtual Sites (Virtual Hosts)">

If IIS is managing multiple virtual sites (better known as virtual hosts), then you need to configure IIS to use the isapi_srun.dll filter for each virtual site. Configure IIS to have the virtual directory /scripts for each virtual site point to d:\inetpub\scripts, so that each virtual site uses the isapiu_srun.dll.

</s2>

<s2 title="Troubleshooting">

  1. Check your configuration with the standalone web server. In other words, add a <http port='8080'/> block and browse http://localhost:8080.
  2. Check http://localhost/caucho-status. That will tell if

    the ISAPI filter/extension is properly installed.

  3. Each server should be green and the mappings should

    match your resin.xml.

  4. If caucho-status fails entirely, the problem is in the isapi_srun

    installation. Try http://localhost/scripts/isapi_srun.dll/caucho-status directly (bypassing the filter). If this fails, IIS can't find isapi_srun.dll.

    • Check that isapi_srun.dll is in c:\inetpub\scripts.
    • Make sure that both IIS and the underlying NTFS file system have permissions set appropriately for isapi_srun.dll.
    • Make sure that your IIS host has a mapping from /scripts

      to c:\inetpub\scripts and that the /scripts has execute permissions.

    • IIS 6 users may need to take <a href="#iis6">additional steps</a>.
  5. If you've created a new

    IIS web site, you need to create a virtual directory /scripts pointing to the d:\inetpub\scripts directory.

  6. If caucho-status shows the wrong mappings, there's something wrong

    with the resin.xml.

  7. If caucho-status shows a red servlet runner, then resin.exe hasn't

    properly started.

  8. If you get a "cannot connect to servlet engine", caucho-status

    will show red, and resin.exe hasn't started properly.

  9. If resin.exe doesn't start properly, you should look at the logs

    in resin3.2/log. You should start resin.exe -verbose to get more information.

  10. If you get Resin's file not found, the IIS configuration

    is good but the resin.xml probably points to the wrong directories.

<s3 name="iis6" title="Troubleshooting IIS 6">

IIS 6/Windows 2003 users may need to perform additional steps.

  • Make sure that the System account has suffiicient privleges to read the C:\InetPub and C:\InetPub\Scripts directory and the isapi_srun.dll.
  • Check the `Web Service Extensions' listed in the `Internet Service Manager'

    to make sure that Resin is listed as a Web Service Extension and has a status of "enabled". You may need to click "add a new web service extension...", under Extension name add .jsp or whatever your file extension is, click Add and browse to the isapi_srun.dll, check the "Set extension status to allowed box", click OK.


  • Check that the user specified as the

    "application pool identity" for Resin has read/write permission to the Resin installation directory. In the Internet Service Manager, open the Properties dialog for "Application Pools". Find the User on the "Identity" tab, it may be the user named "Network Service" in the drop-down list associated with the radio button labeled "predefined". Then check physical file permissions on the Resin installation directory and all its subdirectories and subfiles, to ensure that that user has read/write permission status is "Enabled".

</s3> </s2> </s1>

<s1 name="plugins" title="Configuring resin.xml to work with Apache and IIS">

The previous sections show how to configure Apache and IIS to work with Resin. This section shows how the plugins for these servers interpret the Resin's configuration and how to change that configuration for your deployment.

The web server plugins (mod_caucho and isapi_srun) have two main tasks:

  1. Select urls to dispatch to the Java process
  2. Pass the request and retrieve the response from the Java process.

<s2 title="ResinConfigServer">

mod_caucho discovers its configuration by contacting the ResinConfigServer specified in the httpd.conf or resin.ini. The ResinConfigServer can be any Resin server. When a user requests a URL, mod_caucho uses the configuration it has determined from the ResinConfigServer to determine whether Resin or Apache should handle the request. That decision is based on the configuration in the ResinConfigServer's resin.xml.

</s2>

<s2 title="servlet-mapping selects URLs">

The <a href="webapp-tags.xtp#servlet-mapping">servlet-mapping</a> tag selects the URLs to send to Resin. <a href="host-tags.xtp#host"><host></a> and <a href="webapp-tags.xtp"><web-app></a> group the servlet-mapping tags.

<s3 title="url-pattern">

servlet-mapping's <a href="webapp-tags.xtp#url-pattern">url-pattern</a> selects the URLs to pass to Resin. servlet-mapping and url-pattern are part of the Servlet 2.3 standard, so there are many references explaining how it works.

url-pattern can take one of four forms:

  • "/" matches all URLs. Use this to pass all requests to Resin.
  • "/prefix/url/*" matches any URL starting with /prefix/url,

    including prefix/url itself. It does not match /prefix/urlfoo because any slash must immediately follow url

  • "/exact/path" matches only the exact path. In other words, it

    will not match /exact/path/bogus.

  • "*.ext" matches any URL with the extension ext. Resin

    allows path-infos, so /foo/bar.ext/path/info will also match.

</s3>

<s3 title="url-regexp">

<note>mod_caucho does not understand regular expressions. If you put regular expressions in your resin.xml, mod_caucho will not send the request to Resin. Apache will handle the request itself.</note>

If you want to use regular expressions in servlet-mapping, web-app, or hosts, you must use Apache-specific configuration to send the request to Resin. You can see this by looking at /caucho-status. /caucho-status will not display any regular expressions.

</s3>

<s3 title="special servlet-mappings">

There are two special servlet-names which only affect the plugins: plugin_match and plugin_ignore.

plugin_match will direct a request to Resin. The servlet engine itself will ignore the plugin_match directive. You can use plugin_match to direct an entire subtree to Resin, e.g. to workaround the regexp limitation, but allow Resin's other servlet-mapping directives to control which servlets are used.

plugin_ignore keeps the request at on the web server. So you could create a directory /static where all documents, including JSPs are served by the web server.

<example> <!-- send everything under /resin to Resin --> <servlet-mapping url-pattern='/resin/*' 

                servlet-name='plugin_match'/>

<!-- keep everything under /static at the web server --> <servlet-mapping url-pattern='/static/*' 

                servlet-name='plugin_ignore'/>

</example>

</s3>

<s3 title="<web-app>">

<a href="webapp-tags.xtp">web-apps</a> collect servlets and JSP files into separate applications. All the servlet-mappings in a web-app apply only to the URL suffix.

In the following example, every URL starting with /prefix/url maps to the web-app. The servlet-mapping only applies to URLs matching the prefix.

<example> ... <web-app id='/prefix/url'> 

 <servlet-mapping url-pattern='*.foo' .../>

</web-app> .. </example>

In the exaple, mod_caucho will match any URL matching /prefix/url/*.foo. /prefix/url/bar.foo will match, but /test/bar.foo will not match.

<note>Resin standalone allows a regexp attribute instead of an id. Because mod_caucho does not understand regexps, it will ignore any web-app with a regexp attribute.</note>

<note>web.xml files and war files are treated exactly the same as web-apps in the resin.xml.</note>

</s3>

<s3 title="<host>">

<a href="cluster-tags.xtp#host">host</a> blocks configure <a href="virtual-host.xtp">virtual hosts</a>. There's a bit of extra work for virtual hosts that we'll ignore here. (Basically, you need to add Apache ServerName directives so Resin knows the name of the virtual host.)

For dispatching, a host block gathers a set of web-apps. Each host will match a different set of URLs, depending on the web-app configuration. The default host matches any host not matched by a specific rule.

As usual, /caucho-status will show the URLs matched for each host.

<note>mod_caucho does not understand the host regexp attribute. It will ignore all hosts using regexp. To get around this, you can either configure Apache directly (see below), or configure the default host with the same set of servlet-mappings. Since mod_caucho will use the default host if no others match, it will send the right requests to Resin.</note>

</s3>

</s2>

</s1>


</body> </document>

<document> 

 <header>
   <product>resin</product>
   <title>Resin with Apache</title>
   <description>

Resin provides a fast servlet runner for Apache 1.3 or greater, allowing Apache to run servlets and JSP files. 

   </description>
 </header>

<body>

<s1>

If you have not yet done so, we suggest you use the <a href="resin-web-server.xtp">Resin standalone web server</a> option first.

</s1>

<localtoc/>

<s1 name="standalone" title="Before you integrate Resin with Apache">

Before integrating Resin with Apache, it is valuable to configure Resin as a <a href="resin-web-server.xtp">standalone server</a>, especially with more complicated setups such as those involving virtual hosts. Doing so isolates the steps and makes troubleshooting easier.

Many users find that the performance, flexibility, and features of Resin make Resin a desirable replacement for Apache.

</s1>

<s1 name="dispatch" title="How Resin integrates with Apache">

When used with Apache, Resin serves JSPs and Servlets and Apache serves static content like html and images. Apache is a frontend server, it handles the request from the browser. Resin's mod_caucho plugin integrates with Apache, it dispatches requests for JSPs and Servlets to one or more backend Resin servers.

<figure src="apache_srun.gif"/>

mod_caucho queries the backend server to distinguish the URLs going to Resin from the URLs handled by Apache. The backend server uses the <servlet-mapping> directives to decide which URLs to send. Also, any *.war file automatically gets all its URLs. Other URLs stay with Apache.

There's a more complete discussion of the URL dispatching in the <a href="plugin-dispatch.xtp">How the Plugins Dispatch to Resin</a> page.

</s1>

<s1 name="unix" title="Unix Installation">

Resin needs Apache 1.3.x or greater and DSO support.

To configure Resin with Apache, you must follow the following steps:

  1. Compile Apache
  2. Compile mod_caucho.so
  3. Configure Apache
  4. Set up environment
  5. Configure resin.xml
  6. Restart Apache and start the backend Resin server

<s2 title="Compiling Apache">

You need a version of Apache with DSO support enabled. Apache has full documentation at <a href="http://httpd.apache.org/docs/dso.html">their website</a>. To check if your apache has DSO support, you can check for mod_so.c in your your httpd <example title="checking apache httpd for mod_so.c"> unix> /usr/local/apache/bin/httpd -l Compiled-in modules: ... mod_so.c ... </example>

Many distributions, e.g. Red Hat Linux, will have Apache preinstalled.

However, because the standard distribution has files all over the

place, some people prefer to recompile Apache from scratch.

Once you untar Apache, build it like:

<example> unix> ./configure --prefix=/usr/local/apache --enable-module=so unix> make unix> make install </example>

Solaris versions of Apache may need additional flags, otherwise you'll get some linking errors when trying to load Resin. You may need to refer to the Apache documentation if you get linking errors. Here's an example configuration on Solaris:

<example> unix> ./configure --prefix=/usr/local/apache \ 

                 --enable-rule=SHARED_CORE \
                 --enable-rule=SHARED_CHAIN \
                 --enable-module=so \
                 --enable-module=most \
                 --enable-shared=max

</example>

</s2>

<s2 title="Compiling mod_caucho.so">

To compile and install mod_caucho on Unix, you'll need to run Resin's configure and then make. This step will create mod_caucho.so and put it in the Apache module directory. Usually, mod_caucho.so will end up in /usr/local/apache/libexec/mod_caucho.so.

If you know where your apxs executable is, you can use --with-apxs. apxs is a little Perl script that the Apache configuration makes. It lets modules like Resin know how all the Apache directories are configured. It is generally in /usr/local/apache/bin/apxs or /usr/sbin/apxs. It's usually easiest to use --with-apxs so you don't need to worry where all the Apache directories are.

<example> unix> ./configure --with-apxs=/usr/local/apache/bin/apxs unix> make </example>

Even if you don't know where apxs is, the configure script can often find it:

<example> unix> ./configure --with-apxs unix> make </example>

As an alternative to --with-apxs, if you've compiled Apache yourself, or if you have a simple configuration, you can generally just point to the Apache directory:

<example> unix> ./configure --with-apache=/usr/local/apache unix> make unix> make install </example>

The previous --with-apxs or --with-apache should cover most configurations. For some unusual configurations, you can have finer control over each directory with the following arguments to ./configure. In general, you should use --with-apache or --with-apxs, but the other variables are there if you know what you're doing.

<deftable> <tr><td>--with-apache=dir</td><td>The Apache root directory. </td></tr><tr><td>--with-apxs=apxs</td><td>Pointer to the Apache extension script </td></tr><tr><td>--with-apache-include=dir</td><td>The Apache include directory </td></tr><tr><td>--with-apache-libexec=dir</td><td>The Apache module directory </td></tr><tr><td>--with-apache-conf=httpd.conf</td><td>The Apache config file </td></tr></deftable>

</s2>

<s2 title="Configure the Environment">

If you don't already have Java installed, you'll need to download a JDK and set some environment variables.

Here's a typical environment that you might put in ~/.profile or /etc/profile

<example>

  1. Java Location

JAVA_HOME=/<installdir>/jdk1.4 export JAVA_HOME

  1. Resin location (optional). Usually Resin can figure this out.

RESIN_HOME=/<installdir>/resin-3.2.2 export RESIN_HOME

  1. If you're using additional class libraries, you'll need to put them
  2. in the classpath.

CLASSPATH= </example>

</s2>

</s1>

<s1 name="windows" title="Windows Installation">

The setup.exe program installs the mod_caucho.dll plugin for any Apache it finds, and modifies the Apache httpd.conf file.

The httpd.conf file is also easily modified manually:

<example title="httpd.conf"> LoadModule caucho_module \ 

   <installdir>/resin-3.2.x/win32/apache-2.0/mod_caucho.dll

ResinConfigServer localhost 6800 <Location /caucho-status> 

 SetHandler caucho-status

</Location> </example>

</s1>


<s1 title="Configuring resin.xml">

The communication between mod_caucho and the backend Resin server takes place using a server port.

The resin.xml for the backend server contains a server to enable the port. The default resin.xml has an server listener on port 6800.

<example title="resin.xml"> <resin xmlns="http://caucho.com/ns/resin" 

      xmlns:resin="http://caucho.com/ns/resin/core">

 ...



 <cluster id="app-tier">

   ...

   <server id="" address="127.0.0.1" port="6800"/>

   ...

</example>


The resin.xml and the layout of your webapps should match the layout that Apache expects. The mapping of urls to filesystem locations should be consistent between Apache and the backend Resin server.


The default resin.xml looks in resin-3.2.x/webapps/ROOT for JSP files and resin-3.2.x/webapps/ROOT/WEB-INF/classes for servlets and java source files. To tell Resin to use Apache's document area, you configure an explicit web-app with the appropriate document-directory:

<example title="resin.xml"> <resin xmlns="http://caucho.com/ns/resin" 

      xmlns:resin="http://caucho.com/ns/resin/core">

 ...

 <server>

   ...

   <host id="">

     <web-app id='/' document-directory="/usr/local/apache/htdocs"/>

   </host>

   ...

 </server>

</resin> </example>

</s1>

<s1 title="Starting the app-tier Resin server">

Now you need to start the app-tier Resin server. Starting Resin is the same with Apache or standalone. See the <a href="resin-web-server.xtp#deploy">Resin Web Server</a> page for a detailed description.

<example> unix> java -jar $RESIN_HOME/lib/resin.jar

unix> bin/resin.sh

win> resin.exe </example>

<results> Resin 3.2.2 (built Mon Aug 4 09:26:44 PDT 2006) Copyright(c) 1998-2006 Caucho Technology. All rights reserved.

Starting Resin on Mon, 04 Aug 2006 09:43:39 -0700 (PDT) [09:43:40.664] Loaded Socket JNI library. [09:43:40.664] http listening to *:8080 [09:43:40.664] ServletServer[] starting [09:43:40.879] hmux listening to *:6800 [09:43:41.073] Host[] starting [09:43:41.446] Application[1] starting [09:43:41.496] Application[2] starting </results>

Resin will print every port it's listening to. In the above example, Resin has an http listener on port 8080 and an server listener on port 6800 (using its custom 'hmux' protocol). mod_caucho establishes connections to Resin using port 6800, and a web browser can connect using port 8080. Usually the 8080 port will be unused, because web browsers will make requests to Apache, these requests get dispatched to Resin as needed by mod_caucho. A Resin configured http listener on port 8080 is a useful debugging tool, it allows you to bypass Apache and make a request straight to Resin.

The following snippet shows the <<a href="port-tags.xtp#http">http</a>> and <<a href="server-tags.xtp#server">server</a>> configuration for the above example.

<example> <resin xmlns="http://caucho.com/ns/resin"> 

 <cluster id="app-tier">
   <server-default>
     <http address="*" port="8080"/>
   </server-default>

   <server id="" address="192.168.2.10" port="6800"/>

   ...
 </cluster>

</resin> </example>

</s1>

<s1 title="Testing the servlet engine">

Create a test file '/usr/local/apache/htdocs/test.jsp'

<example> 2 + 2 = <%= 2 + 2 %> </example>

Browse http://localhost/test.jsp again. You should now get

<results> 2 + 2 = 4 </results>

</s1>

<s1 name="httpd.conf" title="Configuring Apache httpd.conf">

The installation process above automatically changes the httpd.conf file. You can also configure the httpd.conf file manually, or modify the default configuration created by the installation process.

<example title="Unix - httpd.conf"> LoadModule caucho_module libexec/mod_caucho.so

ResinConfigServer localhost 6800 <Location /caucho-status> 

 SetHandler caucho-status

</Location> </example>

<example title="Windows - httpd.conf"> LoadModule caucho_module \ 

   <installdir>/resin-3.2.x/libexec/apache-2.0/mod_caucho.dll

ResinConfigServer localhost 6800 <Location /caucho-status> 

 SetHandler caucho-status

</Location> </example>

The ResinConfigServer is used to tell mod_caucho how to contact the backend Resin server. The backend Resin server tell's mod_caucho which urls should be dispatched.

<deftable> <tr><th>Apache Command</th><th>Meaning </th></tr><tr><td>ResinConfigServer host port</td><td>Specifies the Resin JVM at host:port as a configuration server. </td></tr></deftable>

<s2 name="caucho-status" title="caucho-status">

caucho-status is optional and probably should be avoided in a production site. It lets you ask the Caucho Apache module about it's configuration, and the status of the backend server(s), valuable for debugging.

After any change to httpd.conf, restart Apache. Now browse http://localhost/caucho-status.

</s2>

<s2 name="manual-dispatch" title="Manual configuration of dispatching">

You can also dispatch to Resin directly from the httpd.conf. Instead of relying on the ResinConfigServer directive to determine which url's to dispatch to the backend server, Apache handler's are used to specify the url's to dispatch.

<example> CauchoHost 127.0.0.1 6800

<Location /foo/*> 

 SetHandler caucho-request

</Location> </example>

<deftable> <tr> 

 <th width="30%">Apache Command</th>
 <th>Meaning</th>

</tr> <tr> 

 <td>CauchoHost host port</td>
 <td>Alternative to ResinConfigServer, adds the Resin JVM with an server port at host:port as a backend server.</td>

</tr> <tr> 

 <td>CauchoBackup host port</td>
 <td>Alternative to ResinConfigServer, adds the Resin JVM with
 a server port at host:port as a backup backend server.

</td> </tr> </deftable>

<deftable> <tr> 

 <th width="30%">Apache Handler</th>
 <th>Meaning</th>

</tr> <tr> 

 <td>caucho-status</td>
 <td>Handler to display /caucho-status</td>

</tr> <tr> 

 <td>caucho-request</td>
 <td>Dispatch a request to Resin</td>

</tr> </deftable>

Requests dispatched directly from the Apache httpd.conf will not appear in /caucho-status.

</s2>

</s1>


<s1 name="vhosts" title="Virtual Hosts">

The <a href="virtual-host.xtp">virtual host</a> topic describes virtual hosts in detail. If you're using a single JVM, you only need to configure the resin.xml.

<example title="httpd.conf"> LoadModule caucho_module libexec/mod_caucho.so

ResinConfigServer 192.168.0.1 6800 <Location /caucho-status> 

 SetHandler caucho-status

</Location> </example>

<example title="resin.xml"> <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> 

 <server id="" address="192.168.0.1" port="6800"/>

 <host id='www.gryffindor.com'>
   <host-alias>gryffindor.com</host-alias>
    ...
 </host>

 <host id='www.slytherin.com'>
   <host-alias>slytherin.com</host-alias>
    ...
 </host>

</cluster> </resin> </example>

<s2 name="vhostperjvm" title="Virtual Host per JVM">

If you want a different JVM for each virtual host, your httpd.conf can specify a different server port for each host.

<example title="httpd.conf"> <VirtualHost gryffindor.com> ServerName gryffindor.com ServerAlias www.gryffindor.com ResinConfigServer 192.168.0.1 6800 </VirtualHost>

<VirtualHost slytherin.com> ServerName slytherin.com ServerAlias www.slytherin.com ResinConfigServer 192.168.0.1 6801 </VirtualHost> </example>

<example title="gryffindor.conf"> <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> 

 <server id="" address="192.168.0.1" port="6800"/>

 <host id="">
    ...
 </host>

</cluster> </resin> </example>

<example title="slytherin.conf"> <resin xmlns="http://caucho.com/ns/resin"> <cluster> 

 <server id="" address="192.168.0.1" port="6801"/>

 <host id="">
    ...
 </host>

</cluster> </resin> </example>

<example> $ bin/resin.sh -pid gryffindor.pid -conf conf/gryffindor.conf start $ bin/resin.sh -pid slytherin.pid -conf conf/slytherin.conf start

...

$ bin/resin.sh -pid gryffindor.pid stop

</example>

</s2>

</s1>


<s1 name="balance" title="Load Balancing">

The <a href="resin-clustering.xtp">Reliability and Load Balancing</a> section provides an introduction to the concepts of load balancing.

mod_caucho recognizes cluster configurations for load balancing. Requests are distributed to all machines in the cluster, all requests in a session will go to the same host, and if one host goes down, Resin will send the request to the next available machine. Optional backup machines only receive requests if all of the primaries are down.

<example title="resin.xml"> <resin xmlns="http://caucho.com/ns/resin"> 

 <cluster id="app-tier">
   <server id="a" address="192.168.0.11" port="6800" index="1"/>
   <server id="b" address="192.168.0.11" port="6801" index="2" 
            backup="true"/>
   <server id="c" address="192.168.0.12" port="6800" index="3"/>
   <server id="d" address="192.168.0.12" port="6801" index="4" 
            backup="true"/>
   ...
 </cluster>

</resin> </example>

mod_caucho only needs to know about one of the backend servers. It will query that backend server, and learn about all of the other members of the cluster.

<example> ResinConfigServer 192.168.0.11 6800 </example>

mod_caucho keeps a local cache of the configuration information, so if the backend server becomes unavailable then the cached configuration will be used until the backend server becomes available again.

The httpd.conf file can also specify more than one backend server, when mod_caucho checks for configuration updates, it will check each in turn, and only if none of them are available will it use the local cached copy.

<example> ResinConfigServer 192.168.0.11 6800 ResinConfigServer 192.168.0.12 6801 </example>

<s2 name="manual-dispatch-balance" title="Manual configuration of load balanced dispatching">

Manual dispatching in httpd.conf can also specify the backend hosts and the backend backup hosts, as an alternative to using ResinConfigServer.

<example> CauchoHost 192.168.0.11 6800 CauchoBackup 192.168.0.11 6801 CauchoHost 192.168.0.12 6800 CauchoBackup 192.168.0.12 6801

<Location /foo/*> 

 SetHandler caucho-request

</Location> </example>

</s2>

<s2 name="manual-dispatch-location" title="Manual configuration of location based dispatching">

<example> <Location /applicationA/*> 

 ResinConfigServer 192.168.0.11 6800

</Location>

<Location /applicationB/*> 

 ResinConfigServer 192.168.0.12 6800

</Location> </example>

</s2>

</s1>

<s1 title="Troubleshooting">

  1. First, check your configuration with Resin standalone.sh. In other words, add a <http port='8080'/> and check port 8080.
  2. Check http://localhost/caucho-status. That will tell if mod_caucho has properly connected to the backend Resin server.
  3. Each server should be green and the mappings should match your resin.xml.
  4. If caucho-status fails entirely, the problem is in the mod_caucho installation and the Apache httpd.conf.
  5. If caucho-status shows the wrong mappings, there's something wrong with the resin.xml or the pointer to the backend server in httpd.conf.
  6. If caucho-status shows a red servlet runner, then Resin hasn't properly started.
  7. If you get a "cannot connect to servlet engine", caucho-status will show red, and Resin hasn't started properly.
  8. If Resin doesn't start properly, you should look at the logs in resin-3.2.x/log. You should start resin.sh -verbose or resin.exe -verbose to get more information.
  9. If Resin never shows a "hmux listening to *:6800" line, it's not listening for connections from mod_caucho. You'll need to add a <server> line.
  10. If you get Resin's "file not found", the Apache configuration is good but the resin.xml probably points to the wrong directories.

</s1> 

 </body>

</document>

<document> 

 <header>
   <product>resin</product>
   <title>Resin with IIS</title>

   <description>

For sites requiring the use of IIS, Resin provides a fast servlet runner, allowing IIS to run servlets and JSP files.

   </description>
 </header>

 <body>

<s1> 

     <figure src="iis_srun.gif"/>

If you have not yet done so, we suggest you consider the <a href="resin-web-server.xtp">Resin web server</a> option first, either as a standalone web server or as a web-tier server load-balancing to Resin app-tier servers. Resin's Java web server provides management, clustering, and load-balancing with failover.

</s1> 

   <localtoc/>

<s1 title="Prerequisites and Environment Variables">

Resin requires a 1.5 JDK. You can download one from Sun and install it.

The Control Panel is used to configure two environment variables:

<example> JAVA_HOME=C:\jdk1.5.0 RESIN_HOME=C:\resin-4.0 </example> </s1>

<s1 title="Configuring IIS/PWS">

To configure Resin with IIS, you must follow the following steps:

  1. Configure IIS/PWS
  2. Configure resin.xml
  3. Start resin.exe


<s2 title="ISAPI Filter">

You should run RESIN_HOME/setup.exe to setup your configuration. If setup.exe is not used, or it fails, the steps in <a href="#Manual-Configuration">Manual Configuration</a> are necessary.

</s2>

<s2 title="ISAPI Filter Priority">

isapi_srun.dll installs itself as the default priority. Some users may need to set the priority to a higher level, e.g. to override IIS's DAV support.

<example title="resin.ini"> ResinConfigServer localhost 6802 CauchoStatus yes IISPriority high </example>

</s2>

<s2 title="Configuring resin.xml">

resin.xml should mirror the configuration of IIS. In other words, you need to configure the document root and any directory aliases.

For many users, the only need to change needed in Resin is to change the <a config-tag="document-directory"/> attribute from 'webapps/ROOT' to something like 'C:/inetpub/wwwroot'. The mapping of url paths from the browser to real files on the disk must be the same for Resin as they are for IIS. For more complicated configurations that use mappings in IIS, you'll need to add <a href="webapp-tags.xtp">path-mapping</a> attributes to match.

<example title="Example: resin.xml" language="xml"> <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> 

 <!-- configures the default host, matching any host name -->
 <host id="">

 <!-- configures the root web-app -->
 <web-app id='/'>
   <root-directory>C:/inetpub/wwwroot</root-directory>
   <!-- adds xsl to the search path -->
   <class-loader>
     <simple-loader path="$host-root/xsl"/>
   </class-loader>
 </web-app>

</host>

</cluster> </cluster> </example>

</s2>

<s2 title="Testing the servlet engine">

From a cmd shell run RESIN_HOME/resin.exe to start the servlet runner.

<example title="Run resin.exe"> C:\> cd %RESIN_HOME% C:\resin-3.2> resin.exe </example>

Now browse http://localhost/test.jsp. You should get a 'file not found' message.

Create a test file 'd:\inetpub\wwwroot\test.jsp'

<example> 2 + 2 = <%= 2 + 2 %> </example>

Browse http://localhost/test.jsp again. You should now get

<results> 2 + 2 = 4 </results> </s2>

</s1>

<s1 title="Command line arguments">

The following configuration line arguments are recognized by resin.exe. When command line arguments are used along with -install to install as a service, the arguments are used each time the service starts.

<deftable> <tr><th>Argument</th><th>Meaning </th></tr><tr><td>-verbose</td><td>Write more verbose information to the log file </td></tr><tr><td>-resin_home <path></td><td>Sets the location of Resin </td></tr><tr><td>-java_home <path></td><td>Specify the JDK location </td></tr><tr><td>-msjava</td><td>Use Microsoft's JVM </td></tr><tr><td>-nojit</td><td>Disable JIT compilation to help debugging </td></tr><tr><td>-classpath <cp></td><td>Add to the classpath </td></tr><tr><td>-J<arg></td><td>Set a Java command line argument, e.g. -J-nojit. </td></tr><tr><td>-X<arg></td><td>Set a Java -X command line argument, e.g. -Xms128m. </td></tr><tr><td>-D<foo=bar></td><td>Set a Java variable, e.g. -Dresin.home=here. </td></tr><tr><td>-install</td><td>Install as an NT service </td></tr><tr><td>-install-as <name></td><td>Install as an NT service with the specific name. </td></tr><tr><td>-remove</td><td>Remove as an NT service </td></tr><tr><td>-remove-as <name></td><td>Remove as an NT service with the specific name. </td></tr></deftable>

<s2 title="Memory Configuration">

Memory configuration is part of the JVM's arguments. For most JVMs, you can find the full list by starting "java -X".

<deftable title="Memory Configuration"> <tr><th>Argument</th><th>Meaning </th></tr><tr><td>-Xms<size></td><td>Initial Java heap size, e.g. -Xms32m </td></tr><tr><td>-Xmx<size></td><td>Maximum Java heap size, e.g. -Xmx128m </td></tr><tr><td>-Xms<size></td><td>the size of the heap for the young generation </td></tr></deftable>

See <a href="jvm-tuning.xtp#memory">Performance : JVM Tuning : Memory</a> for more information on JVM memory usage.

</s2>

</s1>

<s1 title="Deploying as an NT Service">

Once you're comfortable with using Resin with IIS, you can install it as an NT service. As a service, Resin will automatically start when NT reboots. The service will also automatically restart Resin if it unexpectedly exits.

To install the service, use

<example> win> resin-3.2.x/resin.exe -install </example>

To remove the service, use

<example> win> resin-3.2.x/resin.exe -remove </example>

You will either need to reboot the machine or start the service from the Control Panel/Services panel to start the server. On a machine reboot, NT will automatically start the servlet runner.

<p/>

<note>There is a bug in many JDKs which cause the JDK to exit when the administrator logs out. JDK 1.4 and later can avoid that bug if the JDK is started with -Xrs. </note>

<example> win> resin-3.2.x/resin.exe -install -Xrs </example>

</s1>

<s1 name="balance" title="Load Balancing">

With Resin, you can distribute requests to multiple machines. All requests with the same session will go to the same host. In addition, if one host goes down, the IIS filter will send the request to the next available machine.

In addition, you can specify backup machines. The backup only will serve requests if all primaries are down.

See the <a href="cluster.xtp">Resin config</a> section for more details.

<example title="resin.xml"> <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> 

   <server id="a" address="host1" port="6802" index="1"/>
   <server id="b" address="host2" port="6802" index="2"/>
   <server id="c" address="backup" port="6802" index="3" backup="true"/>
 ...

</cluster> </resin> </example>

<example title="installing multiple servlet runners as services"> win> resin-3.2.x/resin.exe -install-as "Resin-A" -server a -Xrs win> resin-3.2.x/resin.exe -install-as "Resin-B" -server b -Xrs win> resin-3.2.x/resin.exe -install-as "Resin-C" -server c -Xrs </example> </s1>

<s1 title="Manual Configuration">

Experts may want to configure Resin/IIS by hand instead of using the setup program. The steps involved are:

  1. Make sure resin.exe works
  2. Copy isapi_srun.dll to the IIS scripts directory, d:\inetpub\scripts.

    You may need to run net stop w3svc to get permission to overwrite the file.

  3. If you have a virtual site (virtual hosts), you must configure IIS to have

    the virtual directory /scripts point to d:\inetpub\scripts for each virtual site.

  4. (optional) Create a resin.ini in d:\inetpub\scripts pointing to the ResinConfigServer
  5. (optional) Add a "CauchoStatus yes" line to the resin.ini for debugging
  6. Configure IIS to load isapi_srun.dll as an ISAPI filter.
  7. Restart IIS (control panel/services) or net stop w3svc followed

    by net start w3svc.

  8. Browse /servlet/Hello and /foo.jsp.

    You should see a "cannot connect" error.

  9. Start resin.exe
  10. Browse /servlet/Hello and /foo.jsp. You should now see the servlet.

Copying isapi_srun.dll to inetpub/scripts directory is relatively straightforward. If you're upgrading to a new version of Resin, you may need to stop IIS (control panel/services) to get permission to overwrite isapi_srun.dll.

The resin.ini is an optional file in inetpub/scripts to override the automatic registry $RESIN_HOME/conf/resin.xml configuration file. If you only have one Resin server, you should not create a resin.ini and let isapi_srun.dll use the registry value set by the setup.exe program.

resin.ini is only needed if you have multiple Resin configuration files for different IIS virtual hosts.

The resin.ini should contain the following line:

<example> ResinConfigServer localhost 6802 </example>

You can change the host from localhost to a backend server. You can also add multiple ResinConfigServer items to cluster the configuration.

For debugging, you can add a "CauchoStatus yes" line to the resin.ini:

<example> ResinConfigServer localhost 6802 CauchoStatus yes </example>

For security purposes, the default value of CauchoStatus is "no" when you have a resin.ini.

Adding an ISAPI filter is accomplished in the IIS manager.

<s2 title="IIS and Resin on different machines">

When Resin and IIS are on different machines, you'll change the ResinConfigServer from "localhost" to the IP address of the Resin server.

<example> ResinConfigServer 192.168.0.10 6802 CauchoStatus yes </example>

</s2>

</s1>

<s1 title="Virtual Sites (Virtual Hosts)">

If IIS is managing multiple virtual sites (everyone else calls them virtual hosts), then you need to configure IIS to use the isapi_srun.dll filter for each virtual site. Configure IIS to have the virtual directory /scripts for each virtual site point to d:\inetpub\scripts, so that each virtual site uses the isapiu_srun.dll.

Resin is configured to recognize virtual hosts with the id attribute of <a config-tag="host"/>.

<example title="resin.xml with virtual hosts"> <resin xmlns="http://caucho.com/ns/resin"> 

 ...
 <server>
   ...

   <host id="foo.com">
     ...
   </host>

   <host id="bar.com">
     ...
   </host>

   <host id="baz.com">
     ...
   </host>

 </server>

</resin> </example>

Resin recognizes which host to use by examing the url. With the above example, a url of http://foo.com/some/path will use host id="foo.com" and a url of http://bar.com/some/path will use host id="bar.com".

</s1>

<s1 title="Virtual Sites with different JVM's">

If a seperate JVM for each virtual site is desired, a seperate resin.ini is used for each virtual site. The resin.ini file is placed in the scripts directory.

<example title="resin-foo.xml"> <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> 

 <server port="6800"/>

 ...
 <host id="*">
   ...
 </host>

</cluster> </resin> </example>

<example title="resin-bar.xml"> <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> 

 <server port="6801"/>

 ...
 <host id="*">
   ...
 </host>

</cluster> </resin> </example>

<example title="installing a servlet runner for each virtual site"> win> resin-3.2.x/resin.exe -install-as "Resin-foo" \ 

   -conf resin-foo.xml -Xrs

win> resin-3.2.x/resin.exe -install-as "Resin-bar" \ 

   -conf resin-bar.xml -Xrs

</example>

<example title="resin.ini for IIS virtual site foo.com"> ResinConfigServer localhost 6802 </example>

<example title="resin.ini for IIS virtual site bar.com"> ResinConfigServer localhost 6803 </example>

The ResinConfigServer tells the isapi_srun.dll the port number to use to connect to the Resin instance. You can change the host from localhost to a backend server. You can also add multiple ResinConfigServer items to cluster the configuration.

resin-foo.xml and resin-bar.xml contain a <host id="*">, you do not need to specify the host name because each conf/JVM is only going to receive requests from a particular virtual site (because of the unique resin.ini files).

</s1>

<s1 title="Troubleshooting">

  1. Check your configuration with the standalone web server. In other words, add a <http port='8080'/> block and browse http://localhost:8080.
  2. Check http://localhost/caucho-status. That will tell if

    the ISAPI filter/extension is properly installed.

  3. Each server should be green and the mappings should

    match your resin.xml.

  4. If caucho-status fails entirely, the problem is in the isapi_srun

    installation. Try http://localhost/scripts/isapi_srun.dll/caucho-status directly (bypassing the filter). If this fails, IIS can't find isapi_srun.dll.

    • Check that isapi_srun.dll is in c:\inetpub\scripts.
    • Make sure that both IIS and the underlying NTFS file system have permissions set appropriately for isapi_srun.dll.
    • Make sure that your IIS host has a mapping from /scripts

      to c:\inetpub\scripts and that the /scripts has execute permissions.

    • IIS 6 users may need to take <a href="#iis6">additional steps</a>.
  5. If you've created a new

    IIS web site, you need to create a virtual directory /scripts pointing to the d:\inetpub\scripts directory.

  6. If caucho-status shows the wrong mappings, there's something wrong

    with the resin.xml.

  7. If caucho-status shows a red servlet runner, then resin.exe hasn't

    properly started.

  8. If you get a "cannot connect to servlet engine", caucho-status

    will show red, and resin.exe hasn't started properly.

  9. If resin.exe doesn't start properly, you should look at the logs

    in resin3.2/log. You should start resin.exe -verbose to get more information.

  10. If you get Resin's file not found, the IIS configuration

    is good but the resin.xml probably points to the wrong directories.

<s2 name="iis6" title="Troubleshooting IIS 6">

IIS 6/Windows 2003 users may need to perform additional steps.

  • Make sure that the System account has suffiicient privleges to read the C:\InetPub and C:\InetPub\Scripts directory and the isapi_srun.dll.
  • Check the `Web Service Extensions' listed in the `Internet Service Manager'

    to make sure that Resin is listed as a Web Service Extension and has a status of "enabled". You may need to click "add a new web service extension...", under Extension name add .jsp or whatever your file extension is, click Add and browse to the isapi_srun.dll, check the "Set extension status to allowed box", click OK.


  • Check that the user specified as the

    "application pool identity" for Resin has read/write permission to the Resin installation directory. In the Internet Service Manager, open the Properties dialog for "Application Pools". Find the User on the "Identity" tab, it may be the user named "Network Service" in the drop-down list associated with the radio button labeled "predefined". Then check physical file permissions on the Resin installation directory and all its subdirectories and subfiles, to ensure that that user has read/write permission status is "Enabled".

</s2> </s1> </body> </document>

Retrieved from "http://wiki3.caucho.com/index.php?title=Resin_Installation&oldid=3505"
Personal tools