Provided by: xymon_4.3.0~beta2.dfsg-9.1_amd64 bug


       bbgen - Xymon webpage generator


       bbgen -?
       bbgen --help
       bbgen --version
       bbgen [options] [output-directory]
       (See the OPTIONS section for a description of the available commandline options).


       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.


       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.


       --help or -?
              Provide a summary of available commandline options.

              Prints the version number of bbgen

              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,     you     would    enable    this    with
              "--docurl=/xymon/admin/notes.php?host=%s". For the host  this  will
              result in a link to "/xymon/admin/notes.php?".

              This option is deprecated; please use --docurl instead.

              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.

              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".

              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".

              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 bb2.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.

              Limit the eventlog on the BB2 page to only N events. Default: 100.

              Limit  the  eventlog  on  the  BB2  page  to events that happened within the past N
              minutes. Default: 240.

              Disable the eventlog normally displayed on the BB2 page

              Limit the acknowledgment log on the BB2 page to only N events. Default: 25.

              Limit the acknowledgment log on the BB2 page to acks that happened within the  past
              N minutes. Default: 240.

              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


       These options affect how the webpages generated by bbgen appear in the browser.

              Put page- and subpage-links after hosts.

              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.

              Determines  the number of columns used for links to pages and subpages. The default
              is N=1.

              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.

              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.

              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.

              Normally, page headings are underlined using an HTML "horizontal ruler"  tag.  This
              option disables the underlining of headings.

              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.

              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.

              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.

              Same as "--dialupskin", but for reverse tests (tests with '!' in front).

              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)


       These  options  affect  which  columns  (tests)  are included in the webpages generated by

              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

              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.

              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.

              Same as the --ignorecolumns, but applies to hosts on the BB2 page only.

              Deprecated, use "--bb2colors" instead.

              Ignore all dialup hosts on the BB2 page, including the BB2 eventlog.

              Always  include  these  columns  on  bb2  page  Will include certain columns on the
              bb2.html page, regardless of its color. Normally, bb2.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 bb2.html page.

              Ignore these tests in the BB2 event log display.


       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.

              Disable upwards status propagation when PURPLE.

              Disable upwards status propagation when RED or YELLOW.

              Disable  upwards  status propagation when status has been acknowledged. If you want
              to disable all acked tests from being propageted, use "--nopropack=*".


       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

              Generate a logfile of all purple status messages.


              Build webpages for an alternate pageset than the default. See the PAGESETS  section

              Use  an alternate template for header and footer files. Typically used together the
              the "--pageset" option; see the PAGESETS section below.


              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

              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",
                    alert("Sidebar only for Mozilla or Netscape 6+");

              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

                 <A HREF="javascript:addNetscapePanel();">
                    <IMG SRC="/gifs/add-button.gif" HEIGHT=45 WIDTH=100
                         ALT="[Add Sidebar]" STYLE="border:0">

              The      "add-button.gif"      is      available       from       Netscape       at

              If FILENAME does not begin with a slash, the Netscape sidebar file is placed in the
              $BBHOME/www/ directory.

              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

       --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

              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".

              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.

              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


              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.

              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.

              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.

              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


              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

              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.


       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-nt4.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. # OS:win-xp # OS:unix-sun

       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:


              BBWEB="/xymon/os" $BBHOME/bin/bbgen \
                   --pageset=os --template=os \

       Save this to $BBHOME/ext/, 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
         "", you will then access
         the new pageset as ""
         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/
       * "--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.


       bbgen  reporting  is implemented via drop-in replacements for the standard Xymon reporting
       scripts ( and 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, bb2.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.


       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"


       Normally, bbgen produce reports that link  to  dynamically  generated  webpages  with  the
       detailed status of a test (via the 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; or you can use the "etime"  utility  for  the  same  purpose,  which  is
       available from the archive at

       "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 \

       The   "BBWEB"   setting   means   that  the  report  will  be  available  with  a  URL  of
       "".   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.


       bb-hosts(5),  hobbitserver.cfg(5), hobbitlaunch.cfg(5), bb-rep.cgi(1), bb-snapshot.cgi(1),