weblookerd
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
