Big Brother help
Help

Big Brother - the bb-hosts.cfg file

BB is controlled almost entirely by the bb-hosts.cfg file. Its format was based on the UNIX /etc/hosts file, with modifications.

A sample BB hosts file: 

#
# SAMPLE bb-hosts.cfg file.
#
group-compress MacLawran Servers
0.0.0.0		www.maclawran.com # BBPAGER BBNET BBDISPLAY ftp dns smtp pop3 
192.168.17.80	bobo.root.sh # ftp smtp pop3 http://bobo.root.sh/ dns 
192.168.17.80	bobo.login.sh # ftp smtp pop3 http://bobo.login.sh/ dns !nntp
page sean  Sean's Universe
192.168.17.6	home.somewhere.com # ftp pop3 http://home.somewhere.com/ 
192.168.17.7	away.somewhere.com # ftp pop3 http://away.somewhere.com/ dns smtp
192.168.17.61	fromhome.somewhere.com # dialup
#
summary bigbrother.dev1 www.maclawran.com http://www.maclawran.com/bb/bb.html
summary bigbrother.dev2 www.maclawran.com http://www.maclawran.com/bb/bb2.html

Lines are of the format:

IP-ADDR		HOSTNAME	# DIRECTIVES

IP-ADDR: XXX.XXX.XXX.XXX

HOSTNAME: 	if FQDN="TRUE"  host.domain.com
		if FQDN!="TRUE" host

		FQDN (display with Fully Qualified Domain Name) is a
		variable that you set in the etc/bbdef.cfg file.

Directives


When BB starts up, the first thing that happens is that it looks for itself in the bb-hosts.cfg file. Once it has found its line in the bb-hosts.cfg file, it knows what it has to do. The roles are:
    BBDISPLAY - this host receives incoming status reports and generates the bb.html and bb2.html web pages. There may be more than one BBDISPLAY if you want redundancy. This directive should always be specified on the host entry of the BB server.

    BBPAGER - this host receives requests to notify admins and processes those notification requests. There may be more than one BBPAGER as well, for redundancy. Of course, you'll be notified more than once per problem.

    BBNET - this machine performs all network tests for each protocol listed in the bb-hosts.cfg file for each host. Many hosts can act as a BBNET. If you do have more than one BBNET, make sure that the bb-hosts.cfg file only contains the hosts that you will test against. You must be very careful because if a host is tested by many BBNETs then the status display for the services on that host will only show that last test status received. You may get errors for that host even though it shows green, it's just that another BBNET sent a status message afterwards and that message returned OK. On the other hand you may want to have tests from different location.

    BBRELAY: - the host defined in the BBRELAY directive will be relayed all message received by the host defined in the current entry:
    1.2.3.4 bbhost # BBDISPLAY BBRELAY:2.3.4.5

    the bbhost that is a BBDISPLAY will relay all of its incoming messages to the 2.3.4.5 host. Note that the current host does not have to be a BBDISPLAY. It can be a lone BBRELAY:
    1.2.3.4 bbhost # BBRELAY:2.3.4.5

    Note that for this setup, all BB clients must assume that 1.2.3.4 is a BBDISPLAY.
    This feature is useful to redirect status messages to a central location as well as keeping a local copy. It is also helpful if you need to move the BBDISPLAY but don't have time to modify all clients with the new BBDISPLAY address. Note that you can specify multiple BBRELAYs.


The bb-hosts.cfg file also controls the display format of the web pages. This is done using the keywords page, subpage, group, group-compress and group-only.

    BB always creates two HTML pages: bb.html/bb2.html. When the page directive is encountered, BB will then create a new HTML page until another "page" directive is found and will save the output from that point on to that new HTMLpage. It will keep a pointer of the new sub page in bb.html. The first argument is the directive, the second one is the name of the page (i.e. nyrouters) and the remaining arguments is the caption that will appear in bb.html when it creates the link to that page. Always place your page directives after all hosts that you want to appear in the bb.html page. When you use a page directive then all subsequent ouput will be in at least on page. "subpage" enables a second level of pages. A subpage directive is effective within the current "page". N.B. summaries and dialup directives will always appear on bb.html/b2.html and not in any HTML subpages. The page keyword creates a new display subpage. The format of the page/subpage keywords is:
    page    page-name       Whatever you'd like the page title to be
subpage subpage-name    Whatever you'd like the subpage title to be

    group, group-compress and group-only The Web display may be broken into tables to create a more aesthetic and sensible display. It's also much faster to load small tables, than one giant table. So consider grouping your bb-hosts.cfg entries logically and separating them using the "group" or "group-compress" directives. Group-compress only displays the columns that have data. Group-only enables you to create a group table with specific columns. The format of the keywords is:

    group    Whatever you'd like the group title to be
