weblooker

	weblooker - The client component of the weblooker network
	Copyright (C) 2011 by Christian Eppler 	<weblooker@silentchris.de>

	File:     README
	Author:   Tobias C. Sutor <tobias@sutor-it.com>
	Version:  0.2.1 $Rev: 494 $

	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 3, or (at your option)
	any later version. See the file "COPYING" supplied with the distribution 
	for additional info.


	Content
	=======
	 ___________________________________________________________________
	|                                                                   |
	| 1.) Introduction                                                  |
	|                                                                   |
	| 2.) Quick start                                                   |
	|                                                                   |
	| 3.) Installation                                                  |
	|     3.1.) Supported Systems                                       |
	|     3.2.) Requirements                                            |
	|     3.3.) Using A Package                                         |
	|         3.3.1.) GNU/Debian / Ubuntu                               |
	|         3.3.2.) Red Hat / CentOS / Scientific Linux / SUSE        |
	|     3.4.) Building From Source                                    |
	|                                                                   |
	| 4.) Configuration                                                 |
	|     4.1.) Configuration-file                                      |
	|     4.2.) Logging                                                 |
	|                                                                   |
	| 5.) Running weblooker                                             |
	|     5.1.) Using Init                                              |
	|     5.2.) Using The Command-line                                  |
	|                                                                   |
	| 6.) Troubleshooting / Bugs                                        |
	|    6.1.) General Tips                                             |
	|    6.2.) Installation                                             |
	|    6.3.) Running                                                  |
	|___________________________________________________________________|


	1.) Introduction
	================

	weblooker is the client component of the weblooker network.
	It's the core-application which must to run on every machine that will be 
	monitored. It checks the specified local services periodically for their 
	availability and collects informations about their up- and downtimes. 
	Regardless of how many clients you're going to use, you require at least one 
	machine running the weblooker daemon (weblookerd), which receives and stores 
	the values collected by the clients.

	The weblooker network consists of three parts:

	    a.) weblookerd      - the daemon
	    b.) ** weblooker ** - the client
	    c.) weblookerui     - the webinterface

	This file will guide you through the installation and configuration of the 
	client (if you haven't installed and configured the daemon on either this or 
	another machine yet, stop here and do that first!). You'll find more 
	information for the daemon or the webinterface in their README files.

	Whether you're going to use this system to monitor one or more servers 
	(physical machines (VMs are fine too), not servers in the meaning of services 
	like, http or mail) you'll need at least one running instance of the daemon. 
	But you need a client (this package) on every machine you're going to monitor.

	2.) Quick start
	===============

	This part is for advanced people only. If you're not sure, skip to section 3.0.

	So you're brave and you know what you're doing? I assume, you're familiar with 
	your shell and already grabbed the proper package for your system. I also 
	assume, that you know how to get root privileges and when you need them.

	Commands prefixed with a R are for Red Hat-based systems, D for GNU/Debian.
	OK, let's start:

	I. Get the dependencies and install the package
	    R:     
		yum -y install openssl
		rpm -Uvh <package>
	    D:     
		apt-get update && apt-get install lsb-base libssl0.9.8
		dpkg -i <package>

	II. Adjust configuration-file
		{nano|vi} /etc/weblooker/weblooker.conf
		
	    Section II,  adjust: $SERVER, $LISTEN, $SECRET
	    Section III, adjust: $KEY, $SALT
	    
	III. Start the daemon at boottime
	    R:     chkconfig weblooker on
	    D:     update-rc.d weblooker defaults

	IV. Check if all went fine:
		/etc/init.d/weblooker start
		/etc/init.d/weblooker status
	    
	    Shouldn't fail and output the pid like: "weblooker (pid 1133) is running..."
	    
		ps -u weblooker
	    
	    Should show the above process id i.e.: "1133 ? 00:00:00 weblooker"
	    
		tail /var/log/messages
	    
	    Should print something like: "weblooker[1133]: Socket created successfully"

	V. Coffee time!


	3.) Installation
	================

	There are two ways to install the client:
	    a.) using a Debian (.deb) or Red Hat (.rpm) package - which is highly
		recommended
	    b.) compiling the source by yourself (only recommend for experienced users
		and not deeply covered here)


	3.1.) Supported Systems
	-----------------------

	At the moment, only two people are involved in this project so we have limited 
	resources regarding time (money) and test-systems. For this reason we decided 
	to create a three-level model regarding the operating systems we're going 
	to support and in which manner.

	    Grade A:
		        - GNU/Debian 5 / 6 (stable, old-stable and if possible testing)
		        - Red Hat EL 5 / 6
		        - CentOS 5 / 6
		        - Scientific Linux 6
		        - Fedora¹ 15 / 16
	    
	    Grade B:
		        - Red Hat EL 4
		        - CentOS 4
		        - Ubuntu >= 10.04.2
		        - OpenSUSE 11.4 / 12.1
		        - SLE >= 11
		        - Mandriva 2011
	    Grade C:
		        - End-of-life versions of the above
		        - Any other Linux²
		        - *BSD²
		        - Mac (no Grade D defined yet)
		        - Win (no Grade D defined yet)

	 Definition:
	 -----------

	    Grade A:    These systems are our primary target. Reported bugs and feature-
		        requests will be handled with the highest priority. Released
		        packages are usually well-tested. If we're forced to break
		        the compatibility to a platform, Grade A will always win.
		        (GNU/Debian vs. Red Hat will result in two supported branches).
		        
		        ¹Note: Fedora may become B if it ever breaks the Red Hat 
		                compatibility (very unlikely, but you've been warned!)
		        
	    Grade B:    If we're able to provide packages for these systems we will do 
		        so. However, these packages are commonly untested and not known 
		        to run correctly (until we get feedback). We will try to fix 
		        reported bugs for these systems - if the reporter is willing to 
		        provide further information and confirm provided patches.
		        
	    Grade C:    At the moment, we don't care or are unable to build/test for/on 
		        those platforms.
		        
		        ²Note: We would love to support *BSD, Arch and Gentoo.
		                 If you can provide us with feedback, logs or
		                 if you're able to support us creating ports - feel
		                 free to contact us.


	3.2.) Requirements
	------------------

	* Grade A or B System (C if you're a brave or going to volunteer)
	* An already running weblookerd server (local or remote)
	* The OpenSSL-libraries (see installation steps below)
	* root-privileges (or equal)

	* If you want to build it from source, you additionally need a C compiler and 
	    the devel-files of OpenSSL (libssl-dev on GNU/Debian), (openssl-devel
	    on Red Hat). Of course, there is some other stuff, but I'm sure, you know.


	3.3.) Using a package
	---------------------

	Installing the client with one of the provided packages is the recommend way. 
	At the time this file were written, there were no versions in the official 
	repositories available. So you have to grab the appropriate package from the 
	project-site or a third-pary repo (like our openSUSE buildsystem repo).


	3.3.1.) GNU/Debian / Ubuntu
	---------------------------

	For GNU/Debian-based systems we provide *.deb packages which will put all
	necessary files in the correct location, create the user and register the 
	client as a system-service.

	After downloading the appropriate file for your platform, open a terminal
	and "cd" in the directory where you had placed the downloaded package.

	*** NOTE ***: I assume, you know how to get root-privileges 
	(or "equal permissions" for all people out there without a real root-account).
	Hint: it's either
		su -
		su -c 'command to run as root'
		sudo -s
		sudo command to run with "equal permissions"

	It's necessary to install the package with root-privileges. We want to be sure
	that our required dependencies are met. So don't get confused about the 
	additional commands. From now on you need to be root or prefix the commands 
	with "su -c" or "sudo".

		apt-get update && apt-get install lsb-base libssl0.9.8
		dpkg -i weblooker_0.2.0_amd64.deb

	You have to adjust the filename of course, all commands are examples.


	3.3.2.) Red Hat / CentOS / Scientific Linux / SUSE
	--------------------------------------------------

	For Red Hat-based systems like CentOS or Scientific Linux (SUSE is untested and 
	based on Slackware anyway, although it's pretending to use RPMs) we provide 
	*.rpm packages, which will put all necessary files in the correct location, 
	create the user and register the client as a system-service.

	After downloading the appropriate file for your platform, open a terminal
	and "cd" in the directory where you had placed the downloaded package.

	*** NOTE ***: I assume, you know how to get root-privileges (fortunately, Red
	Hat-based systems are real Linux'es and therefore providing a root account. 
	However if you're just a sudoer try sudo -s). 
	Hint: it's either
		su -
		su -c 'command to run as root'
		sudo -s
		sudo command to run with "equal permissions"

	It's necessary to install the package with root-privileges. We want to be sure 
	that our required dependencies are met. Don't get confused about the 
	additional commands. From now on you need to be root or prefix the commands 
	with "su" or "sudo".

		yum -y install openssl
		rpm -Uvh weblooker-0.2.0-25.1.x86_64.rpm
		
	alternatively you can use (try) yum:

		yum localinstall --nogpgcheck weblooker-0.2.0-25.1.x86_64.rpm

	You have to adjust the filename of course, all commands are examples.


	3.4.) Building From Source
	--------------------------

	If you've decided to go the brave way you'll find a complete set of 
	instructions in the file called "INSTALL".
	Basically it's the typical stuff:

		./autogen.sh && ./configure && make && make install

	However you have to create a user "weblooker", take care of the init-scripts 
	and put the config-file in the correct location with the correct permissions.
	It's generally easier to use a package or fill a bugreport if a package is not 
	working for you. ;)

	After the completion of the above tasks, you should come back and proceed 
	with the below section: 4.) Configuration.


	4.) Configuration
	=================

	4.1.) Configuration-file
	------------------------

	Simply open the configuration-file with your favorite text-editor. Remember, 
	that you have to be root or at least have the appropriate permissions to edit 
	this file. The configuration-file should be located at:

		/etc/weblooker/weblooker.conf

	The file is well documented and you can leave most of the values alone. 


	4.2) Logging
	------------

	The client sends log-messages via syslog (mainly to support you while trouble- 
	shooting). Since there are many different syslog-systems out there 
	(syslogd, syslog-ng, rsyslog, ...) we decided to NOT touch their configurations.

	Briefly, all log-messages will go to

		/var/log/messages

	if not configured otherwise. You can change the logging-behaviour by making the 
	proper entries in your syslog-configuration. The following values describe how 
	weblookerd communicates with syslog:

		Facility:      daemon
		Levels:        debug, info, notice, warn, err
		Prefix:        weblooker[PID]

	Please take a look in the documentation of your syslog-system and add the 
	entries as needed.


	5.) Running weblooker
	=====================

	Because weblooker is a service, you'll usually use the init-scripts to control 
	its start/stop behaviour. However, there might be reasons to invoke the 
	commands manually - mostly for reasons of troubleshooting problems.

	*** NOTE ***: Although, the client will be registered as a service by the 
	DEB/RPM, it will NOT be set to start at boottime. To achiev this, use the 
	following commands.

	For Red Hat-based systems:

		chkconfig weblooker on

	For GNU/Debian-based systems:

		update-rc.d weblooker defaults


	5.1) Using Init
	---------------

	Basically you can start it with:

		/etc/init.d/weblooker start

	and stop it with:

		/etc/init.d/weblooker stop

	Too see if it's already/still running use:

		/etc/init.d/weblooker status


	5.2) Using The Command-line
	---------------------------

	If you want (or need) to run it directly on the command-line, you can simply 
	use the "weblooker" command. Adding the -h argument will show you a list of 
	supported parameters.

		weblooker -h
		
		[output omited]
		Options:
		      -c        	: check if weblooker is already running
		      -d loglevel   : start with additional debugging output
		[output omited]

	Taking a look into the man-pages would be even better:

		man weblooker


	6.) Troubleshooting / Bugs
	==========================

	First, if you think you found a bug, take a look in the file called BUGS.
	If it's not listed there, we ask you to fill a bugreport or visit the support-
	forums at: http://sourceforge.net/projects/weblooker/support

	We put a lot of effort in this release to provide you with all necessary tools 
	for finding and troubleshooting possible problems. Since this is a service, we 
	expect basic knowledge in troubleshooting and will only explain a few steps and 
	commands to point you into the right direction.


	6.1.) General Tips
	------------------

	* Verifying the correct location of important files:
	    - for the configuration-file:
		    weblooker -v
		->    Config        : /etc/weblooker/weblooker.conf

	    - for the path of the pidfile:
		    weblooker -V
		->    -DPIDDIR=/var/run

	    - for the location of the application:
		    which weblooker
		->    /usr/sbin/weblooker

	* Verifying the user-account:
	    - get the user:
		    weblooker -v
		->    User        : weblooker
	    
	    - check if the user is present:
		    grep weblooker /etc/passwd
		->    weblooker:x:486:486:The weblookerd user:/home/weblooker:/sbin/nologin
	    
	    - check if the service drops the root-privileges:
		    ps -u weblooker
		->    18625 ?        00:00:00 weblooker

	* Verifying the file-permissions:
	    - config:
		    ls -l /etc/weblooker/weblooker.conf
		->    -rw-r----- 1 weblooker weblooker
	    - pidfile:
		    ls -l /var/run/weblooker.pid
		->    -rw-r--r-- 1 weblooker weblooker
		
	* Check your logs
	    - change the $LOGLEVEL in your configuration to 7
		    tail /var/log/messages
		->    weblooker[2372]: weblooker starting.

	6.2.) Installation
	------------------

	If you're unable to install the package for your distribution, be sure that
	    a.) you have the correct package for your system:
		- correct plattform x86/x86_64
		- the correct package *.deb for GNU/Debain and Ubuntu systems
		    *.rpm for Red Hat, Fedora and simliar
		- if you're using RPM be sure that you didn't grab the *.src.rpm
		    it's not what you want!
	    b.) your system meets all requirements and you have the proper permissions
		- are the required dependencies installed as described at 3.3.1./3.3.2.?
		- do you have enough permissions? (root/sudo)
	    c.) check if the package is already installed
		- *.deb: dpkg -s weblooker
		- *.rpm: rpm -qi weblooker
	    d.) if all seems to be correct and you're still not able to install it, it's
		probably our (my) fault. Please fill a bugreport including any 
		error-messages and the operating system you're using

	6.3.) Running
	-------------

	If everything works fine but the client doesn't start at boottime scroll up to 
	section 5.) and bend your head in shame. :)

	If you're unable to start weblooker try the following:
	    a.) first, check if it's already running by either typing:
		    - weblooker -c
		    - /etc/init.d/weblooker status
		    - ps -A | grep weblooker
	    b.) check your logfile:
		    - tail /var/log/message
		or start with additional output:
		    - weblooker -d loglevel(1-8)
		    - weblooker -r loglevel(1-8)
		some common errors are:

	* Error: Unable to create a pidfile at: ... /weblooker.pid
	    - you're trying to run it with an un-privileged user