BigBen 0.5 - Documentation
==========================

BigBen is a collection of three perl scripts useful to monitor a Unix 
network. The scripts are:

- LittleBen (client program. This program collect the info on a system and
             send all the data to the server)
- BigBen (server program. Accept the connections from the clients and save
          the data in the proper place/format)
- Weber (output formatter. This script collect the data files saved by the
         server, and creates an HTML output, so you can check your network
         on a WEB browser)

As you can see, the use of this application is quite simple. All the three
scripts run as daemons. BigBen and Weber run on the same system, and the 
LittleBen client can be installed on several systems (all the systems you
need to check).

The check logic of Weber is the following:

- when it starts for the first time, it checks for data file sent by the
  clients. The data file will be unavailable, because it's easy that the
  clients start at the same time, so Weber set an initial Warning message
- if at the second check, it does not find a data file, not it set an 
  error flag (may be that the client is not started, or has some problems)
- after each pause, it checks the file and display the infos in them. An
  error is set if it does not find the data file

To avoid problem due to the timings between the client and the server
(both wait for a while before check), it's better to start the client before.

Now, we can analyze the scripts in detail.

LittleBen
=========

LittleBen is the client application: it runs as a daemon, and it is 
configurable through the configuration file (see the LittleBen.conf sample
file). In this file you can put the processes you want to monitor, and the
Min and Max values you want for these processes; if these values are out
of the border you set, the client send an ERROR or a WARNING to the server.
The file format is the following:

#
# The format for processes is: name     Min,Max         Error/Warning
#

name= process name (/usr/sbin/crond for example). There are some special keys
(USERS and LOAD) to check the system load about CPU and users.

Min,Max= the minimum and maximum value desired for the process. If these 
borders are broken, the client send a message to the server

Error/Warning= the message sent to the server when the limits are broken.
You can choose to put E or W depending on the criticity of the error.

The client reads the configuration file when starts, but you can force the
program to re-load the file with a HUP signal (kill -HUP <procID>).

The client writes a log in /tmp.

You can configure the LittleBen also with some command line options:

        -s nnn     Seconds between two check (default: 20)
        -p nnn     Port where BigBen is listening (default: 4455)
        -r xxx     Remote host where BigBen is located (default: localhost)
        -c xxx     Configuration file (default: LittleBen.conf)
        -l xxx     Log file (default: /tmp/LittleBen.log)
        -ps xxx    Option for ps to show processes (default: -au)
                   This option allow you to set the ps command line options
                   to get the running process on a system. Since the ps 
                   options are not really standard, you can configure them
                   with this switch.
        -nolog     Disable logging


BigBen
======

This is the server script. Once installed, it listens on a port (default 4455)
for the data sent out by the clients. 
When the packet is received, it saves the data in the proper directory, where
the formatter will get the data.

The command line options available are:

        -d xxx     Working directory (default: ./store)
                   WARNING: this MUST be the same set in Weber
        -p nnn     Port where BigBen is listening (default: 4455)
        -l xxx     Log file (default: /tmp/BigBen.log)
        -nolog     Disable logging


Weber
=====

The Weber gets the data saved by the BigBen, and creates a couple of HTML
pages, so you can check the data with your HTML browser.
The HTML file created, is able to auto-reload itself, so you will get the
last date in each moment.
The Weber and the BigBen will run on the same system.

Weber needs a configuration file (see the Weber.conf sample file) with this
format:

#
# system_name   system_IP               seconds
#

In this file are set all the systems where the LittleBen is running. In this
way the Weber knows which files need to check.
The fields are:

system_name= the name of each system where the LittleBen is running

system_IP= the IP address of the system

seconds= number of seconds between two check of the system. Be careful with
this value; this value must be greater or at least equal to the pause set
for the LittleBen. For example, if the LittleBen for on system foo.bar.com,
checks the processes every 3000 seconds, the seconds value set here for the
foo.bar.com must be at least 3000.

The command line options for Weber are:

        -d xxx     Working directory (default: ./store)
                   WARNING: this MUST be the same set in BigBen
        -c xxx     Configuration file (default: ./Weber.conf)
        -l xxx     Log file (default: /tmp/Weber.log)
        -nolog     Disable logging


In ./server/store directory, are saved some GIFs, needed to build the HTML
page. If you want to use a different working directory, you have to copy 
these files in the new dir.
