<document>
  <header>
    <product>resin</product>
    <resin-2.0>$resin/java_tut/linux-boot.xtp</resin-2.0>
    <title>How to start Resin when Linux Boots</title>
  </header>

  <body>
    <summary/>

<p><em>Thanks to Guy McArthur and Carlos Hanson for the examples and much
of the explanation for this tutorial.</em></p>

<section title="Modifying httpd.sh">

<p>The easiest way to start Resin when Linux boots is to modify your
httpd.sh and create symbolic link in /etc/rc.d/rc3.d and /etc/rc.d/rc5.d.
Because the boot process does not set environment variables, you'll need
to set them in the httpd.sh.</p>

<ol>
<li>Copy httpd.sh to "resin-a.sh" in resin/bin and change permissions.
<li>Configure JAVA_HOME, RESIN_HOME, PATH, and "-pid" in resin-a.sh.
<li>Check that "resin-a.sh start" and "resin-a.sh stop" work from the command line when running as root.
<li>"ln -s /usr/local/resin/bin/resin-a.sh /etc/rc.d/rc3.d/S86resin-a"
<li>"ln -s /usr/local/resin/bin/resin-a.sh /etc/rc.d/rc5.d/S86resin-a"
<li>"ln -s /usr/local/resin/bin/resin-a.sh /etc/rc.d/rc2.d/K14resin-a"
<li>Reboot to test.
</ol>

<p>A sample resin-a.sh might look like:</p>

<example>
#! /bin/sh
#
# ...
#
JAVA_HOME=/usr/java
export JAVA_HOME

RESIN_HOME=/usr/local/resin
export RESIN_HOME

PATH=/bin:/usr/bin:/usr/local/bin
export PATH

args="-Xms75M -Xmx100M start -pid $RESIN_HOME/resin-a.pid"
class=com.caucho.server.http.HttpServer
name=httpd

perl=/usr/local/bin/perl

exec $perl $RESIN_HOME/bin/wrapper.pl -chdir -name "$name" \
                                      -class "$class" $args $*
</example>

<p>An advantage of this method is that you can use the same script
to start and start the server interactively.</p>

</section>

<section title="Linux booting background">

<p>At startup, Linux runs the /etc/rc.d/rc script at the current runlevel
(normally 3 or 5).  All the Sxx scripts in /etc/rc.d/rc3.d/S*
are started in order.</p>

<example title="Fragment of the rc script">
for i in /etc/rc$runlevel.d/S*; do
  $i start
done
</example>

<p>So S86resin-a will be called as "S86resin-a start" as the root user.
Since the script can't assume any environment variables, it needs to set
them itself.</p>

<p>Since Resin is an application, as opposed to a system service, it
should be started late in the boot process.  S86 is a decent choice.  The
specific order only matters if your startup depends on another service.
For example, if you have a load-on-startup servlet that depends on a
database, the database should be S85 or lower.</p>

<p>Some configurations boot up in runlevel 3 and others boot
in runlevel 5.  The actual boot order will then be {1,2,3} or {1,2,5}.
A machine booting with runlevel 3 will have /etc/inittab with the following
line:</p>

<example title='/etc/inittab fragment'>
id:3:initdefault
</example>

<p>On server shutdown, Linux calls the scripts in /etc/rc.d/rc2.d/K*
in order.</p>

<example>
for i in /etc/rc$runlevel.d/K*; do
  $i stop
done
</example>

<p>In this case, Resin is an application, as opposed to a system service, it
should be killed early in the shutdown process.</p>

</section>

<section title="Alternatives">

<p>An alternative to modifying the httpd.sh is to create another script
that passes arguments to the original httpd.sh.</p>

<example>
#!/bin/sh 

# script name: resin 
# 
# start/stop script for Resin 

RESIN_HOME=/usr/resin 
JAVA_HOME=/usr/java/jdk1.3 
PATH="$PATH:/usr/java/jdk1.3/bin:/usr/X11R6/bin" 
export PATH JAVA_HOME RESIN_HOME 

${RESIN_HOME}/bin/httpd.sh -Xms75M -Xmx100M -java_home ${JAVA_HOME} "$*" 
</example>

<p>Guy McArthur writes</p>

<p>I find it a bit easier to edit wrapper.pl rather than creating a
script that passes in environment variables.   But that's just because
I'll be starting/stopping resin manually using httpd.sh to try
something out, so having that single point of control is good.</p>

<p>Carlos Hanson writes:</p>

<p>I originally started by editing wrapper.pl, but having a script
that passes the  necessary arguments to httpd.sh allows me to
reinstall or upgrade Resin more easily. All I have to worry about
is configuration files. This is important when dealing with developers new
to Unix and maintaining a large number of production and development
servers. We keep the script and the conf files in source control.</p>

</section>
  </body>
</document>
