Big Sister - CONFIG

- Common Features
- file adm/bb-display.cfg
- file adm/permissions and adm/hosts.allow
- file adm/grouping
- file adm/uxmon-asroot
- file adm/uxmon-net
- file etc/syslog, etc/eventlog, etc/logfile, etc/OV etc.
- file adm/display_map.cfg (%image)
- file adm/bb_event_generator.cfg
- file adm/notify.cfg

    This file should be a detailed description of
    the config files. Unfortunately it's not finished
    yet ...

## Common Features

    Most of the config files now (release >=0.93) share
    some characteristics:

      - The config files are now searched (in order) in
        the adm subdirectory, then in the etc directory,
        then in the root install directory. Therefore
        you decide which file should go into what directory
        at your site.

      - comments are lines starting with a '#' character

      - Other files can be included via the 'include'
        directive: put the word 'include' at the start
        of a line followed by the file name.

        The file name may contain variables (starting
        with '$'). Currently only one variable is
        defined though - "HOST".

        E.g.:

          include sample-file1

        will find sample-file1 in the adm, etc or install
        directory and include this file, while

          include etc/sample-file1

        will include sample-file1 located in the etc
        directory and

          include /usr/local/etc/sample-file1

        will include /usr/local/etc/sample-file1 and

          include $HOST-sample-file1

        will include the file myhost-sample-file1 if
        Big Sister is running on a machine called 'myhost'.

