phpBBHC - PHP Big Brother Hosts Configurator

[top] [download] [installing] [using phpBBHC] [contact]

Where am I? What is this place?

[top]
Welcome to the official homepage of phpBBHC! 

phpBBHC is a collection of PHP scripts and one C program to configure hosts
for the Big Brother network monitoring software. It doesn't cover all the
possible settings for Big Brother's hosts file but it should be enough for
most demands.

Ammendment: Big Brother has been pretty much replaced by Hobbit. I haven't
got around to using Hobbit yet but I've heard it's pretty backwards compatible
with Big Brother's configuration and scripts. I've heard of successful stories
of phpBBHC being used to configure Hobbit.

Download & CHANGELOG

[top]
Version 0.3: Released Feb 2007
	- Fixed the bug which prevented you from adding multiple hosts at once
	  without saving the changes each time
	- Fixed the bug which prevented you from deleting multiple hosts at
	  once without saving the changes each time       
	- Fixed the bug which prevented you from including file names in the URL
	  (previously you could only enter http://www.hostname.org/ but now you
	  can enter something such as http://www.hostname.org/test.php). The
	  benefit of this is that you can create a PHP script or something to
	  test the connection to a database seeing as Big Brother doesn't include
	  support to check database connections (see the README for more info
      	  on this little hack with an example script).
	- Added a button to check/uncheck all the checkboxes for deleting hosts

Version 0.2: Released May 2005
	- Added support for wms service (an external module I wrote for Big
	  Brother to check the status of Windows Media Streaming servers, available
	  at http://www.hart.co.jp/gnu/ (number 6)). 

	  You can get bb-wms.pl here.

Version 0.1: Released December 2003
	- Initial release

phpBBHC 0.3: by http by ftp

phpBBHC 0.2: by http by ftp

phpBBHC 0.1: by http by ftp

Installing & Configuration of phpBBHC

[top]
(Copied from the INSTALL file)

Prerequisites:
--------------

phpBBHC doesn't need much to run. Obviously you need a web server running PHP.
I developed phpBBHC on Free BSD and have also tried it on Linux. You shouldn't
have any trouble on any other Unix variants. If your system doesn't use the
standard Unix '\n' newline character then you might get some funny configuration
files. Other programs used include the common programs; wc, awk, dirname. It is
assumed these are in the $PATH environment variable that the web server uses.
It goes without saying you need Big Brother installed. Big Brother can be found
at http://bb4.com.

Unpacking:
----------

You've no doubt already untarred this package as you're reading this file, but
just in case here is the command you'll need to untar phpBBHC:

tar zxfv phpBBHC-0.1.tar.gz

I'll leave changing to this directory for you to figure out :-)

Configuring:
------------

You should configure (there's not much to do) phpBBHC before you install the
files to where they will live in harmony with Big Brother.

1. Find the uid (user id - a number) of the user Big Brother runs as. If your
   Big Brother installation was a pretty normal one, chances are this user is
   called "bb". You can find the uid by typing:

   id <user name>

   And you should get some output like:

   uid=1005(bb) gid=1005(bb) groups=1005(bb)

   It is the first number you want; 1005 (numbers might be different on some
   systems). Memorize this like your girlfriend's phone number or write it down
   if you're on of those forgetful types.

2. Know where Big Brother resides in your system. I will use /home/bb/bb.
   If you're lucky runbb.sh should reside here. If not find it and take note
   of its location. Check also that inside the bin directory here there is a
   script called bbrm, used to remove stale log files relating to entries
   and services removed from bb-hosts.

3. Open up bbcontrol.h in your favourite text editor.

   I'm a vi lover.

   vi bbcontrol.h

   Hint: to quit vi press the escape key, then type :wq to save and quit.

   There are only three parameters here to set.

   a) Change int bbUserUid = 0; to the uid you found in 1.

   b) Change the value of char *runbb = "/home/bb/bb/runbb.sh"; to the actual
      location of runbb.sh on your system you found 2. 

   c) Change the value of char *bbrm = "/home/bb/bb/bin/bbrm"; to the actual
      location of bbrm on your system.

  That's the C configuration done. Next we configure the PHP scripts.

4. Now edit (with the same or a different text editor, doesn't really matter)
   conf.inc.php.

   a) Change $bburl to match the full URL of where you access Big Brother
      on the web. Best to have the "http://" bit at the start.

   b) Probably the most important variable of all, set $bbhosts to the location
      of bb-hosts, Big Brother's hosts configuration file. Following our example
      this will be /home/bb/bb/etc/bb-hosts.

   c) Set $bbchkhosts to the location of where the bbchkhosts.sh script is.
      In our example this would be /home/bb/bb/etc/bbchkhosts. As a final check 
      to make sure you, or heaven forbid phpBBHC, hasn't stuffed anything up in 
      the newly created bb-hosts file phpBBHC runs this Big Brother script to
      check that bb-hosts is all hunky-dory with no syntax errors.

   That's all the configuration. Congratulations! You can now quit vi, do you
   remember how? Onto compiling and copying the files over to their final 
   destination.

