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.


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.) 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
    R:     
        yum -y install mysql-libs openssl
        rpm -Uvh <package>
    D:     
        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 III, adjust: $LISTENIP, $CONNECTIONS, $SECRET
    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
        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 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:

        /usr/share/doc/weblookerd-0.2.1/
        /usr/share/doc/weblookerd/

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
            Bye
            
        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:

        /etc/weblooker/weblookerd.conf

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 
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:        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]
        Options:
              -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

#EOF