Install FAQ

Latest revision as of 19:42, 3 February 2008

Where can I put .jar files so that they are available to all of my web applications?

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 WEB-INF/lib for every web application that I have?

1. Make the directory $RESIN_HOME/ext-lib
2. Place the jars files that will be available to all of your web applications in $RESIN_HOME/ext-lib, for example $RESIN_HOME/extlib/hogwarts.jar

Any jar file in $RESIN_HOME/ext-lib will be available to all of the web applications.

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

Some jars are not classloader-aware (e.g. using static fields improperly). For those libraries, you will need to put them in $RESIN_HOME/ext-webapp-lib instead.

What happened to bin/resin?

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

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

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:

• OpenSSL
• low level system calls, for things like socket connections etc. (for performance reasons).
• setuid for unix
• profiling and heap analysis

So Resin can run without the JNI libraries, it just won't be as fast as Resin.

<user-name> and <group-name> support no longer need the resin binary either.

How can I bind to a port under 1024 and still run as a non-root user?

I want to bind resin to port 80, but my operating system only allows root to bind to ports under 1024. If I run Resin as root, it is a security risk. How can I start Resin as root but then change the user and group id after it is bound to the port?

Unix systems can simply use the <user-name> and <group-name> configuration tags. Although you will start the Resin watchdog process as root, the watchdog will change user ids before starting the Resin instance. So Resin always runs as the specified user-name.

Can I run multiple instances of Resin on the same machine?

One instance is for production, one for deployment testing.

Yes, as long as you use different http and server port numbers (so they don't conflict). Also, don't point each instance at the same webapps/ 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.

Why do I get 'can't connect to parent' after installing Resin?

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.

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

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.

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.

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.

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.

What happened to exception-type='connection'?

In Resin 2.1 I used an exception-type='connection' with <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.

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.

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.

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

Specifying a 503 page with Apache - httpd.conf

ErrorDocument 503 /error/serverDownError.shtml

How do I start automatically with Mac OS X?

(contributed by Rob Lockstone)

Resin can be configured to start automatically when the system boots up using StartupItems. Create a directory in /Library/StartupItems called "Resin". In that directory are two files:

/Library/StartupItems/Resin/Resin

#!/bin/sh

##
# Resin Application Server
##

. /etc/rc.common

JAVA_HOME=/Library/Java/Home
export JAVA_HOME
RESIN_HOME=/path/to/resin
export RESIN_HOME

StartService ()
{
 	ConsoleMessage "Starting Resin"
	$JAVA_HOME/bin/java -jar $RESIN_HOME/lib/resin.jar start
}

StopService ()
{
 	ConsoleMessage "Stopping Resin"
	$JAVA_HOME/bin/java -jar $RESIN_HOME/lib/resin.jar stop
}

RestartService ()
{
 	ConsoleMessage "Restarting Resin"
	$JAVA_HOME/bin/java -jar $RESIN_HOME/lib/resin.jar restart
}

RunService "$1"

The StartupParameters.plist file example above requires that the service named "Web Server", which is Apache, is started before Resin starts. If you run Resin standalone, remove that dependency.

Resin will start automatically when your system boots. You can stop, start and restart Resin using the following commands from a terminal:

sudo SystemStarter start Resin
sudo SystemStarter stop Resin
sudo SystemStarter restart Resin

Since Resin is started by root, consider using the <user-name> and <group-name> tags to change the effective user id of Resin:

resin.conf

<resin id="">
<cluster id="">

  <server-default>
    <user-name>nobody</user-name>
    <group-name>daemon</group-name>
  </server-default>

  ..
</cluster>
</resin>

For more info than you probably want to know about Mac OS X's boot process and startup items, see Apple's documentation.