Unix client for Hobbit
======================
As of version 4.1, Hobbit ships with a native client for
most Unix-based systems.

The Hobbit client will generate status columns for:
* cpu    : CPU utilisation
* disk   : Filesystem (disk) utilisation
* files  : File- and directory attributes and sizes
* memory : Memory and Swap utilisation
* msgs   : Log file messages
* ports  : TCP/IP Network connections
* procs  : Processes

It will also feed data to generate some graphs:
* ifstat : Raw traffic data for network interfaces
* netstat: TCP/IP statistics
* vmstat : Various performance counters (OS-specific)

In the default setup, all configuration of disk thresholds, 
load limits, which processes to monitor etc. is done on the 
Hobbit server, NOT on the client. This is to allow centralized 
configuration of the monitored systems.

If you prefer to have the client configuration done locally
on each of the systems you monitor, this is an option when
building the client. It is possible to have a mix of systems,
with some systems configured locally, and others that use
the central configuration. Note: The locally-configured
client requires the PCRE libraries to be installed on the
client host.

The Hobbit client is released under the GNU GPL, version 2
or later. See the file COPYING for details.


Installation
============
Building the client package requires a working C compiler
and GNU make on the target platform. None of the extra libraries
needed for building Hobbit are used by the client - so a
plain C compiler installation with GNU make is all that is 
needed.

To build the client:

	- create a "hobbit" userid on the system
	  (not required, but recommended).
	- extract the Hobbit source archive
	- cd to the hobbit-X.X directory
	- run "./configure --client; make"
	- as root, run "make install"

The client installation is kept entirely within
the "hobbit" users' home-directory. All client-related
files are in the ~hobbit/client/ directory. If convenient,
this directory can be copied directly to other systems
of the same type, so you need not build the client from
source on all systems.


Running it
==========
To start the client, su to the "hobbit" user, then run
   $HOME/client/runclient.sh start

You should arrange for your boot-time scripts to run this
command at startup.


Client configuration
====================
All of the normal configuration is done on the Hobbit SERVER.
See the hobbit-clients.cfg(5) and client-local.cfg(5) man-
pages on the Hobbit server.


Hostname detection
------------------
The client reports to Hobbit using the hostname taken from
the "uname -n" command output. Whether this provides a fully
qualified DNS name (myserver.foo.com) or a simple hostname
(myserver) varies a lot. If your client gets it wrong, you
can override the default with the "--hostname=CLIENT.HOST.NAME"
option to the runclient.sh startup command.


OS detection on Linux systems
-----------------------------
The client normally determines the operating system auto-
matically from the "uname -s" output. This results in all
Linux systems reporting as "Linux" - which causes the
vmstat graphs to fail for certain types of systems:

	- Systems running Linux kernels 2.2.x (e.g. Debian Woody)
	  Must report "linux22" instead.
	- Red Hat Enterprise Linux 2.1
	  Must report "linux22" instead.
	- Red Hat Enterprise Linux 3 update 1
	  The default is adequate
	- Red Hat Enterprise Linux 3 update 2 or later
	  Must report "rhel3" instead.
	- Red Hat Enterprise Linux 4 update 2 and later
	  The default is adequate

To override the default, start the client using the 
"--os=OSNAME" option to the runclient.sh startup command.

(Thanks to Thomas Seglard Enata for providing the about the 
 various Red Hat versions).


Extension scripts
-----------------
The file client/etc/clientlaunch.cfg configures the "hobbitlaunch"
used to run the client scripts. If you need to run extension
scripts for your client, you can add them to this file. The 
environment variables commonly used by Big Brother-based extensions 
are made available by hobbitlaunch for the scripts, so in most
cases extensions written for the Big Brother client will work 
without modifications on Hobbit.

Each script should have a separate section in the file, like the
default one that runs the core client:

[myextension]
	ENVFILE /usr/lib/hobbit/client/etc/hobbitclient.cfg
	CMD /usr/lib/hobbit/client/ext/myscript.sh
	INTERVAL 5m
	LOGFILE /usr/lib/hobbit/client/logs/myscript.log

See the hobbitlaunch.cfg(5) man-page for a full description 
of this file.


Installing on multiple systems
==============================
After building and installing the client on one system, you can
copy the client installation to other systems. You need only copy
the directory structure with the "client" directory. 

The client does not have any hardcoded file- or directory-paths
embedded in it, so you can put the client files anywhere you
like, as long as you preserve the directory structure below the
"client" directory.



Henrik Stoerner, 2006-Apr-23