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.
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 |
---|---|
The |
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 |
---|---|
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 **).
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.
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 |
---|---|
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 |
---|---|
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 |
---|---|
|
%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 |
---|---|
|
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.
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 name | what is it doing with my display? |
---|---|
title_in_table | make table titles part of the table |
white_bg | set pages' background to white in place of the default colored back- ground |
structured_bg | another alternate background |
static_lamps | display non-blinking status lights |
frames | frame optimized skin |
bigbro13 | Big Brother 1.3 like look |
alt_contentsicons | especially ugly status lights in contents frame |
![]() | Note |
---|---|
The default skin is automatically part of any skin set, there is no need for explicitly listing it! |
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
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.
Big Sister supports graphical image maps since version 0.22. To use this feature follow this procedure:
check if you've installed the Perl module GD.pm
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 |
---|---|
Older versions of GD only support GIF while newer versions support PNG and JPEG! |
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
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)
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 |
---|---|
The generated image will be called www/mapxx.png, where xx is a sequence number hold in adm/display_map.cfg.seq |
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.