Mod-Gearman Quickstart Guide
============================

This quickstart guide was written for Debian Lenny (5.0) but probably works with
different Linux systems too.  As there are currently no packages for Gearman
and Mod-Gearman, we have to install them from source. 

This guide assumes you have a basic nagios system running.

All commands  have to be executed as root.


Build Preparation
-----------------
We need a couple of packages for building Gearman and Mod-Gearman:
--------------------------------------
#> apt-get update
#> apt-get install autoconf automake make gcc g++ wget tar file netcat uuid-dev libltdl3-dev libncurses5-dev libevent-dev
--------------------------------------

We will install Gearman in '/opt' to make later removal easier. For example if
there will be a Debian package sometimes. This keeps your base system clean from
non-packaged software, but in order to make that work, we have to add '/opt/lib' to
the ld lib path.

--------------------------------------
#> echo "/opt/lib" > /etc/ld.so.conf.d/opt_lib.conf
#> ldconfig
--------------------------------------


Install Gearman
---------------
We need at least Gearman version >= 0.14. Execute the following steps to
install Gearman from source.

--------------------------------------
#> cd /tmp
#> wget "http://launchpad.net/gearmand/trunk/0.14/+download/gearmand-0.14.tar.gz"
#> tar zxf gearmand-0.14.tar.gz
#> cd gearmand-0.14
#> ./configure --prefix=/opt
#> make
#> make install
--------------------------------------


Mod-Gearman
-----------

Half way done, the next step installs Mod-Gearman.

--------------------------------------
#> cd /tmp
#> wget "http://labs.consol.de/wp-content/uploads/2010/09/mod_gearman-1.0.10.tar.gz"
#> tar zxf mod_gearman-1.0.10.tar.gz
#> cd mod_gearman-1.0.10
#> ./configure --prefix=/opt --with-gearman=/opt --with-user=nagios --with-init-dir=/etc/init.d
#> make
#> make install
#> make install-config
#> cp ./extras/gearmand-init /etc/init.d/gearmand
--------------------------------------


Nagios
------

We need a nagios installation if not already installed.
--------------------------------------
#> apt-get install nagios3
--------------------------------------

Gearman runs as user nagios which needs a valid shell:

--------------------------------------
#> chsh nagios
Changing the login shell for nagios
Enter the new value, or press ENTER for the default
        Login Shell [/bin/false]: /bin/bash
--------------------------------------


Starting Up
-----------
Now we can start the Gearman daemon and our Mod-Gearman worker:

--------------------------------------
#> /etc/init.d/gearmand start
Starting gearmand done
#> /etc/init.d/gearmand status
gearmand is running with pid 31869
#> /etc/init.d/mod_gearman_worker start
Starting mod_gm_worker done
#> /etc/init.d/mod_gearman_worker status
mod_gm_worker is running with pid 31939
--------------------------------------


Nagios Configuration
--------------------
Open your nagios.cfg and enable eventbroker. When using the packaged nagios3
from Debian the file is located at /etc/nagios3/nagios.cfg.

--------------------------------------
event_broker_options=-1
broker_module=/opt/lib/mod_gearman/mod_gearman.o config=/opt/etc/mod_gearman.conf
--------------------------------------

and finally restart nagios:

--------------------------------------
#> /etc/init.d/nagios3 restart
Restarting nagios3 monitoring daemon: nagios3
--------------------------------------

Your nagios.log should contain a line:

--------------------------------------
#> grep mod_gearman /var/log/nagios3/nagios.log
[1295003042] mod_gearman: Version 1.0.10
[1295003042] Event broker module '/opt/lib/mod_gearman/mod_gearman.o' initialized successfully.
--------------------------------------




Testing
-------
We can perform a few tests to see if everything is up and running.

Gearman-Top
~~~~~~~~~~~

First we have a look at '/opt/bin/gearman_top'. You should have at least one
worker for each queue.

 2011-01-07 23:23:24  -  localhost:4730   -  v0.14
 Queue Name      | Worker Available | Jobs Waiting | Jobs Running
 ------------------------------------------------------------------
 check_results   |               1  |           0  |           0
 eventhandler    |               1  |           0  |           0
 host            |               1  |           0  |           0
 service         |               1  |           0  |           0
 worker_debian64 |               1  |           0  |           0
 ------------------------------------------------------------------

Check-Gearman
~~~~~~~~~~~~~

Then we have a look at the shiped check plugin:

--------------------------------------
#> /opt/bin/check_gearman -H localhost -q worker_`hostname` -t 10 -s check
check_gearman OK - debian64 has 1 worker and is working on 0 jobs. Version: 1.0.10|worker=1 jobs=2c
--------------------------------------

The interesting number is the last one, '2c' in our case, which means there
have been already 2 jobs executed by this worker.



Troubleshooting
---------------

First check if everything is up and running:

--------------------------------------
 #> /etc/init.d/nagios3 status
 checking /usr/sbin/nagios3...done (running).
 #> /etc/init.d/gearmand status
 gearmand is running with pid 31921
 #> /etc/init.d/mod_gearman_worker status
 mod_gm_worker is running with pid 31939
--------------------------------------

If one of them is not running, try to start it or check the logfiles for possible error messages.

 - Nagios: /var/log/nagios3/nagios.log
 - Gearmand: /opt/var/mod_gearman/gearmand.log
 - Mod-Gearman Worker: /opt/var/mod_gearman/mod_gearman_worker.log
