home
Caucho Technology

resin with iis reference page

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

IIS Prerequisites

  • .NET Extensibility
  • ASP
  • ASP.NET
  • ISAPI Extensions
  • ISAPI Filters
  • IIS Management Console (optional)
  • IIS Management Scripts and Tools (optional)

Installing and Configuring Resin IIS Handler

  • Copy Resin.IIS.Handler.dll to web application's bin directory
  • Register the handler in ASP.NET web application config file
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"/>
       ...

Port 6800 is the default HMUX port used by Resin.

Resin IIS Handler accepts the following configuration parameters:

NAMEDESCRIPTIONDEFAULT
resin.serversSpace separated list of ip:port pairs to backend Resin servers e.g. '127.0.0.1:6800 127.0.0.1:6801' 127.0.0.1:6800
resin.log-levelLogging level: Information | Warning | Error | None Error
resin.session-cookieSession Cookie NameJSESSIONID
resin.ssl-session-cookieSecure Session Cookie NameSSLJSESSIONID
resin.sticky-sessionsUse sticky sessions for distributing requeststrue
resin.session-url-prefixprefix used to identifiy sessionid in urls;jsessionid=
resin.load-balance-connect-timeoutTimeout used with connect to backend5 sec.
resin.load-balance-idle-timeMaximum time to keep sockets to backend open5 sec.
resin.load-balance-recover-timeRetry period on failed backend server15 sec.
resin.socket-timeoutHow long to wait for a read or write operation to backend server to complete 65 sec.
resin.caucho-statusEnables or disables /caucho-status request. true

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>

Configuring using appcmd.exe configuration utility

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.

Assuming that we are working with the Default Web Site:

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

Specifying parameters using 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 & Logging with Resin IIS Handler

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

Resin IIS Handler Status

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.

Copyright © 1998-2012 Caucho Technology, Inc. All rights reserved.
Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.