getting started

resin with apache and iis

Resin provides a fast servlet runner for Apache 2.2, and IIS allowing these HTTP servers to dispatch requests to Resin.

Before you integrate Resin with Apache or IIS

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 it a desirable replacement for Apache and IIS. These 3rd party HTTP servers add overhead to Resin's operation, therefore you should have a specific reason to run one of them with Resin.

Using Resin with Apache

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.

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.

Unix Installation

Resin needs Apache 2.x or greater and DSO support. You probably have DSO support, but if you're not sure, you can check for mod_so.c when running httpd -l:

checking apache httpd for mod_so.c

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

If you don't have DSO support, you can recompile Apache or install another package from your operating system vendor. Check their documentation for more details.

Compiling mod_caucho.so

Compiling mod_caucho on Unix is usually as easy as changing the way that you configure Resin during installation:

Locate the apxs program that is included with Apache.
Follow the Resin installation instructions. In addition to any other configure script options, add the --with-apxs option. Assuming that your apxs program is in /usr/sbin/apxs, you might run configure in the following way:
```
unix> ./configure --with-apxs=/usr/sbin/apxs --prefix=/usr/local/resin
```
Run make and make install as specified in the installation instructions. In addition to building the normal Resin native libraries, these steps will also build mod_caucho, install it, and add some directives to the end of your httpd.conf file configuring mod_caucho.

Windows Installation

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

The httpd.conf file is also easily modified manually:

httpd.conf

LoadModule caucho_module \
    <resin.home>/win32/apache-2.0/mod_caucho.dll

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

Replace win32 with win64 above if you're using a 64-bit version of Apache.

Configuring resin.xml

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

The resin.xml for the backend server contains a server to enable the port. The default resin.xml has an server listener on port 6800.

resin.xml

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin">
  ...
  <cluster id="app-tier">
    ...
    <server id="" address="127.0.0.1" port="6800"/>
    ...

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

resin.xml

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin">
  ...
  <cluster id="">
    ...
    <host id="">
      <web-app id='/' document-directory="/usr/local/apache/htdocs"/>
    </host>
    ...
  </cluster>
</resin>

Configuring Apache httpd.conf

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 COMMAND	MEANING
ResinConfigServer hostport	Specifies the Resin JVM at host:port as a configuration server.

The caucho-status handler 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.

CauchoHost 127.0.0.1 6800

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

APACHE COMMAND	MEANING
CauchoHost hostport	Alternative to ResinConfigServer, adds the Resin JVM with an server port at host:port as a backend server.
CauchoBackup hostport	Alternative to ResinConfigServer, adds the Resin JVM with a server port at host:port as a backup backend server.

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.

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.

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. 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 6800
ResinConfigServer 192.168.0.12 6801

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.

CauchoHost 192.168.0.11 6800
CauchoBackup 192.168.0.11 6801
CauchoHost 192.168.0.12 6800
CauchoBackup 192.168.0.12 6801

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

Manual configuration of location based dispatching

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

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

Troubleshooting

Check your configuration with Resin standalone. In other words, add a <http port='8080'/> and check port 8080.
Check http://localhost/caucho-status. That will tell if mod_caucho has properly connected to the backend Resin server. Each server should be green and the mappings should match your resin.xml.
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.xml or the pointer to the backend server in httpd.conf.
If caucho-status shows a red servlet runner, then Resin hasn't properly started.
If you get a "cannot connect to servlet engine", caucho-status will show red, then Resin hasn't started properly.
If Resin doesn't start properly, you should look at the logs in <resin.log>/log. You should start java -jar <resin.home>/lib/resin.jar -verbose or resin.exe -verbose to get more information.
If Resin never logs a "hmux listening to *:6800" line, it's not listening for connections from mod_caucho. You'll need to add a <server> line.
If you get Resin's "file not found", the Apache configuration is functional but the resin.xml probably points to the wrong directories.

IIS

Environment Variables

Configure the following two environment variables in the Control Panel:

JAVA_HOME=C:\jdk1.5.0
RESIN_HOME=C:\Resin

Of course, adjust these to the correct directories for Java and Resin if they differ from your own.

Configuring IIS/PWS

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

Configure IIS/PWS
Configure resin.xml
Start resin.exe

ISAPI Filter

You should run RESIN_HOME/setup.exe to setup your configuration. If setup.exe is not used, or it fails, the steps in Manual Configuration are necessary.

ISAPI Filter Priority

isapi_srun.dll installs itself as the default priority. Some users may need to set the priority to a higher level, e.g. to override IIS's DAV support.

resin.ini

ResinConfigServer localhost 6802
CauchoStatus yes
IISPriority high

