<title css='default.css'>Caucho Servlet Engine on Apache Unix</title>

<summarylist/>

Resin provides a fast servlet runner for Apache, allowing Apache
to run servlets and JSP files.  The servlet runner needs Apache 1.3.x
and DSO support.

<center>
<ct:img src='apache_srun.gif'/>
</center>

<section title='Installation'>

<p/>To configure Resin with Apache, you must follow the following steps:
<ol>
<li>Compiling Apache
<li>Compile mod_caucho.so
<li>Configure Apache
<li>Set up environment
<li>Configure resin.conf
<li>Restart Apache and start srun
</ol>

<subsection 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">http://httpd.apache.org/docs/dso.html</a>.

<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/>Once you untar Apache, build it like:

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

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

<def>
unix> ./configure --prefix=/usr/local/apache \
                  --enable-rule=SHARED_CORE \
                  --enable-rule=SHARED_CHAIN \
                  --enable-module=so \
                  --enable-module=most \
                  --enable-shared=max
</def>

</subsection>

<subsection title='Compiling mod_caucho.so'>

To compile and install <var/mod_caucho/> on Unix, you'll need to run
Resin's <code/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.

<p/>If you know where your <var/apxs/> executable is, you can use --with-apxs.
<var/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.

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

<p/>Even if you don't know where <var/apxs/> is, the configure script
can often find it:

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

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

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

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

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

</subsection>

<subsection title='Configure the Environment'>

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

<p/>Here's a typical environment that you might put in ~/.profile or
/etc/profile
<example>
# Java Location
JAVA_HOME=/&lt;installdir>/jdk1.2.2
export JAVA_HOME

# Resin location (optional).  Usually Resin can figure this out.
RESIN_HOME=/&lt;installdir>/resin1.2
export RESIN_HOME

# If you're using additional class libraries, you'll need to put them
# in the classpath.
CLASSPATH=
</example>

</subsection>

<subsection title='Configuring resin.conf'>

By default, Resin will look in resin1.2/doc for JSP files and
resin1.2/doc/WEB-INF/classes for servlets and beans.  To tell Resin
to use Apache's document area, you configure the <var/app-dir/>.
Change <var/app-dir/> from 'doc' to something like '/usr/local/apache/htdocs'.

<example title='resin.conf'>
&lt;caucho.com>
  &lt;http-server
      app-dir='/usr/local/apache/htdocs'>
    &lt;servlet-mapping url-pattern='/servlets/*'
              servlet-name='invoker'/>

    &lt;servlet-mapping url-pattern='*.xtp'
                        servlet-name='com.caucho.jsp.XtpServlet'/>
    &lt;servlet-mapping url-pattern='*.jsp'
                        servlet-name='com.caucho.jsp.JspServlet'/>
  &lt;/http-server>
&lt;/caucho.com>
</example>

</subsection>

<subsection title='Starting the Servlet Engine'>

Now you need to start the servlet engine.  Starting Resin is the same
with Apache or standalone.  See the <a href="httpd.xtp#deploy">httpd</a> page
for a detailed description.

<example>
unix> resin1.2/bin/httpd.sh
Resin 1.2.s010113 -- Sat Jan 13 11:17:18 PST 2001
http listening to *:8080
srun listening to localhost:6802
</example>

<p/>Resin will print every port it's listening to.  In the above example,
Resin is listening to port 8080 using HTTP and 6802 using its servlet
runner protocol.  In other words, mod_caucho can connect to Resin
with 6802 only on same host, but you can browse port 8080 from any host.

<p/>The following snippet shows the <var/&lt;http>/> and <var/&lt;srun>/>
configuration for the above example.

<example>
&lt;caucho.com>
  &lt;http-server>
    &lt;http port='8080'/>
    &lt;srun host='localhost' port='6802'/>

    ...
  &lt;/http-server>
&lt;/caucho.com>
</example>

</subsection>

<subsection title='Testing the servlet engine'>

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

<example>
2 + 2 = &lt;%= 2 + 2 %>
</example>

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

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

</subsection>

<subsection title='Troubleshooting'>

<ol>
<li>First, check your configuration with the standalone httpd.sh.  In other words, add a &lt;http port='8080'/> and check port 8080.
<li>Check http://localhost/caucho-status.  That will tell if
mod_caucho has properly read the resin.conf.  
<li>Each srun host should be green and the mappings should
match your resin.conf.
<li>If caucho-status fails entirely, the problem is in the mod_caucho
installation and the Apache httpd.conf.
<li>If caucho-status shows the wrong mappings, there's something wrong
with the resin.conf or the pointer to resin.conf in httpd.conf.
<li>If caucho-status shows a red servlet runner, then httpd.sh hasn't
properly started.
<li>If you get a "cannot connect to servlet engine", caucho-status
will show red, and httpd.sh hasn't started properly.
<li>If httpd.sh doesn't start properly, you should look at the logs
in resin1.2/log.  You should start <var/httpd.sh -verbose/> to get
more information.
<li>If httpd.sh says "no servers defined", your resin.conf is missing a
&lt;srun> or &lt;httpd> definition.
<li>If httpd.sh never shows a "srun listening to *:6802" line,
it's not paying attention to mod_caucho.  You'll need to add a &lt;srun>
line.
<li>If httpd.sh shows "srun listening to localhost:6802" line, only an
Apache on the same host can connect to the srun.  If you need an Apache
on a different host to connect to srun, you'll need to change the
<var/host/> attribute in the srun configuration.
<li>If you get Resin's "file not found", the Apache configuration
is good but the resin.conf probably points to the wrong directories.
</ol>

