Configuring the Server and customizing the Display

The main server configuration file: bb-display.cfg

With very few exceptions every display related configuration appears somewhere in this file.

The suggested structure of the file is:

  • Options

  • System names and groups

  • Web pages

Each of these sections is composed of a number of statements. Statements always start on a new line and are prefixed by a % character. Most statements take arguments, so a valid statement looks like e.g.:

%Autojoin new NEW(Autojoin with first argument new and second argument NEW. Please see Automatically joined Groups for more information on the autojoin command)

See the section on bb-display.cfg in the Server configuration reference documentation for a complete list of known statements. Note that the above structure is mandatory.

The options section

In the options section you specify various not necessarily display related parameters. Statements belonging to the options section include

option: specify (boolean) options

autoconn: switch on the autoconn feature for specific hosts

pager: set the pager program used by Big Brother agents

A valid options section might look like

                         # The port bbd will listen to
%Port 1984

# Options ...
%Option -ImmediateHTML +KeepGroups +StartOK -DNS

# this is only used by BB clients
%Pager /usr/local/lib/bb/bin/bb-page.sh

# put newly appearing hosts into group NEW
%Autojoin new NEW

# ... and every host into ALL
%Autojoin all_hosts ALL

# ... and everything into UNIVERSE
%Autojoin all UNIVERSE

[Note]Note

The %Autoconn statement indicates to bbd (notbsmon!) for which hosts it should enable the autoconn feature. Whenever an agent connects to bbd for transmission of status information bbd looks up the system hosting the agent in the list of autoconn hosts. If it is listed there bbd automatically generates a green status message for this hosts conn (connection) status. When the agent does not connect to the server for more than 15 minutes the status is automatically changed to red.

The names and group section

Defining and using groups

Big Sister uses groups at various places. You will meet them when defining what systems' status will appear on which web page (see The Web pages section) as well as when setting up your alarming rules (see Configure alarmin).

In the system names and groups section of bb-display.cfg you specify displayed system and group names and define the group hierarchy. The most important statement you will want to remember is the Groups statement. All the lines between a Group statement and the next valid statement will be treated as group and/or name specifications.

Each line is of the form

hostname(Displayed Host Name) GROUP1 ... GROUPN

or

groupname(Displayed Group Name) GROUP1 ... GROUPN

where hostname/groupname is the name of a host (group resp.) and the string in parenthesis is the description of the host or group shown on web pages. GROUP1 through GROUPN are names of groups hostname/groupname is a member of.

Groups are created when they are first referenced so you can use an arbitrary name for both the groupname or GROUPN arguments. Groups may themselves be mem- bers of other groups.

[Warning]Warning

It is a good idea to avoid circular groups.

Time for an example: Assuming washington, paris and london are three systems monitored by Big Sister

%Groups
washington(Our server in Washington) USA SERVER
paris(Our server in Paris) EUROPE SERVER 
london(Our server in London) EUROPE SERVER 
EUROPE(Good old Europe) WORLD 
USA(The United States) WORLD 
WORLD(all the continents) UNIVERSE 
SERVER(all our servers) UNIVERSE

the grouping statement above will create :

  • a group called USA containing only the system washington,

  • the group EUROPE containing the systems paris and london,

  • the group WORLD containing the groups EUROPE and USA,

  • the group SERVER containing all three systems,

  • and finally the group UNIVERSE containing the groups SERVER and WORLD (see figure **).

Figure 3.2. Group hierarchy example

Group hierarchy example

Automatically joined groups

Big Sister can automatically add a host to special groups at the time the first status message for the host comes in. Via the Autojoin statement you declare which groups Big Sister will use for this purpose. Basically there are three available autojoin features:

  • %Autojoin new GROUPNAME

    hosts joining in that are not member of any group yet (semantics: "they are new" / "not defined yet") will join the group named GROUPNAME. This is especially useful for detecting hosts which are already monitored by an agent but which are not correctly configured on server side.

  • %Autojoin all_hosts GROUPNAME

    any host (but not groups!) becomes member of the group named GROUPNAME.

  • %Autojoin all GROUPNAME

    any host or group becomes member of the group named GROUPNAME.

Deleting groups

The Webpages section

The web pages section defines what web pages are generated as well as what they look like. A few statements (like the skin and Logskin statements) are of a global nature while others (like title, table, etc.) are only applicable in conjunction with a Page statement.

Mainly you will define the basic look of your web pages via the skin and Logskin statements, then you describe the pages you would like to be generated and their contents via the Page statement and its "children" (title, refto, table, ref, itemref, image). Each page description starts with a Page statement as e.g.

 %Page top The_main_page

