Resin Documentation

resin with iis

For sites requiring the use of IIS, Resin provides a fast servlet runner, allowing IIS to run servlets and JSP files.

If you have not yet done so, we suggest you consider the Resin web server option first, either as a standalone web server or as a web-tier server load-balancing to Resin app-tier servers. Resin's Java web server provides management, clustering, and load-balancing with failover.

Resin requires a 1.5 JDK. You can download one from Sun and install it.

The Control Panel is used to configure two environment variables:

JAVA_HOME=C:\jdk1.5.0
RESIN_HOME=C:\resin-3.0

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

1. Configure IIS/PWS
2. Configure resin.conf
3. Start httpd

ResinConfigServer localhost 6802
CauchoStatus yes
IISPriority high

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

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

C:\> cd %RESIN_HOME%
C:\resin-3.0> cd bin
C:\resin-3.0> httpd.exe

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

2 + 2 = 4

The following configuration line arguments are recognized by httpd.exe. When command line arguments are used along with -install to install as a service, the arguments are used each time the service starts.

Once you're comfortable with using Resin with IIS, you can install it as an NT service. As a service, Resin will automatically start when NT reboots. The service will also automatically restart Resin if it unexpectedly exits.

To install the service, use

win> resin-3.0.x/httpd -install

To remove the service, use

win> resin-3.0.x/httpd -remove

You will either need to reboot the machine or start the service from the Control Panel/Services panel to start the server. On a machine reboot, NT will automatically start the servlet runner.

Note

There is a bug in many JDKs which cause the JDK to exit when the administrator logs out. JDK 1.4 and later can avoid that bug if the JDK is started with -Xrs.

win> resin-3.0.x/httpd -install -Xrs

With Resin, you can distribute requests to multiple machines. All requests with the same session will go to the same host. In addition, if one host goes down, the IIS filter 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 Resin config section for more details.

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

win> resin-3.0.x/httpd -install-as "Resin-A" -server a -Xrs
win> resin-3.0.x/httpd -install-as "Resin-B" -server b -Xrs
win> resin-3.0.x/httpd -install-as "Resin-C" -server c -Xrs

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

1. Make sure httpd.exe works
2. 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.
3. 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.
4. (optional) Create a resin.ini in d:\inetpub\scripts pointing to the ResinConfigServer
5. (optional) Add a "CauchoStatus yes" line to the resin.ini for debugging
6. Configure IIS to load isapi_srun.dll as an ISAPI filter.
7. Restart IIS (control panel/services) or net stop w3svc followed by net start w3svc.
8. Browse /servlet/Hello and /foo.jsp. You should see a "cannot connect" error.
9. Start httpd.exe
10. 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.conf 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.

ResinConfigServer 192.168.0.10 6802
CauchoStatus yes

If IIS is managing multiple virtual sites (everyone else calls them 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.

Resin is configured to recognize virtual hosts with the id attribute of <host>.

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

    <host id="foo.com">
      ...
    </host>

    <host id="bar.com">
      ...
    </host>

    <host id="baz.com">
      ...
    </host>

  </server>
</resin>

Resin recognizes which host to use by examing the url. With the above example, a url of http://foo.com/some/path will use host id="foo.com" and a url of http://bar.com/some/path will use host id="bar.com".

If a seperate JVM for each virtual site is desired, a seperate resin.ini is used for each virtual site. The resin.ini file is placed in the scripts directory.

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

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

win> resin-3.0.x/httpd -install-as "Resin-foo" \
    -conf resin-foo.conf -Xrs
win> resin-3.0.x/httpd -install-as "Resin-bar" \
    -conf resin-bar.conf -Xrs

ResinConfigServer localhost 6802

ResinConfigServer localhost 6803

The ResinConfigServer tells the isapi_srun.dll the port number to use to connect to the Resin instance. You can change the host from localhost to a backend server. You can also add multiple ResinConfigServer items to cluster the configuration.

resin-foo.conf and resin-bar.conf contain a <host id="*">, you do not need to specify the host name because each conf/JVM is only going to receive requests from a particular virtual site (because of the unique resin.ini files).

1. Check your configuration with the standalone web server. In other words, add a <http port='8080'/> block and browse http://localhost:8080.
2. Check http://localhost/caucho-status. That will tell if the ISAPI filter/extension is properly installed.
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 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.
5. If you've created a new IIS web site, you need to create a virtual directory /scripts pointing to the d:\inetpub\scripts directory.
6. If caucho-status shows the wrong mappings, there's something wrong with the resin.conf.
7. If caucho-status shows a red servlet runner, then httpd.exe hasn't properly started.
8. If you get a "cannot connect to servlet engine", caucho-status will show red, and httpd.exe hasn't started properly.
9. If httpd.exe doesn't start properly, you should look at the logs in resin3.0/log. You should start httpd.exe -verbose to get more information.
10. If you get Resin's file not found, the IIS configuration is good but the resin.conf probably points to the wrong directories.