Contents



    How to set up SNMP trapping
    How to tunnel Big Sister connection through ssh
    How to use check frequencies other than the default
    How to re-use your Big Brother monitoring scripts
    How to centrally archive your history log files
    How to make bbd rotate display.history log file
    How to set up an image map
    How to interoperate with Big Brother
    How to debug Big Sister
    How to add your own "checks"
    How to reduce network traffic in a large network
    How to set up a Relay Status Collector
    How to set up redundant Status Collectors


How to set up SNMP trapping



Since release 0.38 Big Sister supports

  - receiving SNMP traps (basic support)
  - sending SNMP traps whenever an alarm is raised

Trap sending is currently merely done by the Event
Generator. By setting the variable "trap" in the
bb_event_generator.cfg config file (see CONFIG) you
indicate the trap destination, e.g.

	*.*	trap=myhost

will tell the Event Generator to send a trap for each
alarm event to myhost. Events currently covered are:

	- raising an alarm
	- clearing an alarm
	- alarm reminders
	- alarm acknowledgements

In near future Big Sister will be able to send a
trap on every status change.

You will find a file bigsister.mib in the contrib
directory. This file contains the SNMP MIB Big Sister
applies. There is also a file named bigsister.fmt.
This file is an HP OpenView trap configuration file -
OpenView will learn Big Sister traps via the command

	xnmevents -load bigsister.fmt

There is currently only very basic support for trap
reciption in the uxmon agent. If a file adm/bstrapd.cfg
exists during uxmon startup the boot script (bb_start)
will start up an additional daemon called 'bstrapd'.
This daemon will listen to the SNMP trap port, receive
traps and log them to var/snmp_traplog. There is a new
monitor called 'snmp_trap' (see CONFIG) similiar to all
the other log file monitors (syslog, EventLog, etc.)
which will read the bstrapd log file and raise status
messages.




How to tunnel Big Sister connection through ssh



Big Sister uses TCP connections for exchanging status
information between agents and servers as well as
between multiple servers. It is very simple to build
a secure (encrypted) tunnel for these status connections
using Secure Shell (ssh).

Agent to Server



On the host running the agent start up ssh forwarding,
e.g.:

	ssh -n displaymachine -L 10192:localhost:1984 sleep 600

(This will forward connections to 10192 to displaymachine
 port 1984 for 10 minutes)

In uxmon-net use the following server entry:

	localhost	port=10192 bsdisplay


Server to Server



Use ssh the same way as above. In bb-display.cfg use
the Rsync statement like e.g.:

	%Rsync mastermachine:10192 prefix GROUP




How to use check frequencies other than the default



Uxmon will perform any configured check every 5
minutes by default. For various reasons you may
want to change this frequency: Either the check
is CPU consuming and you do not want it to be
performed too often or the monitored service is
so important you want to check it more often. Release
0.36 introduced the 'frequency' argument in the
the uxmon-net config file: Using it you can specify
individually for each check how often uxmon should
run it, e.g.:

	host1	frequency=10 ping
	host2	frequency=60 ping

will run a ping test against host1 every 10 minutes
and one against host2 every 60 minutes.

The frequency argument is also effective when used
together with reporters, e.g.:

	display1    frequency=10 bsdisplay
	display2    frequency=1 bsdisplay

will send a status report to display1 every 10
minutes while sending a status report to display2
every minute.

You should carefully choose your testing intervals
though. Keep in mind:

  - chosing a test interal smaller than the smallest
    interval you use together with a reporter is
    senseless, e.g.:

	# very important host
	host1	frequency=1 ping
	display1 frequency=5 bsdisplay

    this will ping host1 every minute - but since
    status reports are only sent every 5 minutes
    a failure of host1 will though it will be
    detected by uxmon shortly after occuring only
    be reported to the status collector after up
    to 5 minutes. In this case you would have to
    use:

	host1  frequency=1 ping
	display1 frequency=1 bsdisplay

  - chosing small intervals may significantly
    increase your network or system load depending
    on the test and/or the size of the status
    reports sent to the status collector

  - in case of service failures some tests will
    take some time to perform (timeouts). Note
    that if uxmon cycles repeatedly take too
    much time (e.g. uxmon runs a number of tests
    once a minute and they take up more than one
    minute) uxmon will first try to do its best
    performing cycles when it finds time to perform
    then - and finally will leave out arbitrary
    cycles and therefore skip tests

  - the reporter intervals are limited by the
    status collector. The status collector expects
    every agent to refresh its status messages
    every now and then no matter if they are
    repeatedly the same or not. After a timeout
    (15 minutes) the status collector will declare
    a status being invalid and set it to 'no status
    report'. Therefore the reporters' interval
    should be significantly below 15 minutes.

  - the frequency is supposed to be a value with
    the meaning 'every xx minutes'. Minute 0
    is equal to January 1st, 1970 00:00 (Unix
    time). One of the effects is that checks
    with the same frequency value will always
    run in the same minutes. On startup and
    on configuration file change every check
    is performed once no matter what its
    frequency value is.



