weblookerui
weblookerui - The webinterface 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: 496 $
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.) Manual installation |
| |
| 4.) Configuration |
| 4.1.) Database |
| |
| 5.) Running weblookerui |
| 5.1.) Menu explanation |
| 5.2.) User specific monitoring web page |
| 5.3.) Special groups |
| |
| 6.) Troubleshooting / Bugs |
| 6.1.) General Tips |
| 6.2.) Installation |
|___________________________________________________________________|
1.) Introduction
================
weblookerui is the webinterface for weblooker and weblookerd. After the confi-
guration of the two daemons it's probably the only part you'll actually "see".
It's in charge of the following core functions:
* easy configuration and administration of the monitored services
* generation of the overview-sites based on the collected values
Although, the most work is done by the other two daemons, this part is most
likely providing the features you want and is therefore the actual reason why
you've decided to start using weblooker.
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
weblookerui (which should be the last part you're going to install). If you need
help for the daemon or the client take a look in their README files.
To be clear: you need a running instance of at least one weblookerd and one or
more weblooker's. If you don't - stop here and goto to the README of either the
daemon or client (or both, starting at the daemon) and get them up first.
2.) Quick start
===============
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. Install the package
R:
rpm -Uvh <package>
D:
dpkg -i <package>
II. Adjust configuration-file / databse connection
{nano|vi} /usr/share/weblookerui/config.inc.php
III. Check webserver configuration
{nano|vi} /etc/httpd/conf.d/weblookerui.conf
(or something appropriate - take a look in the weblookerui.conf to get an
idea what's necessary to tell your webserver where to find our files)
IV. Check if all went fine:
browse to: http://localhost/weblooker
Should display a working site
V. 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.) copy the files by yourself (only recommend for experienced users
and not deeply covered here)
3.1.) Supported Systems
-----------------------
At the moment, 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 form.
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: This systems are our primary targets. Reported bugs and feature-
requests will be treated 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 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 this systems we will do
so. However, these packages are commonly untested and not known
to run correct (until we get feedback). We will try to fix
reported bugs for this systems - if the reporter is willing to
provide further information and test provided patches.
Grade C: At the moment, we don't care or are unable to build/test for/on
these platforms.
** Note: We would love to support *BSD, Arch and Gentoo.
If you can provide us with feedback, log files or
if you're able to support us creating ports - feel
free to contact us.
3.2.) Requirements
------------------
* A grade A or B Linux (C if you're a brave or going to volunteer)
* A running instance of at least one daemon and one or more clients
* A working webserver with PHP 5.x and PHP-MySQL support (apache is preferred,
others will be fine too, but might need further configuration steps)
* Access to the weblookerd-database. Either local or remote
* root-privileges (or equal) to make changes in your webserver-configuration
3.3.) Using a package
---------------------
Installing the webinterface 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 make the proper
changes in your apache configuration (if you're using apache)
After downloading the appropriate file for your platform, open a terminal
and cd in the directory where you've 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. From now on you need
to be root or prefix the commands with sudo.
dpkg -i weblookerui_0.2.1_noarch.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 using RPMs) we provide *.rpm packages,
which will put all necessary files in the correct location, create the user and
make the proper changes in your apache configuration (if you're using apache)
After downloading appropriate file for your platform, open a terminal
and cd in the directory where you've 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. From now on you need
to be root or prefix the commands with sudo.
rpm -Uvh weblookerui-0.2.1-25.1.noarch.rpm
alternatively you can use (try) yum:
yum localinstall --nogpgcheck weblookerui-0.2.1-25.1.noarch.rpm
You have to adjust the filename of course, all commands are examples.
3.4.) Manual installation
--------------------------
If you decided to go the brave way you should be familiar with your filesystem,
file-permissions and your webserver-config.
Basically it's the typical stuff:
mkdir /usr/share/weblookerui && cp -R * /usr/share/weblookerui/
chmod -R 755 /usr/share/weblookerui
chown -R root:httpd /usr/share/weblookerui
configure your server to use the above location (see weblookerui.conf)
This is actually a brief example only. You have to adjust the permissions/user
and possbile the paths too (you may have noticed, that I'm a bit lazzy regar-
ding this explanation - simply use the package or know what you're doing ;)).
After the completion of the above tasks you should come back and proceed
with 4.) Configuration.
4.) Configuration
=================
4.1.) Database
--------------
The easiest way is to simply visit http://127.0.0.1/weblooker/install
(assuming you installed it on the local system) and follow the displayed steps.
If you do so, delete the install folder afterwards and continue reading at 5.).
If you've decided to go the manual way continue reading.
If you have already another weblooker-package installed, there's a chance,
that you'll find your configfile in a location like
/etc/weblooker/weblookerui.conf
However, the configuration-file is always in a location like:
/usr/share/weblookerui/includes/config.inc.php
You have to edit that file and adjust the values for the database connection.
Although the file is self-explaining, below follows a brief description about
the values:
$dbhost = "localhost";
-> the address of your database, might also be an IP-address or another
url. Note, that this must be the same database as configured in the
weblookerd-configuration.
$dbuser = "weblooker";
-> the user with the privileges to access the database (not necessarely
a system-account). You can probably use the same as configured in
the weblooker-configuration.
$dbpass = "test";
-> the password for the above user. In some enviroments it's empty.
Note: if the user above is also present as a system-account - the
passwords are not necesserality the same!
$dbname = "status";
-> the name of the database. If you used the template from the web-
lookerd package it should already match.
$key = "1hkjsahfde78fhKJHkjsfhwe987hfsalifhjJHGAJFDLS";
-> this is a very important value and you have to read the following
very carefully! The key is used to make the user-password safer.
The user-passwords will be stored using a hash. A hash is some sort
of one-way encryption (that is technically not correct, but should
help you to understand the basics). The important thing about hashes
is the fact, that the same input text will always result in the same
output-hash. If a user tries to login, the system creates a hash of
his input and compares it with the stored hash. The reason for this
whole story is the simple fact, that a hash (in theory) can not be
reverted (you can't get the password from the hash). So neither the
administrator nor a bad guy with database-access will be able to get
the user passwords. Since the bad guys are usually also very smart,
there are so called "rainbow-tables" out there, these are list of
already hashed passwords, making it incredible easy to compare these
hashes with the "stolen" hashes and therefore get the password
associated with that hash. To prevent this the hashes are salted
with a random string, making the rainbow-tables useless.
The above key is such a salt, this will lead in exactly two impor-
tant facts you should know:
1.) change the key to some random text, once, NOW
2.) never, ever change that salt - it'll make all stored passwords
useless. You won't be able to recover them and your users
won't be able to login. The only exception is if you get hacked,
than you MUST change the salt and force your users to set new
passwords - good luck! ;)
Delete the /install folder.
5.) Using weblookerui
======================
To use the webinterface simply browse to http://127.0.0.1/weblooker (assuming
you installed it on the local system). The webinterface should be
self-explained.
To login use the following values:
!!CHANGE JET. No not later ;)!!
User: weblooker
Password: admin
5.1.) Menu explanation
-----------------------
After you are logged in you see only the top level menu.
with this 2 entrys:
|* show
| On the show menu informations about the monitored services and
| PC's are presented.
| There is no option to change some thing.
|
|---|
| |* Services
| | Here you can check the status of various monitored services.
| |
| |* uptime
| | Shows the downtime of the monitored servers with a statement of the day and duration.
| | Under each computer is also the entire downtime in the monitored period in hours and
| | in percentage.
| |
| |* uptime services
| | Shows the downtime of the monitored services with a statement of the day and duration.
| | Under each services of one computer is also the entire downtime of the service
| | in the monitored period in hours and in percentage.
|* Settings
| Ong zhis menu entry are all options to administer the weblooker service.
|
|---|
| |* Service
| | Here you can add services that should be monitored to the different servers.
| |
| | Entrys:
| | - Host -> The server on this the service should be monitored.
| | - Searchtext -> The !!exact!! name of the service that should be monitored.
| | With this will be searched after the running processes in
| | the / proc directory.
| | - Monitor -> If checked it will be monitored else it is only a entry on
| | the DB.
| | - Servicename -> The name of the services which will be shown .
| | For the same services must always be the same if you want a
| | correcte table structure.
| | - Monitor w. telnet -> If checked the service will checked with telnet on the
| | entered port.
| | - delete -> Deletes the entry with all of its collected data from
| | the database.
| | - Port -> Is used for telnet test.
| | - Applay setting -> ... ;)
| |
| |* Language
| | In order to make language settings.
| |
| |---|
| | |* Menu
| | | To set the web interface language.
| | | This is possible for each user individually.
| | |
| | |* Overviewsite
| | | To set the language of the main site.
| | | Only User with root rights (User with ID 1 or user on group with ID 1) can do this.
| |
| |* Rights
| | In this menu you can find the entire right procurement.
| |
| |---|
| | |* Groups
| | | Here you can create/delete groups and assign them various computer with
| | | different rights.
| | | !!Root and Admin group can't delete!!
| | |
| | | If you select on group you can add them a computer:
| | | Entrys:
| | | - Computer -> The name of the Computer that should be added to this group
| | | - View -> Give the right to view this computer .
| | | View is the minimum prerequisite that the client can do
| | | his job for this reason is preselected.
| | | - Write -> With this rights the group can add services that should
| | | be monitored to the pc.
| | | - Delte -> With this rights the group can delete this PC.
| | | - Create -> If one entry has this rights the group can add new pc's.
| | | - Web -> With this rights the group can change the options which
| | | Information is showed on main site.
| | | - Android -> Future setting for android client not in use now.
| | |
| | | - delete -> Delete this entry from group.
| | | - Applay setting-> ...
| | |
| | |* Users
| | | Here you can create user groups and assign them different and pc's.
| | |
| | | Settings for user.
| | | Entrys:
| | | - Username -> ...
| | | - Passwd -> ...
| | | - Password confirmation -> ...
| | | - Groups -> You can select N groups to one user.
| | | - delete -> Delete user from database.
| | |
| | | Settings for add a pc to user.
| | | Entrys:
| | | - Computer -> The name of the Computer that should be added to this user.
| | | - View -> Give the right to view this computer.
| | | View is the minimum prerequisite that the client can do
| | | his job for this reason is preselected.
| | | - Write -> With this rights the user can add services that should
| | | be monitored to the pc.
| | | - Delte -> With this rights the user can delete this PC.
| | | - Create -> If one entry has this rights the user can add new pc's.
| | | - Web -> With this rights the user can change the options which
| | | Information is showed on main site.
| | | - Android -> Future setting for android client not in use now.
| | |
| | | - delete -> Delete this entry from the user.
| | | - Applay setting-> ...
| | |
| | |* PCs
| | | Here you can create and edit PCs.
| | | Entrys:
| | | - Computer -> Exact name of PC which should be monitored.
| | | !!Must be the hostname of server!!
| | | - delete -> Delete the PC with all his collected data from database.
| | | - Applay setting-> ...
| |
| |* Main site text
| | Here you can adjust the text that is displayed on the main page.
| | For example, disorders and similar.
| | This text will be displayed on the user specific page too (onlyFrontview?user=USER)
| | !!Only root can do this!!
| |
| | Entrys:
| | - Width -> The width of the text box in percent
| | - Heigth -> The height of the text box in percent
| | - Margin -> Distance to the left and right in percent
| | - Border -> Border of the text box
| | - 0 No border
| | - 1 Normal border
| | - 2 Big border
| | - Space above -> Distance in pixels from the table above
| | - Text flow -> Type of textflow
| | - Text on -> ...
| | - Applay setting -> ...
| |
| |* Main site
| | It can be set for each computer which informations are displayed on the main site.
| |
| | Entrys:
| | - Host -> Name of host
| | - Service status -> Show the Status of services (on,off,away,...)
| | - Uptime services -> Show the Uptime of the service in percent
| | - Host Status -> Show the Status of server (on,off,away,...)
| | - Uptime host -> Show the Uptime of the server in percent
| | - Show Host -> Show the host on mainpage
| | - Applay setting -> ...
| |
| |* Template
| | Here you can chouse the template that you want do use by default ther is ony on.
| | !!Only root can do this!!
5.2.) User specific monitoring web page
---------------------------------------
It is possible that each user has his own page
To use these functionality you must call the php file "onlyFrontview" with
the user as a parameter:
- Example: http://YourDomain/weblooker/onlyFrontview?user=foo
By default the web interface can be achieved only via localhost.
So you must edit the apache settings (/etc/apache2/sites-available/default)
You must edit the line:
- Allow from 127.0.0.1/255.0.0.0 ::1/128
- apachectl -k graceful
!!This change results in a higher risk !!
5.3.) Special groups
--------------------
As Default weblooker has two groups:
-root
Root can do all so don't use it for normal client/server connection!
-admin
Admin can see all pc's and the configuration from them.
6.) Troubleshooting / Bugs
==========================
First, if you think you found a bug, take a look in the file called BUGS first.
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 much effort in this release to provide you with all necessary tools for
finding and troubleshooting possible problems. Since this is a daemon, 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 database-connection:
- check the config.inc.php for the entered values
- check if the database is running and containing the expected tables/data
* Webserver configuration:
- check if your webserver knows about the path and it's files
- check if the permissions are correct, i.e. the server is able to access
them (read and perhaps execute)
- check if your PHP is working, if you're using modules like FastCGI there
might be additional steps required
- check if your PHP is able to connect with your MySQL (php-mysql)
- take a look in the server logfiles, common locations are something like:
/var/log/httpd/error_log
/var/log/nginx/error.log
/var/log/php.log
- keep in mind, that by default, only localhost is able to see the site.
If you're trying to reach the site from another host adjust the values
in the /etc/httpd/conf.d/weblookerui.conf to allow additional access
6.2.) Installation
------------------
If you're unable to install the package for your distribution, be sure that
a.) 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)
b.) check if the package is already installed
- *.deb: dpkg -s weblookerui
- *.rpm: rpm -qi weblookerui
c.) 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