It will create a web page called top.html with title "The main page"

[Note]Note

The page-title must not contain spaces. To bypass this limitation underscores will be replaced by spaces.

A single Page statement will not create much more than an empty page. The lines immediately following it should define some contents. Most important in this respect is the table statement. Followed by one or more groups it will insert one table per group containing the hosts or groups in the respective group and their status. So e.g. (the group names and members are taken from the example in section Defining and using groups)

%Page top The_main_page %table EUROPE USA

will create a page with filename top.html containing two tables, one containing all the members of the group EUROPE (namely paris and london), the other containing all the members of the group USA.

[Warning]Warning

That will only list the members of a group at the next hierarchy level. The command:

 %table WORLD

will list EUROPE and USA, not washington, london, paris.

You can control how deep table digs by prefixing the group name(s) with a "+" sign. Multiple "+" signs will make table go deeper in the hierarchy.

 %table +WORLD

This will list the group members two levels below WORLD (washington, london, paris).

All the other statements (except for the image statement documented in section Using Imagemaps) will not create contents themselves. Instead they modify the behaviour of the following table statement.

%title [ title | none | auto]

Specifies the tables title. if you use the special word none instead of a title tables are created without any title, the special word auto makes table use the display name (see Defining and using groups) of the groups the respective tables are created from.

[Note]Note

auto is the suggested variation.

%itemref [directory]

Specifies the sub-directory (of www) in which the file host.check.html is. So by clicking on a status light the browser will open the respective file. Two commonly used shortcut-arguments are:

  • %itemref html

    point to the Big Sister html-ized status messages

  • %itemref logs

    point to the un- html-ized (ASCII) status messages. This only works if the BBLog option is enabled.

%refto [name{ url | none }]

Whenever host names or group names appear in a table Big Sister will create a hypertext link pointing to url#hostname. Usually url will be the name of a page created via bb-display.cfg and is used to point from tables showing consolidated status information to more detailed tables. Big Sister will automatically create the necessary labels each time it inserts a table in a web page. Of course you are free to use URLs pointing somewhere outside the set of auto generated pages.

refto accepts a few special pseudo-URLs: refto none will suppress hypertext linking, refto self will create links pointing to the same page.

[Note]Note

refto always applies to all rows of a table.

refto name url - the refto statement explained above always takes effect on a whole table. However sometimes it is necessary to link individual hosts or group to individual pages. Another flavour of the refto statement supports exactly this. Via e.g.

Example 3.4.  Example without name argument

%Page top Top_Page
%refto detailed 
%table WORLD 
%Page detailed Host_Details 
%itemref html 
%refto http://oursite.com/serverlist.html %table EUROPE USA

This will create two web pages top.html and detailed.html. On the first page only a single table containing rows for "Good old Europe" and "The United States" is shown. These two labels are linked to the second page where there are two tables, one listing all the hosts in the group EUROPE, one listing the hosts in the group USA. The labels in this two tables are linked to a manually created descriptive page ...serverlist.html.

Example 3.5.  Example with name argument

%refto washington /servers/washington.html

you force the following table statements to link each appearing washington label to the page /servers/washington.html#washington. No matter which comes first an individual refto always overrides a global one, so that e.g.

%Page top Top_Page 
%refto EUROPE europe 
%refto USA usa
%refto all_the_rest 
%table WORLD 
%Page europe Europe 
%refto none 
%table EUROPE 
%Page usa USA 
%refto none 
%table USA

will work correctly, thus creating three pages, one being an index page show- ing consolidated status for Europe and USA pointing to the respective pages listing the servers in Europe and USA.

Example 3.6.  Example with special argument : clear

Individual refto entries are kept across Page statements. If you need to limit scope of entries you can use the special pseudo-url clear as in this example:

%Page top Top_Page 
%refto EUROPE europe 
%refto USA usa
%refto servers 
%table WORLD 
%refto clear 
%table WORLD

This will create a table with links to the Europe and USA pages, then another table with links to the servers page.

Skins

While Big Sister strictly limits the contents of web pages to a few elements (actually tables and image maps) the way web pages look is configurable via the so called skin mechanism. A skin defines the layout of pages - to give some examples skins decide if tables get borders, if the background is white or yellow, if legends are at the top or at the bottom of a page or not present at all, if status lights are round and blinking or rather triangular and static, and so on.