Configuring resin.xml

resin.xml should mirror the configuration of IIS. In other words, you need to configure the document root and any directory aliases.

For many users, the only need to change needed in Resin is to change the document-directory attribute from 'webapps/ROOT' to something like 'C:/inetpub/wwwroot'. The mapping of url paths from the browser to real files on the disk must be the same for Resin as they are for IIS. For more complicated configurations that use mappings in IIS, you'll need to add path-mapping attributes to match.

Example: resin.xml

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <!-- configures the default host, matching any host name -->
  <host id="">

  <!-- configures the root web-app -->
  <web-app id='/'>
    <root-directory>C:/inetpub/wwwroot</root-directory>
    <!-- adds xsl to the search path -->
    <class-loader>
      <simple-loader path="$host-root/xsl"/>
    </class-loader>
  </web-app>
</host>

</cluster>
</cluster>

Load Balancing

Resin's IIS plugin supports load balancing in much the same way as mod_caucho does for Apache. Consult the mod_caucho load balancing section for more details.

Manual Configuration

Experts may want to configure Resin/IIS by hand instead of using the setup program. The steps involved are:

Make sure resin.exe works
Copy isapi_srun.dll to the IIS scripts directory, d:\inetpub\scripts. You may need to run net stop w3svc to get permission to overwrite the file.
If you have a virtual site (virtual hosts), you must configure IIS to have the virtual directory /scripts point to d:\inetpub\scripts for each virtual site.
(optional) Create a resin.ini in d:\inetpub\scripts pointing to the ResinConfigServer
(optional) Add a "CauchoStatus yes" line to the resin.ini for debugging
Configure IIS to load isapi_srun.dll as an ISAPI filter.
Restart IIS (control panel/services) or net stop w3svc followed by net start w3svc.
Browse /servlet/Hello and /foo.jsp. You should see a "cannot connect" error.
Start resin.exe
Browse /servlet/Hello and /foo.jsp. You should now see the servlet.

Copying isapi_srun.dll to inetpub/scripts directory is relatively straightforward. If you're upgrading to a new version of Resin, you may need to stop IIS (control panel/services) to get permission to overwrite isapi_srun.dll.

The resin.ini is an optional file in inetpub/scripts to override the automatic registry $RESIN_HOME/conf/resin.xml configuration file. If you only have one Resin server, you should not create a resin.ini and let isapi_srun.dll use the registry value set by the setup.exe program.

resin.ini is only needed if you have multiple Resin configuration files for different IIS virtual hosts.

The resin.ini should contain the following line:

ResinConfigServer localhost 6802

You can change the host from localhost to a backend server. You can also add multiple ResinConfigServer items to cluster the configuration.

For debugging, you can add a "CauchoStatus yes" line to the resin.ini:

ResinConfigServer localhost 6802
CauchoStatus yes

For security purposes, the default value of CauchoStatus is "no" when you have a resin.ini.

Adding an ISAPI filter is accomplished in the IIS manager.

IIS and Resin on different machines

When Resin and IIS are on different machines, you'll change the ResinConfigServer from "localhost" to the IP address of the Resin server.

ResinConfigServer 192.168.0.10 6802
CauchoStatus yes

Virtual Sites (Virtual Hosts)

If IIS is managing multiple virtual sites (better known as virtual hosts), then you need to configure IIS to use the isapi_srun.dll filter for each virtual site. Configure IIS to have the virtual directory /scripts for each virtual site point to d:\inetpub\scripts, so that each virtual site uses the isapiu_srun.dll.

Troubleshooting

Check your configuration with the standalone web server. In other words, add a <http port='8080'/> block and browse http://localhost:8080.
Check http://localhost/caucho-status. That will tell if the ISAPI filter/extension is properly installed.
Each server should be green and the mappings should match your resin.xml.
If caucho-status fails entirely, the problem is in the isapi_srun installation. Try http://localhost/scripts/isapi_srun.dll/caucho-status directly (bypassing the filter). If this fails, IIS can't find isapi_srun.dll.
- Check that isapi_srun.dll is in c:\inetpub\scripts.
- Make sure that both IIS and the underlying NTFS file system have permissions set appropriately for isapi_srun.dll.
- Make sure that your IIS host has a mapping from /scripts to c:\inetpub\scripts and that the /scripts has execute permissions.
- IIS 6 users may need to take additional steps.
If you've created a new IIS web site, you need to create a virtual directory /scripts pointing to the d:\inetpub\scripts directory.
If caucho-status shows the wrong mappings, there's something wrong with the resin.xml.
If caucho-status shows a red servlet runner, then resin.exe hasn't properly started.
If you get a "cannot connect to servlet engine", caucho-status will show red, and resin.exe hasn't started properly.
If resin.exe doesn't start properly, you should look at the logs in resin3.2/log. You should start resin.exe -verbose to get more information.
If you get Resin's file not found, the IIS configuration is good but the resin.xml probably points to the wrong directories.

