Watchdog

From Resin 3.0

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

   <description>

For reliability and security, Resin servers are started and monitored by a separate Resin watchdog process. The watchdog continually checks the health of the Resin server and restarts the Resin instance if is becomes unresponsive.

In most cases, the watchdog reads the resin.xml and configures itself automatically, so no extra configuration is required. Certain specialized configurations like ISPs can configure the watchdog to isolate JVMs for protection and security.

   </description>
 </header>

<body>

Because the watchdog runs quietly as a separate service, most of the time you won't need to pay attention to the watchdog at all. The standard configuration launches on watchdog per machine which monitors all the Resin JVMs on that matchine, so most sites will not need to change any watchdog configuration.

The main management tasks where you might need to pay attention to the watchdog is shutting it down if something is severely wrong with the machine, and checking the watchdog logs for Resin restart events.

The watchdog automatically restarts Resin if the Resin JVM ever crashes or exits. So if you want to stop Resin, you need to tell the watchdog to stop the instance, or you can stop the watchdog entirely. The watchdog is typically controlled by the resin.jar main program (ResinBoot), which has commands to start, stop, and restart Resin instances as well as reporting the watchdog status.

While most users will use the watchdog automatically with no extra configuration, ISPs and larger and complicated sites can create a specialised watchdog.xml with a <watchdog-manager> tag to control the watchdog at a much finer level. The <watchdog-manager> lets an ISP run the watchdog under its own control, and specify exactly the command-line parameters for their users' Resin instances, including the ability to create secure chroot instances for their users. Typically, the watchdog will run as root, while the user instances will run with their respective user ids.

</s1>

The watchdog is controlled on the command-line using resin.jar's main class, ResinBoot. The major operations are: start, stop, restart, shutdown and status.

The "console" command starts a new Resin instance in a console window for development. The standard output of the Resin instance will appear in the console window.

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

</s2>

The "start" command starts a new Resin instance with the given server id. ResinBoot will first try to contact the watchdog on the current machine, and start a new watchdog if necessary. The server id must be unique for all servers defined in the resin.xml.

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

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

</s2>

The "stop" command stops the Resin instance with the given server id. If the stopped instances is the last one managed by the watchdog, the watchdog will automatically exit. If no -server is specified, the watchdog defaults to -server "".

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

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

</s2>

The "status" command summarizes the current Resin instances managed by the watchdog service.

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

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

server : active

 password: missing
 user: ferg
 root: /home/test/resin/
 conf: /etc/resin/resin.xml

</example>

</s2>

</s1>

This example shows a single-server site listening to the standard HTTP port 80 and running the server as the "resin" user. In this example, the watchdog typically runs as root so it can bind to the protected port 80, while the Resin instance runs as "resin" for security.

Since this configuration uses the default, the watchdog listens to port 6600 for commands.

<example title="Example: /etc/resin/resin.xml"> <resin xmlns="http://caucho.com/ns/resin"

      xmlns:resin="urn:java:com.caucho.resin">

 <server id="app-a" address="127.0.0.1">
   <user-name>resin</user-name>
   <group-name>resin</group-name>

   <http port="80"/>
 </server>

 <resin:import path="${__DIR__}/app-default.xml"/>

 <host id="">
   <web-app id="" path="/var/www/htdocs"/>
 </host>

</cluster> </resin> </example>

</s1>

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.

In this example, there is one web-tier server acting as a load-balancer and two app-tier servers handling the backend data, all on a single machine. A site might want multiple app-tier servers for more reliable maintenance and upgrades. While one server is down, traffic can be handled by a second server.

The example uses default watchdog configuration from the standard resin.xml file. The watchdog process and ResinBoot will both read the resin.xml file for the server configuration, so there's no explicit watchdog configuration necessary. The watchdog detects that multiple servers are running on the same machine and manages all of them automatically.

<example title="Example: /etc/resin/resin.xml"> <resin xmlns="http://caucho.com/ns/resin"

      xmlns:resin="urn:java:com.caucho.resin">

 <server-default>
   <user-name>resin</user-name>
   <group-name>resin</group-name>
 </server-default>

 <server id="app-a" address="192.168.1.10" port="6810"/>
 <server id="app-b" address="192.168.1.10" port="6811"/>

 <host id="">
   <web-app id="" path="/var/www/htdocs"/>
 </host>

