What is watchcatd?

Watchcat is a neologism we created inspired by 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 locks 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 for watchcat: ff it 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).

Copyright (c) 2004-2014 Digirati.

Download

To install, simply type make and then make install. The default installation prefix is /usr/local. You can change this by setting the PREFIX environment variable before running make, as in env PREFIX=/my/watchcat/prefix make.

Note: Watchcat's current version is 1.2.1, while libwcat's is 1.1. These add support for FreeBSD, and also change the default path of the watchcat device from /dev/watchcat to /var/run/watchcat.socket. Therefore, to use the latest version of watchcatd, you'll also need to install the latest libwcat.

Source tarballs:

• watchcatd-1.3.1.tar.gz
• libwcat-1.1.tar.gz

Installation on Debian and Ubuntu can be done directly from their official package repositories.

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);