## file adm/bb-display.cfg

    This file contains the configuration for the Big
    Sister Status Collector 'bbd'. Its name is bb-display.cfg
    since it originally did merely describe what html
    pages bbd was supposed to maintain.

    The file contains a set of one-line statements
    beginning with '%'. A few statements (e.g. %Groups)
    expect multi-line argument data. In this case
    the lines between this statement and the next
    line starting with '%' is treated as arguments.
    Lines starting with '#' are silently ignored.

    Statements:

        %Port portnumber

    	Arguments:

    	    portnumber: a port number (or service name)

    	Set the port bbd will listen to. Note that this has
    	no influence on uxmon agents. If you configure the
    	port in bb-display.cfg to be something else than
    	1984 you will have to mention this port in uxmon-net
    	too, e.g.

    		myhost	port=3956 bsdisplay

        %Option [+|-]option1 ...

    	Arguments:

    	    optionN: option name

    	Set Status Collector options. If prefixed with
    	a '-' switch the option off, if prefixed with
    	'+' switch it on. If no prefix is given '+' is
    	assumed.

    	Known options:

    		DNS		(since 0.98: default: off)

    			if enabled bbd and bsmon will under
    			some circumstances heavily use
    			gethostby* calls to translate IP
    			addresses into host names and vice
    			versa. Since on many systems name
    			resolution is done via DNS this will
    			often lead to performance degradation
    			when there is a problem accessing the
    			DNS server(s) - the situation when Big
    			Sister should work reliably. It is
    			a good idea to not use name resolution
    			in critical parts of Big Sister at all.
    			Switching the DNS option off will restrict
    			name resolution usage to non-critical
    			Big Sister modules.

    		ImmediateHTML	(default: off)

    			write HTML status files immediately
    			on status receipt no matter if the
    			status text has changed or not.

    		KeepGroups	(default: off)

    			read saved grouping information on
    			startup and whenever the configuration
    			changes - do not lose dynamic group
    			information

    		BBLog		(default: on)

    			Log incoming status messages to
    			www/logs/*.* files ("BB compatible
    			logging")

    		StartOK		(default: off)

    			When the display server receives the
    			first status message for a new host/check,
    			assume the status was green before.
    			This has effects on alarming: If StartOK
    			is off then no alarm will be generated
    			if a newly added check already reports
    			"down". If StartOK is on then the alarm
    			generator will handle the status as if
    			it had changed from green to the reported
    			status.

        %Autoconn host1 ... hostn

    	Arguments:

    	    hostx: host name

    	NOTE: the host name must be resolvable!

    	Tell bbd to automatically set the status of
    	host.conn to 'green' each time a connection is
    	coming in from this host. Set status to 'red'
    	(not to 'purple') if no report for >15 min.

        %Autojoin what group

    	Arguments:

    	    what: either 'new', 'all' or 'all_hosts'

    	    group: a group name

    	%Autojoin new GROUP

    	    tells bbd to automatically put
    	    any newly appearing host into
    	    the group 'GROUP'
    	    ("newly appearing" means that bbd
    	    is receiving status messages for a
    	    host not yet known)

    	%Autojoin all_hosts GROUP

    	    tells bbd to automatically put
    	    every known host into group 'GROUP'
    	    (where "host" means every object
    	    bbd is receiving status messages
    	    for)

    	%Autojoin all GROUP

    	    tells bbd to automatically put
    	    every known object - hosts and
    	    groups - into group 'GROUP'

        %Autojoin pattern regexp GROUP

    	   tells Big Sister to automatically
    	   put a host which name matches "regexp"
    	   into group GROUP as soon as it first
    	   appears. Regexp is a Perl regular
    	   expression.

    	   Examples:

    	       %Autojoin pattern domain1\.com$ DOMAIN1
    		   %Autojoin pattern domain2\.com$ DOMAIN2

        %Pager cmd

    	Arguments:

    	    cmd: the name of a program that should
    		 be invoked when bbd gets a page
    		 request ...

    	The %Pager command is provided for compatibility
    	with Big Brother. Big Brother clients use to send
    	pages directly via their Display Server. Usually
    	- in a Big Brother environment - you will use %Pager
    	like:

    		%Pager /usr/where-bb-is/bin/bb-pager.sh

        %Groups

    	Arguments: none

    	The %Groups statement is followed by a
    	number of lines with the syntax:

    	    name(Display name)	GROUP1 ... GROUPN

    	The meaning is: 'name' will be printed as
    	'Display name' when appearing on a html
    	page and belongs to the groups GROUP1 ... GROUPN.

    	The group definitions are recursive.
    	This means that e.g.:

    	    host1(Computer 1)	GROUP1 GROUP2
    	    GROUP1(Group of computers)	GROUP3

    	is valid and means that the reported status
    	values for host1 will influence not only
    	GROUP1 and GROUP2 but also GROUP31.

        %Itemgroup groupname groupmember ...

    	Arguments:

    		groupname: name of the item group to be defined
    		groupmember: item name

        The %Itemgroup statement defines a group containing
    	a list of items (where an item is a check/column name).
    	Item groups can be used in %select_items statements.

    	Note: groupmembers are always column/check names,
    	      itemgroups must not be groupmembers

        Example:

    		%Itemgroup LOCAL disk cpu bak msgs
    		%Itemgroup NETWORK net smtp ssh
    		%Page top SomePage
    		%select_items LOCAL
    		table ALL
    		%select_items NETWORK
    		table ALL

    	%Section title

    	Arguments:

    	    title: the section title

        When using a skin with a contents bar (frames) this will
    	emit a section title in the contents bar

        %Page name title template

    	Arguments:

    	    name: the file name of the created page.
    		  ".html" is automatically appended if
    		  the name is not ending in ".htm" or
    		  ".html". The file is created in
    		  the directory 'www'

    	    title: the title of the created page

    	    template: the template file used (default
    		  is 'template.proto'. The file is
    		  expected to be in the 'www' directory.

    	Note: Since release 0.29 'template' is obsolete
    	      and should not be used any more. Rather
    	      use the 'skin' mechanism as described
    	      below

    	The %Page statement is usually followed by
    	one or more statements describing the contents
    	of the page (e.g. %table).

    	The template file is a html file which contains
    	variable references. 'bbd' does - when creating
    	a page - read in the template file, replace
    	the variables by their values and write the
    	result to the right file. Valid variables names
    	are:

    		@TITLE@		- The page title
    		@BGROUND@	- the URL to the background
    				  graphics file
    		@EXPIRES@	- the time "now+5 minutes"
    				  when the page contents
    				  will expire
    		@TIME@		- the current time in human
    				  readable format
    		@TEXT@		- the page text generated by
    				  'bbd'

        %skin skin1 ... skinN

    	Arguments: list of skin names

    	Use the skinset skin1 thru skinN to describe the
    	look of created pages. See the www/skins directory
    	for valid skin names and www/skins/*/README files
    	for what the respective skins are meant to introduce.

    	Most of the skins are incomplete - means they add
    	certain details to another skin. Therefore you can
    	list more than one skin in one %skin statement.
    	The skins are treated in order - later listed skins
    	taking precedence over earlier listed ones. The
    	'default' skin is always the first skin included.

    	E.g.:

    		%skin default white_bg static_lamps

    	will force Big Sister to create pages with the
    	default look but with a white background rather
    	than the variable one and static instead of
    	blinking lights. Since the default skin is
    	always implicitly included it's exactly the
    	same as:

    		%skin white_bg static_lamps

        %Logskin skin1 ... skinN

    	Arguments: like %skin

    	%Logskin is similiar to %skin, but it does define
    	the look of log pages (the pages where the current
    	status of a monitor is shown)

        %title title

    	Arguments: title

    	This statement should only be used within %Page
    	statements. It tells 'bbd' which title should
    	be used for the tables generated by following
    	%table statements. If 'title' is set to 'auto'
    	the display names as defined in the %Groups
    	section are used.

        %refto url

    	(see also below)

    	Arguments: url

    	This statement should only be used within %Page
    	statements. When creating tables 'bbd' will
    	usually create hypertext links for hosts or
    	groups appearing in the table (left row). This
    	is done by appending a "#" charakter plus the
    	name of the host or group to the url given.

    	Special pseudo-urls:

    		none	- omit creating hypertext links
    		self	- the host/group will be found
    			  on the same page
    		clear	- clear table with individual
    			  urls (see below)

        %refto name url

    	Arguments: name	- name of group or host displayed
    		   url	- the URL which should appear in this group's
    			  hrefs

    	(see also above)
    	This statement allows to set individual hypertext
    	links for specific groups or hosts. If a group or
    	host called 'name' appears in a table the
    	"%refto url" is overriden by the url given in the
    	respective "%refto name url" command. You can set
    	up a table of name/url pairs by using multiple
    	%refto statements. The table is truncated with
    	the statement "%refto clear".

        %sort criteria

    	Arguments: criteria

    	Sort hosts/groups within tables by "criteria".
    	Known criterias so far are:

    	  - severity: sort by status (most alarming status
    	    first), within same status sort by name
    	  - name: sort by name only

        %select [<|>|<=|>=]color

        	Arguments: comparison, color

    	Selects which hosts should appear in a table. Only
    	hosts which summarized status <, >, <=, >= the given
    	status color are displayed. E.g. you can make Big
    	Sister display every host with status worse than
    	green with

    		%select <green
    		%table ALL

        %select_names pattern ...

    	    Arguments: pattern: Perl regular expression

        Selects which hosts should appear in a table. Every
    	host name is matched against the pattern list (Perl
    	regular expressions, case insensitive).

    	Examples:

    		%select_names s.* a.*
    		%table WEST

            will display all the hosts in table WEST with
    		names starting with 's' or 'a'

        %select_items item|group ...

    	Arguments: item: an item (column/check) to be
    				  displayed in a status table
    			   group: an item group (see %Itemgroup)
    			   	  to be displayed in a status table

        Selects which columns should appear in a status
    	table.

        Note: There is a special predefined group called
    	      ALL (meaning "all items"). However, something
    		  like "%select_items ALL -disk -cpu" will not
    		  work!

    	Examples:

    		%select_items cpu disk bak
    		%select_items ALL
    		%Itemgroup SOME cpu disk bak ssh smtp
    		%select_items SOME -ssh

        See also: %Itemgroup

        %itemref url

    	Arguments: url

    	This statement should only be used within %Page
    	statements. When creating tables 'bbd' will
    	usually create hypertext links for each status
    	lamp in the table. This is done by appending
    	a '/' character, the name of the host/group, a
    	'.' character plus the name of the status item
    	to the url given.

    	If a file with the prefix '.html' exists, then
    	this one is used...

    	Special pseudo-urls:

    		none	- omit creating hypertext links

    	Reasonable %itemrefs are e.g.:

    		%itemref logs

    			point to the status message collected
    			by the Status Collector

    		%itemref html

    			point to the HTML version of the
    			status message

        %table GROUP1 ... GROUPN

    	Arguments: list of group names

    	This statement should only be used within %Page
    	statements. It tells 'bbd' to create a table
    	for each of the arguments containing all the
    	hosts/groups contained in the respective group.

    	Since 0.22beta each group may be prefixed by
    	one or more "+" characters. In this case the
    	table will not contain the groups/hosts in
    	the respective group but all the groups/hosts
    	found when descending the group tree.

        %image cfg-file

    	Arguments: configuration file

    	Inserts an image/HTML image map into the page.
    	Please see below for a description of the config
    	file (default: adm/display_map.cfg)

    	NOTE: when using %image you must have installed
    	      the GD perl module.

        %ref name

    	Arguments: name

    	This statement should only be used within %Page
    	statements. It tells 'bbd' to create a HTML label
    	<A NAME ...> at the current position in the html
    	code. 'bbd' does automatically generate labels
    	for any table appearing within the page, so this
    	statement is not commonly used.

        %Rsync host[:port] prefix GROUP1 ... GROUPN

    	Arguments: host	- remote status collector's host name
    		   port - remote status collector's port
    			  (defaults to 1984)
    		   prefix - the prefix prepended to each
    			  host name reported to the remote
    			  status collector
    		   GROUP1 ... GROUPN - a list of groups that
    			  must be reported to the remote status
    			  collector

    	This statement tells 'bbd' to regularly (each 5 minutes
    	cycle) build a list of stati known to it and report them
    	to a remote status collector. Each host name is prepended
    	by a prefix (prefix "none" means no prefix). Currently
    	only host stati can be synced. No group information is
    	exchanged.

        %Frameset output-file initial-page title

    	Arguments: output-file	the name of the generated html file
    		   initial-page	the name of the html file initially
    				displayed
    		   title	the title of the page

    	This creates a frameset frameing the Big Sister status
    	pages.

    	NOTE: The frameset is only generated when bb-display.cfg
    	      is re-read (e.g. after a configuration change or
    	      on startup).

    	NOTE: for %Frameset to work correctly a skinset must be
    	      used that includes frame definitions (e.g. "frames")

        %include file1 ... filen

    	Arguments: file		the name of a file to include (if
    				no absolute path is given the
    				path is supposed to be relative to
    				the Big Sister root directory)

    	This statement only works when used within %Page statements.
    	It tells bbd to include a file whenever the respective page
    	is rebuild. The file is included at the 'current' position,
    	so e.g.

    		%Page ...
    		%table TEST
    		%include file

    	will include the file 'file' after the table 'TEST'

