MRTG and Hobbit or Big Brother integration

NOTES:

This page originally contained patches to implement some of what is documented below. I've moved the patches to a another section.
bbmrtg-v1.8 was released 2005-11-03. See the changelog for what's new.

Big Brother (or bb) is a tool for monitoring the availability of network devices, servers and much more. The default tool has a basic set of tests for checking connectivity, and a variety of services like web pages, ssh, telnet, ftp, and dns. In addition to the standard tests, many extensions have been written, and Big Brother has grown to become a central reporting tool for a wide variety of tests on all sorts of platforms. A large archive of the extensions and other tests for Big Brother can be found at www.deadcat.net.

Hobbit is a replacement for Big Brother that started out as the bbgen toolkit. It was written to support small and large networks. It offers enhancements such as integrated graphing of some tests and parallel ping tests (using fping) for performance. Hobbit is released under the GPL.

MRTG started as a tool for monitoring traffic on network links. Like Big Brother, it has been extended by the user community to monitor all sorts of other data beyond network traffic. I've used it for montioring memory and disk usage on Netware servers, traffic on network switches and servers, and Squid (a web proxy) traffic. Others have used the tool to monitor much more.

The bbmrtg.pl extension

This document deals primarily with the use of BBMRTG, a Big Brother extension that integrates the results of MRTG data collection and graphing into a Hobbit or Big Brother display as shown on the right. The integration is twofold:

the status is set based on bb-specific threshold values defined in the MRTG configuration file; and
the graphs generated via mrtg are displayed within Hobbit/bb if the status is above a certain level, or if preferred, always (i.e., a status of green or above).

Installation

The latest version of BBMRTG (bbmrtg-v1.8) should be available from deadcat.net. Note that it's been forked once already, although Chris Cook has managed to merge the forked changes back into v1.5, which is were I started from when adding features to create v1.6.

As already mentioned, BBMRTG is an extension, meaning installation of the script is a simple as copying bbmrtg.pl to your ext directory on the Hobbit/bb server, and on *NIX machines making it executable.

Configuration

Big Brother itself needs only a couple of changes to get bbmrtg working:

Add "EMBEDHTML" to the RUNOPTS variable in $BBHOME/etc/bbdef-server.sh on bb server.
Add bbmrtg.pl to $BBHOME/etc/bb-bbexttab (I used ": : bbmrtg.pl").

Hobbit needs only to have bbmrtg added to $HOBBITHOME/etc/hobbitlaunch.cfg as follows:

[bbmrtg]
    ENVFILE /opt/hobbit/server/etc/hobbitserver.cfg
    CMD /opt/hobbit/server/ext/bbmrtg.pl
    LOGFILE $BBSERVERLOGS/bbmrtg.log
    INTERVAL 5m

Configuration of BBMRTG is done in two locations: the script itself, and the MRTG configuration files. Global parameters are are defined at the top of the script, and are well documented there. Pay special attention to the locations of your libraries and configurations (the first two options), as the precise paths are needed in order for the script to work at all.

BBMRTG reads a standard MRTG configuration file and looks for specific additional parameters identified with a bb* prefix. These parameters tell BBMRTG how to label columns, what the threshold values are for each status colour are, and how to label the graphical output.

bb*host[ezwf]: hostname: This defines the hostname to which the MRTG results will be attached in Big Brother. The hostname value should exactly match the hostname defined in bb-hosts.
bb*svc[ezwf]: column_name: This parameter tells Big Brother the column name under which it will report the status of the data collected in this section of the MRTG configuration file.
bb*althost[ezwf]: hostname: This defines a second host against which to attach the MRTG results. The hostname value should exactly match the hostname as defined in bb-hosts. This parameter was added in v1.6 so that traffic on a switch interface could also be reported in a column next to the host attached to that interface. At this time the values are not flipped as they should be, so traffic-in and traffic-out are from the perspective of the switch, not the end host.
bb*altsvc[ezwf]: column_name: This parameter is the same as bb*svc above: it defines the column next to the host defined in bb*althost under which the status will be reported
bb*yellow[ezwf]: 70% bb*red[ezwf]: 85%: These parameters set the threshold values for setting the status that will be reported to Big Brother. Each value may take any of three different formats:

MAX: Warning/panic levels are checked only against a maximum value.
MIN:MAX: Warning/panic levels are checked against minimun and maximum values.
INMIN:INMAX:OUTMIN:OUTMAX: Warning/panic levels are checked against minimun and maximum values for both incoming and outgoing channels.