</cluster>

 <server-default>
   <user-name>resin</user-name>
   <group-name>resin</group-name>
 </server-default>

 <server id="web-a" address="192.168.1.10" port="6800">
   <http port="80"/>
 </server>

 <host id="">

    <resin:LoadBalance regexp="" cluster="app-tier"/>

 </host>

</cluster>

</resin> </example>

</s1>

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 <server> block configures a separate <watchdog-port>. Because the watchdog will read the resin.xml and use the <server> block matching the -server id command-line argument, each watchdog will start with it's own port.

 <server-default>
   <user-name>resin</user-name>
   <group-name>resin</group-name>
 </server-default>

 <server id="app-a" address="192.168.1.10" port="6810">
   <watchdog-port>6700</watchdog-port>

   <http port="8080"/>
 </server>

 <server id="app-b" address="192.168.1.10" port="6811">
   <watchdog-port>6701</watchdog-port>

   <http port="8081"/>
 </server>

 <host id="">
   <web-app id="" path="/var/www/htdocs"/>
 </host>

</cluster>

</resin> </example>

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

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

</s1>

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.xml is not readable by the users, and make sure to set a management user (see <a href="security.xtp">resin-security</a>).

Start and restart the user's Resin JVM
Set JVM parameters and Java executable
Set the Resin instance root-directory
setuid user-name and group-name
Set the resin.xml configuration (must be readable by the user)
Open protected ports like port 80
Optional chroot for additional security

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.

<example title="Example: /etc/resin/watchdog.xml"> <resin xmlns="http://caucho.com/ns/resin"

      xmlns:resin="urn:java:com.caucho.resin">

<resin:AdminAuthenticator>

 <user name="harry" password="MD5HASH=="/>

</resin:AdminAuthenticator>

<watchdog-manager>

 <watchdog-default>
   <jvm-arg>-Xmx256m</jvm-arg>
 </watchdog-default>

 <watchdog id="user_1">
   <user-name>user_1</user-name>
   <group-name>group_1</group-name>

   <resin-xml>/home/user_1/conf/resin.xml</resin-conf>
   <resin-root>/home/user_1/www</resin-root>

   <open-port address="192.168.1.10" port="80"/>
 </watchdog>

...

 <watchdog id="user_n">
   <user-name>user_n</user-name>
   <group-name>group_n</group-name>

   <resin-conf>/home/user_n/conf/resin.xml</resin-conf>
   <resin-root>/home/user_n/www</resin-root>

   <open-port address="192.168.1.240" port="80"/>
 </watchdog>

</watchdog-manager>

</resin> </example>

</s1>

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.

</s1>

 </body>

</document>

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

   <description>

For reliability and security, Resin servers are started and monitored by a separate Resin watchdog process. The watchdog continually checks the health of the Resin server and restarts the Resin instance if is becomes unresponsive.

In most cases, the watchdog reads the resin.xml and configures itself automatically, so no extra configuration is required. Certain specialized configurations like ISPs can configure the watchdog to isolate JVMs for protection and security.

   </description>
 </header>

<body>

Because the watchdog runs quietly as a separate service, most of the time you won't need to pay attention to the watchdog at all. The standard configuration launches on watchdog per machine which monitors all the Resin JVMs on that matchine, so most sites will not need to change any watchdog configuration.

The main management tasks where you might need to pay attention to the watchdog is shutting it down if something is severely wrong with the machine, and checking the watchdog logs for Resin restart events.

The watchdog automatically restarts Resin if the Resin JVM ever crashes or exits. So if you want to stop Resin, you need to tell the watchdog to stop the instance, or you can stop the watchdog entirely. The watchdog is typically controlled by the resin.jar main program (ResinBoot), which has commands to start, stop, and restart Resin instances as well as reporting the watchdog status.

While most users will use the watchdog automatically with no extra configuration, ISPs and larger and complicated sites can create a specialised watchdog.xml with a <watchdog-manager> tag to control the watchdog at a much finer level. The <watchdog-manager> lets an ISP run the watchdog under its own control, and specify exactly the command-line parameters for their users' Resin instances, including the ability to create secure chroot instances for their users. Typically, the watchdog will run as root, while the user instances will run with their respective user ids.

</s1>

The watchdog is controlled on the command-line using resin.jar's main class, ResinBoot. The major operations are: start, stop, restart, shutdown and status.

The "start" command starts a new Resin instance with the given server id. ResinBoot will first try to contact the watchdog on the current machine, and start a new watchdog if necessary. The server id must be unique for all servers defined in the resin.xml.

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

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

