Resin with IIS Reference Page

resin Resin with IIS Reference Page

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

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

Copy Resin.IIS.Handler.dll to web application's bin directory
Register the handler in ASP.NET web application config file

<?xml version="1.0" encoding="UTF-8"?> <configuration> <system.webServer> <handlers> <add name="ResinHandlerFactory"  path="*"  verb="*"  type="Caucho.IIS.ResinHandlerFactory"  preCondition="integratedMode"/> </handlers> </system.webServer> <appSettings> <add key="resin.servers" value="127.0.0.1:6800"/>  <add key="resin.log-level" value="Information"/>  </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 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:

Name Description Default resin.servers Space 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-level Logging level: Information | Warning | Error | None Error resin.session-cookie Session Cookie Name JSESSIONID resin.ssl-session-cookie Secure Session Cookie Name SSLJSESSIONID resin.sticky-sessions Use sticky sessions for distributing requests true resin.session-url-prefix prefix used to identifiy sessionid in urls ;jsessionid= resin.load-balance-connect-timeout Timeout used with connect to backend 5 sec. resin.load-balance-idle-time Maximum time to keep sockets to backend open 5 sec. resin.load-balance-recover-time Retry period on failed backend server 15 sec. resin.socket-timeout How long to wait for a read or write operation to backend server to complete 65 sec. resin.caucho-status Enables 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:

<?xml version="1.0" encoding="UTF-8"?> <configuration> <system.webServer> <handlers> <add name="ResinHandlerFactory"  path="*"  verb="*"  type="Caucho.IIS.ResinHandlerFactory"  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"/>  <add key="resin.log-level" value="Information"/>  </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.

Assuming that we are working with the Default Web Site:

# 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:

# 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']

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.

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

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.

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.