NAME
bbgen - Xymon webpage generator
SYNOPSIS
bbgen -?
bbgen --help
bbgen --version
bbgen [options] [output-directory]
(See the OPTIONS section for a description of the available commandline
options).
DESCRIPTION
bbgen generates the overview webpages for the Xymon monitor. These are
the webpages that show the overall status of your hosts, not the
detailed status pages for each test.
Note: The data for the webpages is retrieved from the hobbitd(8)
daemon, and bbgen uses the values of the BBDISPLAY / BBDISPLAYS
environment variables to determine the network address where hobbitd
can be reached. If you have more than one server listed in BBDISPLAYS,
make sure the first one is the local hobbitd server - this is the one
that bbgen will query for data.
OPTIONS
bbgen has a large number of commandline options. The options can be
used to change the behaviour of bbgen and affect the web pages
generated by it.
GENERAL OPTIONS
--help or -?
Provide a summary of available commandline options.
--version
Prints the version number of bbgen
--docurl=URL
Make hostnames be hyperlinks to documentation, accessed via a
common web page (typically a CGI script or a PHP-driven dynamic
page). The URL parameter is a formatting string with the name of
the web page - you can put a "%s" in it which will be replaced
by the hostname being accessed. E.g. if you use the bb-notes
extension from www.deadcat.net, you would enable this with
"--docurl=/xymon/admin/notes.php?host=%s". For the host
www.storner.dk this will result in a link to
"/xymon/admin/notes.php?host=www.storner.dk".
--doccgi=URL
This option is deprecated; please use --docurl instead.
--no-doc-window
By default, links to documentation for hosts and services cause
a new window to appear with the information. With this option,
the documentation will appear in the same window as the Xymon
status.
--htmlextension=.EXTENSION
Sets the filename extension used for the webpages generated by
bbgen. By default, an extension of ".html" is used. Note that
you need to specify the "dot".
--report[=COLUMNNAME]
With this option, bbgen will send a status message with details
of how many hosts were processed, how many pages were generated,
any errors that occurred during the run, and some timing
statistics. The default columnname is "bbgen".
--htaccess[=htaccess-filename]
Create .htaccess files when new web page directories are
created. The content of the .htaccess files are determined by
the BBHTACCESS environment variable (for the top-level directory
with bb.html and b.html); by the BBPAGEHTACCESS variable (for
the page-level directories); and by the BBSUBPAGEHTACCESS
variable for subpage- and subparent-level directories. The
filename of the .htaccess files default to ".htaccess" if no
filename is given with this option. The BBHTACCESS variable is
copied verbatim into the top-level .htaccess file. The
BBPAGEHTACCESS variable may contain a "%s" where the name of the
page is inserted. The BBSUBPAGEHTACCESS variable may contain
two "%s" instances: The first is replaced with the pagename, the
second with the subpagename.
--max-eventcount=N
Limit the eventlog on the BB2 page to only N events. Default:
100.
--max-eventtime=N
Limit the eventlog on the BB2 page to events that happened
within the past N minutes. Default: 240.
--no-eventlog
Disable the eventlog normally displayed on the BB2 page
--max-ackcount=N
Limit the acknowledgment log on the BB2 page to only N events.
Default: 25.
--max-acktime=N
Limit the acknowledgment log on the BB2 page to acks that
happened within the past N minutes. Default: 240.
--no-acklog
Disable the acknowledgement log normally displayed on the BB2
page.
--nklog[=NK log column]
This generates a text-based log of what is shown on the
bbnk.html status page, and sends a status message for the
BBDISPLAY server itself reflecting the color of the NK status
page. This allows you to track when problems have appeared on
the bbnk status page. The logfile is stored in
$BBHOME/nkstatus.log
PAGE LAYOUT OPTIONS
These options affect how the webpages generated by bbgen appear in the
browser.
--pages-last
Put page- and subpage-links after hosts.
--pages-first
Put page- and subpage-links before hosts (default).
These two options decide whether a page with links to subpages
and hosts have the hosts or the subpages first.
--subpagecolumns=N
Determines the number of columns used for links to pages and
subpages. The default is N=1.
--maxrows=N
Column headings on a page are by default only shown at the
beginning of a page, subpage or group of hosts. This options
causes the column headings to repeat for every N hosts shown.
--pagetitle-links
Normally, only the colored "dots" next to a page or subpage act
as links to the page itself. With this option, the page title
will link to the page also.
--pagetext-headings
Use the description text from the "page" or "subpage" tags as a
heading for the page, instead of the "Pages hosted locally" or
other standard heading.
--no-underline-headings
Normally, page headings are underlined using an HTML "horizontal
ruler" tag. This option disables the underlining of headings.
--recentgifs[=MINUTES]
Use images named COLOR-recent.gif for tests, where the test
status has changed within the past 24 hours. These GIF files
need to be installed in the $BBHOME/www/gifs/ directory. By
default, the threshold is set to 24 hours - if you want it
differently, you can specify the time limit also. E.g.
"--recentgifs=3h" will show the recent GIFs for only 3 hours
after a status change.
--sort-group-only-items
In a normal "group-only" directive, you can specify the order in
which the tests are displayed, from left to right. If you prefer
to have the tests listed in alphabetical order, use this option
- the page will then generate "group-only" groups like it
generates normal groups, and sort the tests alphabetically.
--dialupskin=URL
If you want to visually show that a test is a dialup-test, you
can use an alternate set of icons for the green/red/yellow>/etc.
images by specifying this option. The URL parameter specified
here overrides the normal setting from the BBSKIN environment
variable, but only for dialup tests.
--reverseskin=URL
Same as "--dialupskin", but for reverse tests (tests with ’!’ in
front).
--tooltips=[always,never,main]
Determines which pages use tooltips to show the description of
the host (from the COMMENT entry in the bb-hosts(5) file). If
set to always, tooltips are used on all pages. If set to never,
tooltips are never used. If set to main, tooltips are used on
the main pages, but not on the BB2 (all non-green) or NK
(critical systems) pages.
COLUMN SELECTION OPTIONS
These options affect which columns (tests) are included in the webpages
generated by bbgen.
--ignorecolumns=test[,test]
The given columns will be completely ignored by bbgen when
generating webpages. Can be used to generate reports where you
eliminate some of the more noisy tests, like "msgs".
--nk-reds-only
Only red status columns will be included on the NK page. By
default, the NK page will contain hosts with red, yellow and
clear status.
--bb2-colors=COLOR[,COLOR]
Defines which colors cause a test to appear on the "All non-
green" status page (a.k.a. the BB2 page). COLOR is red, yellow
or purple. The default is to include all three.
--bb2-ignorecolumns=test[,test]
Same as the --ignorecolumns, but applies to hosts on the BB2
page only.
--bb2-ignorepurples
Deprecated, use "--bb2colors" instead.
--bb2-ignoredialups
Ignore all dialup hosts on the BB2 page, including the BB2
eventlog.
--includecolumns=test[,test]
Always include these columns on bb2 page Will include certain
columns on the b.html page, regardless of its color. Normally,
b.html drops a test-column, if all tests are green. This can
be used e.g. to always have a link to the trends column (with
the RRD graphs) from your b.html page.
--eventignore=test[,test]
Ignore these tests in the BB2 event log display.
STATUS PROPAGATION OPTIONS
These options suppress the normal propagation of a status upwards in
the page hierarchy. Thus, you can have a test with status yellow or
red, but still have the entire page green. It is useful for tests that
need not cause an alarm, but where you still want to know the actual
status. These options set global defaults for all hosts; you can use
the NOPROPRED and NOPROPYELLOW tags in the bb-hosts(5) file to apply
similar limits on a per-host basis.
--nopropyellow=test[,test] or --noprop=test[,test]
Disable upwards status propagation when YELLOW. The "--noprop"
option is deprecated and should not be used.
--noproppurple=test[,test]
Disable upwards status propagation when PURPLE.
--nopropred=test[,test]
Disable upwards status propagation when RED or YELLOW.
--nopropack=test[,test]
Disable upwards status propagation when status has been
acknowledged. If you want to disable all acked tests from being
propageted, use "--nopropack=*".
PURPLE STATUS OPTIONS
Purple statuses occur when reporting of a test status stops. A test
status is valid for a limited amount of time - normally 30 minutes -
and after this time, the test becomes purple.
--purplelog=FILENAME
Generate a logfile of all purple status messages.
ALTERNATE PAGESET OPTIONS
--pageset=PAGESETNAME
Build webpages for an alternate pageset than the default. See
the PAGESETS section below.
--template=TEMPLATE
Use an alternate template for header and footer files. Typically
used together the the "--pageset" option; see the PAGESETS
section below.
ALTERNATE OUTPUT FORMATS
--wml[=test1,test2,...]
This option causes bbgen to generate a set of WML "card" files
that can be accessed by a WAP device (cell phone, PDA etc.) The
generated files contain the hosts that have a RED or YELLOW
status on tests specified. This option can define the default
tests to include - the defaults can be overridden or amended
using the "WML:" or "NK:" tags in the bb-hosts(5) file. If no
tests are specified, all tests will be included.
--nstab=FILENAME
Generate an HTML file suitable for a Netscape 6/Mozilla sidebar
entry. To actually enable your users to obtain such a sidebar
entry, you need this Javascript code in a webpage (e.g. you can
include it in the $BBHOME/web/bb_header file):
<SCRIPT TYPE="text/javascript">
<!--
function addNetscapePanel() {
if ((typeof window.sidebar == "object") &&
(typeof window.sidebar.addPanel == "function"))
window.sidebar.addPanel ("Xymon",
"http://your.server.com/nstab.html","");
else
alert("Sidebar only for Mozilla or Netscape 6+");
}
//-->
</SCRIPT>
and then you can include a "Add this to sidebar" link using this
as a template:
<A HREF="javascript:addNetscapePanel();">Add to Sidebar</A>
or if you prefer to have the standard Netscape "Add tab" button,
you would do it with
<A HREF="javascript:addNetscapePanel();">
<IMG SRC="/gifs/add-button.gif" HEIGHT=45 WIDTH=100
ALT="[Add Sidebar]" STYLE="border:0">
</A>
The "add-button.gif" is available from Netscape at
http://developer.netscape.com/docs/manuals/browser/sidebar/add-
button.gif.
If FILENAME does not begin with a slash, the Netscape sidebar
file is placed in the $BBHOME/www/ directory.
--nslimit=COLOR
The minimum color to include in the Netscape Sidebar - default
is "red", meaning only critical alerts are included. If you want
to include warnings also, use "--nslimit=yellow".
--rss Generate RSS/RDF content delivery stream of your Xymon alerts.
This output format can be dynamically embedded in other web
pages, much like the live newsfeeds often seen on web sites. Two
RSS files will be generated, one reflects the BB2 page, the
other reflects the BBNK page. They will be in the "bb2.rss" and
"bbnk.rss" files, respectively. In addition, an RSS file will
be generated for each page and/or subpage listing the hosts
present on that page or subpage.
The FILENAME parameter previously allowed on the --rss option is
now obsolete.
For more information about RSS/RDF content feeds, please see
http://www.syndic8.com/.
--rssextension=.EXTENSION
Sets the filename extension used for the RSS files generated by
bbgen. By default, an extension of ".rss" is used. Note that
you need to specify the "dot".
--rssversion={0.91|0.92|1.0|2.0}
The desired output format of the RSS/RDF feed. Version 0.91
appears to be the most commonly used format, and is the default
if this option is omitted.
--rsslimit=COLOR
The minimum color to include in the RSS feed - default is "red",
meaning only critical alerts are included. If you want to
include warnings also, use "--rsslimit=yellow".
OPTIONS USED BY CGI FRONT-ENDS
--reportopts=START:END:DYNAMIC:STYLE
Invoke bbgen in report-generation mode. This is normally used by
the bb-rep.cgi(1) CGI script, but may also be used directly when
pre-generating reports. The START parameter is the start-time
for the report in Unix time_t format (seconds since Jan 1st 1970
00:00 UTC); END is the end-time for the report; DYNAMIC is 0 for
a pre-built report and 1 for a dynamic (on-line) report; STYLE
is "crit" to include only critical (red) events, "nongr" to
include all non-green events, and "all" to include all events.
--csv=FILENAME
Used together with --reportopts, this causes bbgen to generate
an availability report in the form of a comma-separated values
(CSV) file. This format is commonly used for importing into
spreadsheets for further processing.
The CSV file includes Unix timestamps. To display these as human
readable times in Excel, the formula
=C2/86400+DATEVALUE(1-jan-1970) (if you have the Unix timestamp
in the cell C2) can be used. The result cell should be formatted
as a date/time field. Note that the timestamps are in UTC, so
you may also need to handle local timezone and DST issues
yourself.
--csvdelim=DELIMITER
By default, a comma is used to delimit fields in the CSV output.
Some non-english spreadsheets use a different delimiter,
typically semi-colon. To generate a CSV file with the proper
delimiter, you can use this option to set the character used as
delimiter. E.g. "--csvdelim=;" - note that this normally should
be in double quotes, to prevent the Unix shell from interpreting
the delimiter character as a commandline delimiter.
--snapshot=TIME
Generate a snapshot of the Xymon pages, as they appeared at
TIME. TIME is given as seconds since Jan 1st 1970 00:00 UTC.
Normally used via the bb-snapshot.cgi(1) CGI script.
DEBUGGING OPTIONS
--debug
Causes bbgen to dump large amounts of debugging output to
stdout, if it was compiled with the -DDEBUG enabled. When
reporting a problem with bbgen, please try to reproduce the
problem and provide the output from running bbgen with this
option.
--timing
Dump information about the time spent by various parts of bbgen
to stdout. This is useful to see what part of the processing is
responsible for the run-time of bbgen.
Note: This information is also provided in the output sent to
the Xymon display when using the "--report" option.
BUILDING ALTERNATE PAGESETS
With version 1.4 of bbgen comes the possibility to generate multiple
sets of pages from the same data.
Suppose you have two groups of people looking at the BB webpages.
Group A wants to have the hosts grouped by the client, they belong to.
This is how you have Xymon set up - the default pageset. Now group B
wants to have the hosts grouped by operating system - let us call it
the "os" set. Then you would add the page layout to bb-hosts like
this:
ospage win Microsoft Windows
ossubpage win-nt4 MS Windows NT 4
osgroup NT4 File servers
osgroup NT4 Mail servers
ossubpage win-xp MS Windows XP
ospage unix Unix
ossubpage unix-sun Solaris
ossubpage unix-linux Linux
This defines a set of pages with one top-level page (the bb.html page),
two pages linked from bb.html (win.html and unix.html), and from e.g.
the win.html page there are subpages win-n.html and win-xp.html
The syntax is identical to the normal "page" and "subpage" directives
in bb-hosts, but the directive is prefixed with the pageset name. Dont
put any hosts in-between the page and subpage directives - just add all
the directives at the top of the bb-hosts file.
How do you add hosts to the pages, then ? Simple - just put a tag
"OS:win-xp" on the host definition line. The "OS" must be the same as
prefix used for the pageset names, but in uppercase. The "win-xp" must
match one of the pages or subpages defined within this pageset. E.g.
207.46.249.190 www.microsoft.com # OS:win-xp http://www.microsoft.com/
64.124.140.181 www.sun.com # OS:unix-sun http://www.sun.com/
If you want the host to appear inside a group defined on that page, you
must identify the group by number, starting at 1. E.g. to put a host
inside the "NT4 Mail servers" group in the example above, use "OS:win-
nt4,2" (the second group on the "win-nt4" page).
If you want the host to show up on the frontpage instead of a subpage,
use "OS:*" .
All of this just defines the layout of the new pageset. To generate
it, you must run bbgen once for each pageset you define - i.e. create
an extension script like this:
#!/bin/sh
BBWEB="/xymon/os" $BBHOME/bin/bbgen \
--pageset=os --template=os \
$BBHOME/www/os/
Save this to $BBHOME/ext/os-display.sh, and set this up to run as a
Xymon extension; this means addng an extra section to hobbitlaunch.cfg
to run it.
This generates the pages. There are some important options used here:
* BBWEB="/xymon/os" environment variable, and the
"$BBHOME/www/os/" option work together, and places the
new pageset HTML files in a subdirectory off the normal
Xymon webroot. If you normally access the Xymon pages as
"http://xymon.acme.com/xymon/", you will then access
the new pageset as "http://xymon.acme.com/xymon/os/"
NB: The directory given as BBWEB must contain a symbolic
link to the $BBHOME/www/html/ directory, or links to
individual status messages will not work. Similar links
should be made for the gifs/, help/ and notes/
directories.
* "--pageset=os" tells bbgen to structure the webpages
using the "os" layout, instead of the default layout.
* "--template=os" tells bbgen to use a different set of
header- and footer-templates. Normally bbgen uses the
standard template in $BBHOME/web/bb_header and
.../bb_footer - with this option, it will instead use
the files "os_header" and "os_footer" from the
$BBHOME/web/ directory. This allows you to customize
headers and footers for each pageset. If you just want
to use the normal template, you can omit this option.
USING BBGEN FOR REPORTS
bbgen reporting is implemented via drop-in replacements for the
standard Xymon reporting scripts (bb-rep.sh and bb-replog.sh) installed
in your webservers cgi-bin directory.
These two shell script have been replaced with two very small shell-
scripts, that merely setup the Xymon environment variables, and invoke
the bb-rep.cgi(1) or bb-replog.cgi(1) scripts in $BBHOME/bin/
You can use bbgen commandline options when generating reports, e.g. to
exclude certain types of tests (e.g. "--ignorecolumns=msgs") from the
reports, to specify the name of the trends- and info- columns that
should not be in the report, or to format the report differently (e.g.
"--subpagecolumns=2"). If you want certain options to be used when a
report is generated from the web interface, put these options into your
$BBHOME/etc/hobbitserver.cfg file in the BBGENREPOPTS environment
variable.
The report files generated by bbgen are stored in individual
directories (one per report) below the $BBHOME/www/rep/ directory.
These should be automatically cleaned up - as new reports are
generated, the old ones get removed.
After installing, try generating a report. You will probably see that
the links in the upper left corner (to bb-ack.html, b.html etc.) no
longer works. To fix these, change your $BBHOME/web/bbrep_header file
so these links do not refer to "&BBWEB" but to the normal URL prefix
for your Xymon pages.
SLA REPORTING
bbgen reporting allows for the generation of true SLA (Service Level
Agreement) reports, also for service periods that are not 24x7. This is
enabled by defining a "REPORTTIME:timespec" tag for the hosts to define
the service period, and optionally a "WARNPCT:level" tag to define the
agreed availability.
Note: See bb-hosts(5) for the exact syntax of these options.
"REPORTTIME:timespec" specifies the time of day when the service is
expected to be up and running. By default this is 24 hours a day, all
days of the week. If your SLA only covers Mon-Fri 7am - 8pm, you define
this as "REPORTTIME=W:0700:2000", and the report generator will then
compute both the normal 24x7 availability but also a "SLA availability"
which only takes the status of the host during the SLA period into
account.
The DOWNTIME:timespec parameter affects the SLA availability
calculation. If an outage occurs during the time defined as possible
"DOWNTIME", then the failure is reported with a status of "blue". (The
same color is used if you "disable" then host using the Xymon "disable"
function). The time when the test status is "blue" is not included in
the SLA calculation, neither in the amount of time where the host is
considered down, nor in the total amount of time that the report
covers. So "blue" time is effectively ignored by the SLA availability
calculation, allowing you to have planned downtime without affecting
the reported SLA availability.
Example: A host has "DOWNTIME:*:0700:0730 REPORTTIME=W:0600:2200"
because it is rebooted every day between 7am and 7.30am, but the
service must be available from 6am to 10pm. For the day of the report,
it was down from 7:10am to 7:15am (the planned reboot), but also from
9:53pm to 10:15pm. So the events for the day are:
0700 : green for 10 minutes (600 seconds)
0710 : blue for 5 minutes (300 seconds)
0715 : green for 14 hours 38 minutes (52680 seconds)
2153 : red for 22 minutes (1320 seconds)
2215 : green
The service is available for 600+52680 = 53280 seconds. It is down
(red) for 420 seconds (the time from 21:53 until 22:00 when the SLA
period ends). The total time included in the report is 15 hours (7am -
10pm) except the 5 minutes blue = 53700 seconds. So the SLA
availability is 53280/53700 = 99,22%
The "WARNPCT:level" tag is supported in the bb-hosts file, to set the
availability threshold on a host-by-host basis. This threshold
determines whether a test is reported as green, yellow or red in the
reports. A default value can be set for all hosts with the via the
BBREPWARN environment variable, but overridden by this tag. The level
is given as a percentage, e.g. "WARNPCT:98.5"
PRE-GENERATED REPORTS
Normally, bbgen produce reports that link to dynamically generated
webpages with the detailed status of a test (via the bb-replog.sh CGI
script).
It is possible to have bbgen produce a report without these dynamic
links, so the report can be exported to another server. It may also be
useful to pre-generate the reports, to lower the load by having
multiple users generate the same reports.
To do this, you must run bbgen with the "--reportopts" option to select
the time interval that the report covers, the reporting style
(critical, non-green, or all events), and to request that no dynamic
pages are to be generated.
The syntax is:
bbgen --reportopts=starttime:endtime:nodynamic:style
"starttime" and "endtime" are specified as Unix time_t values, i.e.
seconds since Jan 1st 1970 00:00 GMT. Fortunately, this can easily be
computed with the GNU date utility if you use the "+%s" output option.
If you don’t have the GNU date utility, either pick that up from
www.gnu.org; or you can use the "etime" utility for the same purpose,
which is available from the archive at www.deadcat.net.
"nodynamic" is either 0 (for dynamic pages, the default) or 1 (for no
dynamic, i.e. pre-generated, pages).
"style" is either "crit" (include critical i.e. red events only),
"nongr" (include all non-green events), or "all" (include all events).
Other bbgen options can be used, e.g. "--ignorecolumns" if you want to
exclude certain tests from the report.
You will normally also need to specify the BBWEB environment variable
(it must match the base URL for where the report will be made
accessible from), and an output directory where the report files are
saved. If you specify BBWEB, you should probably also define the
BBHELPSKIN and BBNOTESSKIN environment variables. These should point
to the URL where your Xymon help- and notes-files are located; if they
are not defined, the links to help- and notes-files will point inside
the report directory and will probably not work.
So a typical invocation of bbgen for a static report would be:
START=‘date +%s --date="22 Jun 2003 00:00:00"‘
END=‘date +%s --date="22 Jun 2003 23:59:59"‘
BBWEB=/reports/bigbrother/daily/2003/06/22 \
BBHELPSKIN=/xymon/help \
BBNOTESSKIN=/xymon/notes \
bbgen --reportopts=$START:$END:1:crit \
--subpagecolumns=2 \
/var/www/docroot/reports/xymon/daily/2003/06/22
The "BBWEB" setting means that the report will be available with a URL
of "http://www.server.com/reports/xymon/daily/2003/06/22". The report
contains internal links that use this URL, so it cannot be easily moved
to another location.
The last parameter is the corresponding physical directory on your
webserver matching the BBWEB URL. You can of course create the report
files anywhere you like - perhaps on another machine - and then move
them to the webserver later on.
Note how the date(1) utility is used to calculate the start- and end-
time parameters.
SEE ALSO
bb-hosts(5), hobbitserver.cfg(5), hobbitlaunch.cfg(5), bb-rep.cgi(1),
bb-snapshot.cgi(1), xymon(7)