## file adm/permissions and adm/hosts.allow

    Note: Release 0.36 introduced a new security model. Though
          the old adm/hosts.allow file and format is still
          supported for compatibility reasons the
          adm/permissions file should now be used.

    The permission file tells bbd which clients are allowed
    to connect and which operations they may perform. The file
    is read line by line. Each line contains both a pattern
    and a list of operations accepted or rejected for the
    matching clients. If a client matches multiple patterns
    the associated access lists are treated in a cumulative
    way and applied in the order they appear in the file.

    The format of each line is

    	pattern	  =>  access list

    accepted patterns are:

    	name hostname	client name matches 'name'
    	ip ip		client IP address matches 'ip'
    	anonymous	no user is logged on on this connection

    NOTE: "name name" patterns are ignored if the DNS option in
          bb-display.cfg (see above) is switched off. This is the
          default now!

    NOTE: "user" and "member" patterns as described in former versions
          of this document are not supported at the moment.

    The access list is a list of keywords being associated
    with an operation or a group of client operations. Each
    keyword is preceded by either a "+" or a "-" character
    allowing or rejecting corresponding request. Accepted
    keywords are:

    	all		all operations
    	authenticate	client is permitted to send user
    			authentication
    	status		client is authorized to send
    			status messages
    	page		client is authorized to send page
    			commands
    	grouping	client is permitted to send group
    			join/leave and name commands
    	archiving	log file archiving operations
    	alarm_acking	alarm acknowledging operations
    	perf		performance data transmission
    	remove		removal of status records

    Empty lines and lines starting with '#' are ignored.

    Example:

    	# default - reject everything
    	name .*		=> -all
    	#
    	# hosts in mydomain.com may only send status
    	# messages
    	name .*\.mydomain\.com	=> +status
    	#
    	# archiver may only do archiving
    	name archiver	=> -all +archiving
    	#
    	# localhost may do everything
    	name localhost	=> +all
    	#
    	# unauthenticated clients must never page
    	anonymous	=> -page
    	#
    	# selected hosts may send grouping information
    	name group1	=> +grouping
    	name group2	=> +grouping

## file adm/grouping

    The Big Sister status collector allows clients to join/leave
    groups on client request. The file adm/grouping is used by
    uxmon (provided you are using the standard uxmon-rules.pl file)
    and contains a list of hosts and the groups they should join.
    The file is read line by line. Each line should start with a
    host name continue with a list of groups uxmon should tell
    the status collector to join this host, e.g.:

    	server1		EAST UNIX ALL
    	server2		WEST NETWARE ALL
    	hub1		WEST HUB ALL

    NOTE: lines starting with '#' are treated as comments

    NOTE: Using the 'grouping' feature means that uxmon will send
          the grouping information to the status collector each
          time status is sent (usually each 5 minutes).

    NOTE: If uxmon is terminated normally (e.g. when an agent machine
          is halted intentionally) it sends a group leave command
          to the status collector and the status collector will forget
          about these hosts (and remove the status files from www/logs).
          If it crashes for some reason or other the groups won't be left
          and the status collector will still have the hosts in its lists.

## file adm/uxmon-asroot

    If the file adm/uxmon-asroot exists bb_start will start up uxmon
    with root priviledges.

