$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.