documentation examples changes overview quick start installation command-line configuration admin amber clustering caching database deployment ejb 3.0 embedding filters hessian hmtp ioc jsp logging messaging performance quercus/php remoting scheduled tasks security server push servlets third-party troubleshooting virtual hosting watchdog webapp xml and xslt resin web server apache iis plugin dispatch linux boot | resin with apache
Resin provides a fast servlet runner for Apache 1.3 or greater, allowing Apache to run servlets and JSP files. If you have not yet done so, we suggest you use the Resin standalone web server option first. Before integrating Resin with Apache, it is valuable to configure Resin as a standalone server, 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. 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 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 How the Plugins Dispatch to Resin page. Resin needs Apache 1.3.x or greater and DSO support. To configure Resin with Apache, you must follow the following steps:
Compiling ApacheYou need a version of Apache with DSO support enabled. Apache has full documentation at their website. To check if your apache has DSO support, you can check for in your your httpd unix> /usr/local/apache/bin/httpd -l Compiled-in modules: ... mod_so.c ... 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: unix> ./configure --prefix=/usr/local/apache --enable-module=so unix> make unix> make install 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: unix> ./configure --prefix=/usr/local/apache \ --enable-rule=SHARED_CORE \ --enable-rule=SHARED_CHAIN \ --enable-module=so \ --enable-module=most \ --enable-shared=max Compiling mod_caucho.soTo compile and install If you know where your executable is, you can use --with-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.unix> ./configure --with-apxs=/usr/local/apache/bin/apxs unix> make Even if you don't know where is, the configure script can often find it:unix> ./configure --with-apxs unix> make 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: unix> ./configure --with-apache=/usr/local/apache unix> make unix> make install 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.
Configure the EnvironmentIf 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.4 export JAVA_HOME # Resin location (optional). Usually Resin can figure this out. RESIN_HOME=/<installdir>/resin-3.1.2 export RESIN_HOME # If you're using additional class libraries, you'll need to put them # in the classpath. CLASSPATH=
The The httpd.conf file is also easily modified manually: LoadModule caucho_module \ <installdir>/resin-3.1.x/win32/apache-2.0/mod_caucho.dll ResinConfigServer localhost 6802 <Location /caucho-status> SetHandler caucho-status </Location>
The communication between
The <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> ... <server> ... <cluster> <server id="" address="127.0.0.1" port="6802"/> </cluster> ... 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 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> Now you need to start the app-tier Resin server. Starting Resin is the same with Apache or standalone. See the Resin Web Server page for a detailed description. unix> java -jar $RESIN_HOME/lib/resin.jar unix> bin/httpd.sh win> httpd.exe Resin 3.1.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 *:6802 [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 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 6800 (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 <server> configuration for the above 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> 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 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. LoadModule caucho_module libexec/mod_caucho.so ResinConfigServer localhost 6802 <Location /caucho-status> SetHandler caucho-status </Location> LoadModule caucho_module \ <installdir>/resin-3.1.x/libexec/apache-2.0/mod_caucho.dll ResinConfigServer localhost 6802 <Location /caucho-status> SetHandler caucho-status </Location>
The
caucho-status
After any change to httpd.conf, restart Apache. Now browse http://localhost/caucho-status. Manual configuration of dispatchingYou 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. CauchoHost 127.0.0.1 6802 <Location /foo/*> SetHandler caucho-request </Location>
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. LoadModule caucho_module libexec/mod_caucho.so ResinConfigServer 192.168.0.1 6802 <Location /caucho-status> SetHandler caucho-status </Location> <resin xmlns="http://caucho.com/ns/resin"> <server> <cluster> <server id="" address="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> Virtual Host per JVMIf you want a different JVM for each virtual host, your httpd.conf can specify a different srun port for each host. <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> <resin xmlns="http://caucho.com/ns/resin"> <server> <cluster> <server id="" address="192.168.0.1" port="6802"/> </cluster> <host id=''> ... </host> </server> </resin> <resin xmlns="http://caucho.com/ns/resin"> <server> <cluster> <server id="" address="192.168.0.1" port="6803"/> </cluster> <host id=''> ... </host> </server> </resin> $ 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 The Reliability and 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. <resin xmlns="http://caucho.com/ns/resin"> <server> <cluster> <server id="a" address="192.168.0.11" port="6802"/> <server id="b" address="192.168.0.11" port="6803" backup="true"/> <server id="c" address="192.168.0.12" port="6802"/> <server id="d" address="192.168.0.12" port="6803" backup="true"/> </cluster> ... </server> </resin> 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. ResinConfigServer 192.168.0.11 6802 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. ResinConfigServer 192.168.0.11 6802 ResinConfigServer 192.168.0.12 6802 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 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> Manual configuration of location based dispatching<Location /applicationA/*> ResinConfigServer 192.168.0.11 6802 </Location> <Location /applicationB/*> ResinConfigServer 192.168.0.12 6802 </Location>
|