symon/symon/INSTALL

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

Privileges
==========
symux needs read and write access to its rrdfiles.

symon needs to interface with your kernel. Depending on your host system this
leads to different privilege requirements:

OpenBSD:  - no privs: cpu, debug, df, if, io, mbuf, mem, proc, sensor
          - rw on /dev/pf for pf

NetBSD:   - no privs: cpu, debug, df, if, io, mbuf, proc
          - r on /dev/sysmon for sensor

FreeBSD:  - no privs: all
          - non-chroot on FreeBSD 5.x for CPU ticks in proc
          - rw on /dev/pf for pf and pfq

Linux:    - r on /proc/net/dev: if
          - r on /proc/stat: cpu, cpuiow
          - r on /proc/meminfo: mem

all:
          - r on chroot/etc/localtime for proper timezone logging

Real quick on OpenBSD
=====================
(cd /usr/ports/net/rrdtool && make install) &&
	make &&
	make install &&
	vi /etc/symux.conf /etc/symon.conf &&
	~symon/symux/c_smrrds.sh all &&
	/usr/local/libexec/symux &&
	useradd -d /var/empty -L daemon -c 'symon Account' -s /sbin/nologin _symon
	/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

Install the seperate syweb package to show the data stored in the rrd files.

Less quick, but all OSes
========================
- Install rrdtool on the host that will also run your symux gatherer.
	BSDs: cd /usr/ports/net/rrdtool && make install

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

     + RRDDIR = $RRDDIR/include should yield rrd.h. Define SYMON_ONLY in the
                environment or on the make command line to render this mute.

     + INSTALLUSER / GROUPDIR / GROUPFILE = user and groups that install should
                use.

  Note that:

     + you can define SYMON_ONLY if you do not want to compile symux / do not
       have rrdtool installed.

     + symon/platform/os/Makefile.inc is read before Makefile.inc; define
       your vars in the environment, or in Makefile.inc with != to force
       overwriting the defaults.

   BSDs: Run make && make install
  Linux: Run pmake && pmake install || bmake && bmake install

- Create an '/etc/symon.conf' for each monitored host and one symux.conf for
  the gatherer host. See the manual pages on how to specify alternative
  configuration file locations, if necessary. Note that there are example
  configurations for both in $PREFIX/$SHRDIR.

- Create the rrd files where the incoming symon data is to be
  stored. $PREFIX/$SHRDIR/c_smrrds.sh and symux -l are your friends. Note that
  syweb expects an '.../machine/*.rrd' style directory structure somewhere
  under /var/www.

- Ensure that /etc/localtime is accessible by symon/symux. Failing this you
  will get log messages in GMT. Note that etc is chroot/etc when symon
  chroots.

- Both symon and symux will daemonize if started normally. Start them with
  debugging on initially to iron out any configuration problems:

  $PREFIX/$BINDIR/symux -d &
  $PREFIX/$BINDIR/symon -d

- Remove -d flags and check system logs for any failures.

- Only if you need the webinterface: download and install syweb.

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:

nexus$ 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 was originally built as an OpenBSD application. It now has support
for FreeBSD, NetBSD and Linux.

Willem Dijkstra - wpd@xs4all.nl