Man Linux: Main Page and Category List


       bbgen - Xymon webpage generator


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


       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

              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

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

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

              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

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


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

              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

              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.


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

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

              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

              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.

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

              Generate a logfile of all purple status messages.


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

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

              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 with

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

              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 "--rsslimit=yellow".


              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

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


              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

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

       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.


       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

       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

       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), xymon(7)