
Resin
FAQ
Reference Guide
JavaDoc
Demo
Tutorial

Getting Started
Configuration
EJB
Topics
JSP
XTP/XSL

Resin Web Server
Unix Apache
Windows Apache
Unix Netscape
IIS
WebSite
Other Servlets

Getting Started

Windows Apache

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.

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

Compiling Apache
Compile mod_caucho.so
Configure Apache
Set up environment
Configure resin.conf
Restart Apache and start srun

You need a version of Apache with DSO support enabled. Most 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:

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

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.

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

If you know where your apxs executable is, you can use:

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

apxs is a little Perl script that the Apache configuration makes. It lets modules like Resin know how all the Apache directories are configured.

If you need finer control over the apache configuration, you can use the following arguments to ./configure. Resin needs apache-include, apache-libexec, and apache-conf.

--with-apache=dir The Apache root directory.

--with-apxs=apxs Pointer to the Apache extension script

--with-apache-include=dir The Apache include directory

--with-apache-libexec=dir The Apache module directory

--with-apache-conf=httpd.conf The Apache config file

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

# Java Location JAVA_HOME=/<installdir>/jdk1.2.2 export JAVA_HOME # Resin location (optional). Usually Resin can figure this out. RESIN_HOME=/<installdir>/resin1.2 export RESIN_HOME # If you're using additional class libraries, you'll need to put them # in the classpath. CLASSPATH=

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 app-dir. Change app-dir from 'doc' to something like '/usr/local/apache/htdocs'.
resin.conf

<caucho.com> <http-server app-dir='/usr/local/apache/htdocs'> <servlet-mapping url-pattern='/servlets/*' servlet-name='invoker'/> <servlet-mapping url-pattern='*.xtp' servlet-name='com.caucho.jsp.XtpServlet'/> <servlet-mapping url-pattern='*.jsp' servlet-name='com.caucho.jsp.JspServlet'/> </http-server> </caucho.com>

Now you need to start the servlet engine. Starting Resin is the same with Apache or standalone. See the httpd page for a detailed description.

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

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.

The following snippet shows the <http> and <srun> configuration for the above example.

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

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

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

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

2 + 2 = 4

First, check your configuration with the standalone httpd.sh. Both httpd.sh and srun.sh use the same configuration file, so the results should be identical.
Check http://localhost/caucho-status. That will tell if mod_caucho has properly read the resin.conf.
Each srun host should be green and the mappings should match your resin.conf.
If caucho-status fails entirely, the problem is in the mod_caucho installation and the Apache httpd.conf.
If caucho-status shows the wrong mappings, there's something wrong with the resin.conf or the pointer to resin.conf in httpd.conf.
If caucho-status shows a red servlet runner, then srun.sh hasn't properly started.
If you get a "cannot connect to servlet engine", caucho-status will show red, and httpd.sh hasn't started properly.
If httpd.sh doesn't start properly, you should look at the logs in resin1.2/log. You should start httpd.sh -verbose to get more information.
If httpd.sh says "no servers defined", your resin.conf is missing a <srun> or <httpd> definition.
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 <srun> line.
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 host attribute in the srun configuration.
If you get Resin's "file not found", the Apache configuration is good but the resin.conf probably points to the wrong directories.

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

LoadModule caucho_module libexec/mod_caucho.so AddModule mod_caucho.c <IfModule mod_caucho.c> CauchoConfigFile <installdir>/resin1.2/conf/resin.conf <Location /caucho-status> SetHandler caucho-status </Location> </IfModule>

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.

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

Browse http://localhost/test.jsp. It should return a message like:

Cannot connect to Servlet Runner.

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

Apache Handler Meaning

caucho-status Handler to display /caucho-status

caucho-request Dispatch a request to Resin

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

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

Apache Command Meaning

CauchoConfigFile conf Reads conf for the Resin configuration.

CauchoHost host port Adds the Resin JVM at host:port as a servlet runner.

CauchoBackup host port Adds the Resin JVM at host:port as a backup servlet runner.

The virtual host 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:
httpd.conf

<VirtualHost foo.com> ServerName foo.com ServerAlias www.foo.com CauchoConfigFile /home/foo/conf/foo.conf </VirtualHost> <VirtualHost bar.com> ServerName bar.com ServerAlias www.bar.com CauchoConfigFile /home/bar/conf/bar.conf </VirtualHost>

The foo.conf might look something like:
foo.conf

<caucho.com> <http-server> <srun host='foo.com' port='6802'/> <host id='www.foo.com'> ... </host> </caucho.com>

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.

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

See the http config section for more details.
resin.conf

<caucho.com> <http-server> <srun id="a" host='host1' port='6802'/> <srun id="b" host='host2' port='6802'/> <srun-backup id="c" host='backup port='6802'/> ... </http-server> </caucho.com>

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

resin.conf
... <web-app> <error-page exception-type='connection' location='/conn_error_page.html'/> ... </web-app>

Resin Web Server

Getting Started

Windows Apache