## file adm/uxmon-net

    When using the provided uxmon-rules.pl file this file tells uxmon
    what checks it should run on what hosts and where to send status
    information to. It is read line by line. If a '#' character is
    found all the characters behind # are treated as a comment. Lines
    ending in '\' are treated as being multi-line entries (like e.g.
    in shell). Each line is of one of the following formats:

    	hostname	check1 var1=content1 check2 check3 ... checkn

    or

    	hostname(alias)	check1 var1=content1 check2 check3 ... checkn

    (quotes " and ' allowed and interpreted)

    Hostname is the name of the host uxmon should check. The name returned
    by /bin/hostname or 'localhost' are recognized as the local system.
    Alias is the name uxmon should use when reporting status to the status
    collector. This allows e.g. the following check:

    	server1-interface1(server1)	ping
    	server1-interface2(server1)	ping http

    (where server1 is meant to be a multihomed host with two network
     interfaces which should both be checked but should both be reported
     as being the same machine)

    Var=content sets a variable named 'Var' with the value 'content'. Some of
    the checks allow for passing arguments this way. The variable space is
    cleared after each line ...

    Common variables are:

    	frequency=xx

    		tell uxmon how frequently to run a check. This is
    		not really a frequency but rather an interval - the
    		value is a number specifying the time in minutes
    		between 2 checks, e.g.

    			foobar	frequency=10 ping

    		will ping foobar every 10 minutes

    Checks are names of checks uxmon should run for the respective host. When
    interpreting checks uxmon-rules.pl does look for files carrying the name
    of the check in first adm/Config then in uxmon/Config. If found it does
    interpret it as a perl script setting up some check, runs it and passes
    (optional) arguments (var=...) to it. Currently implemented checks are:

      bbdisplay

        not really a check ... tells uxmon to send status
        reports to this host and use Big Brother compatibility
        mode. Multiple hosts may be bbdisplays. Note that
        some of the functionality is lost when using 'bbdisplay':
        no dynamic grouping (see file adm/grouping), no
        multiple status reports per tcp connection.

         Usage:

    	mydisplay	port=1984 timeout=8 fqdn=no bbdisplay

         (port, timeout and fqdn are optional and default to 1984,
          8 and no)

         'fqdn' tells uxmon to either report host names with stripped
         domain (fqdn=no) to the status collector or with "." in
         hostnames replaced by "_" or "," (fqdn=yes). So e.g.:

    	mydisplay	fqdn=yes bsdisplay
    	foo.bar.com	ping

         will report foo_bar_com.conn to status collector while

    	mydisplay	fqdn=no bsdisplay
    	foo.bar.com	ping

         will only report foo.conn

         'bbdisplay' will rather use a ',' to replace dots in
         FQDNs while bsdisplay will use '_'.

         Since version 0.95 bbdisplay does support collecting
         performance data. Two new arguments have been added:

    	options		a list of optional tasks bsdisplay
    			has to perform. Defaults to
    			"perf,status,group" (send performance,
    			status and grouping messages to
    			server). This argument has been introduced

    	perfdata	the argument value is a file containing
    			a list of regular expressions describing
    			which performance variables should be
    			sent to the Status Collector. If at least
    			one perfdata argument is present uxmon
    			writes out a file 'var/uxmon_variables'
    			listing all the available variables.

          Example:

    	host1	options=perf,status,group perfdata=adm/log_often bsdisplay
    	host1	options=perf perfdata=adm/log_hourly frequency=60 bsdisplay

          this will tell uxmon to send the variables listed in adm/log_hourly
          every 60 minutes, the variables listed in adm/log_often every
          5 minutes (default). The usual status and grouping messages
          are sent every 5 minutes. No need to send them every hour
          too (since "every 5 minutes" includes "every hour" anyway).

          adm/log_often might look like:

    	.*cpu.*
    	myhost:.*disk.*

      bsdisplay

         same as before but use Big Sister protocol. This should
         be preferred to bbdisplay.

      cpuload

         Usage:

    	localhost	cpu_yellow=10 cpu_red=20 cpuload

         check the CPU load as reported by the 'uptime' command.
         cpu_yellow defaults to 10, cpu_red to 20.

      statusfile

         Usage:

    	localhost	file=adm/mystatus statusfile

         read status information from a file and report it to
         the Status Collector. This monitor is thought to be
         useful for interfacing to external simple monitors -
         they can write their status to a file rather than
         careing about TCP connections to Status Collectors,
         e.g.:

    	echo "status myhost.mytest green wow - everything is ok" > adm/mystatus
    	echo "status myhost.oterh yellow something went wrong" >> adm/mystatus

         would do ...

      bbscript

          Usage:

    	localhost	env="LIMIT1=5;LIMIT2=10" file=adm/bb-oracle.sh bbscript

          Use BB style monitor script. "file=" must point to the script
          to execute each 5 minutes, "env=..." lists optional
          environment variables to be set in the scripts environment.
          The common variables (such as BBHOME and the like) are
          automatically set.

      http

         check http response. When used without arguments it will
         connect to port 80 and try to get the file "/". Other
         URLs/ports may be passed in either of the following two
         ways:

    	server	url=http://host:port/somewhere/somefile.html http

         or simple:

    	server	http://host:port/somewhere/somefile.html

         The "check" column the check results will appear under on
         the status display can be specified via the "check" argument
         as in

         	server	check=proxy http://host:3128/whatever/

         The http check is based on the "tcp" check explained below.
         The same additional arguments (especially "timeout=") apply
         to http also.

      tcp

         check if the host does respond to tcp connection request.
         Some well known services (such as smtp, pop3, nntp, ica)
         will be recognized and not only connected to but also
         checked against some expect/send pairs (e.g. when checking
         SMTP uxmon will expect an answer starting with '22').

         Usage:

    	service=pop3,smtp,printer tcp
    	service=ftp timeout=20 tcp

         where service is a variable set to a comma separated list
         of services 'tcp' should check. Timeout is the maximum time
         the tcp check waits for a response (default: 8s).

         Some well known services have their own aliases, so they
         can directly be listed without "service=... tcp", e.g.

    	server1		pop3 smtp printer

         is ok.

         More sophisticated usage:

         	server1		check=tcp service=ftp(21),smtp(3325) tcp

         You can apply a test for a well known service to a non-default
         port by using the syntax "service=service(port)". If the
         "check" argument is set it specifies the column the test
         results appear on the status page.

         Experienced system administrators will probably find the
         following construct useful:

         	server1		check=tcp service=custom(80) \
    			send="HEAD / HTTP/1.0\r\n\r\n" \
    			expect="HTTP" tcp

         The semantics of this is: connect to port 80 of server1,
         send the string specified with the "send" argument, check
         if the stream server1 sends contains the regular expression
         specified with "expect".

      ping

         does a ping. Note that ICMP pings are only possible when
         uxmon is running with root priviledges. By default 'ping'
         will therefore use the UDP protocol. Ping supports icmp/udp/tcp
         though. Most of the IP stacks are implementing both ICMP and
         UDP echo services ...

         For running uxmon with root priviledges create file
         adm/uxmon-asroot and bb_start will start up uxmon as root.

         Usage:

    	server1		ping

         or

    	server1		proto=udp ping proto=tcp ping proto=icmp ping
    	server2		proto=fping ping

         special protocols:

    	if proto=external then a operating system command will be
    	executed instead of using the built-in ping methods. Use
    	proto=external like:

    		server1	proto=external pingcmd="ping -c1" ping

    	proto=karl is another special implementation of using the
    	operating system ping. It is limited to Solaris though.

    	If you have got the fping command on your system you
    	probably want to use

    		proto=fping

      rpc

         does an 'rpc ping', means it does send a 'NULL' remote procedure
         call to the respective program and checks for a correct answer.

         Usage:

    	server1		rpc=mount,nlm rpc rpc=nfs version=3 rpc

         Note: Some of the checks have their own aliases, so you can
    	   also write:

    		server1		mount nfs nlm yp yppasswd

         Note: currently known programs are:

    		mount, nfs, nlm, yp, yppasswd
    		(list can be extended in Monitor::rpc_ping)

         Note: rpc does need a working portmapper on the remote system

      procs

         does check for running processes. On Win32 Systems this monitor
         checks for running services.

         Usage:

    	localhost	procs=nfsd(1-16),sendmail,lpd(1-40) procs

         ("there must be 1 to 16 nfsd processes, at minimum one sendmail
          process and 1 to 40 lpd processes")

    	localhost	pscomm="ps cax" procs=nfsd(1-16),sendmail,lpd(1-40) procs

         (same as above but use the command "ps cax" for finding the running
          processes)

         The "ps" command used for determining the list of processes is
         guessed by the procs check. If available it preferably uses
         "ps -e", on systems without a working "ps -e" it tries to use
         "ps cax". Both "ps -e" and "ps cax" display the process name
         as being the same of argument 0 passed to a program. If you
         prefer checking against the full command line you can use

    	localhost	alternate=yes procs=nfsd,oracleinst1 procs

         This will make "procs" use the "ps -ef" command.

         NOTE: On Win32 systems the "pscomm" argument is ignored.

         NOTE: On Win32 systems it is possible to monitor remote systems.

      diskfree

         does check file systems for free space

         Usage:

    	localhost	type=ufs fs=/(1000-5000),/var(10000-20000) diskfree

         ("status red if / is below 1MByte free, yellow if below 5MBytes,...,
           the file system type is ufs")

    	localhost	fs=all-ext2(10%-20%),all-fat(5%-15%),/boot(500k-1000k) diskfree

         ("status red if /boot goes below 500k free, one of the 'fat' filesystems goes
           below 5% free or one of the ext2 filesystems (except /boot) go below 10%
           free, yellow if /boot goes below 1000k free or one of the fat ...., green
           otherwise")

         Note: the all-... syntax should be used in preference to the "type=" argument

         Note: On Win32 systems only percentual limits are supported and Big Sister
    	   does not distinguish between NTFS or FAT filesystems.

         Note: If specifying specific fileystems the respective file system will
    	   only be checked if it is of the same type as specified in the
    	   "type=" argument or one "fs=all-type"-Argument!

      diskload

         check the average disk load (4 minutes) as reported by 'sar'.

         Usage:

    	localhost	yellow=3 red=8 diskload

         ("report status yellow when load >3%, report status red when load >8%")

      load

         check for CPU idle time, I/O-wait, freeswap as reported by
         sar (4 minutes period)

         Usage:

    	localhost	idle=10 wio=50 freeswap_red=100000 freeswap_yellow=200000 load

         ("report 'yellow' when %idle is below 10%, or %wio is greater than
           50% or freeswap is below 200000 blocks, report red when freeswap
           is below 100000 blocks")

         Note: defaults: idle=15, wio=50, freeswap_red=20000,
    	   freeswap_yellow=60000

      dumpdates

         check for last backup if using dump/ufsdump.

         Usage:

    	localhost	fs=.7(6-10),.0(30-40),/dev/rdsk/c0t1d0s0.7(1-2) dumpdates

         yellow: last level 7 backup older than 6 days, last level 0 backup
    	     older than 10 days, last level 7 backup of
    	     /dev/rdsk/c0t1d0s0 older than 1 day

         red: last level 7 backup older than 10 days, last level 0 backup
    	  older than 40 days, last level 7 backup of
    	  /dev/rdsk/c0t1d0s0 older than 2 days

         Note: the dumpdates check needs a working "mount" command to work
    	   correctly

      syslog

         check system log files

         Usage:

    	localhost	syslog   cfg=/etc/bs_syslog.cfg syslog

         Note: syslog does need its own configuration file. By default this
    	   is etc/syslog. See below for a description of the file format

         Note: On startup syslog will re-read the last 15 minutes of the log
    	   file but at most 30kBytes

      eventlog

         check event log on Win32 systems

         Usage:

    	server1		eventlog

         Note: eventlog does need its own configuration file. By default this
    	   is etc/eventlog. This config file is the same format as the
    	   one for the syslog monitor. See below for a description of
    	   the syslog config file.

      snmp_trap

         check the log file being generated by bstrapd (var/snmp_traplog).
         This is only useful if bstrapd is running (usually bstrapd is
         started up if its configuration file adm/bstrapd.cfg exists).

         Usage:

    	server1		snmp_trap

         Note: snmp_trap has its own configuration file called etc/snmp_trap.
         See below for a description (same format as syslog config file).

      snmp

         remotely monitor hosts running SNMP agents

         Usage:

    	server1		novell
    	hub2		hub
    	server3		type=ping,net,storage,nwusers,cpu,novell snmp
    	router1		community=secret type=net,ping snmp

         The default community (when not passwed with "community=...") is
         'public'. "type" may be a list of checks out of the following:

    	ping	report in host.conn if snmp poll was successfull
    	net	check any network interface for InputErrors and OutputErrors
    		and report a failure if device reports more than 2/s (yellow)
    		or 6/s (red)
    	storage	(currently only together with "novell" and "nt") use the 'hrStorage'
    		oid for checking disk and memory usage
    	cpu	uses 'hrProcessorLoad' to monitor CPU load. Does report "yellow"
    		if load is >80%
    	nwusers	(will only work with Netware servers) Does check 'nwMaxLogins'
    		against 'nwLoginCount', report 'yellow' if only 10 users are
    		left, 'red' if less than 2 are left

    	hub / nt / novell / caty / cds / notes / linux:
    		these do not include any check but will tell 'snmp' which
    		types of machine are checked. Some snmp checks are depending
    		on the type of host ...

    			hub:	network hub
    			nt:	Windows NT
    			novell:	Novell Netware
    			caty:	Cisco Catalyst
    			cds:	Axis CD-Server
    			linux:	Linux (whith UCD SNMP)

          Note: snmp does read the file etc/mibs.txt. By default this contains
    	    only the Internet MIB-II (ping/net). You need to add more mibs
    	    from the contrib/mibs directory, e.g.

    		cat host.txt mib-2.txt nwhostx.txt nwserver.txt > mibs.txt

      OV

         monitor HP Openview trapd.log

         Usage:

    	localhost	cfg=/etc/bs_OV.cfg syslog

         Note: OV does need its own configuration file. By default this
    	   is etc/OV. See below for a description of the file format

         Note: On startup OV will re-read the last 24 hours of the log
    	   file but at most 1MByte

      metastat

         monitor Solstice Disksuite metadevices

         Usage:

    	localhost	stat=/usr/opt/SUNWmd/sbin/metastat metastat

         default value of 'stat' is /usr/opt/SUNWmd/sbin/metastat, so
         'stat=' can be omitted in most cases.

      FQDN / noFQDN

         (obsolete, use "fqdn=" with bsdisplay/bbdisplay instead)

         Usage:

    	localhost	FQDN

         rather an option than a monitor. Tells uxmon to either report
         host names with stripped domain (noFQDN) to the status collector
         or with "." in hostnames replaced by "_" (FQDN). So e.g.:

    	localhost	FQDN
    	foo.bar.com	ping

         will report foo_bar_com.conn to status collector while

    	localhost	noFQDN
    	foo.bar.com	ping

         will only report foo.conn

       ntp

         Usage:

    	foo		ntp

         Check if the machine is running an ntp server. This
         check uses the ntpdate command - therefore only works
         on systems with ntpdate installed.

       mrtg

         Usage:

    	foo.bar.com	 prefix=10.1.1.253/10.1.1.253.1 column=mrtg \
    			 maxlev=10485760 bits=1 mrtg

         The MRTG monitor will retrieve data from a MRTG-style .log file.
         It will check the last value of the data being monitored against
         given thresholds and act accordingly.  In the example above, the
         log file signifies a router interface.  The log file is found in
         mrtglog directory. (see below)

         Here are the available arguments:

    	column 		the column to which status messages are posted
    			default: mrtg   (i.e post to foo.bar.com.mrtg)

    	prefix		the directory/file prefix of the logfile
    			no default, required.

    	bits		determines if we are graphings bits/sec or
    			bytes/sec (used w/ network interfaces)
    			default: bytes

    	maxlev		the maximum value the data may take on
    			Only used to calculate the percentage reported
    			and to calculate yellow/red levels.
    			default: 10mb (bits=1), 1.25mB (bits=0)

    	warnlev		These two options determine at which point the
    	paniclev	monitor should report yellow and red statuses.
    			(0 -> warnlev is green, warnlev-> paniclev is
    			 yellow, >paniclev is red)
    			You may specify a value to compare to the counter
    			directly or a percentage of the maximum value.
    			default: warnlev= 50%, paniclev= 75%

    	units		This determines the units of the value.  Asthetic
    			only.
    			default: b/s (bits=1), Bytes/s (bits=0)

    	intext		These are the labels for the data being graphed.
    	outtext		For network interfaces, In and Out are the default
    			and should be sufficient.

    	resources variables:
    	mrtglog		the directory with mrtg logs in it
    	mrtgweb		the path for the url to link to the graph
    	mrtgloghtml	1 to post html status, 0 to do text only

    	So, it reads the file $mrtglog/$prefix.log, posts the status as
    	a line of text, and optionally links to http://$mrtgweb/$prefix.html
    	and http://$mrtgweb/$prefix.gif to show the graph and get more
    	info.

       atmport
       etherport

         Usage:

    	   fooswitch	switch=192.168.0.4 port=3A2 vpi=0 atmport
    	   fooswitch	switch=192.168.0.4 port=5 etherport

         check operating status of specific ports.

         The atmport monitor is configured to work with Marconi ATM gear.  It
         has been tested with the ASX200BX, ASX1000, LE25, LE155, and ESX3000.
         It will use SNMP to query the switch specified for the status of the
         VPT given.  It checks that signalling is up.  The etherport module
         queries an ethernet switch for the link state of that port and
         reports accordingly.

            switch		the ip address of the host to SNMP query
    	community	the SNMP community to use
    			default: public
    	port		(atmport) Symbolic name for port (Marconi
    			convention) or the number used as the SNMP index
    			(etherport) SNMP index number for the port.
    	vpi		(atmport only) the Path number to monitor

         To find numeric port numbers for the etherport module, use snmpwalk:
    	snmpwalk  10.100.101.61 public ifDescr

    	interfaces.ifTable.ifEntry.ifDescr.2 = "FastEthernet0/1"
    	interfaces.ifTable.ifEntry.ifDescr.3 = "FastEthernet0/2"

         For FastEthernet0/1, I would use port 2.  ifName or ifAlias may yield
         the desired result depending on the switch manufacturer.

       software

         Usage:

    	 foo	type=asn9000 expected=ForeThought.*6\.0\.1 software
    	 foo2	expected=Linux.*2\.0\.36 software

         Get the firmware release via SNMP and check it against
         a configured "expected" version. Report a yellow status
         if the version does not match.

         The "expected=" argument is a regular expression tested
         against the value of system.sysDescr.0.

         Some special "type=" values exist:

    	type=asx	FORE ASX ATM Switches
    			checks ASXSoftware.0 instead of sysDescr

    	type=asn9000	FORE ASN9000 PowerHub
    			checks ASNSoftware.0 instead of sysDescr

    	type=es2810	FORE ES2810 Ethernet Switch

        realhttp

    	Usage:

    	     localhost \
    		     url=http://www.mybc.com realhhtp \
    		     url=http://www.mybc.com/cgi-bin/mycgi item=cgi realhhtp \
    		     url=https://secure.mybc.com:447/index.html item=secure \
    			realhttp \
    		     url=http://127.0.0.1/index.html greppos=success realhttp \
    		     url=http://127.0.0.1/t.html grepneg=test realhttp \

    	This module is used to execute an HTTP request for a specified
    	URL.  It utilizes the LWP libraries so it can support HTTPS
    	if the Crypt/SSLeay libraries have been installed on your
    	system.

    	A query is considered successfull if LWP reports success.  There
    	is no method currently implemented to check that the page
    	returned is what would be expected.

    	This check will only work if you have the LWP::UserAgent perl
    	module installed (see CPAN)

    	Arguments:

    	    url     The url to retrieve.
    	    item    The item to report this test as.  Defaults to 'http'.
    	    greppos A regular expression which should be found in the
    	            contents returned from the server.
    	    grepneg A regular expression which should *NOT* be found in
    	            the contents returned from the server.
    	    user    A username to supply in basic authentication
    	    pass    A password to supply in basic authentication

      memory

           Report memory usage on NT and Linux systems.

           Syntax:

    	    localhost	memory

      oracle

          (see also: HOWTO)

          Syntax:

    	    localhost	ORACLE_CONNECT=... ORACLE_HOME=... ORACLE_BASE=... \
    			ORA_USER=... ORA_PASS=... ORACLE_TNSADMIN=... \
    			ORACLE_NLS_LANG=... ORACLE_ORA_NLS33=... oracle

          Tests oracle database server.

          Arguments:

    	  ORACLE_CONNECT:
    	  Connect String constisting looking like

    	      [HOSTNAME]:[ORACLE_SID]:[BIG_SISTER_COLON_NAME] .

    	  Eg. Your database runs on "Asterix" and the Oracle SID you want to
    	  surveille is called TVD806. You want to have the collon beeing called
    	  "ORACLE DEMO". So your ORACLE_CONNECT string looks like:

    		"Asterix:TVD806:ORACLE DEMO".

    	  ORACLE_HOME:
    	  Home directory of the oracle product (where you have installed oracle version)

    	  ORACLE_BASE:
    	  Home of the oracle user.

    	  ORA_USER:
    	  User to connect to oracle db. ( with our prepared PLSQL default is check_db )

    	  ORA_PASS:
    	  Password for oracle user ORA_USER ( with our prepared PLSQL default is check_db )

    	  ORACLE_TNSADMIN:
    	  Path where oracle will find the tnsnames.ora

    	  optional fields: ORACLE_NLS_LANG, ORACLE_ORA_NLS33

    	  eg:
    	  localhost       ORACLE_CONNECT="ds1skeys:DKMS2:oAPP2" \
    			  ORACLE_HOME=/u00/app/oracle/product/8.1.6 \
    			  ORACLE_BASE=/u00/app/oracle \
    			  ORACLE_NLS_LANG=american_america.WE8ISO8859P1 \
    			  ORACLE_ORA_NLS33=/u00/app/oracle/product/8.1.6/ocommon/nls/admin/data \
    			  ORA_USER=TSMW ORA_PASS=TSMW \
    			  ORACLE_TNSADMIN=/u00/app/oracle/network oracle

      tripwire

          Syntax:

    	  localhost		tripwire
    	  localhost	timeout=10 tripwire

          Check system consistency via tripwire.
          (see also HOWTO)

      ldap
      ldap_mozilla

          Description

          This module is used to query a ldap server and attempt to
          retriew a register. The "ldap" check uses Net::ldap module
          which is available at CPAN while "ldap_mozilla" uses
          Mozilla::LDAP available from Mozilla.org.

          Parameters

          dn    DN to check
          pass  UserPassword
          port  ldap tcp port (default: 389)
          item	The item to report (default: ldap)
          time	The number of seconds to wait for a response before
          		timing out.  (default: 5)

          Manuel de Vega Barreiro
          Madrid,Spain
          mbarreiro@red.madritel.es

          Based in Kevin O'Donnell (kevin_odonnell@telus.net)  Radius Monitor

          Example:

    	myhost		dn="cn=whoever,o=wherever,c=us" pass="test" ldap

      command

          Description

          This module is used to execute an arbitrary command
          this command must return status 0 if test is ok,
          and status != 0 if it is wrong.

          In order to allow interfacing to commands not explicitly
          written for use with Big Sister the default behaviour
          regarding exit codes and other error conditions is
          configurable (see "results" parameter below).

          All text messages send to standard output/error is send as status
          messages to bsdisplay.

          note that command are exec with "/" base directory.
          uxmon-net example:

    	  localhost exec="/opt/bs/otros/test.pl test1" time=10 item=test command

    	  localhost exec="ntpdate -q localhost" \
    	      results="0:green:ntp OK;stratum 16:yellow:ntp running but not synchronized;timeout:red:ntp not running;*:red:ntp FAILURE" \
    	      command

          Parameters

                exec	command to execute
                item	The item to report (default: command)
                time	The number of seconds to wait for a response before
    	      		timing out.  (default: 5)
    	    results	patterns and resulting status to report when a pattern
    			matches. Patterns are separated by semicolons and
    			the results string looks like

    				pattern1:color1:text1;pattern2:color2:....

    			where pattern may be one of

    				<number>: matches the commands exit code
    				timeout : matches if command timed out
    				failed  : matches if uxmon was not able
    					  to even start the command
    				<any regex>: matched against the stdout/
    					  stderr output of the command

    			The first matching pattern decides which rule
    			will apply.

      ups

          Query an uninterruptible power supply supporting SNMP queries
          via the UPS MIB.

          Syntax:

    	  myups		ups

          This test is very limitted. It reports green unless

    	  - the number of "Line Bads" increased during the last hour
    	    => yellow
    	  - the reported power source is something different from "normal"
    	    => red

          In addition to this it collects some useful performance data
          like the Battery voltage (indicating battery quality), the
          output power and output load. The standard graphtemplates file
          includes graph definitions for these values.

      qmqueue

          monitor qmail's mail queue

          Syntax:

    	  localhost	queue_dir=/var/qmail/queue/ \
    	      queue_yellow=2000 queue_red=3500 method=direct qmqueue

    	  localhost	queue_dir=/var/qmail/queue/ \
    	      warnlevl=2000 paniclevl=2000 \
    	      warnlevr=2000 paniclevr=2000 socket=/tmp/.qmail-qstat \
    	      warnlevt=2000 paniclevt=2000 method=socket qmqueue

          Checks the number of messages in qmail's queue, raises
          a warning if message number passes the queue_yellow limit,
          an error if it passes the queue_red limit. Queue_yellow
          defaults to 2000, queue_red to 3500, queue_dir to
          "/var/qmail/queue".

          The monitor will check the remote, local, and todo
          directories against this limit.  The warnlevl and
          paniclevl directives will allow you to specify the
          thresholds for the local queue only.  The warnlevr
          and paniclevr directives work on the remote queue,
          and the warnlevt and paniclevt directives work on
          the todo queue.  If queue_yellow or queue_red is
          specified, then all warn levels default to
          queue_yellow and all panic levels default to
          queue_red for compatibility.

          The method directive can be either direct or socket.
          Direct traverses /var/qmail/queue and counts files.
          Socket checks a UNIX domain socket as provided by
          Bruce Guenter's RPM and using the ucspi-unix package.
          The default socket is /tmp/.qmail-qstat.

## file etc/syslog, etc/eventlog, etc/logfile, etc/OV etc.

    Note: There are quite many things you can do with the log file
          monitor. Unfortunately this fact rendered its config files
          rather complex. It's always a good idea to have a look at
          some samples - e.g. the etc/OV or etc/syslog file.

    Various monitors perform about the same function: They watch log
    files. These monitors include syslog, eventlog, logfile, OV. Each
    of them has its own config file usually called etc/syslog,
    etc/eventlog and so on. The format of all of these files is identical.
    There are only very few differences in the semantics.

    Each file consists of one section per system log file that should be
    watched. Empty lines and lines starting with '#' are ignored. Each
    section starts with a line containing the file name of a log file
    that should be watched followed by a ':', e.g.

    	/var/adm/messages:

    If you would like to use the same config file on multiple systems
    and the file is called differently on some of them you might find
    the following solution handy. You can list multiple filenames comma
    separated on the same line. The monitor will then use the first
    existing file out of this list:

    	/var/adm/messages,/var/log/messages:

    For the eventlog monitor the semantics is different. The 'file' here
    must be the name of a log, e.g. "System" or "Security".

    The lines following the file name are of the format (fields separated
    by one or more tabs):

    	pattern		status		minutes		text	topic

    where 'pattern' is a regular expression (perl style!) that should be
    matched against each line appearing in the log file, status is the
    status that should be reported if a matching line is found (e.g.
    "yellow" or "red"), minutes is the time in minutes the status should
    be reported (remember that "line appearing in log file" is an event
    passing by very fast - so we extend the time a little :-)), text is
    the text that should be appearing in the status message and topic is
    service type part of the status name (defaults to "msgs", thus 'topic'
    is optional). Since 0.98 'topic' may also include a host name (so
    that it optionally looks like 'host.item').

    Like in perl patterns may include sections in parentheses "(...)".
    These can be referenced in text with $1 through $9. E.g. the following
    rule:

    	/var/log/syslog:
    	to=([^,]+)	yellow		10	someone sent mail to $1	  funny

    will report a status of

    	machine.funny:	yellow someone sent mail to blabla

    for 10 minutes if someone sends an email message to user 'blabla'.

    Apart from a color 'status' may be the word 'clear'. In this case the
    log file monitor will not log the corresponding message but will
    rather find any tracked message matching the text and remove it.
    E.g.:

    	host (.*) is down	red	20	host $1 down
    	host (.*) is up		clear	0	host $1 down

    will make the monitor report "host ... down" for 20 minutes after
    seeing "host ... is down" in the watched log file. If within these
    20 minutes the message "host ... is up" is detected the message
    is immediately cleared from the memory though without waiting for
    the whole 20 minutes. In 'clear' patterns the message text is
    treated as a regular expression if it is preceded by a '+' sign,
    e.g.

    	host (.*) was disposed	clear	0	+host.*$1

    will clear any message containig host.*... if the message "host ...
    was disposed" is detected.

    If pattern is 'default' the line is treated as the default status that
    should be reported if no other event is pending. E.g.:

    	default		green		hostname	everything looks fine

    Will report "green everything looks fine" to the Display Server for
    the host 'hostname' if there's nothing else to report. Usually you
    will use "*" for hostname - semantics: set the default for any host
    known to the log file monitor.

    This can be used in a less obvious way too. Consider the following
    example:

    	/var/log/dhcp:
    	default		yellow		0	don't know what's going on		dhcp
    	DHCPOFFER	green		30	we are still giving out addresses	dhcp
    	DHCPACK		green		30	we are still ack'ing leases		dhcp
    	no free leases	red		10	oops - we are out of leases		dhcp

    This will report 'yellow don't know what's going on' if no log entries are
    written, "green we are still giving out addresses" if an address was given
    out during the last 30 minutes ('DHCPOFFER'), "green we are still
    ack'ing leases" if a lease was acknowledged during the last 30 minutes
    and "red oops - we are out of leases" if "no free leases" was logged
    during the last 10 minutes.

    Since you have not got much influence on what is written to log files
    host names appearing there may sometimes be different from the names
    you want them to appear in Big Sister. For this reason the pattern

    	node logname=truename

    has been introduced. Some monitors will automatically add 'node'
    entries during runtime. E.g. the OV monitor will add one each time
    it detects a "System name changed" message.

    One log file can influence more than one column - e.g. you will find
    messages concerning disks, cpu, etc. in /var/log/messages. By issuing
    the 'topic' column (as seen above) you can distribute log file entries
    to multiple columns. Note that you also need multiple "default" lines
    in this case, e.g.

    	default		green	0 	no errors	disk
    	default		green	0 	no errors	msgs
    	full		red	0	fs full		disk
    	error		red	0	some error	msgs

    Also be carefull about re-using already reported columns. It is only
    possible to have multiple checks (e.g. 'syslog' and 'diskfree')
    report to the same column if they are running within the same
    uxmon instance!

## file adm/display_map.cfg (%image)

    Note: The file may be called as you like - adm/display_map.cfg is the
    default.

    This file describes how to build a graphical status display when using the
    %image statement in bb-display.cfg. It consists of a series of one line
    statements. Empty lines and lines starting with "#" are ignored. All file
    names are paths relative to the Big Sister root directory. Known
    statements are:

    Note that the displaymap feature only works if you have got a working
    GD module installed.  Big Sister <0.93 only works with old versions
    of GD (the one supporting the GIF image file format), while 0.93
    works with old and new (the one supporting the PNG format) modules.

    	template filename

    		read background graphic from file filename (must be GIF
    		or PNG format depending on your version of the GD module).
    		This is mandatory! No image without "template" ...

    	name coord coordname

    		remember the display position 'coord' under the name
    		'coordname'. After this statement whenever a display
    		position is expected 'coordname' can be used instead
    		(e.g. in 'at' or 'line' statements).

    		Example: name 100,150 NewYork
    			 name 70,200 Dallas
    			 line NewYork Dallas DALLASWAN
    			 at NewYork NEW_YORK
    			 at Dallas DALLAS

    	red filename
    	yellow filename
    	purple filename
    	green filename
    	blue filename
    	clear filename

    		the graphic to be inserted for red/yellow/purple/green
    		status (GIF or PNG).

    	at coord group

    		display status for group "group" (groups as configured in
    		bb-display.cfg) at position "coord" (0,0 is at upper left
    		corner). Since version 0.98b4 you can also directly address
    		host.check or group.check pairs in place of groups

    		Example: at 100,150 NEW_YORK
    			 at 30,80 WASHINGTON
    			 at 50,50 mymachine.conn
    			 at 15,10 WASHINGTON.disk

    	line coord1 coord2 group

    		draws a line from display position coord1 to display
    		position coord2 with the color of the status of the
    		group group

    	link coord1 href coord2/image

    		includes a hyperlink pointing to "href" in the image
    		map at position coord1. If the 3rd argument is the
    		name of an image file, the image is read and printed
    		at coord1. Otherwise the 3rd argument is expected to
    		be the size of the rectangular region associated with
    		href.

    		Example: link 100,150 http://wherever.com/bla adm/bla.png

    	dump filename

    		write the image to file filename. This must be the last
    		statement. The file must be in the "www" directory,
    		otherwise browsers will not find it.

## file adm/bb_event_generator.cfg

    Bb_event_generator.cfg is the configuration file for the alarm generator
    (bb_event_generator). The file tells on what conditions alarms should
    be sent to whom and with what priority. It consists of one-line-rules.
    Like in other files empty lines and lines starting with '#' are ignored.
    '\' at the end of a line will tell bb_event_generator that the statement
    continues on the following line.

    Each rule is composed of one or more patterns separated by ';' and a list
    of variable settings. The variable settings are separated by spaces or
    tabs.  So a rule looks like:

        pattern1;...;patternN	var1=text1	var2=text2 ... varN=textN

    where pattern1 thru patternN are patterns, var1...varN are variable names
    and text1...textN are variable values.

    Each pattern is composed of a host part and a check part:

        host.check

    where 'host' may be one out of the following:

        - a host name as reported to Big Sister status collector
    	    e.g. myserver, www, ...
        - an IP host or network address in "[" "]" parentheses
    	    e.g. [139.79.159.1], [192.168.50]
          NOTE: this will only work for host names that can be
    	    resolved into an IP address
          NOTE: this will not work if DNS option in bb-display.cfg
                (see above) is switched off. This is currently the
    	    default!
        - a group as known to the Big Sister status collector with
          prefix '@'
    	    e.g. @ALL, @ROUTER
        - an asterisk "*" matching any host

    and 'check' may be either an asterisk "*" matching any check or
    a check as displayed in the columns of the status display.

    Since version 0.29, the pattern may be extended by an additional
    condition. The syntax is

        host.check{condition}

    where condition is a boolean expression, e.g.

        *.*{$mail == "test"}	mail="nobody"

    special functions are 'daytime' and 'weekday', they can be used
    like this:

        *.*{daytime 22:00-06:00 or weekday Sat,Sun}	postpone=30
        *.*{daytime 22:00-06:00}	postpone_to=06:00

    Version 0.98 introduced special rules allowing us to modify the way
    how alarms are delivered. E.g. the rules

        PAGER{$mail eq "someaddress@somehost"} pager=myscript mail=someaddress
        PAGER{$pager eq "sendmail" and $mail eq "test"} mail=addr1,addr2,addr3

    will re-direct alarms sent to someaddress@somehost to the address
    someadress and invoke myscript for sending the alarm (first rule).
    If the pager equals sendmail and the target address is test the
    alarm is redirected to the three addresses addr1,addr2 and addr3.

    The PAGER-Rules are applied once per target address, thus the above
    rules would also apply if the page originated e.g. from a

        *.* mail=someaddress@somehost,test pager=sendmail

    (this would cause the event generator to apply the PAGER rules
    twice: once for "someaddress@somehost", once for "test")

    Note also that target addresses are split into "pager" and "mail"
    before PAGER rules are processed. An address like

    	mail=sendmail:test@somewhat.strange

    will appear to the PAGER rules as

    	mail=test@somewhat.strange pager=sendmail

    Whenever a status change is detected, bb_event_generator.cfg goes
    through the config file and looks for matching patterns. Each
    variable associated with the matching patterns is then set as
    listed. If multiple patterns are matching the associated variables
    are set in order.

    Interpreted variables are:

        - mail	mail addresses where to send alarm (comma separated).
    	 	Alternatively to a mere mail address you can also
    		specify a pager (see "pager" variable) explicitly,
    		e.g.

    			mail=myscript:test,sendmail:me@somewhere.com

    		will send alarms to both "test" via the myscript
    		command and to "me@somewhere.com" via sendmail

        - upmail	mail addresses usen when sending "up" messages -- this
    		defaults to the same as "mail"

        - prio	priority level (0..100)

        - repeat	if set bb_event_generator will send the alarm again all
    		x minutes until the alarm condition has cleared

        - repeatprio	the priority level for repeated alarms (see "repeat")

        - keep	the duration in minutes the alarm is not cleared
    		by the event_generator after the alarm condition
    		is telling us that everything is ok again

        - norepeat	the duration in minutes no alarm can be sent for
    		the same condition

        - delay	the duration in minutes between when the alarm
    		is raised and sent to the user

        - check	a boolean expression that is checked during the
    		'delay' time and forces the alarm to be aborted
    		if the condition is not met once during this time

        - down	(one out of "green", "purple", "yellow", "red",
    		"never") tells the event generator which status
    		should be interpreted as "down". E.g.: "yellow"
    		means that if the status is "yellow" or below
    		("red") is detected then the corresponding
    		service is down.

        - up	(like down) tells the event generator which
    		status should be considered as "up". E.g.
    		down=yellow up=green means that a service
    		is considered as down from the time when it
    		changes to yellow or red to the time when it
    		goes to "green" again (but not if it's going
    		to "purple"!)

        - maxmsg	a numeric value which is the maximum size of
    		a message sent in the subject line of the alarm
    		mail (e.g. if you send it through a pager gateway
    		...)

        - postpone	if set alarms won't be sent for additional x minutes
    		and rather stay in the queue. If during the postpone
    		time period the alarm condition is cleared the alarm
    		is silently thrown away. Postpone is meant to be used
    		e.g. during night when you don't want to get an alarm.

        - postpone_to	same as postpone but the value is expected to be a
    		daytime rather than an interval (e.g. "06:00").

        - pager	use alternative pager program (by default Big Sister
    		tries to use the system's 'sendmail' program, if mailhost
    		is set Big Sister's 'smtpmail' is the default)

        - skin	use the skin specified here for alarm messages

        - trap	if set bb_event_generator will raise an SNMP event
    		for any alarm/acknowledgement. The contents of trap
    		is a trap destination composed of a community and
    		a host of the form community@host. If the community
    		is missing "public" is assumed. See also SNMP_AGENT.

    Examples:

    Usually you will put a general rule with a pattern matching any
    host/check and the default variable values as your first rule, e.g.:

        # default values
        *.*	mail=alarm prio=50 norepeat=20 down=yellow up=green maxmsg=60

    if you do not want to get an alarm about e.g. smtp being down when you
    already know that the connection to the host is down then you could
    use the following rule for instance:

        *.smtp	delay=5 check="$host.conn"

    (semantics: if the "conn" goes down within 5 minutes after smtp down is
    	    detected then throw away the smtp alarm, otherwise send it
    	    after 5 minutes)

    If your very important machines are in a group called "IMPORTANT" then
    you may wish to do something like:

        @IMPORTANT.*	prio=100 repeat=30 repeatprio=60

    (semantics: if a service of a machine in the group IMPORTANT goes down
    	    then send an alarm with priority 100 and send a reminder
    	    with priority 60 each 30 minutes ("yell for help"))

    If the machines in a group EAST are all located in a network connected
    to router "router-east" then you may get plenty of alarms when
    "router-east" goes down since any machine behind is unreachable. You can
    avoid this by e.g.:

        @EAST.conn	check=router-east.conn delay=5
        router-east.conn	check="1" delay=0

    (semantics: if a host is in group EAST and the connection to it goes
    	    down wait for five minutes and if within these five minutes
    	    the connection to router-east is lost too then do not
    	    send an alarm for this host. If the host is the router
    	    itself send an alarm immediately)
    or

        @EAST.*		router=router-east
        *.conn		check="($router.conn) or not $router" delay=5
        router-east.conn	check="1" delay=0

    (semantics: if a host is in group EAST set the variable "router" to
    	    "router-east". If the connection to any host is going
    	    down then wait for five minutes and check if either there
    	    is no router configured for this machine or the connection
    	    to the router goes down as well. Discard the alarm if
    	    the router goes down. Of course except for if the machine
    	    is the router itself)

    NOTE: you cannot use variables in patterns, so e.g. the example above
          cannot be written as (not yet):

        @EAST.*		router=router-east
        $router.conn	check=1 delay=0

    Postpone is used during times when system failures are less important,
    e.g. during night. You can postpone alarms for a time interval:

        *.*{daytime 22:00-06:00}	postpone=60

    This will tell the event generator to keep a raising alarm in the postpone
    queue for 1h before sending an alarm mail. If during this time the alarm
    condition clears no alarm is sent at all. If you never want to be waked
    up by alarms, then

        *.*{daytime 22:00-06:00}	postpone_to=06:00

    might be what you want (Semantics: when an alarm is detected during night
    send it at 06:00)

## file adm/notify.cfg

    Notify was obsoleted in Big Sister 0.98 though it is still included in the
    distribution. Please do not use notify any more. Instead make use of the
    PAGER rules in adm/bb_event_generator.cfg (see above and see also the
    HOWTO section about migrating from notify.cfg).