symon/symon/INSTALL

Installation notes
==================

Priviledges
===========
symux needs read and write access to it's rrdfiles.

monitoring needs:
cpu, if, mem, io - symon can run as nobody
pf               - symon needs r/w on /dev/pf

symon2web is a php4 application and needs access to the rrdfiles. Note that
symon2web interprets the url for graphing parameters. It should never be exposed
to untrusted users | the outside world.

Real quick 
==========
make && make install && vi /etc/symux.conf /etc/symon.conf && 
	~symon/symux/c_smrrds.sh all && 
	/usr/local/libexec/symux && 
	/usr/local/libexec/symon

or grab the port and do
make package
pkg_add symon-mon-version.tgz on all monitored hosts
pkg_add symon-mux-version.tgz on the loghost
pkg_add symon-web-version.tgz on the loghost

Less quick, but more verbose
============================
- Install rrdtool where you want to run the gatherer. 
	cd /usr/ports/net/rrdtool && make install

- Install php4 where you want to run the web frontend. 
	cd /usr/ports/www/php4 && make install

- Building by hand: Check Makefile.inc for settings. Things to watch out for
  are:

     + PREFIX = Where does the installation tree start. Defaults to
                '/usr/local'.

     + BINDIR = Where should the daemons be put, relative to $PREFIX. Defaults
                to 'libexec'.

     + MANDIR = Where should the manuals be installed, relative to
                $PREFIX. Defaults to 'man'.

     + SHRDIR = Where are the example configurations to be installed. Defaults
                to 'share/symon'.

   Run make && make install

- Building from the port: 
	cd ~symon/ports/symon or cd /usr/ports/sysutils/symon
	make package

	cd /usr/ports/packages/$ARCH/All/
	pkg_add symon-mon-version.tgz               on monitored hosts
	pkg_add symon-mux-version.tgz               on the loghost | gatherer
	pkg_add symon-web-version.tgz               on the loghost | webfrontend

- Create an '/etc/symon.conf'. Note that there is an example configuration in
  $PREFIX/$SHRDIR. 

- Create a symux.conf on the gatherer host. You can specify alternative
  locations than '/etc/symux.conf' using 'symux -f <symux.conf>'.

- Create the rrd files where the incoming symon data is to be
  stored. $PREFIX/$SHRDIR/c_smrrds.sh is your friend. Note that 'symon2web'
  expects an '.../machine/*.rrd' style directory structure.

- Fire up symon, symux. Check system logs for any failures.

- Only if you need the webinterface: symon2web is installed in
  $PREFIX/$SHRDIR/. Copy the files to a convenient apache directory and modify
  the symon2web/datasources.inc to reflect your filelocations. datasources.inc
  also contains some settings on how the data is displayed.

  symon2web runs 'rrdtool' to generate graphs as requests for pictures come
  in. As of OpenBSD 3.2 apache is chrooted at /var/www. Make sure a statically
  linked rrdtool is available, or break the chroot. You were not planning of
  running this software on a machine tied to the internet anyway.

     + $symon2web["view"] = show all graphs for all machines ('all') or show
       only graphs for a single selected machine ('one').

     + $symon2web["magnify"] = to which format should the graph be magnified if
       clicked on. Values are:
          '' for no magnification, 
          'tiny'   =  100 x  75, 
          'small'  =  200 x 125,
          'normal' =  300 x 225, 
          'big'    =  600 x 450, 
          'huge'   = 1024 x 640.

     + test your setup with test_config.php - this will try to run rrdtool and
       see if your rrd files are accessable by symon2web.

Getting measurements without the web
====================================

The client directory contains a perl module 'SymuxClient.pm' that can be used
to read measurements as they come in at the symux host. A sample Perl program
called 'getsymonitem.pl' shows how to use the module. 

Example:

hoard$ getsymonitem.pl 127.0.0.1 2100 127.0.0.1 "cpu(0)" "idle"
93.40

Historical data can be gathered using rrdfetch(1) from symux's rrd files.

Portability
===========

This package is an OpenBSD application. You might be able to make symux and
symon2web run on POSIX compliant unixes, but the monitoring application itself
(symon) is OpenBSD specific.

Willem Dijkstra <wpd@xs4all.nl>

$Id: INSTALL,v 1.9 2002/11/29 10:50:28 dijkstra Exp $