How to re-use your Big Brother monitoring scripts



Up to release 0.32 you had to run both Big Brother
and Big Sister (uxmon) clients for running all their 
monitors. Since version 0.33 uxmon has basic support
for running Big Brother monitoring scripts: the
'bbscript' monitor. Using 'bbscript' you can tell
uxmon to create a minimal BB environment and run
BB commands in them, e.g. in uxmon-net:

	localhost	file=adm/bb-oracle.sh bbscript

will run adm/bb-oracle.sh and report its results
to the Status Collector.

Note: some BB scripts will try to include
      $BBHOME/etc/bbdef.sh for setting defaults.
      Usually you will be better off creating
      an empty etc/bbdef.sh (in the Big Sister
      etc directory) and pass the variables
      necessary like

	localhost	env="LIMIT=100;WHATEVER=some text" file=myscript.sh bbscript

Note: the scripts must have the executable bit
      set



How to centrally archive your history log files



If you are running multiple Big Sister Status
Collectors you may have a need to centrally archive
your old log files either for archiving or interpretation.

Since release 0.32 bbd + bsadmin offer a simple
way for achieving this. Bbd offers a method of
saving old log information (see "savelogs" below)
and tranfering the resulting files to a client
("sendlogs"). Bsadmin offers a command called
"archivelogs" retrieving and archiving remote
log files using the savelogs/sendlogs method. A
simple implementation of fault tolerance is included
in the algorithm: bsadmin keeps track of successfull
transmissions and therefore calling bsadmin regularly
will automatically lead to failed transmissions being
retried.

For using this feature you need first to create
an archive directory. Bsadmin will create files
with names composed of the name of the respective
display server with a date appended, e.g.
myhost.19990605. The best way for using archivelogs
is putting something like this in crontab:

    4 1 * * * /usr/local/lib/bs/bin/bsadmin -d myhost archivelogs /var/archivedir

archivelogs takes an optional argument: the period
in days archivelogs will let history log files cumulate
until it archives them. The default value is "7".

NOTE: Though the archive period is well-defined bsadmin
may in some cases not archive files with exact boundaries.
It may happen that the display server is unreachable
when bsadmin is called the first time within a period.
This will lead to archiving the logs the next time
bsadmin is invoked.



How to make bbd rotate display.history log file



"display.history" is a growing log file where bbd
stores any status changes. Since release 0.32 bbd
implements a "savelogs" command which will do the
usual log file housekeeping. Each time savelogs
will be invoked the current log file will be moved
to a file called "display.history.tag" where tag is
composed of the current date and time but may be
overriden by supplying it as an argument to "savelogs".

Saved log files older than 8 weeks are automatically
deleted (only when "savelogs" is invoked).

You can force bbd to execute savelogs e.g. weekly
by adding the following entry to your crontab file
on the Big Sister status collector host:

    4 1 * * 6 /usr/local/lib/bs/bin/bsadmin -d localhost savelogs

The various tools accessing the log files (the Event
Generator, bshistory, etc.) are "savelogs"-aware,
therefore will work correctly after executing savelogs.


How to set up an image map



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

  - 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, e.g. adm/display_map.gif

  - 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
    adm/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. adm/display_map.cfg.
    It could look like:
	
	# read the background image from adm/display_map.gif
	template	adm/display_map.gif

	# use the gifs stat*.gif for red/yellow/green/purple
	# status
	red		www/gifs/statred.gif
	yellow		www/gifs/statyellow.gif
	green		www/gifs/statgreen.gif
	purple		www/gifs/statpurple.gif

	# display status of group GENF at display coordinates
	# 15,308, etc.
	at		15,308	GENF
	at		80,238	LAUSANNE

	# dump the resulting image out to www/map.gif
	dump		www/map.gif

    NOTE: the generated image will be called www/mapxx.gif,
	  where xx is a sequence number hold in 
	  adm/display_map.cfg.seq

  - in adm/bb-display.cfg add the line

	%image adm/display_map.cfg

    to the %Page statement you want to appear the map in.
  


How to interoperate with Big Brother



