<document>
<header>
  <product>resin</product>
  <title>Installation FAQ</title>
  <description>
  </description>
</header>

<body>
<summary objsummary='localtoc'/>

<faq title="Where can I put .jar files so that they are available to all of my web applications?">
<description>
I have some jar files that are used by all of my web applications.  Where
can I put them so that I do not have to put them in <code>WEB-INF/lib</code>
for every web application that I have?
</description>

<ol>

<li>Make the directory <code>$RESIN_HOME/lib/local/</code>

<li>Place the jars files that will be available to all of your web applications in <code>$RESIN_HOME/lib/local/</code>, for example  <code>$RESIN_HOME/lib/local/hogwarts.jar</code>

</ol>

<p>Any jar file in <code>$RESIN_HOME/lib</code> will be available to all of the
web applications.</p>

<p>Resin will also find jars in subdirectories, so you can put your jars in
for example <code>$RESIN_HOME/lib/local/hogwarts.jar</code>.  If you use the
<code>local/</code> subdirectory,  when you upgrade to a new version of Resin
you can just copy the local subdirectory over to the new
<code>$RESIN_HOME/lib</code>.</p>

</faq>

<faq title="What happened to bin/resin?">

<description>
With Resin 2.1 used to run <code>make; make install</code> and then use the binary <code>bin/resin</code> to start Resin, but in Resin 3.0 I can't find the binary.  What happened to it?
</description>

<p>Resin 2.1 used the <code>bin/resin</code> binary to enable two features: JNI
usage (including OpenSSL) and to support <a config-tag="user-name"/> and <a
config-tag="group-name"/> for switching the effective user id of the process
after attaching to ports under 1024.</p>

<p>
Resin now uses the JNI library from within Java.  You don't need
a compiled binary to get at the JNI code (that was bin/resin in
2.1.x).  So, the java process starts up and then hooks into the
JNI libraries.  Resin uses JNI for:
</p>

<ul>
<li>OpenSSL
<li>low level system calls, for things like socket connections etc.
  (for performance reasons).
</ul>

<p>So Resin can run without the JNI libraries, it just won't be as
Resin as Resin.</p>

<a config-tag="user-name">user-name</a> and <a config-tag="group-name">group-name</a> support no longer need the resin binary either. The only
place it won't work is on Linux systems that do not use the newer threading
model.  For those systems, you can use a technique like the one <a
href="How-can-I-bind-to-a-port-under-1024-and-still-run-as-a-non-root-user?">described
here.</a>

</faq>

<faq title="How can I bind to a port under 1024 and still run as a non-root user?">
<description>
I want to bind resin to port 80, but my operating system only allows
<var/root/> to bind to ports under 1024.  If I run Resin as <var/root/>, it is
a security risk.  How can I start Resin as <var/root/> but then change the user
and group id after it is bound to the port?
</description>

<p>Most Unix systems can simply use the <a config-tag="user-name"/> and <a config-tag="group-name"/> configuration tags.</p>

<p>New versions of Linux (with the new threading model) can also use
<a config-tag="user-name"/>, but using "/sbin/iptables" may be
a better solution.  The Linux iptables maps port 80 requests to port 8080.
This way, your Resin instance can start up as a normal user and listen
to port 8080 without needing to start as root.
</p>


<example title="Linux 2.2.x route port 80 to port 8080">
/sbin/ipchains -A input -i eth+ -j REDIRECT 8080 -p tcp --destination-port 80
</example>

<example title="Linux 2.4.x route port 80 to port 8080">
/sbin/iptables -t nat -A PREROUTING -i eth+ -p tcp --dport 80 -j REDIRECT --to-port 8080
</example>

</faq>

<faq name="multipleinstances" title="Can I run multiple instances of Resin on the same machine? ">
<description>
One instance is for production, one for deployment testing.
</description>

<p>
Yes, as long as you use different <code/http/> and <code/srun/> port numbers
(so they don't conflict). Also, don't point each instance at the same
<code>webapps/</code> directory, or the same directory for individual
web-app's.  The two instances will get confused about which is responsible for
things like JSP compilation etc.
</p>
</faq>

<faq name="cantconnecttoparent" title="Why do I get `can't connect to parent' after installing Resin?">
<description>
</description>

<p>
This problem is most often seen on Windows machines that you have a "personal"
firewall installed.  Examples of firewall programs are ZoneAlarm and Sygate
Personal Firewall.  The solution is to either reconfigure your firewall or turn
it off.
</p>

<p>
When Resin is started with <code>httpd.exe</code> (Windows) or
<code>httpd.sh/wrapper.pl</code> (Unix) httpd.exe or wrapper.pl is the parent
process that is ultimately in control of the java server. 
</p>

<p>
When the java server is started, it is passed a tcp port so
that the java process and the parent can communicate. This is done using the
-socketwait arg, if you want to browse the source. This port allows the parent
to indicate to the java server that it should stop. 
</p>

<p>
When the java server is started, if the -socketwait parameter is passed then
Resin will connect to the parent using the passed port number. It will try this
for fifteen seconds, if the connection cannot be made after that time it will
result in the "can't connect to parent" error. 
</p>

<p>
The error usually is seen on very slow or overloaded machines. It can also
happen (as mentioned above) because a firewall-type program is interfering with
the socket connection between the parent and the java process. 
</p>

<p>
If Resin is being started in an init script on *nix, you can put a sleep after
the call the httpd.sh to let Resin have a chance to startup before the next
initialization steps take up most of the CPU.
</p>
</faq>

<faq name="exception-type-connection" title="What happened to exception-type='connection'?">
<description>

<p>
In Resin 2.1 I used an <code>exception-type='connection'</code>
with <a config-tag="error-page"/> to specify the page to show when IIS or
Apache could not reach the backend Resin server, but that does not work any
more.
</p>

</description>

<p>
Resin 3.0 no longer uses the "connection" exception-type.
The isapi_srun or mod_caucho plugin, if it cannot contact the backend Resin
server, propogates a 503 error to IIS or Apache.  So you should be able to use
IIS or Apache to define custom error pages, and those will be used for your
error display.
</p>

<p>
The reason for this change is due to a change in the way plugins
work.  In versions prior to 3.0 the plugin reads  and parses the resin.conf
file.  In version 3.0, the plugin obtains configuration information from
the backend Resin server and no longer reads the resin.conf file.
So if the backend server is not available, the plugin cannot forward to an
error page specified in resin.conf because it does not read resin.conf.
</p>

<p>
You can use IIS or Apache to define the location of
custom error pages for the case where the backend server is down.
</p>

<example title="Specifying a 503 page with Apache - httpd.conf">
ErrorDocument 503 /error/serverDownError.shtml
</example>
</faq>

<faq name="iis-exe" title="IIS 6 will not serve .exe files">

<description>
<p>
Everything seems to work, except that for every file with a <code>.exe</code>
extension I get "HTTP 404 - File not found".
</p>
</description>

<p>(thanks to W Hall)</p>

<p>
When used with IIS, the isapi_srun.dll plugin will dispatch urls to Resin for
jsp's and servlets, but will leave static files for IIS.  So this is really an
IIS issue, Resin is not even trying to handle the url and IIS is failing to
serve the *.exe file.
 </p>

<p>
There is a setting in IIS that prevents .exe files from being
downloaded/launched. 
In  IIS (6.0) the setting is found in 
IIS | Default Website | Properties | Home Directory (tab) | Execute
Permissions (drop down) | 
Change from "Scripts and Executables" to "Scripts Only"
</p>

</faq>

</body>
</document>
