<title>Installation</title>

<summarylist/>

<section title="All Plugins" name="plugin">

<subsection title="Apache/IIS can't contact servlet runner">

The particular error message is something like:

<def>
Cannot connect to servlet runner at localhost:6802
</def>

<p/>The servlet runner process needs to be started.  In resin1.1/bin
the srun executable will start the servlet runner.

<p/>The srun executable will start Java and wait for connections from the
web server.

</subsection>

<subsection title='I just get a 404 for JSP or Servlets!'>

<p/>Make sure you try the following:

<ol>
<li>First, check your configuration with the standalone httpd.
Both httpd and srun use the same configuration file, so the
results should be identical.
<li>Check http://localhost/caucho-status.  That will tell if
mod_caucho has properly read the resin.conf.
<li>The srun hosts should be green and the mappings should match your resin.conf.
<li>If caucho-status fails on Apache, the problem is in the
mod_caucho/iis_srun installation and the Apache httpd.conf.
<li>If caucho-status fails on IIS, try
http://localhost/scripts/iis_srun.dll/caucho-status directly.
If this fails, IIS can't find iis_srun.dll.  
<ul>
<li>Check that iis_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/>.
<li>Make sure that the <var//scripts/> has execute permissions.
</ul>
<li>If caucho-status shows the wrong mappings, there's something wrong
with the resin.conf or the pointer to resin.conf in httpd.conf.
<li>If caucho-status shows a red servlet runner, then httpd.sh hasn't
properly started.
<li>If you get a "cannot connect to servlet engine", caucho-status
will show red, and httpd hasn't started properly.
<li>If httpd doesn't start properly, you should look at the logs
in resin2.0/log.  You should start <var/httpd -verbose/> to get
more information.
<li>If you get Resin's file not found, the Apache configuration
is good but the resin.conf probably points to the wrong directories.
<li>If the error message is from Resin, your <var/app-dir/> is probably set
wrong.  Remember servlets belong in <var/"app-dir"/WEB-INF/classes/>.
</ol>

<p/>Before you ask any questions on the list, you should be able to
answer the following questions:

<ul>
<li>Does httpd standalone work?
<li>What does the /caucho-status show?
<li>Is the 404 coming from your web server or from Resin?
</ul>

<p/>If you don't answer these questions in your mail, the mail will
probably be ignored.

<p/><em>Victor A. Salaman</em> writes:

<p/>This may sound elementary... But check for these common pitfalls:

<ol>
<li>Check in your browser that it's not configured to use a proxy server..
and if it is, make it bypass local accesses or disable proxying altogether
(If you are using IE, just go to Tool/Options/Connection and at the bottom
you'll see the proxy stuff!

<li>Make you are running httpd.exe.... A lot of people try to use "srun.exe",
and this is just a servlet runner.... 

<li>Modify your resin.conf file and add this line right after "&lt;caucho.com>" 
        &lt;log id="/" href="stderr:"/>
</ol>	

<p/>After you do this, execute httpd.exe and see what pops up....

</subsection>

<subsection title="Apache/IIS doesn't pick up resin.conf changes">

For Resin 1.1, you need to restart Apache and IIS for them to pick up
any changes to the resin.conf.  Resin 1.2 picks up the changes
automatically.

</subsection>

<subsection title='browser returns test.jsp source'>

If you're running Resin with IIS or Apache, the web server might not
know how to handle *.jsp files.  On Apache, the httpd.conf needs to
add Resin.  On IIS, the IIS configuration needs to dispatch *.jsp
files to srun_iis.dll.

<p/>Both may need restarting to see the changes.

<p/>To test if this is the problem, stop the srun executable.  If you
browse http://localhost/test.jsp, you should get the 'Cannot connect
to servlet runner' message.

</subsection>

<subsection title='java.net.BindException'>

You'll get this exception if you try to start two Resin
instances using the same port.  You'll need to stop the first one.  Normally, httpd.sh stop or httpd.sh stop wil do the trick.

<p/>On Unix, the dramatic way of stopping Resin is to kill the wrapper.pl
script:

<example>
unix> ps auxw | grep wrapper.pl
ferg     1314   ...  perl resin/bin/wrapper.pl
ferg     1340   ...  grep wrapper.pl
unix> kill 1314
</example>

<p/>Because the 'ps' differs on different flavors of Unix, e.g. ps -ef,
you may need to consult 'man ps'.

</subsection>

<subsection title='File not found'>

The web server (IIS or Apache) and the servlet runner (srun), need to find the
web pages.  The resin.conf file configures srun.  You need to add a
'app-dir' property, to tell srun where to look for the root directory.

<example>
&lt;caucho.com>
  &lt;http-server app-dir='d:\InetPub\wwwroot'>
    &lt;servlet-mapping url-pattern='*.jsp'
      servlet-name='com.caucho.jsp.JspServlet'>
  &lt;/http-server>
&lt;/caucho.com>
</example>

</subsection>

<subsection title="Resin uses the wrong JDK version">

On Win32, Resin tries to find Java in the following
order:

<ul>
<li>The command-line argument, -java_home
<li>The environment variable JAVA_HOME
<li>The registry, using JavaSoft's CurrentVersion of the JDK.
<li>Following the PATH of the java executable.
</ul>

To find out which Java version Caucho JSP is using, use the
'-version' argument on the command line:

<def>
resin1.1> bin/httpd -version
</def>

</subsection>

<subsection title="How do I pass JVM arguments like -ms48m?">

You can pass them on the command line like: <var/-J-ms40m/>.  You don't need
to escape <var/-Dfoo=bar/>. If you're on Unix, you can also add them to httpd.sh in the <var/args/> variable. You may need to quote the assignment:

<example>
args="-J-ms40m -Dfoo=bar"
</example>

</subsection>

<subsection title="NoSuchMethodError: org.w3c.dom.Node: method =
getNamespaceURI()Ljava/lang/String; not found">

<p/>This is caused by an incompatibility in the XML libraries.  Resin's
XSL needs the XML DOM v2.  The dom.jar in resin1.2/lib implements that
interface.  Unfortunately, some JDKs and XML applications (e.g. JAXP)
put an obsolete XML API (DOM v1) in the system classpath,
overriding the newer DOM API.

<p/>You will need to look in your system classpath for the old DOM
implementation (likely jaxp.jar) and remove it.

</subsection>

</section>

<section title="IIS">

<subsection title="caucho-status fails on IIS">

<p/>Try looking at <var/http://localhost/scripts/iis_srun.dll/caucho-status/>.
If this fails, IIS can't use the iis_srun.dll plugin.  The problem is
probably one of the following:

<ul>
<li>iis_srun.dll isn't in <var/c:\inetpub\scripts/>.
<li>The IIS host is missing the <var//scripts/> virtual directory.
<li><var//scripts/> doesn't have proper execute permissions.
</ul>

Resin's IIS module needs the <var//scripts/> virtual directory to contain
iis_srun.dll.  If you create a new IIS virtual host, you must create a
<var//scripts/> virtual directory that points to <var/d:\inetpub\scripts/>.

<p/>When the Resin ISAPI filter detects a JSP page or servlet, it rewrites the
URL to <var//scripts/iis_srun.dll/test.jsp/>.  IIS will then execute
iis_srun.dll as an ISAPI extension.  If your virtual site is missing the
<var//scripts/> directory, IIS can't find the ISAPI extension.

</subsection>

<subsection title="How to use index.jsp as default document on IIS?">

Stefan Wesner writes,

<p/>Activating index.jsp as the default document is a matter of
configuration of
IIS.

<p/>On IIS4.0 you could the following steps:

<ol>
<li>Open the property dialog for the "Default Web Site" (or any other
Web-Site or VirtualDirectorx).

<li>Go to the "Home Directory" Tab for the Default Web Site" or the "Virtual
Directory" Tab for a virtual Directory.

<li>Select "Configuration"

<li>add an application mapping from .xtp and .jsp for your iis_srun.dll (I
use also PUT,DELETE exlusion like it is done for asp mappings but I do not
know why, just copied it)

Close this sub-dialog

<li>Select the "Documents" tab and add index.jsp and index.xtp to the list of
default documents.

<li>Try http://yourhost/
</ol>

</subsection>

</section>

<section title="Apache">

<subsection title="Apache won't start on Win32">

The error message might be something like:

<example>
"Syntax error on line 785 of
C:\PROGRA~1\APACHE~1\APACHE/conf/httpd.conf:
Cannot load c:\resin1.1\srun\win32-1.3.6\mod_caucho.dll into server:"
</example>

Usually, this is a path problem, for example, you may have
used "win-1.3.6" instead of "win32-1.3.6".

It will also happen if the dll is incompatible with the Apache version.
Apache 1.3.6 is compatible with Apache 1.3.9.  If you're using a different
version, send us a message and we'll make sure you get the right
compiled version.

</subsection>

<subsection title="Apache doesn't find my resin.conf">

On windows, the argument to <var/CauchoConfigFile/> should be enclosed in
quotes.  Also, since Apache treats '\' as an escape, you'll need
either to use forward slashes or double the backslashes.

</subsection>

<subsection title="mod_caucho caucho-status returns no data">

This may be due to an "EAPI" conflict.  If your Apache is compiled with
EAPI, but Resin is compiled without it, the mod_caucho may crash.

<p/>The Apache log will have lines like
<example>
[Tue Aug  8 15:33:24 2000] [notice] caught SIGTERM, shutting down
[Tue Aug  8 15:33:24 2000] [warn] Loaded DSO /etc/httpd/modules/mod_caucho.so
  uses plain Apache 1.3 API, this module might crash under EAPI! (please
  recompile it with -DEAPI)
</example>

<p/>Normally, the ./configure script can determine if EAPI is needed
automatically, but if it fails, you can run it as:

<example>
unix> ./configure --with-apache-eapi
</example>

</subsection>

<subsection title="Can I use mod_rewrite with Resin?">

Yes, but you need to make sure to use the passthrough flag so Resin can
get control after mod_rewrite.

<example>
RewriteEngine on
RewriteRule ^/hello.html$ /hello.jsp [L,PT]
</example>

</subsection>

</section>

<section title="Linux/Unix">

<subsection title="libcaucho.so not found">

<p/>libcaucho.so contains some small JNI routines for Unix.  It should be
compiled when you call configure; make.  For some reason, the JVM isn't
picking the library up.  You'll probably want to check LD_LIBRARY_PATH both
in your environment and in wrapper.pl.

<p/>For many sites, a missing libcaucho.so isn't a big deal.  It just
grabs some CPU statistics.  However, it also enabled the setuid needed by
user-name and group-name.  So if you're using user-name to change the
user from root, you'll need to get libcaucho.so running.

</subsection>

<subsection title="How do I install Resin as a Linux service?">

Stephen Kuo asks:

<p/>This should be a very basic question for those Linux guru.

<p/>In my Red Hat 6.2, I put the following line in the /etc/rc.d/rc.local file
to make Resin as a service:
<example>
/usr/local/resin1.1/bin/httpd.sh start
</example>

<p/>But when I reboot the system, Resin does not start up.

<p/>Guy Tal reponds:

<p/>You should also set your environment params in the rc file (when you
execute from the command line, they are ready from your own environment,
however rc files are run as root so these will not be set).
Add the following (with the appropriate settings for your own machine):

<example>
----------Snip----------
PATH=/usr/local/bin:/usr/bin:/bin
export PATH

JAVA_HOME=/usr/java
export JAVA_HOME

RESIN_HOME=/opt/resin1.1
export RESIN_HOME

CLASSPATH=/usr/java/jre/lib/rt.jar
CLASSPATH=$CLASSPATH:/opt/resin1.1/lib/resin.jar
CLASSPATH=$CLASSPATH:/opt/resin1.1/lib/jsdk22.jar
CLASSPATH=$CLASSPATH:/opt/resin1.1/lib/jdk12.jar
export CLASSPATH
----------Snip----------
</example>

<p/>You can also set those environment variables in the httpd.sh itself
or in the wrapper.pl.

</subsection>

</section>