Troubleshooting IIS 6

IIS 6/Windows 2003 users may need to perform additional steps.

Make sure that the System account has suffiicient privleges to read the C:\InetPub and C:\InetPub\Scripts directory and the isapi_srun.dll.
Check the `Web Service Extensions' listed in the `Internet Service Manager' to make sure that Resin is listed as a Web Service Extension and has a status of "enabled". You may need to click "add a new web service extension...", under Extension name add .jsp or whatever your file extension is, click Add and browse to the isapi_srun.dll, check the "Set extension status to allowed box", click OK.
Check that the user specified as the "application pool identity" for Resin has read/write permission to the Resin installation directory. In the Internet Service Manager, open the Properties dialog for "Application Pools". Find the User on the "Identity" tab, it may be the user named "Network Service" in the drop-down list associated with the radio button labeled "predefined". Then check physical file permissions on the Resin installation directory and all its subdirectories and subfiles, to ensure that that user has read/write permission status is "Enabled".

Configuring resin.xml to work with Apache and IIS

The previous sections show how to configure Apache and IIS to work with Resin. This section shows how the plugins for these servers interpret the Resin's configuration and how to change that configuration for your deployment.

The web server plugins (mod_caucho and isapi_srun) have two main tasks:

Select urls to dispatch to the Java process
Pass the request and retrieve the response from the Java process.

ResinConfigServer

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

servlet-mapping selects URLs

The servlet-mapping tag selects the URLs to send to Resin. <host> and <web-app> group the servlet-mapping tags.

url-pattern

servlet-mapping's url-pattern selects the URLs to pass to Resin. servlet-mapping and url-pattern are part of the Servlet 2.3 standard, so there are many references explaining how it works.

url-pattern can take one of four forms:

"/" matches all URLs. Use this to pass all requests to Resin.
"/prefix/url/*" matches any URL starting with /prefix/url, including prefix/url itself. It does not match /prefix/urlfoo because any slash must immediately follow url
"/exact/path" matches only the exact path. In other words, it will not match /exact/path/bogus.
"*.ext" matches any URL with the extension ext. Resin allows path-infos, so /foo/bar.ext/path/info will also match.

url-regexp

Note mod_caucho does not understand regular expressions. If you put regular expressions in your resin.xml, mod_caucho will not send the request to Resin. Apache will handle the request itself.

If you want to use regular expressions in servlet-mapping, web-app, or hosts, you must use Apache-specific configuration to send the request to Resin. You can see this by looking at /caucho-status. /caucho-status will not display any regular expressions.

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.

<!-- send everything under /resin to Resin -->
<servlet-mapping url-pattern='/resin/*'
                 servlet-name='plugin_match'/>

<!-- keep everything under /static at the web server -->
<servlet-mapping url-pattern='/static/*'
                 servlet-name='plugin_ignore'/>

<web-app>

web-apps collect servlets and JSP files into separate applications. All the servlet-mappings in a web-app apply only to the URL suffix.

In the following example, every URL starting with /prefix/url maps to the web-app. The servlet-mapping only applies to URLs matching the prefix.

...
<web-app id='/prefix/url'>
  <servlet-mapping url-pattern='*.foo' .../>
</web-app>
..

In the exaple, mod_caucho will match any URL matching /prefix/url/*.foo. /prefix/url/bar.foo will match, but /test/bar.foo will not match.

Note Resin standalone allows a regexp attribute instead of an id. Because mod_caucho does not understand regexps, it will ignore any web-app with a regexp attribute.
Note web.xml files and war files are treated exactly the same as web-apps in the resin.xml.

<host>

host blocks configure virtual hosts. There's a bit of extra work for virtual hosts that we'll ignore here. (Basically, you need to add Apache ServerName directives so Resin knows the name of the virtual host.)

For dispatching, a host block gathers a set of web-apps. Each host will match a different set of URLs, depending on the web-app configuration. The default host matches any host not matched by a specific rule.

As usual, /caucho-status will show the URLs matched for each host.

Note mod_caucho does not understand the host regexp attribute. It will ignore all hosts using regexp. To get around this, you can either configure Apache directly (see below), or configure the default host with the same set of servlet-mappings. Since mod_caucho will use the default host if no others match, it will send the right requests to Resin.