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