BBMAP : STATUS MAP for BB4

BBMAP is a set of PHP pages (mainly) that tend to give a status map capacity to Big Brother.

Current version V2.5 (27/11/2006).

REQUIREMENT

Well, I've done that with PHP/GD and the Great Help of Henrik Storner (bbgen author)!
As usual, you have the right to use it, modify it, distribute it as long as you let my name with the product. For me, under GPL ! You need the following:

a working BB4 master server (bbdisplay one) under Unix (tested for the moment under Linux) where you will put bbmap

or New with a working Hobbit master server (the following is working in the same way for both cases).
a web server that enables PHP (tested with Apache 1.3, some users say it is ok with Apache 2)
PHP version >= 4.1 (tested with PHP 4.3 which seems to be more stable than 4.1)
- use gzip (libz) support if enabled in PHP and in your system (not mandatory to get bbmap working)
- libjpeg support in PHP and in your system (not mandatory to get bbmap working without jpg pictures)
- freetype support in PHP (V2 prefered) (www.freetype.com) and in your system
- libpng support in PHP and in your system
- GD library (picture library) support in PHP. Should worked with GD >= 1.3 but tested with GD >= 2. PHP4.3 (at least) comes with his own version of GD (V2) and it's ok with it. If you don't used the given GD library in PHP, you need to have it on your system and supported by your PHP
bbgen >= 2.5 (see INSTALLATION as you can use bbgen only for bbmap if you want, even if I personnaly prefer to use bbgen also for the bbdisplay part for bb4 itself)

Of course, there could be some bugs and/or compatibility issues. As far as I know, it works under IE 5 and next, Netscape 4.79 and Mozilla 0.99 (tested). Under Netscape 4.79, it seems that javascript doesn't work for color select, but this is not mandatory since it can set manually too through the interface. The detailed status when moving the mouse on one host in the map is working now on all platform. Not tested on Opera (someone can ?).
There will not be any problem with the BB4 configuration (meaning that if something goes wrong, it will be only with the map feature, not with BB4 since nothing is done inside BB4 itself).
(frederic bregier : )

DOWNLOAD

You can download version V2.4 from here the tar.gz package for BigBrother, or the version V2.5 from here the tar.gz package for Hobbit.
The only difference between these two versions is that the first one support BigBrother and the second one support Hobbit by the package given by Daniel J McDonald. See the following page to see what is the patch that was applied.
You can download picture part (V2.1 since it should not change) from here the tar.gz package for picture only .

Here is the main idea of these scripts:

the final display is a map with a map background that can be blank or a picture (png format)
inside you will find host or hostgroup (group of hosts) or submaps (link to another map) with a shape (circle, diamond, ... or file shape as linux.png), a color status for each node and the map
when the mouse is over a node: simple status (java code)
when click on a node: get the detailed status using bbgen
the hosts, hostgroups and submaps and the services checked are specified for each map (so you can have as many map you want with as many aspect you want : dba profile, user assistance profile, system profile, ...)
There is a big part of the scripts that tend to ease the configuration of a map (setting parameters, fonts, colors, host position, services checked, ...). Everything as possible through the web.

INSTALLATION

