<s1 title="Resin with IIS">

<summarylist/>

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

<figure src='iis_srun.gif'/>

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

<s2 title='Configuring IIS/PWS'>

<s3 title='ISAPI Filter'>

<p>You should use resin-2.1.0/bin/setup.exe to setup your configuration.
If you use setup.exe, you can just skip to the next section.</p>
</s3>

<s3 title='ISAPI Filter Priority'>

<p>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.
</p>

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

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

&lt;caucho.com>
</example>

</s3>

<s3 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>

<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.</p>

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

</s3>

<s3 title='Testing the servlet engine'>

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

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

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

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

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

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

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

</s2>

<s2 title='Command line arguments'>

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

<deftable>
<tr><th>Argument<th>Meaning
<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>-X&lt;arg><td>Set a Java -X command line argument, e.g. -Xms128m.
<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>

<s3 title='Memory Configuration'>

<p>Memory configuration is part of the JVM's arguments.  For most JVMs,
you can find the full list by starting "java -X".</p>

<deftable title='Memory Configuration'>
<tr><th>Argument<th>Meaning
<tr><td>-Xms&lt;size><td>Initial Java heap size, e.g. -Xms32m
<tr><td>-Xmx&lt;size><td>Maximum Java heap size, e.g. -Xmx128m
</deftable>

</s3>

</s2>

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

<p>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>

<p>To install the service, use</p>

<example>
dos> resin-2.1.0/bin/httpd -install
</example>

<p>To remove the service, use</p>

<example>
dos> resin-2.1.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.<p/>

<note>There is a bug in many JDKs which cause the JDK to exit when the
administrator logs out.  JDK 1.3 and later can avoid that bug if the
JDK is started with -Xrs. </note>

<example>
dos> resin-2.1.0/bin/httpd -install -Xrs
</example>

</s2>

<s2 name='balance' title='Load Balancing' version='Resin 1.2'>

<p>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>

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

<p>See the <a href='http-config.xtp'>http config</a> section for more
details.</p>

<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>
</s2>

<s2 title='Manual Configuration'>

<p>Experts may want to configure Resin/IIS by hand instead
of using the setup program.  If you need to know the steps involved:</p>

<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>(optional) 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>

<p>The resin.ini is an optional file in <var/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.</p>

<p>resin.ini is only needed if you have multiple Resin configuration
files for different IIS virtual hosts.</p>

<p>The resin.ini should contain the following line:</p>
<example>
CauchoConfigFile d:/resin2.0/conf/resin.conf
</example>

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

<s2 title='Troubleshooting'>

<ol>
<li>Check your configuration with the standalone bin/httpd.
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>

</s2>
</s1>