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
          - r on /proc/meminfo: mem

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.

   BSDs: Run make && make install
  Linux: Run pmake && pmake 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 is your friend. Note that syweb expects
  an '.../machine/*.rrd' style directory structure somewhere under /var/www.

- 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

$Id: INSTALL,v 1.19 2005/10/21 14:58:41 dijkstra Exp $