Resin with IIS Reference Page

Resin provides a fast servlet runner for IIS, allowing IIS to run servlets and JSP files.

web.config

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="ResinHandlerFactory" <!--Name used by resin handler. Can be changed.-->
           path="*" <!-- Requests path to invoke the handler on-->
           verb="*" <!-- HTTP Method. possible values: 'GET', 'POST', 'HEAD' or combination 'GET,POST' -->
           type="Caucho.IIS.ResinHandlerFactory" <!-- Resin Handler Factory that supplies one reusable handler instance-->
           preCondition="integratedMode"/>
    </handlers>
  </system.webServer>
  <appSettings>
    <add key="resin.servers" value="127.0.0.1:6800"/> <!-- Address and port to Resin server(s)-->
    <add key="resin.log-level" value="Information"/> <!-- logging level used by Resin IIS Handler. Use 'None' for silent operation-->
  </appSettings>
</configuration>

Resin IIS Handler communicates with Resin using HMUX (Resin's internal protocol) with the connection made to the port defined in Resin's configuration file. Matching Resin configuration for the example IIS configuration given above must bind Resin HMUX listener to port 6800.

resin.xml

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

In order to configure Resin IIS Handler to communicate to a set of Resin Pro Servers resin.servers configuration parameter needs be an enumeration of ip:port pairs:

web.config

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="ResinHandlerFactory" <!--Name used by resin handler. Can be changed.-->
           path="*" <!-- Requests path to invoke the handler on-->
           verb="*" <!-- HTTP Method. possible values: 'GET', 'POST', 'HEAD' or combination 'GET,POST' -->
           type="Caucho.IIS.ResinHandlerFactory" <!-- Resin Handler Factory that supplies one reusable handler instance-->
           preCondition="integratedMode"/>
    </handlers>
  </system.webServer>
  <appSettings>
    <add key="resin.servers" value="127.0.0.1:6800 127.0.0.2:6800 127.0.0.1:6801 127.0.0.2:6802"/> <!-- Address and port to Resin server(s)-->
    <add key="resin.log-level" value="Information"/> <!-- logging level used by Resin IIS Handler. Use 'None' for silent operation-->
  </appSettings>
</configuration>

Appcmd.exe offers a command line interface to configuring IIS server. Below are the examples showing how to use the utility to configure various aspects of Resin IIS Handler.

Registering the Resin IIS Handler

        # Remove Resin IIS Hanlder if one is registered
        %APPCMD% set config "Default Web Site" /section:handlers /-[name='ResinHandlerFactory']

        # Add Resin IIS Handler
        %APPCMD% set config "Default Web Site" /section:handlers /+[name='ResinHandlerFactory',path='*',\
        verb='*',type='Caucho.IIS.ResinHandlerFactory',preCondition='integratedMode']

        # Note: The above command needs to be issued in one line. The \ character
        # at the last position of the first line is used to denote that command
        # continues on next line


        # Note: %APPCMD% should be pointing to the location of appcmd.exe utility.
        #       default location is c:\Windows\System32\inetsrv\appcmd.exe

Resin IIS Hanlder parameters

        # Remove resin.servers parameter
        %APPCMD% set config "Default Web Site" /section:appSettings /-[key='resin.servers']
        # Set resin.servers parameter
        %APPCMD% set config "Default Web Site" /section:appSettings /+[key='resin.servers',value='192.168.0.1:6800']

        # Remove resin.log-level parameter
        %APPCMD% set config "Default Web Site" /section:appSettings /-[key='resin.log-level']
        # Set resin.log-level parameter to 'Information'
        %APPCMD% set config "Default Web Site" /section:appSettings /+[key='resin.log-level',value='Information']

Tracing

When Resin IIS Handler is compiled with TRACE option enabled it uses System.Diagnostics.Trace class to output detailed information for every request. This can be useful in debugging errors. Tracing information will go into a file configured in a tracing listener.

Configuring Resin IIS Handler for tracing

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.diagnostics>
    <trace autoflush="true" indentsize="0">
      <listeners>
         <add name="resin-trace" initializeData="C:\temp\resin-iis-trace.log" type="System.Diagnostics.TextWriterTraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

Note, that Resin IIS Handler in distribution compiled with no TRACE option.

Logging

Resin IIS Handler uses standart .NET loggin mechanism to output information on its opeartion. Upon startup, the handler attempts to initialize Logging to write to 'Application' log using 'Resin IIS Handler' log source. If the log source can not be created automatically due to permissions or other issues, the source can be created manually be adding a key 'Resin IIS Handler' to log sources collection in the registry at

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application\Resin IIS Handler]

Alternatively, copy the contents of the following text box into a file with .reg extension and double click on it to import into registry.

Resin IIS Handler Logging Source

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application\Resin IIS Handler]

caucho-status is optional and probably should be avoided in a production site. It lets you ask the Caucho IIS module about it's configuration, and the status of the backend server(s), valuable for debugging. To see caucho-status point your browser url to http://youriisserver/caucho-status.

resin with iis reference page

IIS Prerequisites

Installing and Configuring Resin IIS Handler

Configuring using appcmd.exe configuration utility

Tracing & Logging with Resin IIS Handler

Tracing

Logging

Resin IIS Handler Status