group-compress    Whatever you'd like the group title to be
group-only  conn|cpu|disk     Whatever you'd like the group title to be
    The group directive defines a block of hosts to be grouped in the same HTML table. All hosts lines following the group directive, until a new group/group-compress is defined, belong to that group. The text that follows the directive is the title given to the HTML table. Note that you can embed HTML code in the title: Italic / H3, but use with caution.

    Similarly, the MKBBROWFONT and MKBBCOLFONT variables in skins/.../bbskin.cfg can also be adjusted to change the look of the output.

summary The summary keyword allows you to send a summary of the current display to another remote instance of Big Brother. The current overall status of this BBDISPLAY will appear as a dot of the same color. The user of the remote BBDISPLAY will be able to click on that dot, and will be brought to this instance of Big Brother.

In this manner, hierarchical summaries may be created. The format of the summary command is: 

    summary bigbrother.dev1 www.maclawran.ca http://www.maclawran.ca/bb/bb.html
   |         |       |          |                      + URL of this BBDISPLAY
   |         |       |          + machine or IP address to send info to
   |         |       + column name
   |         + row name
   + keyword

dialup The dialup keyword (not to be confused with the other dialup tag which displays a clear button if the host is down) is used to specify connectivity for a bank of modems. The 2nd parameter is the name to be displayed on the display page. The 3rd argument is the starting IP address of the modem bank. The last argument is the number of modems on that bank. (this is not yet implemented) 

    
dialup modem-bank 204.19.116.20 4

Testing network services

Next, network services to be tested can be listed on a bb-hosts.cfg line. These tests will be performed by the host(s) defined as BBNET.

BB can check any simple TCP-based protocol and has native support for the following protocols: 

    http ssh ssh1 ssh2 telnet ftp pop pop2 pop3 smtp telnet
If the protocol is text-based and simple, then just specify it on the host line. The name of the TCP service must be valid and resolvable, that is, the port ID can be determined, it must be defined in the services file (\System32\drivers\etc\services).

Note that protocols must not only exist in the BBNETSVCS variable but also in the network services file (or equivalent), and their spelling must match. The pop3 service is sometimes listed as pop-3 in the services file... this causes great confusion and pain ;) The services file is configuration file that is part of your OS system. Note that you can still test protocols that are not defined in the services file, the steps are defined further below.

If you need support for a particular protocol, hit the bbnt mailing list or the FTP site, it may already be available.

A service may be prefixed with ! to indicate it shouldn't be running. This option is especially useful on secure networks to make sure certain protocols aren't left open accidentally, i.e. !telnet

You can also prefix a service with ? i.e. ?ftp
This specifies that the service is considered a dialup service and that it the test fails then it should generate a clear status to indicate that it the service is offline.

Here's some more information for the network test:

    http://www_path - The host is tested for http connections using the www_path

    https://www_path - The host is tested for https connections using the www_path
    (requires lynx: http://lynx.browser.org/ or curl: http://curl.haxx.nu/ )

    Note that you can specify multiple URLs by joining the URLs with '|':
    		http://www_path|http://www_path1
    or by specifying them individually: 
    		http://www_path   http://www_path1

    ftp - Test for ftp service
    smtp - Test for smtp server
    pop3 - Test host for pop3 server
    telnet - Check telnet service
    ssh - Test ssh server
    nntp - Test nntp news server
    telnet - Test the telnet service

    Check \System32\drivers\etc\services for the proper service name. Any text based service can be checked by setting the service name as the directive and adding in the list of services in the BBNETSVCS of the bbdef.cfg file (don't forget to stop/start BBNTD).

    You can add qualifiers to a test for a network service:
    :s - Silent mode - connect to service port but don't establish a protocol conversation
    :q - Quiet mode - Run regular network test but return only the result of the test and not protocol conversation. (Currently unavailable)

    To add your own protocol to test (and as long it's text based or you use the :s qualifier), just add a directive in the following manner:
    123.123.123.123 some.host.com # newtest:1234
    This will create a test called 'newtest' and it will test on port 1234. Remember that 'newtest' must be defined in the BBNETSVCS variable of the bbdef.cfg file. The :s and :q qualifier can also be applied.

    Here's some more directives that can be entered:
    dns - Checks for name resolution server
    noping - Don't do ping test for this host
    noconn - Don't do ping test for this host and don't generate a clear dot
    dialup - If host is unreachable then display it with a clear button instead of a red button

    DHCP support via 0.0.0.0 BB supports DHCP addressing. Just put 0.0.0.0 in the IP address field, and the hostname will be used for testing. Note that you can use the testip directive to force the test to use the IP address (unless it's 0.0.0.0, then it'll use the hostname).






Quest Software
Copyright © 1997-2003 Quest Software, Inc - All Rights Reserved