What is watchcatd?

Watchcat is a neologism created by we inspired in watchdog. Watchcat is a software service that monitors processes. If a monitored process locks up, it is killed.

Why do I need a watchcat?

A bug or malicious attacks to machine can lock up a process, leading to a deadlock or an unexpected condition. For example: an Apache httpd with mod_(php|perl|lua|your_preferred_script_language) running a bad script. When the monitored process lock up, the watchcat helps killing him. It is the best thing to do.

You must notice that the process must want to be monitored, therefore it must be conscious about watchcat. Watchcat does nothing alone.

There is another use. If the watchcat is set to send a signal such as SIGALRM, SIGHUP, SIGUSR1 or SIGUSR2, it can be used as a timer.

How does watchcat deamon work?

Before starting a critical region, the process requires a cat to itself and stays sending heartbeat signals to its cat. If the timeout expires before the process sends the hearbeat signal, watchcatd sends a signal to the monitored process, normally SIGKILL.

Authors

Michel Machado
Andre Nathan

watchcatd copyright and license

watchcatd is licensed under the GNU General Public License (GPL).

libwcat is licensed under the GNU Library General Public License (LGPL).

Download

Source tarballs:

Mandrake RPMs (MDK 9.2):

Mandrake RPMs (MDK 10.0):

Dependencies

Libevent - an I/O notification library.

Programs using libwcat

mod_watchcat is a module developed to provide watchcatd-awareness to the Apache 2 webserver.
You can include yours here! Send us a e-mail (you can get it in map pages).

Instalation

As root, execute:

    useradd ?param_FIXME? ?home:/var/empty? watchcat
    cd /var
    mkdir empty
    chown root:root empty
    chmod 000 empty

To compile watchcatd, you need libevent installed. On RPM-based Linux ditributions, the -devel package will also be needed.

Configuration

File: /etc/watchcatd.conf, TODO: write more.

API

int cat_open(void);

Create a default cat. This function is the recomended way to create a new cat because it is designed to work on future versions without problems. The TTL (Time To Live) is started.

The others cat_openN functions create a cat with protocol version N. These functions can disappear in future versions or there can be more of them. Only use them if necessary.

Currently, there is only one protocol and cat_open is a alias to cat_open1(60, SIGKILL, NULL).

int cat_open1(int timeout, int signal, const char *info);

Create a cat with protocol version 1. This protocol allows a timeout setting in seconds, a signal to send when the timeout expires and a info field to register in log if timeout occurs.

Returns the cat handle (>= 0) or -1 on fail.

int cat_heartbeat(int cat);

Say hello to the cat. The TTL is reset to its initial value (timeout).

Returns zero on success and -1 on fail.

int cat_close(int cat);

Finishes the "cat".

Returns zero on success and -1 on fail.

Example

#include <watchcat.h>

int cat = cat_open();

while (1) {

    /*
     *  Make something in a short time.
     *  Typically, a short time is 10 seconds or less.
     */

    cat_heartbeat(cat);
}
cat_close(cat);