weblookerd - The server 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.

	|                                                                   |
	| 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.) Database                                                |
	|         4.1.1.) Command-line-based                                |
	|         4.1.2.) Webinterface / phpMyAdmin                         |
	|     4.2.) Configuration-file                                      |
	|     4.3.) Logging                                                 |
	|                                                                   |
	| 5.) Running weblookerd                                            |
	|     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

	weblookerd is the server component of the weblooker network. It is listening 
	for incoming client-connections and stores the received values into the (MySQL) 
	database. The daemon can handle multiple incoming client-connections. 
	A DoS-protection, session tokens and AES-256 secured data-transfers are used to 
	provide confidence and security.

	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
	daemon (which should be the first part you're going to install). If you need 
	help for the client or the webinterface take a look in their README files.

	Basically, the daemon is the part of the weblooker network which collects
	the up-/ and downtime statistics recognized by the weblooker clients and 
	stores them into the database.

	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 this daemon.

	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 
	the 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
	yum -y install mysql-libs openssl
	rpm -Uvh <package>
	apt-get update && apt-get install lsb-base libssl0.9.8 libmysqlclient16
	dpkg -i <package>

	II. Create database / set permissions
	mysql -uroot -p
	mysql> CREATE DATABASE status;
	mysql> GRANT INSERT,SELECT,UPDATE,DELETE ON status.* TO weblooker 
	    IDENTIFIED BY 'pass123';
	mysql> \q

	III. Import table-structure
	cp /usr/share/doc/weblookerd-0.2.1/weblookerd.sql.gz .
	tar xfv weblookerd.sql.gz

	mysql -uroot -p status 	< weblookerd.sql

	IV. Adjust configuration-file
	{nano|vi} /etc/weblooker/weblookerd.conf

	Section II,  adjust: $SERVER, $PORT, $USER, $PASSWD, $DBNAME
	Section IV,  adjust: $KEY, $SALT, $HASH_SALT

	V. Start daemon at boottime
	R:     chkconfig weblookerd on
	D:     update-rc.d weblookerd defaults

	VI. Check if all went fine:
	/etc/init.d/weblookerd start
	/etc/init.d/weblookerd status

	Shouldn't fail and print the pid like: weblookerd (pid 1133) is running...

	ps -u weblooker

	Should show the above process id i.e.: 1133 ? 00:00:00 weblookerd

	tail /var/log/messages

	Should print something like: weblookerd[1133]: Socket created successfully

	VII. Coffee time!

	3.) Installation

	There are two ways of installing this daemon:
	a.) using a Debian (.deb) or Red Hat (.rpm) package - which is highly
	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)


	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 Linux (C if you're a brave or going to volunteer)
	* A running MySQL-Server (5.1 is tested, might run on other versions too)
	* The OpenSSL- and MySQL-libraries (see installation steps below)
	* root-privileges (or equal) and the permissions to create and manage databases 
	on your MySQL-server

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

	3.3.) Using a package

	Installing the daemon with one of the provided packages is the recommend way. 
	At the time this file was written, there were no repository-versions
	available so you have to grab the appropriate package from the project-site.

	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 libmysqlclient16
	dpkg -i weblookerd_0.2.1_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 mysql-libs openssl
	rpm -Uvh weblookerd-0.2.1-25.1.x86_64.rpm

	alternatively you can use (try) yum:

	yum localinstall --nogpgcheck  weblookerd-0.2.1-25.1.x86_64.rpm

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

	3.4.) Building From Source

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

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

	However you have to create a user "weblooker" and 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 4.) Configuration.

	4.) Configuration

	4.1.) Database

	Since packages are not allowed to create a database (you might wanna use a 
	database on another system anyway) or if you've decided to compile the source 
	by yourself, it's your job (sorry) to take care of this step. At the time this 
	file is written, weblookerd supports MySQL only.
	Maria DB or other compatible databases might work too. It's on our TODO to 
	provide support for other DBs.

	Be it as it may, you'll find a weblookerd.sql (or weblookerd.sql.gz) in your 
	documentationpath, which is usually similar to:


	Copy (and unpack if the file suffix is .gz or .tgz) this file in your current 
	working directory (keep the original as a backup at the original location):

	cp /usr/share/doc/weblookerd-0.2.1/weblookerd.sql.gz .
	tar xfv weblookerd.sql.gz

	*** NOTE ***: Your database might be located on another machine - in that 
	case, you should tell your mysql command to connect to the proper location, 
	or perform the below commands via ssh or something else. I assume, you know 
	what to do, just remember to move the template sql there.

	4.1.1) Command-line based

	In this step we will use the mysql command on a shell like Bash. You need the 
	password for a privileged mysql-user who is able to create and set appropriate 
	permissions to the database. In the following example is based on the 
	assumtion, that the new database will be called "status", the user will be 
	named "weblooker2 using "pass123" as his password. We use the root-acount to 
	achieve the necessary tasks.
	NOTE: the mysql-root user is usually NOT the system root and therefore uses a 
	different password to authenticate. If you have problems you'll find help 
	at: http://dev.mysql.com/doc/refman/5.0/en/resetting-permissions.html

	1. If you have the required permissions and want the daemon to use the 
	    own database you have to create it first. Note, that USER is the 
	    user who has the required permissions of creating new databases 
	    (usually root).
	    mysql -uUSER -p
	    mysql> CREATE DATABASE status;
	    Query OK, 1 row affected (0.00 sec)
	    mysql> GRANT INSERT,SELECT,UPDATE,DELETE ON status.* TO weblooker 
	    IDENTIFIED BY 'pass123';
	    Query OK, 0 rows affected (0.01 sec)
	    mysql> \q
	2. Now we have a database called "status" with a user "weblooker".
	    Next, we're going to import the table-structure.
	    You should have the uncompressed weblookerd.sql file in your 
	    current directory as described above. To import it in your freshly 
	    created database use the following command:
	    NOTE: you need the privileged user again and I assume that you've
		    named your database "status". You might have to adjust the
		    values in the following command!
		mysql -uUSER -p status 	< weblookerd.sql
	    You should get no message if everything went fine 
	    (no news is good news!)

	4.1.2) Webinterface / phpMyAdmin

	If you're using phpMyAdmin (I love it!) or a similar webinterface create/choose 
	the database and simply use the import-menu to import the (compressed) sql-file.
	Setting permissions and other stuff is quite simple there - use their excellent 
	helpsystem if you're facing any problems. Or fill a support/bug-report on 
	OUR project-site.

	4.2.) Configuration-file

	After you've setup the database, you deserve a cup of coffee, because the most 
	annoying work is done now.

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


	The file is well documented and you can leave most of the values alone.
	It's important to check the database preferences (host, db-name, user, 
	db-password) and adjust them to the values you just set above.

	4.3) Logging

	The daemon will send log-messages via syslog (mainly to support you while 
	troubleshooting problems). Since there are many different syslog-systems out 
	there (syslogd, syslog-ng, rsyslog, ...) we decided to NOT touch their 

	Briefly, all log-messages will go to


	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:        weblookerd[PID]

	5.) Running weblookerd

	Because weblookerd is a daemon, you'll usually use the init-scripts to control 
	its start/stop behaviour. However, there might be reasons to invoke the command 
	manually - mostly for troubleshooting tasks.

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

	For Red Hat-based systems:

	chkconfig weblookerd on

	For GNU/Debian-based systems:

	update-rc.d weblookerd defaults

	5.1) Using Init

	Basically you can start it with:

	/etc/init.d/weblookerd start

	and stop it with:

	/etc/init.d/weblookerd stop

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

	/etc/init.d/weblookerd status

	5.2) Using The Command-line

	If you want (or need) to run it directly on the command-line, you can simply 
	do that by using the "weblookerd" command. Adding the -h argument will show you 
	a list of possible options.

	weblookerd -h

	[output omited]
	      -c        : check if weblookerd is already running
	      -d        : start with additional debugging output
	[output omited]

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

	man weblookerd

	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: 
	    weblookerd -v
	->    Config        : /etc/weblooker/weblookerd.conf

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

	- for the location of the program: 
	    which weblookerd
	->    /usr/sbin/weblookerd

	* Verifying the user-account:
	- get the user: 
	    weblookerd -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 daemon drops the root-privileges: 
	    ps -u weblooker
	->    18625 ?        00:00:00 weblookerd

	* Verify file-permissions:
	- config:
	    ls -l /etc/weblooker/weblookerd.conf
	->    -rw-r----- 1 weblooker weblooker
	- pidfile:
	    ls -l /var/run/weblookerd.pid
	->    -rw-r--r-- 1 weblooker weblooker

	* Check your logs
	- change the $LOGLEVEL in your configuration to 7
	    tail /var/log/messages
	->    weblookerd[2372]: weblookerd 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 enough 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 weblookerd
	- *.rpm: rpm -qi weblookerd
	d.) if all seems to be correct and you're still not able to install it, it's
	probably our fault. Please fill a bugreport including any error-messages 
	and the operating system

	6.3.) Running

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

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

	* No usable MySQL configuration found in ... /weblookerd.conf
	- goto section 4.2.) and bend your head in shame.

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