Both the agent and status collector part of Big Sister 
are compatible with Big Brother. To use the agent
(uxmon) with Big Brother list the Big Brother Display
machine in adm/uxmon-net with the reporter 'bbdisplay'
(NOTE: bsdisplay and bbdisplay ARE different!), e.g.:

	server1	ping pop3 bbdisplay # this is our Big Brother display
	server2 ping bsdisplay # and this is our Big Sister display

The status collector (bbd) will look to any Big Brother
components like the original one - it does even use
the same log directory structure ...

Since version 0.37 the BB compatible log file mechanism
may be switched off (save disk I/O). Make sure you put

	%Option +BBLog

into bb-display.cfg if you need the www/logs/*.* file
structure (this option is on by default but future
versions might behave differently).

NOTE: not all of the functionality is available when
      mixing Big Brother with Big Sister:

	- Big Sister clients do not support pageing
	  (Big Sister does rather use bb_event_generator)
	- Big Brother does not support dynamic grouping
	  (the "join" and "leave" commands)
	- Big Brother does not support syncing of
	  displays (though syncing from Big Sister displays
	  to Big Brother ones might be implemented soon)
	- Big Brother does not allow clients to send
	  multiple status reports 'at once' (using only
	  one tcp connection)
	- The Big Sister event generator will not be able
	  to use grouping (unless you manually create
	  the group file) when used together with Big Brother
	  bbd

NOTE: a few users wished to run Big Sister "bbd" only for
      web page creation and use Big Brother for all the
      rest. Since 0.24 this can be done by replacing
      the section in runbb.sh (if Big Sister is not
      installed in /usr/local/lib/bs then change as you
      need):

	if test "$BBDISPLAY" = TRUE
	.
	.
	.
	fi

      through

	if test "$BBDISPLAY" = TRUE 
	then
	    /usr/local/lib/bs/bin/bbd -b /usr/local/lib/bs -c
	fi

      and make /usr/local/lib/bs/www be a link to your
      BB www directory.



How to debug Big Sister



Any of the daemons (bb_event_generator, bbd and
uxmon) can be run in debug mode. Use the "-D" option
to start them without going in the background and
print some debug information, e.g.:

	bbd -D 5



How to add your own "checks"



uxmon-rules.pl runs for each check it finds listed
in uxmon-net the corresponding perl code in 
either the adm/Config or uxmon/Config directory.
So this is the place you want to add your checks.

The Config/* code is only a frontend to the modules
found in uxmon/Monitor though. Therefore if you want
to add a really completely new check you'll have
to write a perl module ... Best have a look at
some of the modules. Mandatory methods are
"new" and "check", "check" being called every
5 minutes.



How to reduce network traffic in a large network



Each Big Sister agent does connect to its server(s)
each five minutes and sends its clients status. This
is the minimum network traffic you can't avoid.
Anyway there are a few hints:

  - if using network monitors (such as ping or tcp
    monitors) do rather check status from an agent
    which is near to the watched client (near in
    terms of network bandwith) than an agent in
    a distant network

  - if necessary you can set up Relay Big Sister Status
    Collectors serving a whole lot of agents and
    reporting consolidated status to a central
    Status Collector. This will prevent the agents
    from connecting to the central collector 
    individually. Instead the status of the whole
    part of this network can be transmitted in only
    one connection.



How to set up a Relay Status Collector



A status collector is able to send the stati it
receives regularly to another status collector.
Therefore you can set up relay status collectors
serving a part of the agents and sending its
consolidated status to a Central Status Collector
regularly this way (e.g.):

  - set up a central status collector on Host1 

  - set up a first relay status collector on Host2.
    By using the "%Rsync" statement in bb-display.cfg
    you can tell it to synchronize its status with
    the central status collector, e.g.:

	%Rsync Host1 relay1_ ALL

  - set up a number of agents connecting to Host2, say
    on Host3 through Host10. Tell them (uxmon-rules.pl)
    to report to Host2

  - set up a second status collector on Host11, use e.g.:

	%Rsync Host1 relay2_ ALL

  - set up a number of agents connecting to Host11, say
    on Host12 through Host15. Tell them (uxmon-net)
    to report to Host2

Know Host3 through Host10 will report to Host2, Host12 through
Host15 will report to Host11. Host2 and Host11 will send their
whole status to Host1 prefixing each name with "relay1_" ("relay2_")
respectively. Thus Host1 will see stati like relay1_Host3.cpu,
relay2_Host12.cpu and the like.

If you don't want to use a prefix then use

	%Rsync Host1 none ALL



How to set up redundant Status Collectors



- set up two or more status collectors, let's say on Host1 and Host2

- tell your agents to send their reports to Host1 and Host2 (uxmon-net)

- tell your status collectors to send their reports to each other
  (using %Rsync in bb-display.cfg)