Apache

From Resin 3.0

(Difference between revisions)
Jump to: navigation, search
(migration)
Line 51: Line 51:
 
''mod_so.c'' in your httpd binary:
 
''mod_so.c'' in your httpd binary:
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000001
 
  unix> /usr/local/apache/bin/httpd.exe -l
 
  unix> /usr/local/apache/bin/httpd.exe -l
 
  Compiled-in modules:
 
  Compiled-in modules:
Line 57: Line 57:
 
   mod_so.c
 
   mod_so.c
 
   ...
 
   ...
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000002
  
 
Many Unix installations have Apache preinstalled.
 
Many Unix installations have Apache preinstalled.
Line 65: Line 65:
 
Once you untar Apache, build it like:
 
Once you untar Apache, build it like:
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000003
 
  unix> ./configure --prefix=/usr/local/apache --enable-module=so
 
  unix> ./configure --prefix=/usr/local/apache --enable-module=so
 
  unix> make
 
  unix> make
 
  unix> make install
 
  unix> make install
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000004
  
 
Solaris versions of Apache may need additional flags, otherwise
 
Solaris versions of Apache may need additional flags, otherwise
Line 76: Line 76:
 
example configuration on Solaris:
 
example configuration on Solaris:
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000005
 
  unix> ./configure --prefix=/usr/local/apache \
 
  unix> ./configure --prefix=/usr/local/apache \
 
                   --enable-rule=SHARED_CORE \
 
                   --enable-rule=SHARED_CORE \
Line 83: Line 83:
 
                   --enable-module=most \
 
                   --enable-module=most \
 
                   --enable-shared=max
 
                   --enable-shared=max
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000006
  
 
=== Compile mod_caucho.so ===
 
=== Compile mod_caucho.so ===
Line 99: Line 99:
 
need to worry where all the Apache directories are.
 
need to worry where all the Apache directories are.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000007
 
   unix> ./configure --with-apxs=/usr/local/apache/bin/apxs
 
   unix> ./configure --with-apxs=/usr/local/apache/bin/apxs
 
   unix> make
 
   unix> make
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000008
  
 
Even if you don't know where ''apxs'' is, the configure script
 
Even if you don't know where ''apxs'' is, the configure script
 
can often find it:
 
can often find it:
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000009
 
   unix> ./configure --with-apxs
 
   unix> ./configure --with-apxs
 
   unix> make
 
   unix> make
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000000A
  
 
As an alternative to --with-apxs, if you've compiled Apache yourself, or if you
 
As an alternative to --with-apxs, if you've compiled Apache yourself, or if you
Line 116: Line 116:
 
to the Apache directory:
 
to the Apache directory:
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000000B
 
   unix> ./configure --with-apache=/usr/local/apache
 
   unix> ./configure --with-apache=/usr/local/apache
 
   unix> make
 
   unix> make
 
   unix> make install
 
   unix> make install
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000000C
  
 
The previous --with-apxs or --with-apache should cover most
 
The previous --with-apxs or --with-apache should cover most
Line 144: Line 144:
 
/etc/profile
 
/etc/profile
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000000D
 
  # Java Location
 
  # Java Location
 
  JAVA_HOME=/<installdir>/jdk1.4
 
  JAVA_HOME=/<installdir>/jdk1.4
Line 156: Line 156:
 
  # in the classpath.
 
  # in the classpath.
 
  CLASSPATH ==
 
  CLASSPATH ==
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000000E
  
 
== Windows ==
 
== Windows ==
Line 173: Line 173:
 
has an srun listener on port 6802.
 
has an srun listener on port 6802.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000000F
 
  <resin xmlns="http://caucho.com/ns/resin"
 
  <resin xmlns="http://caucho.com/ns/resin"
 
         xmlns:resin="http://caucho.com/ns/resin/core">
 
         xmlns:resin="http://caucho.com/ns/resin/core">
Line 188: Line 188:
 
    
 
    
 
     ...
 
     ...
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000010
  
 
The resin.conf and the layout of your webapps should match the
 
The resin.conf and the layout of your webapps should match the
Line 202: Line 202:
 