</subsection>

</section>

<section title='Configuring Apache by hand'>

<p/>Making mod_caucho will automatically change your httpd.conf file.
You can also configure Apache directly, instead of letting Caucho read
configuration from the resin.conf file. If you use this method, you
need to make sure you match the Apache configuration with the Resin
configuration.

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

&lt;IfModule mod_caucho.c&gt;
  CauchoConfigFile &lt;installdir>/resin1.2/conf/resin.conf
  &lt;Location /caucho-status>
    SetHandler caucho-status
  &lt;/Location>
&lt;/IfModule&gt;
</example>

<note>The caucho-status is optional and probably should be avoided in
a production site.  It lets you ask the Caucho Apache module about the
Caucho status, valuable for debugging.</note>

<p/>Restart Apache.  Now browse http://localhost/caucho-status.  It
should return a table indicating that the servlet runner is stopped.

<p/>Browse http://localhost/test.jsp.  It should return a message like:
<results>
Cannot connect to Servlet Runner.
</results>

<p/>You can also dispatch to Resin directly from the httpd.conf.  The apache handler name is "caucho-request".

<deftable>
<tr><th>Apache Handler<th>Meaning
<tr><td>caucho-status<td>Handler to display /caucho-status
<tr><td>caucho-request<td>Dispatch a request to Resin
</deftable>

<p/>Requests dispatched directly from the Apache httpd.conf will not
appear in /caucho-status.  You can use caucho-request as follows:

<example>
&lt;Location /foo/*>
  SetHandler caucho-request
&lt;/Location>
</example>

<deftable>
<tr><th>Apache Command<th>Meaning
<tr><td>CauchoConfigFile <var/conf/><td>Reads <var/conf/> for the Resin configuration.
<tr><td>CauchoHost <var/host/> <var/port/><td>Adds the Resin JVM at <var/host:port/> as a servlet runner.
<tr><td>CauchoBackup <var/host/> <var/port/><td>Adds the Resin JVM at <var/host:port/> as a backup servlet runner.
<tr><td>
</deftable>

<subsection 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.conf.  If you want a different JVM for each virtual host, your
httpd.conf can load a different resin.conf for each JVM:

<example title='httpd.conf'>
&lt;VirtualHost foo.com>
ServerName foo.com
ServerAlias www.foo.com
CauchoConfigFile /home/foo/conf/foo.conf
&lt;/VirtualHost>

&lt;VirtualHost bar.com>
ServerName bar.com
ServerAlias www.bar.com
CauchoConfigFile /home/bar/conf/bar.conf
&lt;/VirtualHost>
</example>

<p/>The foo.conf might look something like:

<example title='foo.conf'>
&lt;caucho.com>
&lt;http-server>
  &lt;srun host='foo.com' port='6802'/>

  &lt;host id='www.foo.com'>
     ...
  &lt;/host>
&lt;/caucho.com>
</example>

</subsection>

<subsection title="Dispatching">

mod_caucho selects URLs specified by the servlet-mapping directives to go to
Resin.  Other URLs stay with Apache.  There's a more complete
discussion of the URL dispatching in the <a
href="../java_tut/plugin-dispatch.xtp">plugin-dispatch</a> tutorial.

</subsection>

</section>

<a name='balance'/>
<section title='Load Balancing' version='Resin 1.2'>

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

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

<p/>See the <a href='http-config.xtp'>http config</a> section for more
details.
<example title=resin.conf>
&lt;caucho.com>
&lt;http-server>
  &lt;srun id="a" host='host1' port='6802'/>
  &lt;srun id="b" host='host2' port='6802'/>
  &lt;srun-backup id="c" host='backup port='6802'/>
  ...
&lt;/http-server>
&lt;/caucho.com>
</example>
</section>

<section title='Error Page' version='Resin 1.2'>

When mod_caucho can't reach any JVM, it will send a default error
page.  Sites can customize the error page with the
<var/error-page/> directive in the resin.conf.

<example title=resin.conf>
...
&lt;web-app>
  &lt;error-page exception-type='connection'
              location='/conn_error_page.html'/>
  ...
&lt;/web-app>
</example>

</section>
