Resin provides a fast servlet runner for IIS and PWS, allowing IIS
to run servlets and JSP files.
If you have not yet done so, we suggest you use the Resin standalone web server option
first.
Resin requires a 1.4 JDK. You can download one from Sun and install it.
The Control Panel is used to configure two environment variables:
JAVA_HOME=C:\j2sdk1.4.2
RESIN_HOME=C:\resin-3.0
|
To configure Resin with IIS, you must follow the following steps:
- Configure IIS/PWS
- Configure resin.conf
- Start httpd
You should run RESIN_HOME/bin/setup.exe to setup your
configuration. If setup.exe is not used, or it fails, the steps in Manual Configuration are necessary.
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.
resin.ini
ResinConfigServer localhost 6802
CauchoStatus yes
IISPriority high
|
resin.conf should mirror the configuration of IIS. In other words, you
need to configure the document root and any directory aliases.
For many users, the only need to change needed in Resin is to change the
<document-directory> attribute from 'webapps/ROOT' to something
like 'C:/inetpub/wwwroot'. The mapping of url paths from the browser to real
files on the disk must be the same for Resin as they are for IIS. For more
complicated configurations that use mappings in IIS, you'll need to add path-mapping attributes
to match.
resin.conf
<!-- configures the default host, matching any host name -->
<host id=''>
<!-- configures the root web-app -->
<web-app id='/'>
<document-directory>C:/inetpub/wwwroot</document-directory>
<!-- adds xsl to the search path -->
<class-loader>
<simple-loader path="$host-root/xsl"/>
</class-loader>
</web-app>
</host>
|
From a cmd shell run RESIN_HOME/httpd.exe to start the
servlet runner.
Run httpd.exe
C:\> cd %RESIN_HOME%
C:\resin-3.0> cd bin
C:\resin-3.0> httpd.exe
|
Now browse http://localhost/test.jsp. You should get a 'file not
found' message.
Create a test file 'd:\inetpub\wwwroot\test.jsp'
Browse http://localhost/test.jsp again. You should now get
The following configuration line arguments are recognized by httpd.exe.
When command line arguments are used along with -install to
install as a service, the arguments are used each time the service starts.
Argument | Meaning
|
-verbose | Write more verbose information to the log file
|
-resin_home <path> | Sets the location of Resin
|
-java_home <path> | Specify the JDK location
|
-msjava | Use Microsoft's JVM
|
-nojit | Disable JIT compilation to help debugging
|
-classpath <cp> | Add to the classpath
|
-J<arg> | Set a Java command line argument, e.g. -J-nojit.
|
-X<arg> | Set a Java -X command line argument, e.g. -Xms128m.
|
-D<foo=bar> | Set a Java variable, e.g. -Dresin.home=here.
|
-install | Install as an NT service
|
-install-as <name> | Install as an NT service with the specific name.
|
-remove | Remove as an NT service
|
-remove-as <name> | Remove as an NT service with the specific name.
|
Memory configuration is part of the JVM's arguments. For most JVMs,
you can find the full list by starting "java -X".
Memory Configuration
Argument | Meaning
|
-Xms<size> | Initial Java heap size, e.g. -Xms32m
|
-Xmx<size> | Maximum Java heap size, e.g. -Xmx128m
|
-Xms<size> | the size of the heap for the young generation
|
See Performance : JVM Tuning : Memory for more information on JVM memory usage.
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 also automatically restart Resin if it
unexpectedly exits.
To install the service, use
win> resin-3.0.x/httpd -install
|
To remove the service, use
win> resin-3.0.x/httpd -remove
|
You will either need to reboot the machine or start the service
from the Control Panel/Services panel to start the server. On a
machine reboot, NT will automatically start the servlet runner.
Note: There is a bug in many JDKs which cause the JDK to exit when the
administrator logs out. JDK 1.4 and later can avoid that bug if the
JDK is started with -Xrs.
win> resin-3.0.x/httpd -install -Xrs
|
With Resin, you can distribute requests to multiple machines. All
requests with the same 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.
In addition, you can specify backup machines. The backup only will serve
requests if all primaries are down.
See the Resin config section for more
details.
resin.conf
<resin xmlns="http://caucho.com/ns/resin">
<server>
<cluster>
<srun id="a" host="host1" port="6802" index="1"/>
<srun id="b" host="host2" port="6802" index="2"/>
<srun id="c" host="backup" port="6802" index="3" backup="true"/>
...
</server>
</resin>
|
installing multiple servlet runners as services
win> resin-3.0.x/httpd -install-as "Resin-A" -server a -Xrs
win> resin-3.0.x/httpd -install-as "Resin-B" -server b -Xrs
win> resin-3.0.x/httpd -install-as "Resin-C" -server c -Xrs
|
Experts may want to configure Resin/IIS by hand instead
of using the setup program. The steps involved are:
- Make sure httpd.exe works
- Copy isapi_srun.dll to the IIS scripts directory, d:\inetpub\scripts.
You may need to run net stop w3svc to get permission to overwrite the file.
- If you have a virtual site (virtual hosts), you must configure IIS to have
the virtual directory /scripts point to d:\inetpub\scripts for
each virtual site.
- (optional) Create a resin.ini in d:\inetpub\scripts pointing to the ResinConfigServer
- (optional) Add a "CauchoStatus yes" line to the resin.ini for debugging
- Configure IIS to load isapi_srun.dll as an ISAPI filter.
- Restart IIS (control panel/services) or net stop w3svc followed
by net start w3svc.
- Browse /servlet/Hello and /foo.jsp.
You should see a "cannot connect" error.
- Start httpd.exe
- Browse /servlet/Hello and /foo.jsp. You should now see the servlet.
Copying isapi_srun.dll to 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.
The resin.ini is an optional file in 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.
resin.ini is only needed if you have multiple Resin configuration
files for different IIS virtual hosts.
The resin.ini should contain the following line:
ResinConfigServer localhost 6802
|
You can change the host from localhost to a backend server.
You can also add multiple ResinConfigServer items to cluster the
configuration.
For debugging, you can add a "CauchoStatus yes" line to the resin.ini:
ResinConfigServer localhost 6802
CauchoStatus yes
|
For security purposes, the default value of CauchoStatus is "no" when
you have a resin.ini.
Adding an ISAPI filter is accomplished in the IIS manager.
When Resin and IIS are on different machines, you'll change
the ResinConfigServer from "localhost" to the IP address of the
Resin server.
ResinConfigServer 192.168.0.10 6802
CauchoStatus yes
|
If IIS is managing multiple virtual sites (everyone else calls them virtual
hosts), then you need to configure IIS to use the isapi_srun.dll filter for
each virtual site. Configure IIS to have the virtual directory /scripts
for each virtual site point to d:\inetpub\scripts, so that each virtual site uses the isapiu_srun.dll.
Resin is configured to recognize virtual hosts with the id attribute
of <host> .
resin.conf with virtual hosts
<resin xmlns="http://caucho.com/ns/resin">
...
<server>
...
<host id="foo.com">
...
</host>
<host id="bar.com">
...
</host>
<host id="baz.com">
...
</host>
</server>
</resin>
|
Resin recognizes which host to use by examing the url. With the above
example, a url of http://foo.com/some/path will use host
id="foo.com" and a url of http://bar.com/some/path
will use host id="bar.com".
If a seperate JVM for each virtual site is desired, a seperate
resin.ini is used for each virtual site. The resin.ini file is placed
in the scripts directory.
resin-foo.conf
<resin xmlns="http://caucho.com/ns/resin">
<server>
<cluster>
<srun port="6802"/>
</cluster>
...
<host id="*">
...
</host>
</server>
</resin>
|
resin-bar.conf
<resin xmlns="http://caucho.com/ns/resin">
<server>
<cluster>
<srun port="6803"/>
</cluster>
...
<host id="*">
...
</host>
</server>
</resin>
|
installing a servlet runner for each virtual site
win> resin-3.0.x/httpd -install-as "Resin-foo" -conf resin-foo.conf -Xrs
win> resin-3.0.x/httpd -install-as "Resin-bar" -conf resin-bar.conf -Xrs
|
resin.ini for IIS virtual site foo.com
ResinConfigServer localhost 6802
|
resin.ini for IIS virtual site bar.com
ResinConfigServer localhost 6803
|
The ResinConfigServer tells the isapi_srun.dll the port number to use to
connect to the Resin instance. You can change the host from localhost
to a backend server. You can also add multiple ResinConfigServer items
to cluster the configuration.
resin-foo.conf and resin-bar.conf contain a <host id="*">, you do not
need to specify the host name because each conf/JVM is only going to
receive requests from a particular virtual site (because of the unique
resin.ini files).
- Check your configuration with the standalone web server.
In other words, add a <http port='8080'/> block and
browse http://localhost:8080.
- Check http://localhost/caucho-status. That will tell if
the ISAPI filter/extension is properly installed.
- Each srun host should be green and the mappings should
match your resin.conf.
- If caucho-status fails entirely, the problem is in the isapi_srun
installation. Try
http://localhost/scripts/isapi_srun.dll/caucho-status directly
(bypassing the filter). If this fails, IIS can't find isapi_srun.dll.
- Check that isapi_srun.dll is in c:\inetpub\scripts.
- Make sure that both IIS and the underlying NTFS file system have permissions set appropriately for isapi_srun.dll.
- Make sure that your IIS host has a mapping from /scripts
to c:\inetpub\scripts and that the /scripts has execute
permissions.
- IIS 6 users may need to take additional steps.
- If you've created a new
IIS web site, you need to create a virtual directory /scripts pointing
to the d:\inetpub\scripts directory.
- If caucho-status shows the wrong mappings, there's something wrong
with the resin.conf.
- If caucho-status shows a red servlet runner, then httpd.exe hasn't
properly started.
- If you get a "cannot connect to servlet engine", caucho-status
will show red, and httpd.exe hasn't started properly.
- If httpd.exe doesn't start properly, you should look at the logs
in resin3.0/log. You should start httpd.exe -verbose to get
more information.
- If you get Resin's file not found, the IIS configuration
is good but the resin.conf probably points to the wrong directories.
IIS 6/Windows 2003 users may need to perform additional steps.
- Make sure that the System account has suffiicient privleges to
read the C:\InetPub and C:\InetPub\Scripts directory
and the isapi_srun.dll.
- Check the `Web Service Extensions' listed in the `Internet Service Manager'
to make sure that Resin is listed as a Web Service Extension and has a status
of "enabled". You may need to click "add a new web service extension...",
under Extension name add .jsp or whatever your file extension is,
click Add and browse to the isapi_srun.dll, check the "Set extension status
to allowed box", click OK.
- Check that the user specified as the
"application pool identity" for Resin has read/write
permission to the Resin installation directory.
In the Internet Service Manager, open the Properties dialog for
"Application Pools". Find the User on the "Identity" tab, it may
be the user named "Network Service" in the drop-down list associated
with the radio button labeled "predefined".
Then check physical file permissions on the Resin installation
directory and all its subdirectories and subfiles, to ensure that
that user has read/write permission status is "Enabled".
Copyright © 1998-2005 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark,
and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc. | |
|