[[web-app]] with the appropriate [[document-directory]]:
 
[[web-app]] with the appropriate [[document-directory]]:
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000011
 
  <resin xmlns="http://caucho.com/ns/resin"
 
  <resin xmlns="http://caucho.com/ns/resin"
 
         xmlns:resin="http://caucho.com/ns/resin/core">
 
         xmlns:resin="http://caucho.com/ns/resin/core">
Line 214: Line 214:
 
   </server>
 
   </server>
 
  </resin>
 
  </resin>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000012
  
 
== Start the backend Resin server ==
 
== Start the backend Resin server ==
Line 222: Line 222:
 
for a detailed description.
 
for a detailed description.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000013
 
   unix> bin/httpd.sh
 
   unix> bin/httpd.sh
 
    
 
    
 
   win> httpd.exe
 
   win> httpd.exe
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000014
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000015
 
  Resin-pro-3.0.x (built Fri, 03 Feb 2006 09:47:48 EST)
 
  Resin-pro-3.0.x (built Fri, 03 Feb 2006 09:47:48 EST)
 
  Copyright(c) 1998-2006 Caucho Technology.  All rights reserved.
 
  Copyright(c) 1998-2006 Caucho Technology.  All rights reserved.
Line 241: Line 241:
 
  [09:43:41.446] Application[http://localhost:8080/resin-doc] starting
 
  [09:43:41.446] Application[http://localhost:8080/resin-doc] starting
 
  [09:43:41.496] Application[http://localhost:8080] starting
 
  [09:43:41.496] Application[http://localhost:8080] starting
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000016
  
 
Resin will print every port it's listening to.  In the above example,
 
Resin will print every port it's listening to.  In the above example,
Line 255: Line 255:
 
configuration for the above example.
 
configuration for the above example.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000017
 
  <resin xmlns="http://caucho.com/ns/resin">
 
  <resin xmlns="http://caucho.com/ns/resin">
 
   <server>
 
   <server>
Line 267: Line 267:
 
   </server>
 
   </server>
 
  </resin>
 
  </resin>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000018
  
 
== Test the servlet engine ==
 
== Test the servlet engine ==
Line 273: Line 273:
 
Create a test file '/usr/local/apache/htdocs/test.jsp'
 
Create a test file '/usr/local/apache/htdocs/test.jsp'
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000019
 
  2 + 2 = <%= 2 + 2 %>
 
  2 + 2 = <%= 2 + 2 %>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000001A
  
 
Browse http://localhost/test.jsp again.  You should now get
 
Browse http://localhost/test.jsp again.  You should now get
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000001B
 
  2 + 2 = 4
 
  2 + 2 = 4
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000001C
  
 
== Configure Apache httpd.conf ==
 
== Configure Apache httpd.conf ==
Line 291: Line 291:
 
Unix:
 
Unix:
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000001D
 
  LoadModule caucho_module libexec/mod_caucho.so
 
  LoadModule caucho_module libexec/mod_caucho.so
 
   
 
   
Line 298: Line 298:
 
   SetHandler caucho-status
 
   SetHandler caucho-status
 
  </Location>
 
  </Location>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000001E
  
 
Windows:
 
Windows:
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000001F
 
  LoadModule caucho_module <installdir>/resin-pro-3.0.x/libexec/apache-2.0/mod_caucho.dll
 
  LoadModule caucho_module <installdir>/resin-pro-3.0.x/libexec/apache-2.0/mod_caucho.dll
 
    
 
    
Line 309: Line 309:
 
   SetHandler caucho-status
 
   SetHandler caucho-status
 
  </Location>
 
  </Location>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000020
  
 
=== ResinConfigServer ===
 
=== ResinConfigServer ===
Line 351: Line 351:
 
dispatch.
 
dispatch.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000021
 
  CauchoHost 127.0.0.1 6802
 
  CauchoHost 127.0.0.1 6802
 
   
 
   
Line 357: Line 357:
 
   SetHandler caucho-request
 
   SetHandler caucho-request
 
  </Location>
 
  </Location>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000022
  
 
<table>
 
<table>
Line 378: Line 378:
 
the resin.conf.
 
the resin.conf.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000023
 
  LoadModule caucho_module libexec/mod_caucho.so
 
  LoadModule caucho_module libexec/mod_caucho.so
 
    
 
    
Line 385: Line 385:
 
   SetHandler caucho-status
 
   SetHandler caucho-status
 
  </Location>
 
  </Location>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000024
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000025
 
  <resin xmlns="http://caucho.com/ns/resin">
 
  <resin xmlns="http://caucho.com/ns/resin">
 
  <server>
 
  <server>
Line 405: Line 405:
 
  </server>
 
  </server>
 
  </resin>
 
  </resin>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000026
  
 
== Special servlet-mappings ==
 
== Special servlet-mappings ==
Line 423: Line 423:
 
served by the web server.
 
served by the web server.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000027
   <!-- send everything under /resin to Resin -->
+
   NaodW29-HTMLCommentStrip714c0aba658cd2f400000028
 
   <servlet-mapping url-pattern='/resin/*'
 
   <servlet-mapping url-pattern='/resin/*'
 
                   servlet-name='plugin_match'/>
 
                   servlet-name='plugin_match'/>
  
   <!-- keep everything under /static at the web server -->
+
   NaodW29-HTMLCommentStrip714c0aba658cd2f400000029
 
   <servlet-mapping url-pattern='/static/*'
 
   <servlet-mapping url-pattern='/static/*'
 
                   servlet-name='plugin_ignore'/>
 
                   servlet-name='plugin_ignore'/>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000002A
  
 
== Virtual host per JVM ==
 
== Virtual host per JVM ==
Line 438: Line 438:
 
httpd.conf can specify a different srun port for each host.
 
httpd.conf can specify a different srun port for each host.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000002B
 
  <VirtualHost gryffindor.com>
 
  <VirtualHost gryffindor.com>
 
  ServerName gryffindor.com
 
  ServerName gryffindor.com
Line 450: Line 450:
 
  ResinConfigServer 192.168.0.1 6803
 
  ResinConfigServer 192.168.0.1 6803
 
  </VirtualHost>
 
  </VirtualHost>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000002C
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000002D
 
  <resin xmlns="http://caucho.com/ns/resin">
 
  <resin xmlns="http://caucho.com/ns/resin">
 
  <server>
 
  <server>
Line 464: Line 464:
 
  </server>
 
  </server>
 
  </resin>
 
  </resin>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000002E
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000002F
 
  <resin xmlns="http://caucho.com/ns/resin">
 
  <resin xmlns="http://caucho.com/ns/resin">
 
  <server>
 
  <server>
Line 478: Line 478:
 
  </server>
 
  </server>
 
  </resin>
 
  </resin>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000030
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000031
 
  $ bin/httpd.sh -pid gryffindor.pid -conf conf/gryffindor.conf start
 
  $ bin/httpd.sh -pid gryffindor.pid -conf conf/gryffindor.conf start
 
  $ bin/httpd.sh -pid slytherin.pid -conf conf/slytherin.conf start
 
  $ bin/httpd.sh -pid slytherin.pid -conf conf/slytherin.conf start
Line 488: Line 488:
 
  $ bin/httpd.sh -pid gryffindor.pid stop
 
  $ bin/httpd.sh -pid gryffindor.pid stop
 
   
 
   
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000032
  
 
== Load balancing ==
 
== Load balancing ==
Line 502: Line 502:
 
down.
 
down.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000033
 
  <resin xmlns="http://caucho.com/ns/resin">
 
  <resin xmlns="http://caucho.com/ns/resin">
 
  <server>
 
  <server>
Line 514: Line 514:
 
  </server>
 
  </server>
 
  </resin>
 
  </resin>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000034
  
 
mod_caucho only needs to know about one of the backend servers. It will query
 
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.
 
that backend server, and learn about all of the other members of the cluster.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000035
 
  ResinConfigServer 192.168.0.11 6802
 
  ResinConfigServer 192.168.0.11 6802
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000036
  
 
mod_caucho keeps a local cache of the configuration information, so if the
 
mod_caucho keeps a local cache of the configuration information, so if the
Line 531: Line 531:
 
only if none of them are available will it use the local cached copy.
 
only if none of them are available will it use the local cached copy.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000037
 
  ResinConfigServer 192.168.0.11 6802
 
  ResinConfigServer 192.168.0.11 6802
 
  ResinConfigServer 192.168.0.12 6802
 
  ResinConfigServer 192.168.0.12 6802
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000038
  
 
== Manual configuration of load balanced dispatching ==
 
== Manual configuration of load balanced dispatching ==
Line 540: Line 540:
 
Manual dispatching in httpd.conf can also specify the backend hosts and the backend backup hosts, as an alternative to using <tt>ResinConfigServer</tt>.
 
Manual dispatching in httpd.conf can also specify the backend hosts and the backend backup hosts, as an alternative to using <tt>ResinConfigServer</tt>.
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f400000039
 
  CauchoHost 192.168.0.11 6802
 
  CauchoHost 192.168.0.11 6802
 
  CauchoBackup 192.168.0.11 6803
 
  CauchoBackup 192.168.0.11 6803
Line 549: Line 549:
 
   SetHandler caucho-request
 
   SetHandler caucho-request
 
  </Location>
 
  </Location>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000003A
  
 
== Manual configuration of location based dispatching ==
 
== Manual configuration of location based dispatching ==
  
<!-- pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000003B
 
  <Location /applicationA/*>
 
  <Location /applicationA/*>
 
   ResinConfigServer 192.168.0.11 6802
 
   ResinConfigServer 192.168.0.11 6802
Line 561: Line 561:
 
   ResinConfigServer 192.168.0.12 6802
 
   ResinConfigServer 192.168.0.12 6802
 
  </Location>
 
  </Location>
<!-- /pre -->
+
NaodW29-HTMLCommentStrip714c0aba658cd2f40000003C
  
 
== Troubleshooting ==
 
== Troubleshooting ==
Line 575: Line 575:
 
# If Resin never shows a "srun listening to *:6802" line, it's not listening for connections from mod_caucho.  You'll need to add a [[srun]] directive..
 
# If Resin never shows a "srun listening to *:6802" line, it's not listening for connections from mod_caucho.  You'll need to add a [[srun]] directive..
 
# If you get Resin's "file not found", the Apache configuration is good but the resin.conf probably points to the wrong directories.
 
# If you get Resin's "file not found", the Apache configuration is good but the resin.conf probably points to the wrong directories.
 +
 +
=== Debug logging ===
 +
 +
Debug logging output from mod_caucho is created with the ''--enable-debug'' option to ./configure.  It causes a large amount of information to be
 +
dumped to <tt>/tmp/log</tt>, probably not suitable for a production environment,
 +
 +
./configure --enable-debug --with-apache=...

Revision as of 16:03, 8 March 2006

When used with Apache, Resin installs a Apache module named mod_caucho and dispatches JSPs and Servlets to backend Resin servers while Apache serves static content like html and images.

Contents

Before you integrate Resin with Apache

Many users find that the performance, flexibility, and features of Resin make Resin a desirable replacement for Apache. Resin, for example, serves static content as fast or faster than Apache. Unless specific features of Apache are required, consider running Resin as the primary web server.

If you have not yet done so, follow the Resin web server instructions and get a working installation with Resin as the only web server. This is especially true with more complicated setups such as those involving virtual hosts. Doing so isolates the steps and makes troubleshooting easier.

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.

File: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. Any *.war file automatically causes Resin to gets all URLs with the corresponding prefix. Other URLs stay with Apache.

Unix

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.conf
  6. Restart Apache and start the backend Resin server

Compile Apache

You need a version of Apache with DSO support enabled. Apache has full documentation at [[1]] To check if your apache has DSO support, you can check for mod_so.c in your httpd binary:

NaodW29-HTMLCommentStrip714c0aba658cd2f400000001

unix> /usr/local/apache/bin/httpd.exe -l
Compiled-in modules:
  ...
  mod_so.c
  ...

NaodW29-HTMLCommentStrip714c0aba658cd2f400000002

Many Unix installations 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:

NaodW29-HTMLCommentStrip714c0aba658cd2f400000003

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

NaodW29-HTMLCommentStrip714c0aba658cd2f400000004

Solaris versions of Apache may need additional flags, otherwise there are 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:

NaodW29-HTMLCommentStrip714c0aba658cd2f400000005

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

NaodW29-HTMLCommentStrip714c0aba658cd2f400000006

Compile mod_caucho.so

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

NaodW29-HTMLCommentStrip714c0aba658cd2f400000007

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

NaodW29-HTMLCommentStrip714c0aba658cd2f400000008

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

NaodW29-HTMLCommentStrip714c0aba658cd2f400000009

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

NaodW29-HTMLCommentStrip714c0aba658cd2f40000000A

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

NaodW29-HTMLCommentStrip714c0aba658cd2f40000000B

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

NaodW29-HTMLCommentStrip714c0aba658cd2f40000000C

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.

--with-apache=dirThe Apache root directory.
--with-apxs=apxsPointer to the Apache extension script
--with-apache-include=dirThe Apache include directory
--with-apache-libexec=dirThe Apache module directory
--with-apache-conf=/path/httpd.confThe Apache config file

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

NaodW29-HTMLCommentStrip714c0aba658cd2f40000000D

# Java Location
JAVA_HOME=/<installdir>/jdk1.4
export JAVA_HOME

# Resin location (optional).  Usually Resin can figure this out.
RESIN_HOME=/<installdir>/resin-pro-3.0.2
export RESIN_HOME

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

NaodW29-HTMLCommentStrip714c0aba658cd2f40000000E

Windows

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

Configure resin.conf

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

The resin.conf for the backend server contains an srun to enable the port. The default resin.conf has an srun listener on port 6802.

NaodW29-HTMLCommentStrip714c0aba658cd2f40000000F

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
 
  ...
 
  <server>
 
    ...
 
    <cluster>
      <srun server-id="" host="127.0.0.1" port="6802"/>
    </cluster>
 
    ...

NaodW29-HTMLCommentStrip714c0aba658cd2f400000010

The resin.conf 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.conf looks in resin-pro-3.0.x/webapps/ROOT for JSP files and resin-pro-3.0.x/webapps/ROOT/WEB-INF/classes for servlets and java source files. To tell Resin to use Apache's document area, configure an explicit web-app with the appropriate document-directory:

NaodW29-HTMLCommentStrip714c0aba658cd2f400000011

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

NaodW29-HTMLCommentStrip714c0aba658cd2f400000012

Start the backend Resin server

Now you need to start the backend Resin server. Starting Resin is the same with Apache or standalone. See the Resin web server page for a detailed description.

NaodW29-HTMLCommentStrip714c0aba658cd2f400000013

 unix> bin/httpd.sh
 
 win> httpd.exe

NaodW29-HTMLCommentStrip714c0aba658cd2f400000014

NaodW29-HTMLCommentStrip714c0aba658cd2f400000015

Resin-pro-3.0.x (built Fri, 03 Feb 2006 09:47:48 EST)
Copyright(c) 1998-2006 Caucho Technology.  All rights reserved.
    
Starting Resin on Mon, 13 Feb 2006 20:16:19 -0500 (EST)
 
[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 *:6802
[09:43:41.073] Host[] starting
[09:43:41.446] Application[2] starting
[09:43:41.496] Application[3] starting

NaodW29-HTMLCommentStrip714c0aba658cd2f400000016

Resin will print every port it's listening to. In the above example, Resin has an http listener on port 8080 and an srun listener on port 6802 (using its custom `hmux' protocol). mod_caucho establishes connections to Resin using port 6802, 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 http and srun configuration for the above example.

NaodW29-HTMLCommentStrip714c0aba658cd2f400000017

<resin xmlns="http://caucho.com/ns/resin">
  <server>
    <http id="" host="*" port="8080"/>

    <cluster>
      <srun id="" host="localhost" port="6802" index="1"/>
    </cluster>

    ...
  </server>
</resin>

NaodW29-HTMLCommentStrip714c0aba658cd2f400000018

Test the servlet engine

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

NaodW29-HTMLCommentStrip714c0aba658cd2f400000019

2 + 2 = <%= 2 + 2 %>

NaodW29-HTMLCommentStrip714c0aba658cd2f40000001A

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

NaodW29-HTMLCommentStrip714c0aba658cd2f40000001B

2 + 2 = 4

NaodW29-HTMLCommentStrip714c0aba658cd2f40000001C

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

Unix:

NaodW29-HTMLCommentStrip714c0aba658cd2f40000001D

LoadModule caucho_module libexec/mod_caucho.so

ResinConfigServer localhost 6802
<Location /caucho-status>
  SetHandler caucho-status
</Location>

NaodW29-HTMLCommentStrip714c0aba658cd2f40000001E

Windows:

NaodW29-HTMLCommentStrip714c0aba658cd2f40000001F

LoadModule caucho_module <installdir>/resin-pro-3.0.x/libexec/apache-2.0/mod_caucho.dll
 
ResinConfigServer localhost 6802
<Location /caucho-status>
  SetHandler caucho-status
</Location>

NaodW29-HTMLCommentStrip714c0aba658cd2f400000020

ResinConfigServer

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.

Apache CommandMeaning
ResinConfigServer host portSpecifies the Resin JVM at host:port as a configuration server.

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

After reading the configuration from the backend Resin instance, mod_caucho keeps a local cahce of the information on disk. If the backend server becomes unavailable, mod_caucho uses the last known configuration until the backend server is again available to provide the configuration information.

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.

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.

NaodW29-HTMLCommentStrip714c0aba658cd2f400000021

CauchoHost 127.0.0.1 6802

<Location /foo/*>
  SetHandler caucho-request
</Location>

NaodW29-HTMLCommentStrip714c0aba658cd2f400000022

Apache CommandMeaning
CauchoHost host portAlternative to ResinConfigServer, adds the Resin JVM with an srun port at host:port as a backend server.
CauchoBackup host portAlternative to ResinConfigServer, adds the Resin JVM with an srun port at host:port as a backup backend server.
Apache HandlerMeaning
caucho-statusHandler to display /caucho-status
caucho-requestDispatch a request to Resin

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

The virtual host topic describes virtual hosts in detail. If you're using a single JVM, you only need to configure the resin.conf.

NaodW29-HTMLCommentStrip714c0aba658cd2f400000023

LoadModule caucho_module libexec/mod_caucho.so
 
ResinConfigServer 192.168.0.1 6802
<Location /caucho-status>
  SetHandler caucho-status
</Location>

NaodW29-HTMLCommentStrip714c0aba658cd2f400000024

NaodW29-HTMLCommentStrip714c0aba658cd2f400000025

<resin xmlns="http://caucho.com/ns/resin">
<server>
  <cluster>
    <srun id="" host="192.168.0.1" port="6802"/>
  </cluster>
 
  <host id='www.gryffindor.com'>
    <host-alias>gryffindor.com</host-alias>
     ...
  </host>
 
  <host id='www.slytherin.com'>
    <host-alias>slytherin.com</host-alias>
     ...
  </host>
</server>
</resin>

NaodW29-HTMLCommentStrip714c0aba658cd2f400000026

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.

NaodW29-HTMLCommentStrip714c0aba658cd2f400000027

 NaodW29-HTMLCommentStrip714c0aba658cd2f400000028
 <servlet-mapping url-pattern='/resin/*'
                  servlet-name='plugin_match'/>
 NaodW29-HTMLCommentStrip714c0aba658cd2f400000029
 <servlet-mapping url-pattern='/static/*'
                  servlet-name='plugin_ignore'/>

NaodW29-HTMLCommentStrip714c0aba658cd2f40000002A

Virtual host per JVM

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

NaodW29-HTMLCommentStrip714c0aba658cd2f40000002B

<VirtualHost gryffindor.com>
ServerName gryffindor.com
ServerAlias www.gryffindor.com
ResinConfigServer 192.168.0.1 6802
</VirtualHost>
 
<VirtualHost slytherin.com>
ServerName slytherin.com
ServerAlias www.slytherin.com
ResinConfigServer 192.168.0.1 6803
</VirtualHost>

NaodW29-HTMLCommentStrip714c0aba658cd2f40000002C

NaodW29-HTMLCommentStrip714c0aba658cd2f40000002D

<resin xmlns="http://caucho.com/ns/resin">
<server>
  <cluster>
    <srun id="" host="192.168.0.1" port="6802"/>
  </cluster>
 
  <host id=>
     ...
  </host>
</server>
</resin>

NaodW29-HTMLCommentStrip714c0aba658cd2f40000002E

NaodW29-HTMLCommentStrip714c0aba658cd2f40000002F

<resin xmlns="http://caucho.com/ns/resin">
<server>
  <cluster>
    <srun id="" host="192.168.0.1" port="6803"/>
  </cluster>
 
  <host id=>
     ...
  </host>
</server>
</resin>

NaodW29-HTMLCommentStrip714c0aba658cd2f400000030

NaodW29-HTMLCommentStrip714c0aba658cd2f400000031

$ bin/httpd.sh -pid gryffindor.pid -conf conf/gryffindor.conf start
$ bin/httpd.sh -pid slytherin.pid -conf conf/slytherin.conf start

...

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

NaodW29-HTMLCommentStrip714c0aba658cd2f400000032

Load balancing

The load balancing 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.

NaodW29-HTMLCommentStrip714c0aba658cd2f400000033

<resin xmlns="http://caucho.com/ns/resin">
<server>
  <cluster>
    <srun id="a" host="192.168.0.11" port="6802" index="1"/>
    <srun id="b" host="192.168.0.11" port="6803" index="2" backup="true"/>
    <srun id="c" host="192.168.0.12" port="6802" index="3"/>
    <srun id="d" host="192.168.0.12" port="6803" index="4" backup="true"/>
  </cluster>
  ...
</server>
</resin>

NaodW29-HTMLCommentStrip714c0aba658cd2f400000034

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.

NaodW29-HTMLCommentStrip714c0aba658cd2f400000035

ResinConfigServer 192.168.0.11 6802

NaodW29-HTMLCommentStrip714c0aba658cd2f400000036

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.

NaodW29-HTMLCommentStrip714c0aba658cd2f400000037

ResinConfigServer 192.168.0.11 6802
ResinConfigServer 192.168.0.12 6802

NaodW29-HTMLCommentStrip714c0aba658cd2f400000038

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.

NaodW29-HTMLCommentStrip714c0aba658cd2f400000039

CauchoHost 192.168.0.11 6802
CauchoBackup 192.168.0.11 6803
CauchoHost 192.168.0.12 6802
CauchoBackup 192.168.0.12 6803

<Location /foo/*>
  SetHandler caucho-request
</Location>

NaodW29-HTMLCommentStrip714c0aba658cd2f40000003A

Manual configuration of location based dispatching

NaodW29-HTMLCommentStrip714c0aba658cd2f40000003B

<Location /applicationA/*>
  ResinConfigServer 192.168.0.11 6802
</Location>

<Location /applicationB/*>
  ResinConfigServer 192.168.0.12 6802
</Location>

NaodW29-HTMLCommentStrip714c0aba658cd2f40000003C

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 srun host should be green and the mappings should match your resin.conf.
  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.conf 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-pro-3.0.x/log. You should start httpd.sh -verbose or httpd.exe -verbose to get more information.
  9. If Resin never shows a "srun listening to *:6802" line, it's not listening for connections from mod_caucho. You'll need to add a srun directive..
  10. If you get Resin's "file not found", the Apache configuration is good but the resin.conf probably points to the wrong directories.

Debug logging

Debug logging output from mod_caucho is created with the --enable-debug option to ./configure. It causes a large amount of information to be dumped to /tmp/log, probably not suitable for a production environment,

./configure --enable-debug --with-apache=...
Personal tools