IIS

Latest revision as of 17:54, 18 January 2010

When used with IIS, Resin installs an IIS filter named isapi_srun and dispatches JSPs and Servlets to backend Resin servers while IIS serves static content like html and images.

Before you integrate Resin with IIS

Many users find that the performance, flexibility, and features of Resin make Resin a desirable replacement for IIS. Unless specific features of IIS are required, consider running Resin as the primary web server.

If you have not yet done so, follow the Resin web server instructions and get a working installation with Resin as the only web server. This is especially true with more complicated setups such as those involving virtual hosts. Doing so isolates the steps and makes troubleshooting easier.

Prerequisites and environment variables

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

The Control Panel is used to configure two environment variables:

 JAVA_HOME=C:\j2sdk1.4.2
 RESIN_HOME=C:\resin-pro-3.0.x

Configuring IIS/PWS

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

1. Configure the isapi_srun filter
2. Configure resin.conf
3. Start httpd.exe

ISAPI filter

Resin uses an ISAPI filter isapi_srun.dll to dispatch requests from IIS to backend Resin servers.

You should run RESIN_HOME/bin/setup.exe to setup your configuration and install isapi_srun.dll. 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.

ResinConfigServer localhost 6802
CauchoStatus yes
IISPriority high

Configure resin.conf

The default resin.conf looks in resin-pro-3.0.x/webapps/ROOT for JSP files and resin-pro-3.0.x/webapps/ROOT/WEB-INF/classes for servlets and java source files. To tell Resin to use IIS's document area, configure an explicit web-app with the appropriate document-directory:

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 directives to match.

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  ...
  <server>
    ...
    <host id="">
      <web-app id='/' document-directory="C:\Intepub"/>
    </host>
    ...
  </server>
</resin>

Test the servlet engine

From a cmd shell run httpd.exe to start the servlet runner.

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

Now browse http://localhost/test.jsp. You should get a 'file not found' message.

Create a test file 'd:\inetpub\wwwroot\test.jsp'

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

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

 2 + 2 = 4

Command line options

Main article: command line option

Deploying a Windows service

Main article: Windows service

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

To install the service, use

 win> resin-pro-3.0.x/httpd.exe -install

To remove the service, use

 win> resin-pro-3.0.x/httpd.exe -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.

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-pro-3.0.x/httpd.exe -install -Xrs

Load balancing

Main article: load balancing

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.

<resin xmlns="http://caucho.com/ns/resin">
  <server>
    <cluster>
      <srun id="a" host="123.0.11" port="6802" index="1"/>
      <srun id="b" host="123.0.12" port="6802" index="2"/>
    </cluster>
    ...
  </server>
</resin>

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

Manual configuration

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.

resin.ini

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.

ResinConfigServer

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.

The ResinConfigServer is used to tell isapi_srun how to contact the backend Resin server. The backend Resin server tell's mod_caucho which urls should be dispatched.

isapi_srun 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, isapi_srun 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.conf.

After reading the configuration from the backend Resin instance, isapi_srun keeps a local cahce of the information on disk. If the backend server becomes unavailable, isapi_srun uses the last known configuration until the backend server is again available to provide the configuration information.

caucho-status

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.

caucho-status is optional and probably should be avoided in a production site. It lets you ask the isapi_srun module about it's configuration, and the status of the backend server(s), valuable for debugging.

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 (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 isapi_srun.dll.

Details for configuring Resin to recognize virtual hosts are in the virtual hosts topic.

Virtual sites with different JVM's

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-foo.conf:

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

resin-bar.conf:

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

Install a servlet runner for each virtual site:

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

resin.ini for IIS virtual site foo.com:

ResinConfigServer localhost 6802

resin.ini for IIS virtual site bar.com:

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

Troubleshooting

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.
5. Check that isapi_srun.dll is in c:\inetpub\scripts.
6. Make sure that both IIS and the underlying NTFS file system have permissions set appropriately for isapi_srun.dll.
7. Make sure that your IIS host has a mapping from scripts/ to c:\inetpub\scripts and that the /scripts has execute permissions.
8. IIS 6 users may need to look at Troubleshooting IIS 6 below for additional steps.
9. If you've created a new IIS web site, you need to create a virtual directory scripts pointing to the d:\inetpub\scripts directory.
10. If caucho-status shows the wrong mappings, there's something wrong with the resin.conf.
11. If caucho-status shows a red servlet runner, then httpd.exe hasn't properly started.
12. If you get a "cannot connect to servlet engine", caucho-status will show red, and httpd.exe hasn't started properly.
13. 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.
14. If you get Resin's file not found, the IIS configuration is good but the resin.conf probably points to the wrong directories.

Troubleshooting IIS 6

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

1. Make sure that the System account has suffiicient privleges to read the C:\InetPub and C:\InetPub\Scripts directory and the isapi_srun.dll.
2. 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.
3. 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".

Using Resin with IIS 7 on Windows Vista

IIS 7/Windows Vista users will need to install the isapi_srun.dll manually. Image below is given as a reference to show list of handler mappings after successful isapi_srun.dll installation.

Steps to install isapi_srun.dll filter:

1. Enable ISAPI in Control Panel: Make sure that Internet Information Services -> World Wide Web Services -> Application Development Features -> ISAPI Extensions & ISAPI Filters is checked in Control Panel -> Programs and Features -> Turn Windows features on or off. Image below shows the needed features in selected state.
2. 
   1. You may need to toggle the checkboxes a couple of times before ISAPI-dll appears in the list of Handler Mappings.
3. Create directory Scripts under c:\InetPub\ if one does not exist.
4. Copy isapi_srun.dll to c:\InetPub\Scripts
5. Enable ISAPI-dll in IIS: Open Internet Information Services Manager and navigate to the Default Web Site. Open "Handler Mappings". If ISAPI-dll appears in disabled group, right click on ISAPI-dll and choose Edit Feature Permissions... Check off "Execute" and click OK. The ISAPI-dll should now appear in the enabled group. Image below shows ordered list of Global Handlers
6. 
7. Choose "Add Script Map" from the Actions menu and specify Request path as '*' without the quotes.
8. Set "Executable" pointing to c:\InetPub\Scripts\isapi_srun.dll; set "Name" to RESIN. Click OK. Image below shows ordered list of handlers for the site.
9. 
10. Restart IIS and make sure Resin is running
11. Navigate to a jsp page e.g. http://localhost/index.jsp on default configuration.
12. Navigating to /caucho-status should show state of resin cluster (Image below)
13.