Installing:
-----------

5. I developed phpBBHC on a Free BSD system and found that Free BSD does not
   allow the setuid function to work on shell scripts. I originally intended
   to use a shell script with the setuid bit set (if you don't know what setuid
   is just ignore this paragraph) so it Big Brother could be restarted from
   the phpBBHC interface. On most systems running Big Brother, the user that
   maintains it and the user the web server runs under will be different and
   a script being executed from phpBBHC will obviously run under the user of
   the web server but in order to run runbb.sh (the main script controlling
   Big Brother) one must be the Big Brother user. I overcome this by writing
   a small utility in C as binary programs can use the setuid bit. I also
   added functionality to run bbrm as the Big Brother user too, as when removing
   log files the owner of the files will not be the user the web server runs
   under.

   So enough of the background talk, tell me how I compile it! Easy.

   gcc -o bbcontrol bbcontrol.c

   I said it was easy. You should now have a binary program called bbcontrol
   in your current working directory.

6. Now we put phpBBHC to rest.

   Continuing to use /home/bb/bb as the place where Big Brother resides;
	
   mkdir /home/bb/bb/www/phpBBHC

   cp *.php bbcontrol /home/bb/bb/www/phpBBHC

   The files in /home/bb/bb/www/ should belong to the user the web server runs
   as. phpBBHC's files should be owned by the same user.

   cd /home/bb/bb/www/
   su (ie su to root)
   chown <web server username>:<web server group> phpBBHC phpBBHC/*.php

   Now we set the setuid bit for bbcontrol in two simple steps.

   cd phpBBHC-0.1
   chown <Big Brother user>:<Big Brother group> bbcontrol
   chmod 4755 bbcontrol

   And you're all done!

   Point your browser at Big Brother's home page but tag a "/phpBBHC" onto
   the end of the URL and you're away laughing.... muwahahaha.

7. Have a coffee and cigarette.

EOF

How do I use phpBBHC?

[top]
(Copied from the HowToUse file)

At the top of all web pages in phpBBHC there is a navigation bar with four
links; Hosts, BB Control, Status Page and phpBBHC Homepage. I break this
document into four respective parts.

Hosts:
------

This is core of phpBBHC. Unfortunately the HTML tables can get a big at times 
and might mean you've gotta do a bit of scrolling in your browser side to side
and up and down.

At the top of this page is a read-only text box which shows the contents of
the bb-hosts (Big Brother's hosts configuration file) since its last save.

Below that are two tables, the first one for adding a new entry to bb-hosts,
the second for modifying/deleting entries already in bb-hosts.

No changes will be saved until you click on "Save Changes" at the bottom of
the page. When you click on "Save Changes" changes are saved and then using
a shell script bundled with Big Brother the bb-hosts file is checked for errors,
any errors are printed to the screen. Please e-mail me if you find any errors
that might be a bug.

Usage is pretty self-explanatory. If a service (ie a network service like pop3,
telnet etc etc) is already configured to be checked by Big Brother, a tick will
appear in the corresponding entry row and service column. To disable checking
of a particular service, just untick it. If you want to delete an entire
host just tick the checkbox under the "Delete Host" column and it will be
deleted when you save the changes. You can add/delete http and https (ie http
over SSL) on the fly before saving the changes. Entries with the same hostname
will not be permitted, even if they've got different IP addresses. One will
just overwrite the others because phpBBHC uses associative arrays, but that's
just getting too complicated so we'll skip this technical part :-)

BB Control:
-----------

There are three links here that, assuming bbcontrol.c was compiled and installed
correctly, allow you to start, stop and restart Big Brother. Big Brother should
be restarted after you've made any modifications to the bb-hosts file via
phpBBHC. You can also remove stale log files corresponding to entries/services
in bb-hosts which have been removed. phpBBHC uses this functionality when it
detects a host or service has been removed for checking from bb-hosts.

Status Page:
------------

This link takes you to the URL where you have setup your copy of Big Brother.

phpBBHC Homepage:
-----------------

A link to the official phpBBHC homepage.

How can I contact the programmer?

[top]
You can contact me at wocky #NOSPAM# @ #NOSPAM# akibageeks dot com


[top] [download] [installing] [using phpBBHC] [contact]