$OpenBSD: README,v 1.8 2018/09/04 12:46:18 espie Exp $

+-----------------------------------------------------------------------
| Running smokeping on OpenBSD
+-----------------------------------------------------------------------

Basic configuration
===================

Smokeping is split into two main parts, the daemon (running the probes
and updating RRD files) and the part responsible for generating website
graphs.

Edit /etc/smokeping/config (at least add some hosts to
monitor) and enable the daemon:

    rcctl enable smokeping
    rcctl start smokeping

The simplest method to generate graphs is as static HTML and images.
There is no possibility to zoom into graphs interactively from the
browser, but it is easy to configure and might be quite acceptable.
Do this by running 'smokeping --static=/path/to/html-dir' from cron.

Alternatively it will run as a CGI/FastCGI script with a web server.
Smokeping itself doesn't work well with a chroot jail, but the script
can be run as a persistant process outside the jail, and communicate
with a chroot'ed webserver via FastCGI. The included smokeping_fcgi
rc script will start Smokeping ready to communicate over a FastCGI
UNIX socket /var/www/run/smokeping.sock. If you wish to use this
method, enable this:

    rcctl enable smokeping_fcgi
    rcctl start smokeping_fcgi

And configure your web server to access it - here is a sample
configuration section for use with nginx:

    location ~ /smokeping/smokeping.cgi$ {
	fastcgi_pass	unix:run/smokeping.sock;
	fastcgi_split_path_info ^(/cgi-bin/[^/]+)(.*);
	fastcgi_param	PATH_INFO $fastcgi_path_info;
	fastcgi_param	SCRIPT_FILENAME $fastcgi_script_name;
	include		fastcgi_params;
    }

Other probe types
=================

Smokeping is commonly used to perform ICMP monitoring using fping, but
also includes probes to monitor other protocols. Some have additional
dependencies which are not forcibly installed. Use pkg_add to install
the relevant packages if needed.

 RADIUS:	   p5-Authen-Radius
 TelnetIOSPing:	   p5-Net-Telnet
 OpenSSHEOSPing:   p5-Net-OpenSSH, p5-IO-Pty
 OpenSSHJunOSPing: p5-Net-OpenSSH, p5-IO-Pty
 AnotherDNS:	   p5-Net-DNS
 LDAP:		   p5-ldap, p5-IO-Socket-SSL

Advanced topic: Heavy load systems
==================================

If problems are seen with excessive load or i/o, it is possible to
configure Smokeping to use rrdcached instead. Read through the whole
section before starting; this is *not* needed for a typical setup.

To do this, group permissions should be set to allow Smokeping to
access the rrdcached socket, and to allow rrdcached to access
Smokeping's files, e.g.:

	$ grep _smokeping /etc/group
	_smokeping:*:562:_rrdcached
	_rrdcached:*:726:_smokeping

	# chgrp -R _rrdcached /var/db/smokeping
	# chmod -R g+w /var/db/smokeping

The rrdcached daemon must be running:

	# rcctl enable rrdcached
	# rcctl set rrdcached flags -b /var/db/smokeping -B -m 770 \
	    -l unix:/var/run/rrd/rrdcached.sock -j /var/db/smokeping/journal \
	    -p /var/run/rrd/rrdcached.pid
	# rcctl restart rrdcached

Smokeping must be told to use the daemon. This is done by setting an
environment variable; add this to /etc/login.conf:

smokeping:setenv=RRDCACHED_ADDRESS=unix\c/var/run/rrd/rrdcached.sock:tc=daemon

The Smokeping FastCGI script must also be told to use the daemon.
This is done by setting the variable in your web server. For nginx:

fastcgi_param  RRDCACHED_ADDRESS unix:/var/run/rrd/rrdcached.sock;

Then restart smokeping and smokeping_fcgi. Use -d to show more information
in case of errors at startup.

	# rcctl -d restart smokeping
	# rcctl -d restart smokeping_fcgi
