watchmonkey Files

# About the watchmonkey package

watchmonkey is a daemon package that watches specified files/folders for changes and
runs commands in response to those changes. It is similar to
[incron](http://incron.aiken.cz), however, configuration uses a simpler
to read ini file instead of a plain text file. Unlike incron it can also
recursively monitor directories.

The script watchmonkey.sh comes from Stephen C Phillips -- http://blog.scphillips.com/2013/07/getting-a-python-script-to-run-in-the-background-as-a-service-on-boot/ and was modified to fit the needs of this tool set.

The python script watchmonkey.py originated with Andreas Gohr http://www.splitbrain.org/blog/2011-01/07-watchmonkey_a_recursive_incron_alternative and was modified extensively to work with watchmonkey.sh.

.watchmonkey.ini also came from Andreas Gohr above and was only slightly changed. He also provided the basis for this README.


It's written in Python, making it easier to hack.

## Requirements

You need Python 2.7  or greater and the [pyinotify](http://github.com/seb-m/pyinotify)
library.

In Ubuntu (and Debian) you can install these with:

    sudo apt-get install python python-pyinotify 
    
It is possible that you might need python-argparser and if you have problems start here.  python-argparser is available in the Debian repos so you can apt-get it.  It along with python is probably in most modern setups already.

## Configuration

By default the program installs three files.
1. /etc/init.d/watchmonkey.sh
2. /usr/local/bin/watchmonkey/watchmonkey.py
3. /etc/.watchmonkey.ini

The first watchmonkey.sh is nothing more than a script that starts the watchmonkey daemon. It requires no configuration except if you want it to autostart you should run as root: 
	update-rc.d watchmonkey.sh defaults enable
It can be started and stopped like any daemon with:
	/etc/init.d/watchmonkey.sh start|stop|status|restart
Note that on systemd boxes this is slightly different and you have to use systemctl and then you have access to reload and force-reload.

The second file /usr/local/bin/watcher/watchmonkey.py is a python script that uses pyinotify to monitor events drawn from the .watchmonkey.ini configuration file. The watchmonkey.py should not need to be modified. 

The .watchmonkey.ini file provided is a dummy file that sits in the folder /etc.  It should be moved to ~/.watchmonkey.ini and edited. 
The first change is line 25 where you define the folder you want to watch. 
The next is line 48 that sets what you want to monitor. The parameters are described in lines 27-43 and can just be separated by comma's. The default is create,delete. 
Line 52 allows you to set what folders in the tree or files to exclude and the same rules apply. 
Line 55 allows you to set whether you want the folder watched recursively or not. 
Line 58 will offer you the option of autoadd new subdirectories. 
Line 67 allows you to enter a command to run when an event is triggered.  

Once you have changed and saved the file ~/.watchmonkey.ini you can start the daemon with:
	/etc/init.d/watchmonkey.sh start
Note that any events that trigger watchmonkey (start/stop/file change/etc) are logged to syslog and that there is a pid file created in /tmp called watchmonkey.tmp.  That's really the only impact of watchmonkey other than the files themselves and the events you create.  It will sit and wait for an event silently.  If an event happens it does it's job, finishes and goes back to sleep.

You can easily test watchmonkey by running an event in your watched folder and looking for the desired results.

Happy monkey-watching.