<title css='default.css'>Caucho Servlet Engine on IIS</title>

<summarylist/>

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

<center>
<ct:img src='iis_srun.gif'/>
</center>

<p/>To configure Resin with IIS, you must follow the following steps:
<ol>
<li>Configure IIS/PWS
<li>Configure resin.conf
<li>Start httpd
</ol>

<section title='Configuring IIS/PWS'>

<subsection title='ISAPI Filter'>

<p/>You should use resin1.1/bin/setup.exe to setup your configuration.
If you use setup.exe, you can just skip to the next section.

<p/>However, if you need to know the steps involved:

<ol>
<li>Make sure httpd.exe works
<li>If you have a virtual site, you must have the virtual directory
<var//scripts/> point to <var/d:\inetpub\scripts/>
<li>Copy isapi_srun.dll to the IIS scripts directory, <var/d:\inetpub\scripts/>.
You may need to run <var/net stop w3svc/>.
<li>Create a resin.ini in <var/d:\inetpub\scripts/> pointing to the resin.conf.
<li>Configure IIS to load isapi_srun.dll as an ISAPI filter.
<li>Restart IIS (control panel/services) or <var/net stop w3svc/> followed
by <var/net start w3svc/>.
<li>Browse /servlet/Hello and /foo.jsp.
You should see a "cannot connect" error.
<li>Start httpd.exe
<li>Browse /servlet/Hello and /foo.jsp.  You should now see the servlet.
</ol>

<p/>Copying isapi_srun.dll to <var/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.

<p/>The resin.ini is an optional file in <var/inetpub/scripts/> to override the automatic registry
$RESIN_HOME/conf/resin.conf configuration file.
The resin.ini should contain the following line:
<example>
CauchoConfigFile d:/resin1.2/conf/resin.conf
</example>

<p/>Adding an ISAPI filter is accomplished in the IIS manager.
</subsection>

<subsection title='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.

<example>
&lt;caucho.com>
&lt;iis priority='high'/>

&lt;http-server>
 ...
&lt;/http-server>

&lt;caucho.com>
</example>

</subsection>

<subsection title='Configuring resin.conf'>

<p/>resin.conf should mirror the configuration of IIS.  In other words, you 
need to configure the document root and any directory aliases.

<p/>For many users, you only need to change the <var/app-dir/>
attribute from 'doc' to something like 'd:\inetpub\wwwroot'.  For more
complicated configurations, you'll need to add
<a href='app-config.xtp'>path-mapping</a> attributes.

<example title='resin.conf'>
&lt;caucho.com>
  &lt;http-server
      app-dir='d:\inetpub\wwwroot'>
    &lt;servlet-mapping url-pattern='/servlet/*'
              servlet-name='invoker'/>

    &lt;servlet-mapping url-pattern='*.xtp'
                        servlet-name='com.caucho.jsp.XtpServlet'/>
    &lt;servlet-mapping url-pattern='*.jsp'
                        servlet-name='com.caucho.jsp.JspServlet'/>
  &lt;/http-server>
&lt;/caucho.com>
</example>

</subsection>

<subsection title='Testing the servlet engine'>

<p/>From the Resin bin folder, you need to start httpd.exe to start the
servlet runner.

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

<p/>Create a test file 'd:\inetpub\wwwroot\test.jsp'

<example>
&lt;%@ page language=javascript %>
2 + 2 = &lt;%= 2 + 2 %>
</example>

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

<results>
2 + 2 = 4
</results>

<p/>As a final test, change language to 'java' and refresh the page.
Nothing should change.
</subsection>


<subsection title='Troubleshooting'>

<ol>
<li>First, check your configuration with the standalone httpd.sh.
In other words, add a &lt;http port='8080'/> block and
browse http://localhost:8080.
<li>Check <var/http://localhost/caucho-status/>.  That will tell if
the ISAPI filter/extension is properly installed. 
<li>Each srun host should be green and the mappings should
match your resin.conf.
<li>If caucho-status fails entirely, the problem is in the <var/isapi_srun/>
installation.  Try
<var/http://localhost/scripts/isapi_srun.dll/caucho-status/> directly
(bypassing the filter).  If this fails, IIS can't find isapi_srun.dll.
<ul>
<li>Check that isapi_srun.dll is in <var/c:\inetpub\scripts./>
<li>Make sure that your IIS host has a mapping from <var//scripts/>
to <var/c:\inetpub\scripts/> and that the <var//scripts/> has execute
permissions.
</ul>
<li>If you've created a new
IIS web site, you need to create a virtual directory <var//scripts/> pointing
to the <var/d:\inetpub\scripts/> directory.
<li>If caucho-status shows the wrong mappings, there's something wrong
with the resin.conf.
<li>If caucho-status shows a red servlet runner, then httpd.exe hasn't
properly started.
<li>If you get a "cannot connect to servlet engine", caucho-status
will show red, and httpd.exe hasn't started properly.
<li>If httpd.exe doesn't start properly, you should look at the logs
in resin2.0/log.  You should start <var/httpd.exe -verbose/> to get
more information.
<li>If you get Resin's file not found, the IIS configuration
is good but the resin.conf probably points to the wrong directories.
</ol>

</subsection>
</section>

<section title='Command line arguments'>

The following configuration line arguments are recognized by httpd.exe.
When installed as a service, these argument will be used when
the service starts.

<deftable>
<tr><td>-verbose<td>Write more verbose information to the log file
<tr><td>-resin_home &lt;path><td>Sets the location of Resin
<tr><td>-java_home &lt;path><td>Specify the JDK location
<tr><td>-msjava<td>Use Microsoft's JVM
<tr><td>-nojit<td>Disable JIT compilation to help debugging
<tr><td>-classpath &lt;cp><td>Add to the classpath
<tr><td>-J&lt;arg><td>Set a Java command line argument, e.g. -J-nojit.
<tr><td>-D&lt;foo=bar><td>Set a Java variable, e.g. -Dresin.home=here.
<tr><td>-install<td>Install as an NT service
<tr><td>-install-as &lt;name><td>Install as an NT service with the specific name.
<tr><td>-remove<td>Remove as an NT service
<tr><td>-remove-as &lt;name><td>Remove as an NT service with the specific name.
</deftable>

</section>

<subsection title='Deploying as an NT Service'>

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 automatically restart Resin if it
unexpectedly exits.

<p/>To install the service, use

<example>
dos> resin2.0/bin/httpd -install
</example>

<p/>To remove the service, use

<example>
dos> resin2.0/bin/httpd -remove
</example>

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

</subsection>

<a name='balance'/>
<section title='Load Balancing' version='Resin 1.2'>

In Resin 1.2, you can distribute requests to multiple machines.  All
requests in a 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.

<p/>In addition, you can specify backup machines.  The backup only will serve
requests if all primaries are down.

<p/>See the <a href='http-config.xtp'>http config</a> section for more
details.
<example title=resin.conf>
&lt;caucho.com>
&lt;http-server>
  &lt;srun id="a" host='host1' port='6802'/>
  &lt;srun id="b" host='host2' port='6802'/>
  &lt;srun-backup id="c" host='backup' port='6802'/>
  ...
&lt;/http-server>
&lt;/caucho.com>
</example>
</section>