bb*unit[ezwf]: unit: This is the unit of measure for the data being collected. On a network port it may be bytes/sec; on a disk it my simply be MB.
bb*in[ezwf]: In bb*out[ezwf]: Out: Specifies the label used to identify the two values tracked by MRTG. You may want to change this if MRTG is watching disk or CPU utilization, or some other parameter for which In and Out are meaningless labels. The default values are 'In' and 'Out'.

cfgmaker Templates

Later versions of MRTG's cfgmaker utility supports the use of templates that simplify the creation of bbmrtg.pl ready configuration files. The following example can be used to create such a config file in one step. Paste the template into a file and call it with the cfgmaker command-line shown below.

# 
# Template for use with bbmrtg.pl script (integrates MRTG output into Hobbit/BigBrother)
# 2004-11-17 - Al Payne (apayne at pleiades.com)

# define how many interfaces are grouped into a column in Big Brother:
my $bbgroup=8;

# name the column in BB
my $bbintgrp=int($ifindex/$bbgroup);
my $bbsvc=sprintf("int%02d-%02d",
                  int($ifindex/$bbgroup)*$bbgroup+1,
                  (int($ifindex/$bbgroup)+1)*$bbgroup
                 );

$target_lines .= <<ECHO;
$default_target_directive
# bb* = Big Brother info
bb*host[$target_name]: $$router_ref{routername}
bb*svc[$target_name]: $bbsvc
bb*unit[$target_name]: bytes/sec
ECHO
if ($if_snmp_alias) {
    $target_lines .= <<ECHO;
bb*althost[$target_name]: $if_snmp_alias
bb*altsvc[$target_name]: traffic
ECHO
}
#$default_setenv_directive
my $setEnvLine = ($if_snmp_alias) ? 
   "SetEnv[$target_name]: MRTG_INT_IP=\"$if_ip\" MRTG_INT_DESCR=\"Interface to $if_snmp_alias\"" :
   "SetEnv[$target_name]: MRTG_INT_IP=\"$if_ip\" MRTG_INT_DESCR=\"$if_snmp_descr\"";
$target_lines .= <<ECHO;
$setEnvLine
$default_directory_directive
$default_maxbytes_directive
$default_title_directive
$default_pagetop_directive
ECHO

For additional examples of templates, see the Somix Technologies MRTG repository for a great collection.

After creating the above template, run cfgmaker as follows:

cfgmaker --if-template=<template_name> host -output host.cfg

If all goes well, you should end up with an MRTG config file that includes the information BBMRTG needs on each interface, as shown in the example below.

### Interface 1 >> Descr: 'EtherNet-Port-on-unit-1,-port:1' 
#   | Name: 'Port1' | Ip: '192.168.0.13' | Eth: '00-0f-1f-33-52-19' ###
Target[it-0560_1]: 1:community@it-0560:
# bb* = Big Brother info
bb*host[it-0560_1]: it-0560
bb*svc[it-0560_1]: int01-08
bb*unit[it-0560_1]: bytes/sec
bb*althost[it-0560_1]: 2k-citrix
bb*altsvc[it-0560_1]: traffic
SetEnv[it-0560_1]: MRTG_INT_IP="192.168.0.13" MRTG_INT_DESCR="Interface to 2k-citrix"

MaxBytes[it-0560_1]: 125000000
Title[it-0560_1]: Traffic Analysis for 1 -- it-0560
PageTop[it-0560_1]: <H1>Traffic Analysis for 1 -- it-0560</H1>

The resulting host.cfg file is the file you'll want to point bbmrtg.pl at. Edit the script and set $mrtgCfg to point to it. Alternatively, if you have several config files, list them as includes in a seperate configuration file and point $mrtgCfg to it.

BBMRTG is now configured and ready to report MRTG results to Hobbit/Big Brother. Note that BBMRTG does not actually collect the data - you'll still need to configure MRTG to run and do the actual data collection.

If you use mrtg-rrd to generate your graphs when needed, you'll need to patch the script so that it recognizes the bb* parameters as legitimate.

Questions and comments are welcome via email to apayne@pleiades.com. Be sure to include the name of the script in the subject of your message in order to avoid the spam trap.

Changes:
15 Dec 2004 - links to new scripts, graphic added
13 Jan 2005 - added bb config notes from Jim Johnson
19 Feb 2005 - update bbmrtg link to reflect latest version
12 Mar 2005 - updated page to include information about Hobbit
10 May 2005 - added Somix Technologies link
04 Nov 2005 - update bbmrtg link to v1.8
Copyright © 2004-2006 - Al Payne