Most skins do not define the whole palette of possible features. Instead, there is a basic skin (the default skin) and various skins modifying only a few layout elements - e.g. the white_bg skin will change the background to white, the static_lamps skin will replace the blinking status lights by non-blinking lights, etc. A whole set of such skins is called a skin set.

Skins appear in conjunction with the Logskin and skin statement. Logskin is used to specify the skin set Big Sister uses when creating the web pages for each checks detailed status while skin sets the default skin for everything else.

Example 3.7. Example on cgi's skins

 %Logskin white_bg %skin static_lamps,structured_bg,frames

This will make Big Sister create the HTML log pages with white background in place of the default one and all the other web pages with static status lights, a textured background and using HTML frames.

Table 3.6. Some available skins

skin namewhat is it doing with my display?
title_in_table make table titles part of the table
white_bgset pages' background to white in place of the default colored back- ground
structured_bganother alternate background
static_lampsdisplay non-blinking status lights
framesframe optimized skin
bigbro13Big Brother 1.3 like look
alt_contentsiconsespecially ugly status lights in contents frame
[Note]Note

The default skin is automatically part of any skin set, there is no need for explicitly listing it!

Skins in CGI programs

Skins are actually used by CGI programs too. In order to make Big Sister administrator's life a little bit more difficult (:-)) CGIs will not read bb-display.cfg. Instead, you can set the skin they should use via the adm/resources file. An entry like

 *.skin=structured_bg,static_lamps

in /etc/bigsister/resources will set the default skin used by every Big Sister component (including CGIs) to "structured_bg" and "static_lamps". If you replace "*" by the name of one specific utility or CGI then the setting only applies to it.

You can also select a skin via an argument to the CGI program, e.g. use

 http://..../...cgi/bshistory?SKIN=structured_bg

Frames

Have you already read section concentrating on skins?

Pages displayed in frames are in fact just a special way of layouting pages, therefore you need only use a frames-enabled skin set (e.g. one including the skin frame) and you get a layout using frames.

Anyway, there is one little problem. It is not sufficient to create all the status pages, additionally an index page defining the frame set as well as the non-status frames are needed. This is the realm of the Frameset statement of bb-display.cfg:

 %Frameset index top Monitored_by_Big_Sister

It will create an index page called index.html, the initial page displayed when entering index.html is top.html and the title of the frame set is "Monitored by Big Sister".

The statement will only work if the specified skin is frame-aware. If the skin defines a menu frame only the pages defined up to the Frameset statement will be respected.

Using imagemaps

Big Sister supports graphical image maps since version 0.22. To use this feature follow this procedure:

  1. check if you've installed the Perl module GD.pm

  2. create a background image you want to place your status lights on (e.g. a geographical map) and save it as a GIF, PNG or JPEG, e.g. display_map.png

    [Note]Note

    Older versions of GD only support GIF while newer versions support PNG and JPEG!

  3. think about what you'd like to display on the image map. Note that you need to have a group for any of the buttons that should appear on the map. So configure the necessary groups in bb-display.cfg

  4. think about where to place the buttons in the image map and get the display coordinates (sorry, you have to use your tools for that, but this should be not too much work)

  5. create an image map config file, e.g. display_map.cfg. It could look like:

    # read the background image from adm/display_map.png       
    template        adm/display_map.png
        
    # use the png stat*.png for red/yellow/green/pruple/... status        
    red           www/skins/default/statred.png
    yellow        www/skins/default/statyellow.png
    green         www/skins/default/statgreen.png
    purple        www/skins/default/statpurple.png
    clear         www/skins/default/statclear.png
    blue          www/skins/default/statblue.png
    
    # remember display coordinates in the image canvas by name
    name          15,308 genf
    name          80,238 lausanne           
    name          96,115 central_switch
    
    # insert status lamps for groups GENF and LAUSANNE at the
    # position genf and lausanne         
    at              genf  GENF
    at              lausanne  LAUSANNE
    
    insert a status lamp for host/check switch1.conn at position central_switch
    at              central_switch switch1.conn
            
    # draw a line in the status color of GENF from position central_switch
    # to position genf
    line            central_switch genf GENF      
    
    # include a custom link/icon
    link 90,238 http://myweb.com/lausanne/ adm/lausanneicon.png 
    
    # dump the resulting image out to www/map.png       
    dump            www/map.png        
            
           

    [Note]Note

    The generated image will be called www/mapxx.png, where xx is a sequence number hold in adm/display_map.cfg.seq

  6. in adm/bb-display.cfg add the line %image some.path/display_map.cfg to the %Page statement you want to appear the map in.