Resin 1.1
FAQ
Reference
JavaDoc
Demo
Java Tutorial
Getting Started
Configuration
Topics
JSP
XTP/XSL
JavaScript
JS Library
Resin Web Server
Unix Apache
Windows Apache
Unix Netscape
IIS
Other Servlets
Caucho Servlet Engine on Apache Unix
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.
Installation
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 ### Compiling Apache 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=all unix> make unix> make install
### 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.
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
### Configuring Apache by hand Making mod_caucho will automatically change your httpd.conf file. For reference, here are the changes:
httpd.conf
LoadModule caucho_module libexec/mod_caucho.so AddModule mod_caucho.c <IfModule mod_caucho.c> CauchoConfigFile <installdir>/resin1.1/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.
caucho-status | Handler to display /caucho-status
caucho-request | Handler to connect to srun
### Configure the Environment If you don't already have Java installed, you'll need to download a JDK and set some environment variables. Good JDKs are available at blackdown and at IBM 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.1 export RESIN_HOME # If you're using additional class libraries, you'll need to put them # in the classpath. CLASSPATH=
### Configuring resin.conf By default, Resin will look in resin1.1/doc for JSP files and resin1.1/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>
### Starting the Servlet Engine Now you need to start the servlet engine.
> resin1.1/bin/srun.sh
The servlet runner takes the same optional arguments as http.sh:
-verbose | Information about the arguments to start Java
-conf <conf> | Specify a new configuration path
-java_home <java_home> | Specify the Java location
-resin_home <resin_home> | Specify the Resin home directory
-classpath <path> | Specify a global CLASSPATH
-nojit | Disable JIT compilation. Useful for debugging.
-J<arg> | Pass arg to the JVM
<-Darg> | Pass -Darg to the JVM
A better way to run the servlet engine in a production environment is to use the start and stop scripts. These scripts add extra reliability to the server. If Resin should ever exit, it will automatically be restarted. To start the servlet runner, use
unix> resin1.1/bin/srun.sh start
To stop it, use
unix> resin1.1/bin/srun.sh stop
### Testing the servlet engine Create a test file '/usr/local/apache/htdocs/test.jsp'
<%@ page language=javascript %> 2 + 2 = <%= 2 + 2 %>
Browse http://localhost/test.jsp again. You should now get
2 + 2 = 4
### Troubleshooting 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:8080/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 srun.sh hasn't started properly. If srun.sh doesn't start properly, you should look at the logs in resin1.1/log. You should start srun.sh -verbose to get more information. If you get Resin's file not found, the Apache configuration is good but the resin.conf probably points to the wrong directories.
Load Balancing | Resin 1.1
In Resin 1.1, 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 host='host1' port='6802'/> <srun host='host2' port='6802'/> <srun-backup host='backup port='6802'/> ... </http-server> </caucho.com>
Error Page | Resin 1.1
When mod_caucho can't reach any JVM, it will send a default error page. Sites can customize the error page with the CauchoErrorPage directive.
httpd.conf
CauchoErrorPage /usr/local/apache/htdocs/resin_error_page.html
Resin Web Server |  | Windows Apache
Copyright © 1998-2000 Caucho Technology. All rights reserved. Last modified: Tue, 25 Apr 2000 12:33:35 -0700 (PDT)