$Id: INSTALL,v 1.2.2.3 2007/06/25 13:27:29 trockij Exp $

OVERVIEW
--------

There are several components you'll need to get working to
have a fully functional mon installation. 

    1. mon, the server 
    2. Mon::Client, the Perl library used by some clients
    3. C programs in mon.d
    4. Optional (but highly useful) monitors
    5. A customized mon.cf to make the server do what you want


1. MON SERVER
-------------

The "mon" daemon uses Perl 5.n, where n >= 005_01. 

Mon requires that *.ph be created from the system header files.  If you try to
run mon and Perl complains with the "did you run h2ph?" message, then chances
are this step wasn't done, either by your package manager or manually after
Perl installation. You can fix it by doing the following, as root:

	cd /usr/include
	h2ph -r -l .

You'll need the following modules for the server to function, all of
which are available from your nearest CPAN archive. The listed
CPAN paths relative to /cpan/modules/by-authors/id/ -- versions of 
modules on CPAN change quickly, so there may be newer versions available,
but the following are known to work:

    Time::Period	PRYAN/Period-1.20.tar.gz
    Time::HiRes		J/JH/JHI/Time-HiRes-1.59.tar.gz


2. INSTALLING THE PERL CLIENT MODULE
------------------------------------

The Perl client module is distributed as a separate package, and is required
for the web interfaces "mon.cgi" and "monshow" and for "moncmd". It is named
"mon-client-*.tar.gz".  Refer to that for installation instructions.  It is
available on kernel.org mirrors in the /pub/software/admin/mon directory, and
in CVS on sourceforge.net.  Be sure to match the version of mon-client with the
version of mon you are using.  At this time, branch "mon-1-2-branch" of the mon
CVS module matches the "mon-client-1-2-branch" branch of the mon-client CVS
module. See http://sourceforge.net/projects/mon/ for information on CVS access.


3. COMPILING THE C CODE (optional)
----------------------------------

Some of the monitors included with mon are written in C and need to
be compiled for your system. If you want to use the RPC monitor or the 
dialin.monitor wrapper,

    cd mon.d
    (edit Makefile)
    make
    make install
    cd ..

Keep in mind that although this is known to work on Linux, Solaris, and AIX,
it may not compile on your system. It is not required for the operation of mon
itself.


4. MONITORS
-----------

All of the monitor and alert scripts that are packaged with mon are actually
optional in that mon will only use the monitors which you have specified in
your configuration. There is no need to install any extra dependencies, such as
Perl modules, for monitors which you will not be using.

You may test to see if a monitor works outside of mon by simply running it from
the command line, giving it a host as an argument. For example:

    $ ./fping.monitor uplift

    start time: Mon Jun 25 07:52:34 2007
    end time  : Mon Jun 25 07:52:34 2007
    duration  : 0 seconds

    --------------------------------------------------------------------------
    reachable hosts                          rtt
    --------------------------------------------------------------------------
    uplift                                   0.07 ms

Some monitors may need Perl modules which may not already be installed on your
system. To determine if you have the requisite modules installed, you can pass
the monitor to "perl -c" and see if it says "OK", like this:

   $ perl -c fping.monitor 
   fping.monitor syntax OK

If it gripes about "Can't locate...", then what follows are the modules which
you'll need to install from CPAN.

Monitors may have their own embedded documentation at the top, and some
may provide their own POD (viewable with "pod2man xyz.monitor | nroff -man").
There may also be some additional documentation on some monitors in the "doc"
directory of the root of the tarball.


5. MON.CF CUSTOMIZATION AND STARTUP
-----------------------------------

-You may want to begin learning about mon by following the slides from the
 presentation. They cover the components, what they do, how they relate, and
 how it all works together. Find them here:

 http://mon.wiki.kernel.org/index.php/Documentation

-Read the man page for "mon" and "moncmd" in the doc/ directory to get
 an overview of the directories involved, i.e. the configuration,
 alert, monitors, state, and run directories.

 cd doc
 nroff -man mon.8 | more

-read the "READMEs" in the doc/ directory for some useful
 insight on system configuration.

-Make your own mon.cf file, using the suppled "example.cf" (located
 in the etc/ directory) as a template, or the m4-based "example.m4":

 cp etc/example.cf mon.cf
 
or

 cp etc/example.m4 mon.m4

-Edit the "auth.cf" file. This file controls which users can perform
 what command. The default is pretty restrictive (read-only), but that's
 only for safety. Currently, "moncmd", "monshow", and "mon.cgi" are the
 only clients which are able to authenticate themselves to the server;
 the 2-way pager interface does not yet perform authentication. However,
 these programs work fine in read-only mode.


-Add the following lines to /etc/services:

mon             2583/tcp                        # MON
mon             2583/udp                        # MON traps

-You may want to make a DNS CNAME entry called "monhost" for your
 host that will run "mon". You can then set the environment variable
 MONHOST to be this host. "moncmd" uses this variable.

-The Perl scripts look for perl in /usr/bin. You might want to change
 this. I'd advise keeping a locally-installed copy of Perl if you're
 going to monitor network resources and you expect this stuff to work
 when some component of the network is down.

-Test it by starting "mon" from the distribution directory. Use these
 arguments if you chose the non-m4 config:

    ./mon -f -c mon.cf -b `pwd`

and these arguments for the m4-based config:

    ./mon -f -M -c mon.m4 -b `pwd`

To see if it's running on your machine:

    ./clients/moncmd -s localhost list pids

If you get some output, then things are probably OK. Check the
syslog for further diagnostics.

Mon doesn't really need to be installed in any special location.  Just
keep it on the local disk of the machine which will be running the server.


WEB INTERFACE
-------------

This distribution contains two web interfaces: monshow and mon.cgi.  monshow is
a simple report-only tool which supports configurable "views" of the mon
configuration. monshow also operates as a textmode report generator.

mon.cgi, however, supports the full functionality of mon, including the ability
to disable/enable groups and hosts and services, acknowledge failed services,
show alert and downtime history, authenticate users, among many other things.

To install monshow, simply copy clients/monshow into your web server's cgi-bin
path and name it "monshow.cgi". You may want to read the man page in the doc/
directory so that you can understand how to configure a "view" to your liking.

To install mon.cgi, follow the instructions found in doc/README.mon.cgi.