</s2>

The "stop" command stops the Resin instance with the given server id. If the stopped instances is the last one managed by the watchdog, the watchdog will automatically exit. If no -server is specified, the watchdog defaults to -server "".

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

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

</s2>

The "status" command summarizes the current Resin instances managed by the watchdog service.

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

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

server : active

 password: missing
 user: ferg
 root: /home/test/resin/
 conf: /etc/resin/resin.xml

</example>

</s2>

</s1>

This example shows a single-server site listening to the standard HTTP port 80 and running the server as the "resin" user. In this example, the watchdog typically runs as root so it can bind to the protected port 80, while the Resin instance runs as "resin" for security.

Since this configuration uses the default, the watchdog listens to port 6600 for commands.

 <server id="app-a" address="127.0.0.1">
   <user-name>resin</user-name>
   <group-name>resin</group-name>

   <http port="80"/>
 </server>

 <resin:import path="${resin.home}/conf/app-default.xml"/>

 <host id="">
   <web-app id="" path="/var/www/htdocs"/>
 </host>

</cluster> </resin> </example>

</s1>

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.

In this example, there is one web-tier server acting as a load-balancer and two app-tier servers handling the backend data, all on a single machine. A site might want multiple app-tier servers for more reliable maintenance and upgrades. While one server is down, traffic can be handled by a second server.

The example uses default watchdog configuration from the standard resin.xml file. The watchdog process and ResinBoot will both read the resin.xml file for the server configuration, so there's no explicit watchdog configuration necessary. The watchdog detects that multiple servers are running on the same machine and manages all of them automatically.

 <server-default>
   <user-name>resin</user-name>
   <group-name>resin</group-name>
 </server-default>

 <server id="app-a" address="192.168.1.10" port="6810"/>
 <server id="app-b" address="192.168.1.10" port="6811"/>

 <host id="">
   <web-app id="" path="/var/www/htdocs"/>
 </host>

</cluster>

 <server-default>
   <user-name>resin</user-name>
   <group-name>resin</group-name>
 </server-default>

 <server id="web-a" address="192.168.1.10" port="6800">
   <http port="80"/>
 </server>

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

</cluster>

</resin> </example>

</s1>

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 <server> block configures a separate <watchdog-port>. Because the watchdog will read the resin.xml and use the <server> block matching the -server id command-line argument, each watchdog will start with it's own port.

 <server-default>
   <user-name>resin</user-name>
   <group-name>resin</group-name>
 </server-default>

 <server id="app-a" address="192.168.1.10" port="6810">
   <watchdog-port>6700</watchdog-port>

   <http port="8080"/>
 </server>

 <server id="app-b" address="192.168.1.10" port="6811">
   <watchdog-port>6701</watchdog-port>

   <http port="8081"/>
 </server>

 <host id="">
   <web-app id="" path="/var/www/htdocs"/>
 </host>

</cluster>

</resin> </example>

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

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

</s1>

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.xml is not readable by the users, and make sure to set a management user (see <a href="resin-security.xtp">resin-security</a>).

Start and restart the user's Resin JVM
Set JVM parameters and Java executable
Set the Resin instance root-directory
setuid user-name and group-name
Set the resin.xml configuration (must be readable by the user)
Open protected ports like port 80
Optional chroot for additional security

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.

 <user name="harry" password="MD5HASH=="/>

</management>

<watchdog-manager>

 <watchdog-default>
   <jvm-arg>-Xmx256m</jvm-arg>
 </watchdog-default>

 <watchdog id="user_1">
   <user-name>user_1</user-name>
   <group-name>group_1</group-name>

   <resin-xml>/home/user_1/conf/resin.xml</resin-conf>
   <resin-root>/home/user_1/www</resin-root>

   <open-port address="192.168.1.10" port="80"/>
 </watchdog>

...

 <watchdog id="user_n">
   <user-name>user_n</user-name>
   <group-name>group_n</group-name>

   <resin-conf>/home/user_n/conf/resin.xml</resin-conf>
   <resin-root>/home/user_n/www</resin-root>

   <open-port address="192.168.1.240" port="80"/>
 </watchdog>

</watchdog-manager>

</resin> </example>

</s1>

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.

</s1>

 </body>

</document>

Watchdog

From Resin 3.0

Views

Personal tools

Navigation

Search

Toolbox