<document>
  <header>
    <product>resin</product>
    <title>Resin Watchdog</title>
    <type>contents</type>

    <description>
      <p>
      The Resin watchdog process monitors the Resin JVM instance
      restarting as necessary.
      </p>
    </description>
  </header>

<body>

<localtoc/>

<s1 title="Overview">
<figure src="startup-watchdog.png"/>
</s1>

<s1 title="Single Resin instance">

<example title="Example: conf/resin.conf">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="">

  &lt;server id="app-a" address="192.168.1.10" port="6800">
    &lt;watchdog-port>6700&lt;/watchdog-port>

    &lt;user-name>resin&lt;/user-name>
    &lt;group-name>resin&lt;/group-name>

    &lt;http port="80"/>
  &lt;/server>

  &lt;host id="">
    &lt;web-app id="" path="/var/www/htdocs"/>
  &lt;/host>

&lt;/cluster>
&lt;/resin>
</example>

</s1>

<s1 title="Single machine load balance with shared watchdog">

<p>When running multiple instances of Resin on the same
machine, one watchdog-manager typically handles all the instances.
The server id will select which instance to start or stop.</p>

<example title="Example: conf/resin.conf">
&lt;resin xmlns="http://caucho.com/ns/resin">

&lt;cluster id="app-tier">

  &lt;server-default>
    &lt;watchdog-port>6700&lt;/watchdog-port>

    &lt;user-name>resin&lt;/user-name>
    &lt;group-name>resin&lt;/group-name>
  &lt;/server-default>

  &lt;server id="app-a" address="192.168.1.10" port="6810"/>
  &lt;server id="app-b" address="192.168.1.10" port="6811"/>

  &lt;host id="">
    &lt;web-app id="" path="/var/www/htdocs"/>
  &lt;/host>

&lt;/cluster>

&lt;cluster id="web-tier">

  &lt;server-default>
    &lt;watchdog-port>6700&lt;/watchdog-port>

    &lt;user-name>resin&lt;/user-name>
    &lt;group-name>resin&lt;/group-name>
  &lt;/server-default>

  &lt;server id="web-a" address="192.168.1.10" port="6800">
    &lt;http port="80"/>
  &lt;/server>

  &lt;host id="">
    &lt;web-app id="">
      &lt;rewrite-redirect>
        &lt;load-balance regexp="" cluster="app-tier"/>
      &lt;/rewrite-redirect>
    &lt;/web-app>
  &lt;/host>

&lt;/cluster>

&lt;/resin>
</example>

</s1>

<s1 title="Single machine load balance with distinct watchdog">

<p>In some cases, it's best to let each Resin instance have its own
watchdog, for example when multiple users are sharing the same
machine.  Each &lt;server> block configures a separate &lt;watchdog-port>.
Because the watchdog will read the resin.conf and use the &lt;server> block
matching the <code>-server id</code> command-line argument, each watchdog
will start with it's own port.</p>

<example title="Example: conf/resin.conf">
&lt;resin xmlns="http://caucho.com/ns/resin">

&lt;cluster id="app-tier">

  &lt;server-default>
    &lt;user-name>resin&lt;/user-name>
    &lt;group-name>resin&lt;/group-name>
  &lt;/server-default>

  &lt;server id="app-a" address="192.168.1.10" port="6810">
    &lt;watchdog-port>6700&lt;/watchdog-port>

    &lt;http port="8080"/>
  &lt;/server>

  &lt;server id="app-b" address="192.168.1.10" port="6811">
    &lt;watchdog-port>6701&lt;/watchdog-port>

    &lt;http port="8081"/>
  &lt;/server>

  &lt;host id="">
    &lt;web-app id="" path="/var/www/htdocs"/>
  &lt;/host>

&lt;/cluster>

&lt;/resin>
</example>

<p>In the previous example, starting Resin with <code>-server app-a</code>
will start a watchdog at port 6700.  Starting Resin
with <code>-server app-b</code> will start the watchdog at port 6701.</p>

<example title="Example: starting app-b with watchdog-port=6701">
resin-3.1.x> java -jar lib/resin.jar -server app-b start
</example>

</s1>

<s1 title="ISP watchdog management">

<p>In a situation like an ISP, you may wish to have a separate
configuration file for the watchdog, which launches Resin instances
for different users.  In this case, you will want to make sure
the watchdog.conf is not readable by the users, and make sure to
set a management user (see <a href="resin-security.xtp">resin-security</a>).</p>

<p>The watchdog will launch the Resin instance with the given user as a
setuid.  It will also open any necessary protected ports, e.g. port 80.</p>

<example title="Example: /etc/resin/watchdog.conf">
&lt;resin xmlns="http://caucho.com/ns/resin">

&lt;management>
  &lt;user name="harry" password="MD5HASH=="/>
&lt;/management>

&lt;watchdog-manager>

  &lt;watchdog-default>
    &lt;jvm-arg>-Xmx256m&lt;/jvm-arg>
  &lt;/watchdog-default>

  &lt;watchdog id="user_1">
    &lt;user-name>user_1&lt;/user-name>
    &lt;group-name>group_1&lt;/group-name>

    &lt;resin-conf>/home/user_1/conf/resin.conf&lt;/resin-conf>
    &lt;resin-root>/home/user_1/www&lt;/resin-root>

    &lt;open-port address="192.168.1.10" port="80"/>
  &lt;/watchdog>

  ...

  &lt;watchdog id="user_n">
    &lt;user-name>user_n&lt;/user-name>
    &lt;group-name>group_n&lt;/group-name>

    &lt;resin-conf>/home/user_n/conf/resin.conf&lt;/resin-conf>
    &lt;resin-root>/home/user_n/www&lt;/resin-root>

    &lt;open-port address="192.168.1.240" port="80"/>
  &lt;/watchdog>

&lt;/watchdog-manager>

&lt;/resin>
</example>

</s1>

<s1 title="command-line">

<example title="Example: watchdog status">
resin-3.1.x> java -jar lib/resin.jar status

Resin/3.1.x status for watchdog at 127.0.0.1:6600

server '' : active
  password: missing
  user: ferg
  root: /home/test/resin/
  conf: /tmp/caucho/qa/cfg/resin.conf
</example>

<example title="Example: watchdog start">
resin-3.1.x> java -jar lib/resin.jar -conf conf/test.conf -server a start

Resin/3.1.x started -server 'a' for watchdog at 127.0.0.1:6700
</example>

<example title="Example: watchdog stop">
resin-3.1.x> java -jar lib/resin.jar stop

Resin/3.1.x started -server '' for watchdog at 127.0.0.1:6600
</example>

</s1>

<s1 title="Management/JMX">

<p>The watchdog publishes the watchdog instances to JMX with the JMX name
"resin:type=Watchdog,name=a".  With a JMX monitoring tool like jconsole,
you can view and manage the watchdog instances.</p>

</s1>

  </body>
</document>