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