untar gzip both packages (both img and code archives bbmap-x.y.tar.gz and bbmap-img-2.1.tar.gz) The image archive should not vary except if someone wants to propose some pictures....
You can update an existant bbmap by extract only the code package (new name for the install directory as of the version), then copy the necessary files from your existant bbmap into the new one. Those files should be:
- bbmap-orig/globalmap.cfg
- bbmap-orig/admin/*.cfg
- bbmap-orig/map/*.map (map files)
- bbmap-orig/map/*.png (background pictures)
- bbmap-orig/base/*.png (logo pictures)
- eventually if changed by you in bbmap-orig/: statusbbgen.sh statusreturn.sh fullstatusreturn.sh
in bb4/www you can create a link to bbmap install directory with the name "bbmap"
(bb4/www/bbmap is a link where reside this bbmap install directory where is this README.txt)
OR you can place where you want in your Web server configuration the bbmap directory (for instance mywebserver.com/bbmap)
change of course the access rights to the bb4/httpd user according to what you've done for bb4 (read to all and add write access to bbmap/tmp and bbmap/map/*.map and bbmap/admin/*.cfg)
create an index.php in bb4/www/bbmap as you want (for example: symbolic link bbmap/index.php to bbmap/selectmap.php) or create a bbmap/index.php as an access to all sub directories created in the last point of this install procedure (as a menu) - based on subpage example -

change the bbmap/globalmap.cfg as necessary (copy from bbmap/globalmap-DIST.cfg), mainly:

 

           ; where bbvar directory is
           bbvar = /usr/local/bbvar
           ; where bbmap is with ending '/'
           bbmap = /usr/local/bb4/www/bbmap/
           ; the web gif directory (bkg-red.gif ...) with ending '/' as in web access (http://xxx/bb4/gifs/bbkg-red.gif)

           bbgif = /bb4/gifs/
           ; the web base directory of bbmap with ending '/' as in web access (http://xxx/bb4/bbmap/index.php)
           bbwebmap = /bb4/bbmap/

           ; what is the script to test status (in case better test can be done)
           statusreturn = /usr/local/bb4/www/bbmap/fullstatusreturn.sh
           ; script to generate the bb4 page with bbgen (need bbgen 2.5)
           bbgen = /usr/local/bb4/www/bbmap/statusbbgen.sh
	   ; set this to username:passwd if you put a .htaccess (Apache) or other way to access
	   ; to the bbmap main directory (use at least an admin user)
	   userpasswd =
	   ; example userpasswd = admin:mypassword

change the bbmap/statusbbgen.sh as necessary, mainly:

            BBHOME=/usr/local/bb4
            BBSKIN="/bb/gifs"
            TEMPLATE="map"

change the bbmap/fullstatusreturn.sh as necessary, mainly:

           BBVAR="/usr/local/bbvar"

           (note: I keep statusreturn.sh which uses a different way to compute the status.
           I believe the fullstatus is better, but you can still use the other one.

	   Just change the name in globalmap.cfg and change also the same BBVAR in statusreturn.sh)

	   TAKE CARE THAT THEY DO NOT REQUIRES THE SAME ENTRIES SO DON'T COPY ONE ON THE OTHER!

verify symbolic lynks exist in bbmap/admin to files in bbmap/

                bbmap/admin/ directory   to same file in bbmap/
                globalmap.cfg
                initiate.php
                initiatesubmap.php
                initpostserial.php
                maparea.php
                redirect.php
                serialize.php
                sjava.php
                status.php
                statussubmap.php
                map (to the directory bbmap/map)

create some bbmap/map/*.map files (as statusmap.map given or even empty.map). Note that an empty.map should contain at least "SERVICES = none". Take care to have NO RECURSIVE MAPS (Map1 -> Map2 -> Map1 for instance)
as the administrator (using bbmap/admin/selectmap.php), configure your maps
create if necessary subdirectories (as bbmap/subpage) containing one file (index.php) with the necessary settings (see example in bbmap/subpage/index.php)

Done!

It is not so simple, I agree. You need to try a bit to understand how to use it, but I tried to make as easy as possible, and as configurable as possible.

Whenever you're going into problem, here are some quick help points:

Change the line in initiate.php, initiatesubmap.php and initportserial.php :

          error_reporting(E_ERROR);
	  by
	  error_reporting(E_ERROR|E_WARNING|E_PARSE|E_CORE_ERROR|E_CORE_WARNING|E_ALL);


	  Then take a look at the log of PHP, generaly in /var/log/php.log 
	  (see your php.ini to find where your log file is)
	  Generally, you will find a lot of info to understand why it is not working as expected.

Recheck WRITE access to bbmap/tmp and bbmap/map/*.map and bbmap/admin/*.cfg

If you have access to everything except the picture (generally a crossed picture in red), then you have probably a problem with GD support in PHP
If you have access correctly to a map but having everything in purple, then you probably either set wrongly the directory of BBVAR or either have a protected directory (check read access) or protected html directory (for submap check the user:passwd setting in the map file)

In order to get security access after every map are configured (TRY THIS AFTER GETTING BBMAP WORKING):

put .htaccess (Apache) or other ways from your web service to allow all users (including admin) to access every files in bbmap/, bbmap/base, bbmap/map, bbmap/tmp and only allow the specific user in bbmap/"subpage" (for instance: bbmap/dba, bbmap/assist, bbmap/director, ...)
For instance: admin, dba, assist and director access to everything, but dba only access to bbmap/dba, assist to bbmap/assist, ...
Make one general user (bbmap user for instance) that access to bbmap/, bbmap/base, bbmap/tmp, bbmap/map, not to bbmap/admin.
then only put admin access in bbmap/admin and admin in every access (bbmap/dba for instance)
you can also make specific web access for your users as follow:
http://yourdisplayserver:whateverport/index.php
or http://yourdisplayserver:whateverport/whateverdir/index.php
as long as you specify in the index.php (from example subpage/index.php) the necessary arguments (server, port, access_path_to_bbmap)
(index.php will read through another http request the "real" page so as to hide the location of everything as possible)
Then, in globalmap.cfg, fill the userpasswd variable as the following : userpasswd = bbmap:passwd where bbmap is the user you allow to access to bbmap/, bbmap/base, bbmap/tmp and bbmap/map, and passwd is the aasociated password. By setting this, bbmap will use this value to get access to specific web pages (php code) to fill in values for instance of submap (http requests). So if you have purple with "NaN" as service detail in popup, it can be because of a bad access (bad user, bad passwd, ...).

You can also use bbgen only for bbmap (that is to say not for your bb4 kernel). Of course, I will not encourage this since bbgen seems to be a really good improvement of the bbdisplay part of BB4. But, however, some user still wants to use the "official" way so here is the point to get bbmap working :

First Install bbgen somewhere, let say /directory/bbgen-x.y/

Then change the file statusbbgen.sh as follow:

       #change ${BBHOME}/bin/bbgen --template=${TEMPLATE} --embedded 2> /dev/null

       # to

       /directory/bbgen-x.y/bbgen --template=${TEMPLATE} --embedded 2> /dev/null

Of course, make the bbgen program executable from the web server
That's it... (note that you can change the template here bb to whatever you want)

HOWTO CREATE MINIMAL (BB)RELAY

As a BBRELAY would do, the BBMAP (also BBDISPLAY so running bbd) will receive only the status of servers.services if there are any changes and only for those changes. That is to say it's an evenemential send and not the usual way BB4 does. The interest is to keep low the bandwith required if you have a lot of servers.services on the network and you still want to be informed of what is going on. The status sent is very short (server.service status date_time #base address of the original BBDISPLAY).
Of course, pay attention that bb4/etc/security allows your main BBDISPLAY server to receive from those BBDISPLAY hosts.
This way is not "compatible" with BB4 standard way of doing (no modification of bb-hosts required) so don't expect to have your normal BB4 displaying the result for all of your servers. It will not break your BB4 hopefully !
This way enables you to have the BBMAP able to see any server.services you want, if you have the right to. BBMAP then uses bbgen to generate the BB4 web page and the color point will transport you to the original BBDISPLAY (so that's why we don't need to send the full status).
Finally, someone can do something close (perhaps with bbgen) to produce directly BB4 web pages with this new feature.
Now here is the way to install it for BBMAP.

On a "sub" BBDISPLAY (not the BBMAP one), put the scripts statusget.sh and statusloop.sh (from bbmap/RELAY) into bb4/ext and adapt them to reflect your organization
Mainly, replace:
1. In statusloop.sh: /usr/local/bb4/ext/statusget.sh by the right place where you put this script (can be anywhere).
2. In statusget.sh: FINALHOST="w.x.y.z" by the IP addresse of the BBMAP master server and LASTCHKDIR="/usr/local/bb4/tmp/" by the location of a TEMPORARY directory with write access (here the bb4 tmp directory but can be anywhere).
3. Modify statusloop.sh if needed (for instance the sleep delay)
4. Add the file LASTCOUNT.txt in the LASTCHKDIR directory with a 0 inside ("echo 0 > LASTCOUNT.txt") with write access for the bb4 user
5. Create LCKCONFIG.txt in BBHOME/etc/ (according to the CONFIGFILE variable) with one line by host assumed by the current BBDISPLAY following by a list of services as below:
  host1:service1,service2,service3
  host2:service2,service4
  ...
  where hostx = name of host as in bbhost and servicex as in bbweb page (not as in bbhost) for instance service = conn or oracle or cpu...
6. Then add the following command: "/whereyouplacedthescrip/statusloop.sh > /dev/null 2>&1 &" either in the bbrun.sh or anywhere as you convenience or execute it by hand as bbuser.
On the main BBDISPLAY server (BBRELAY one or hypervision)
1. check security in bb4/etc/security to allow sub-BBDISPLAYs to send status to this one
2. stop here for bbmap (more exactly, now start to configure a map)
3. or by hand, here is a way to start with using bbgen to create your own web page
  1. creating a particular bb-host file as you want. For instance here is what bbmap produces:
    group-only service1|service2|service3 your_groupname
    0.0.0.0 host1
    0.0.0.0 host2
    ...
  2. running such commands
    BBHOSTS=yourfile
    export BBHOSTS
    TEMPLATE="your_template_if_different_than_standard"
    ${BBHOME}/bin/bbgen --template=${TEMPLATE} --embedded > your_page.html
  3. this will produce web page as needed but you will need to take care about the html link (see status.php for what bbmap is doing to correct th web links)