commit

doc/smokeping_install.pod

@@ -0,0 +1,188 @@
+=head1 NAME
+
+smokeping_install - How to install SmokePing
+
+=head1 OVERVIEW
+
+This document explains how to setup SmokePing at your site.
+
+=head1 DESCRIPTION
+
+=head2 Prerequisites
+
+SmokePing does not stand alone. It relies on various other tools and
+services being present. Apart from a Unix OS and a working Perl installation
+you need the following components:
+
+=over
+
+=item RRDtool 1.2.x or later
+
+Smokeping uses RRDtool for logging and graphing. If your linux distro provides
+an rrdtool  package with perl support, use this. If you want to get the latest
+and greatest version, compile your own: L<http://oss.oetiker.ch/rrdtool/>
+
+Ubuntu:
+
+ sudo apt install rrdtool librrds-perl libssl-dev
+
+RedHat:
+
+ sudo yum install rrdtool perl-rrdtool openssl-devel
+
+=item FPing (optional)
+
+Go to L<http://www.fping.org/> to grab a copy.
+
+Note that fping must be installed setuid root. It seems that older versions
+of fping report round trip times in 0.1 milliseconds instead of 1 milliseconds
+as advertised ... SmokePing tries to figure this out. It tells
+you when it starts ... let me know if it gets it wrong.
+
+=item EchoPing  (Optional)
+
+L<https://github.com/bortzmeyer/echoping/>
+
+You need this to run the EchoPing probes
+
+=item Curl (Optional)
+
+L<http://curl.haxx.se/>
+
+You need this for the Curl probe.
+
+=item dig (Optional)
+
+L<http://www.isc.org/sw/bind/>
+
+You need this for the DNS probe.
+
+=item SSH (Optional)
+
+L<http://www.openssh.org/>
+
+You need this for the SSH probe.
+
+=item Webserver 
+
+L<http://httpd.apache.org/>
+
+Well I won't get much into this. The important thing is, to have a webserver
+which allows you to run CGI and preferably FastCGI scripts. If you are using
+Apache I strongly recommend using the F<suexec> system for running CGI
+scripts as a particular user.
+
+See L<http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html> and
+L<http://httpd.apache.org/docs/2.2/mod/mod_suexec.html> for more information
+on this.
+
+=item Perl 5.10.1 or later.
+
+If you still have an older version, maybe have a look at perlbrew.
+
+Ubuntu:
+
+ sudo apt install perl
+
+RedHat:
+
+ sudo yum install perl-core
+
+=back
+
+=head2 Installation
+
+Once the tools listed above are in place, you can start setting up SmokePing
+itself. Unpack the tar archive and run the included configure script:
+
+ ./configure --prefix=/opt/smokeping
+
+Configure will verify that all the required perl modules are available.
+If some are missing it will tell you to run the module build script.
+Just follow the instructions on screen and then run configure again.
+Once it completes, you can run
+
+ make install
+
+to finish your setup.
+
+=head2 Configuration
+
+Use the F<etc/config.dist> file as a template to create your own smokeping configuration file.
+See L<smokeping_config> for details.
+
+=over
+
+=item Installing the webinterface
+
+Copy the content of the F<PREFIX/htdocs> directory to the place where your webserver
+expects its data. Maybe to F</var/www/smokeping>.
+
+Edit the F<smokeping.fcgi> script to point to your smokeping_cgi script.
+
+If you have no FastCGI support in your webserver, you may want to use the
+F<smokeping.cgi> script.
+
+=item F<etc/basepage.html>
+
+Edit the html template to your liking. Please do not remove the link to the
+SmokePing counter and my name from the template.  The content of the
+template will be rendered by smokeping.cgi.  This means that all embedded
+links must be relative to smokeping.cgi.
+If you are using HTTP authentication, then the template variable C<authuser> will be populated
+from the C<$ENV{REMOTE_USER}> environment variable.
+
+=item F<etc/smokemail>
+
+If you are going to use the B<DYNAMIC> IP support, customize the contents of this file.
+
+=back
+
+=head2 Starting the Smokeping Daemon
+
+With all the scaffolding in place, you can now launch the smokeping daemon and
+have it gather data for you. First you may want to run it in debug mode to see what
+it is doing
+
+ ./bin/smokeping --config=/opt/smokeping/etc/config --debug
+
+once all is well, start it up as a daemon. I would recommend you enable the
+logfile option so that you can see if it runs into trouble.
+
+ ./bin/smokeping --config=/opt/smokeping/etc/config --logfile=smoke.log
+
+Once the system works, you may want to put a SmokePing startup script into
+your F</etc/init.d> tree. Check out L<smokeping> for further information.
+
+You can now open the smokeping.cgi webpage to look at your data.
+
+See the L<smokeping_cgi> documentation on how to setup the smokeping web interface.
+
+=head1 COPYRIGHT
+
+Copyright (c) 2001, 2011 by Tobias Oetiker. All right reserved.
+
+=head1 LICENSE
+
+This program is free software; you can redistribute it
+and/or modify it under the terms of the GNU General Public
+License as published by the Free Software Foundation; either
+version 2 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be
+useful, but WITHOUT ANY WARRANTY; without even the implied
+warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE.  See the GNU General Public License for more
+details.
+
+You should have received a copy of the GNU General Public
+License along with this program; if not, write to the Free
+Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
+02139, USA.
+
+=head1 AUTHOR
+
+Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
+
+=cut