Man Linux: Main Page and Category List


       bb-hosts - Main Xymon configuration file




       The  bb-hosts(5)  file is the most important configuration file for all
       of the Xymon programs.  This file contains the full  list  of  all  the
       systems  monitored  by  Xymon,  including  the  set  of tests and other
       configuration items stored for each host.


       Each line of the file defines a host. Blank lines  and  lines  starting
       with  a  hash mark (#) are treated as comments and ignored.  Long lines
       can be broken up by putting a backslash at the  end  of  the  line  and
       continuing the entry on the next line.

       The format of an entry in the bb-hosts file is as follows:
          IP-address hostname # tag1 tag2 ...

       The  IP-address  and  hostname  are  mandatory;  all  of  the  tags are
       optional.  Listing a host with only IP-address and hostname will  cause
       a  network  test to be executed for the host - the connectivity test is
       enabled by default, but no other tests.

       The optional tags are then used to define which tests are relevant  for
       the  host, and also to set e.g. the time-interval used for availability
       reporting by bbgen(1)

       An example of setting up the bb-hosts file  is  in  the  Xymon  on-line
       documentation  (from  the  Help menu, choose "Configuring Monitoring").
       The following describes  the  possible  settings  in  a  bb-hosts  file
       supported by Xymon.


       include filename
              This  tag is used to include another file into the bb-hosts file
              at run-time, allowing for a large bb-hosts file to be  split  up
              into more manageable pieces.

              The  "filename"  argument  should  point to a file that uses the
              same syntax  as  bb-hosts.  The  filename  can  be  an  absolute
              filename  (if  it  begins  with a ’/’), or a relative filename -
              relative filenames are prefixed with  the  directory  where  the
              main bb-hosts file is located (usually $BBHOME/etc/).

              You can nest include tags, i.e. a file that is included from the
              main bb-hosts file can itself include other files.

       dispinclude filename
              Acts like the "include" tag, but only on the  BBDISPLAY  server.
              Can  be  used e.g. to put a group of hosts on multiple subpages,
              without having to repeat the host definitions.

       netinclude filename
              Acts like the "include" tag, but only on the BBNET server.


              Controls whether stale status messages go purple or clear when a
              host  is down. Normally, when a host is down the client statuses
              ("cpu", "disk", "memory" etc) will stop updating  -  this  would
              usually make them go "purple" which can trigger alerts. To avoid
              that, Xymon checks if the "conn" test has failed, and if that is
              true  then  the other tests will go "clear" instead of purple so
              you only get alerts for the "conn" test.  If  you  do  want  the
              stale  statuses  to  go purple, you can use the "noclear" tag to
              override this behaviour.

              Note that "noclear" also affects the behaviour of network tests;
              see below.

       prefer When  a  single  host  is  defined multiple time in the bb-hosts
              file, bbgen tries to guess which definition is the best  to  use
              for  the  information  used  on  the  "info"  column, or for the
              NOPROPRED and other bbgen-specific  settings.  Host  definitions
              that have a "noconn" tag or an IP of get lower priority.

              By using  the  "prefer"  tag  you  tell  bbgen  that  this  host
              definition should be used.

              Note: This only applies to hosts that are defined multiple times
              in the bb-hosts file, although it will not hurt  to  add  it  on
              other hosts as well.


       These tags are processed by the bbgen(1) tool when generating the Xymon
       webpages or reports.

       page NAME [Page-title]
              This defines a page at the level below the entry page. All hosts
              following  the "page" directive appear on this page, until a new
              "page", "subpage" or "subparent" line is found.

       subpage NAME [Page-title]
              This defines a subpage in the second level below the entry page.
              You must have a previous "page" line to hook this subpage to.

       subparent parentpage newpage [Page-title]
              This is used to define subpages in whatever levels you may wish.
              Just like the standard "subpage" tag, "subparent" defines a  new
              Xymon  webpage;  however  with  "subparent"  you explicitly list
              which page it should go as a subpage to. You can pick  any  page
              as  the  parent - pages, subpages or even other subparent pages.
              So this allows you to define any tree structure  of  pages  that
              you like.

              E.g. with this in bb-hosts:

                 page USA United States
                 subpage NY New York
                 subparent NY manhattan Manhattan data centers
                 subparent manhattan wallstreet Wall Street center

              you get this hierarchy of pages:

                 USA (United States)
                   NY (New York)
                     manhattan (Manhattan data centers)
                        wallstreet (Wall Street center)

              Note:  The  parent  page  must  be defined before you define the
              subparent. If not, the page will not be generated, and you get a
              message in the log file.

              Note:  bbgen is case-sensitive, when trying to match the name of
              the parent page.

              The inspiration for this came from Craig Cook’s  script,
              and I am grateful to Craig for suggesting that I implement it in
              bbgen. The idea to  explicitly  list  the  parent  page  in  the
              "subparent" tag was what made it easy to implement.

       group [group-title]

       group-compress [group-title]
              Defines  a  group of hosts, that appear together on the webpage,
              with a single header-line listing  all  of  the  columns.  Hosts
              following  the "group" line appear inside the group, until a new
              "group" or page-line is  found.  The  two  group-directives  are
              handled  identically  by  Xymon  and  bbgen,  but both forms are
              allowed for backwards compatibility.

       group-sorted [group-title]
              Same as the "group" line, but will sort  the  hosts  inside  the
              group so they appear in strict lexicographic order.

       group-only COLUMN1|COLUMN2|COLUMN3 [group-title]
              Same  as  the  "group"  and "group-compress" lines, but includes
              only the columns explicitly listed in the group. Any columns not
              listed will be ignored for these hosts.

       group-except COLUMN1|COLUMN2|COLUMN3 [group-title]
              Same  as the "group-only" lines, but includes all columns EXCEPT
              those explicitly listed in the group. Any columns listed will be
              ignored for these hosts - all other columns are shown.

       title Page, group or host title text
              The  "title"  tag  is used to put custom headings into the pages
              generated by bbgen, in front of page/subpage  links,  groups  or

              The  title  tag  operates  on the next item in the bb-hosts file
              following the title tag.

              If a title tag precedes a host entry, the title  is  shown  just
              before  the  host  is  listed  on  the  status  page. The column
              headings present for the host will be repeated  just  after  the

              If  a  title  tag precedes a group entry, the title is show just
              before the group on the status page.

              If a title tag  precedes  a  page/subpage/subparent  entry,  the
              title  text  replaces  the normal "Pages hosted locally" heading
              normally inserted by Xymon. This appears on the page that  links
              to  the  subpages,  not  on  the subpage itself. To get a custom
              heading on the subpage, you may want  to  use  the  "--pagetext-
              heading" when running bbgen(1)

              Overrides  the  default hostname used on the overview web pages.
              If "hostname" contains spaces, it must  be  enclosed  in  double
              quotes, e.g. NAME:"R&D Oracle Server"

              Defines an alias for a host, which will be used when identifying
              status messages. This is typically used to  accomodate  a  local
              client  that  sends in status reports with a different hostname,
              e.g.  if  you  use  hostnames  with  domains   in   your   Xymon
              configuration,  but  the  client is a silly Window box that does
              not include the hostname. Or vice versa.  Whatever  the  reason,
              this  can  be  used  to  match status reports with the hosts you
              define in your bb-hosts file. It causes incoming status  reports
              with  the  specified  hostname  to  be  filed using the hostname
              defined in bb-hosts.

              Used to drop certain of the  status  columns  generated  by  the
              Xymon  client.  column is one of cpu, disk, files, memory, msgs,
              ports, procs.  This  setting  stops  these  columns  from  being
              updated  for  the  host. Note: If the columns already exist, you
              must use the bb(1) utility to drop them, or they will go purple.

       COMMENT:Host comment
              Adds a small text after the hostname on the webpage. This can be
              used to describe  the  host,  without  completely  changing  its
              display-name  as  the  NAME:  tag  does. If the comment includes
              whitespace, it  must  be  in  double-quotes,  e.g.  COMMENT:"Sun

              Define some informational text about the host. The "Hosttype" is
              a text describing the type of this device - "router",  "switch",
              "hub",  "server" etc. The "Description" is an informational text
              that will be shown on the "Info" column page; this can  e.g.  be
              used  to  store  information  about the physical location of the
              device, contact persons etc. If the text contain whitespace, you
              must  enclose it in double-quotes, e.g.  DESCR:"switch:4th floor
              Marketing switch"

              Force the host to belong to a specific  class.  Class-names  are
              used  when  configuring log-file monitoring (they can be used as
              references in client-local.cfg(5) and  hobbit-clients.cfg(5)  to
              group  logfile  checks). Normally, class-names are controlled on
              the   client   by   starting   the   Xymon   client   with   the
              "--class=Classname"  option.   If you specify it in the bb-hosts
              file on the Xymon server, it overrides any  classname  that  the
              client reports.

       dialup The keyword "dialup" for a host means that it is OK for it to be
              off-line - this should not trigger an alert. All  network  tests
              will  go "clear" upon failure, and any missing reports from e.g.
              cpu- and disk-status will  not  go  purple  when  they  are  not

       nobb2  Ignore  this  host  on  the  BB2  page. Even if it has an active
              alert, it will not be  included  in  the  BB2  page.  This  also
              removes the host from the event-log display.

       nodisp Ignore  this host completely when generating the Xymon webpages.
              Can be useful for monitoring a host without having it show up on
              the  webpages,  e.g. because it is not yet in production use. Or
              for hiding a host that is shown only on a second pageset.

              Defines the  RRD  graphs  to  include  in  the  "trends"  column
              generated by bbgen.  This option syntax is complex.
              If  this  option  is not present, bbgen provides graphs matching
              the standard set of RRD files: la, disk, memory, users,  vmstat,
              iostat, netstat, tcp, bind, apache, sendmail
              *  If  this  option  is specified, the list of graphs to include
              start out as being empty (no graphs).
              *  To  include  all  default  graphs,  use  an  asterisk.   E.g.
              * To exclude a certain graph, speficy it prefixed with ’!’. E.g.
              to see all graphs except users: "TRENDS:*,!users"
              * The netstat, vmstat and  tcp  graphs  have  many  "subgraphs".
              Which   of   these   are  shown  can  be  speficied  like  this:
              "TRENDS:*,netstat:netstat2|netstat3,tcp:http|smtp|conn"     This
              will  show  all graphs, but instead of the normal netstat graph,
              there will be two: The netstat2 and netstat3 graphs. Instead  of
              the  combined  tcp  graphs  showing  all services, there will be
              three: One for each of the http, conn and smtp services.

              Collapses a series of statuses  into  a  single  column  on  the
              overview webpage.


       NOTE:  The  "NK"  set of tags is deprecated. They will be supported for
       Xymon 4.x, but will be dropped in version 5.  It  is  recommended  that
       you move your critical systems view to the hobbit-nkview.cgi(1) viewer,
       which has a separate configuration tool, hobbit-nkedit.cgi(1) with more
       facilities than the NK tags in bb-hosts.

       bbgen  will create three sets of pages: The main page bb.html, the all-
       non-green-statuses page (b.html), and a specially reduced version  of
       b.html  with  only  selected  tests  (bbnk.html).  This page includes
       selected tests that currently have a red or yellow status.

              Define the tests that you want included on the bbnk page.   E.g.
              if  you have a host where you only want to see the http tests on
              bbnk.html, you specify it as

        # NK:http

              If you want multiple  tests  for  a  host  to  show  up  on  the
              bbnk.html  page, specify all the tests separated by commas.  The
              test names correspond to the column names (e.g.  https tests are
              covered by an "NK:http" tag).

              This  tag  limits  the time when an active alert is presented on
              the NK webpage.

              By default, tests with a red or yellow status that are listed in
              the  "NK:testname"  tag will appear on the NK page. However, you
              may not want the test to be  shown  outside  of  normal  working
              hours  -  if, for example, the host is not being serviced during

              You can then use the NKTIME tag to define the time periods where
              the alert will show up on the NK page.

              The timespecification consists of

              day-of-week:  W  means Mon-Fri ("weekdays"), * means all days, 0
              .. 6 = Sunday .. Saturday.  Listing multiple days  is  possible,
              e.g. "60" is valid meaning "Saturday and Sunday".

              starttime:  Time  to  start  showing  errors, must be in 24-hour
              clock format as HHMM hours/minutes.  E.g. for 8 am enter "0800",
              for 9.30 pm enter "2130"

              endtime: Time to stop showing errors.

              If necessary, multiple periods can be specified. E.g. to monitor
              a   site   24x7,   except   between   noon   and   1   pm,   use

              The  interval  between starttime and endtime may cross midnight,
              e.g. *:2330:0200 would be valid and  have  the  same  effect  as


       If bbgen is run with the "--wml" option, it will generate a set of WAP-
       format output "cards" that can be viewed  with  a  WAP-capable  device,
       e.g. a PDA or cell-phone.

              This  tag  determines which tests for this hosts are included in
              the WML (WAP) page. Syntax is identical to the NK: tag.

              The  default  set  of  WML  tests  are  taken  from  the   --wml
              commandline  option.   If  no "WML:" tag is specified, the "NK:"
              tag is used if present.


       These tags affect how a status propagates upwards from a single test to
       the  page  and  higher.  This  can  also  be done with the command-line
       options  --nopropyellow  and  --nopropred,  but  the  tags   apply   to
       individual hosts, whereas the command line options are global.

              This  tag  is  used  to  inhibit  a  yellow  or  red status from
              propagating upwards - i.e. from  a  test  status  color  to  the
              (sub)page status color, and further on to bb.html or b.html

              If  a  host-specific  tag  begins with a ’-’ or a ’+’, the host-
              specific tags are removed/added to the default setting from  the
              command-line  option.  If  the  host-specific tag does not begin
              with a ’+’ or a ’-’, the default setting  is  ignored  for  this
              host and the NOPROPRED applies to the tests given with this tag.

              E.g.:     bbgen      runs      with      "--nopropred=ftp,smtp".
              "NOPROPRED:+dns,-smtp"  gives  a  NOPROPRED setting of "ftp,dns"
              (dns is added to the default, ftp is removed).   "NOPROPRED:dns"
              gives a setting of "dns" only (the default is ignored).

              Note:  If  you set use the "--nopropred=*" commandline option to
              disable propagation of all alerts, you cannot use  the  "+"  and
              "-"  methods to add or remove from the wildcard setting. In that
              case, do not use the "+" or "-" setting,  but  simply  list  the
              required tests that you want to keep from propagating.

              Similar  to  NOPROPRED: tag, but applies to propagating a yellow
              status upwards.

              Similar to NOPROPRED: tag, but applies to propagating  a  purple
              status upwards.

              Similar  to  NOPROPRED:  tag,  but  applies  to  propagating  an
              acknowledged status upwards.


       These options  affect  the  way  the  Xymon  availability  reports  are
       processed (see bb-rep.cgi(1) for details about availability reports).

              This tag defines the time interval where you measure uptime of a
              service for reporting purposes.

              When bbgen generates a report, it computes the  availability  of
              each  service  - i.e. the percentage of time that the service is
              reported as available (meaning: not red).

              By default, this calculation is done on  a  24x7  basis,  so  no
              matter when an outage occurs, it counts as downtime.

              The  REPORTTIME tag allows you to specify a period of time other
              than 24x7 for the service availability calculation.  If you have
              systems  where you only guarantee availability from e.g. 7 AM to
              8 PM on weekdays, you can use
              and the availability calculation will only be performed for  the
              service with measurements from this time interval.

              The  syntax  for  REPORTTIME  is the same as the one used by the
              NKTIME parameter.

              When  REPORTTIME  is  specified,  the  availability  calculation
              happens like this:

              *  Only  measurements  done during the given time period is used
              for the calculation.
              * "blue" time reduces the length of the report interval,  so  if
              you  are  generating a report for a 10-hour period and there are
              20 minutes of "blue" time,  then  the  availability  calculation
              will  consider  the reporting period to be 580 minutes (10 hours
              minus 20 minutes).  This allows you to have  scheduled  downtime
              during    the   REPORTTIME   interval   without   hurting   your
              availability; this is (I believe) the whole idea of the downtime
              being "planned".
              *  "red"  and  "clear"  status  counts as downtime; "yellow" and
              "green" count as uptime. "purple" time is ignored.

              The availability calculation correctly  handles  status  changes
              that cross into/out of a REPORTTIME interval.

              If  no  REPORTTIME  is  given,  the standard 24x7 calculation is

              BB’s reporting facility uses a computed  availability  threshold
              to   color   services  green  (100%  available),  yellow  (above
              threshold, but less than 100%), or red (below threshold) in  the

              This  option allows you to set the threshold value on a host-by-
              host basis, instead of using a global setting for all hosts. The
              threshold is defined as the percentage of the time that the host
              must be available, e.g. "WARNPCT:98.5" if you want the threshold
              to be at 98.5%


       testip By default, Hobbit will perform a name lookup of the hostname to
              get the IP address it will  use  for  network  tests.  This  tag
              causes Hobbit to use the IP listed in the bb-hosts file.

              This  tag  defines  the  host  as  being  tested from a specific
              location.  If bbtest-net  sees  that  the  environment  variable
              BBLOCATION  is  set,  it  will  only  test the hosts that have a
              matching "NET:location" tag in the bb-hosts file. So this tag is
              useful  if  you  have  more than one BBNET system, but you still
              want to keep a consolidated bb-hosts file for all your  systems.

              Note:  The "--test-untagged" option modifies this behaviour, see

              Some network tests depend on others. E.g. if the host  does  not
              respond to ping, then there’s a good chance that the entire host
              is down and all network tests will fail. Or if the  http  server
              is  down,  then  any web content checks are also likely to fail.
              To avoid floods of alerts, the default behaviour is for  bbtest-
              net  to  change  the  status of these tests that fail because of
              another problem to "clear" instead of "red". The  "noclear"  tag
              disables  this  behaviour  and  causes  all  failing tests to be
              reported with their true color.

              This behaviour can also be implemented on a  per-test  basis  by
              putting the "~" flag on any network test.

              Note  that  "noclear" also affects whether stale status messages
              from e.g. a client on the host go purple or clear when the  host
              is  down; see the "noclear" description in the "GENERAL PER-HOST
              OPTIONS" section above.

              Disables the standard check of any  SSL  certificates  for  this
              host.  By default, if an SSL-enabled service is tested, a second
              test  result  is  generated  with  information  about  the   SSL
              certificate  -  this tag disables the SSL certificate checks for
              the host.

              Define the number of days before an SSL certificate expires,  in
              which the sslcert status shows a warning (yellow) or alarm (red)
              status. These default to the values from the "--sslwarndays" and
              "--sslalarmdays"  options for the bbtest-net(1) tool; the values
              specified in the "ssldays" tag overrides the default.

              Enable checking of the encryption strengt of  the  SSL  protocol
              offered  by  the server. If the server offers encryption using a
              key with fewer than MINIMUMKEYBITS bits, the "sslcert" test will
              go  red.  E.g.  to  check  that  your  server  only  uses strong
              encryption (128 bits or better), use "sslbits=128".

              This tag can be used to ignore  failed  checks  during  specific
              times  of  the  day  -  e.g.  if  you run services that are only
              monitored e.g. Mon-Fri 8am-5pm, or you always  reboot  a  server
              every Monday between 5 and 6 pm.

              What  happens is that if a test fails during the specified time,
              it is reported with status BLUE instead of yellow or  red.  Thus
              you  can  still see when the service was unavailable, but alarms
              will not be triggered and the downtime is  not  counted  in  the
              availability calculations generated by the Xymon reports.

              The  "columns" setting is optional - it may be a comma-separated
              list of status columns in which case the DOWNTIME  setting  only
              applies to these columns.

              The  "cause"  string (optional) is a text that will be displayed
              on the status web page to explain thy the system is down.

              The syntax for DOWNTIME is the same  as  the  one  used  by  the
              NKTIME parameter.

              This tag is now deprecated. Use the DOWNTIME tag instead.

              This  tag works the opposite of the DOWNTIME tag - you use it to
              specify the periods of the day that the service should be green.
              Failures OUTSIDE the SLA interval are reported as blue.

              This  tag  allows you to define dependencies betweeen tests.  If
              "testA" for the current host depends on "test1" for host "host1"
              and test "test2" for "host2", this can be defined with


              When   deciding  the  color  to  report  for  testA,  if  either
              host1/test1 failed or host2/test2 failed, if  testA  has  failed
              also  then  the color of testA will be "clear" instead of red or

              Since all tests are actually run  before  the  dependencies  are
              evaluated,  you  can  use  any  host/test  in  the  dependency -
              regardless of the actual sequence that the hosts are listed,  or
              the  tests run. It is also valid to use tests from the same host
              that the dependency is for. E.g.

         foo # http://foo/ webmin depends=(webmin:foo/http)

              is valid; if both the http  and  the  webmin  tests  fail,  then
              webmin will be reported as clear.

              Note:  The  "depends" tag is evaluated on the BBNET server while
              running the network tests. It can therefore only refer to  other
              network  tests that are handled by the same BBNET server - there
              is currently no way to use the e.g. the status  of  locally  run
              tests  (disk,  cpu,  msgs)  or  network  tests  from other BBNET
              servers  in  a  dependency  definition.  Such  dependencies  are
              silently ignored.

              Normally  when  a  network test fails, the status changes to red
              immediately.  With a "badTEST:x:y:z" tag this behaviour changes:
              *  While "z" or more successive tests fail, the column goes RED.
              * While "y" or more successive tests fail, but fewer  than  "z",
              the column goes YELLOW.
              *  While  "x" or more successive tests fail, but fewer than "y",
              the column goes CLEAR.
              * While fewer than "x" successive tests fail, the  column  stays

              The  optional  timespecification  can  be  used  to  limit  this
              "badTEST" setting to a particular time of day, e.g. to require a
              longer period of downtime before raising an alarm during out-of-
              office hours. The time-specification uses:
              * Weekdays: The  weekdays  this  badTEST  tag  applies,  from  0
              (Sunday)  through  6  (Saturday).  Putting  "W"  here  counts as
              "12345", i.e. all working days. Putting "*" here counts  as  all
              days of the week, equivalent to "0123456".
              * starttime and endtime are specified using 24-hour clocks, e.g.
              "badTEST-W-0900-2000" is valid for working  days  between  9  AM
              (09:00) and 8 PM (20:00).

              When  using multiple badTEST tags, the LAST one specified with a
              matching time-spec is used.

              Note: The "TEST" is replaced by the name of the test, e.g.

       # badhttp:1:2:4

              defines a http test that goes "clear" after the  first  failure,
              "yellow"  after  two  successive  failures, and "red" after four
              successive failures.

              For the other network tests, use "badftp", "badssh" etc.


       These tags affect the behaviour of the bbtest-net connectivity test.

       noping Disables the ping-test, but will keep the "conn" column  on  the
              web display with a notice that it has been disabled.

       noconn Disables  the ping-test, and does not put a "conn" column on the
              web display.

       conn   The "conn" test (which does a ping of the host) is  enabled  for
              all  hosts  by default, and normally you just want to disable it
              using "noconn" or "noping". However, on the rare occasion  where
              you  may want to check that a host is NOT up, you can specify it
              as an explicit test, and use the  normal  test  modifiers,  e.g.
              "!conn"  will  be  green  when the host is NOT up, and red if it
              does appear on the network.

              The actual name of the tag - "conn" by default - depends on  the
              "--ping=TESTNAME"  option  for  bbtest-net,  as that decides the
              testname for the connectivity test.

              This adds additional IP-adresses  that  are  pinged  during  the
              normal  "conn"  test.  So the normal "conn" test must be enabled
              (the default) before this tag has any  effect.  The  IP-adresses
              listed here are pinged in addition to the main IP-address.

              When  multiple  IP’s are pinged, you can choose if ALL IP’s must
              respond (the "worst" method), or AT LEAST one  IP  must  respond
              (the  "best"  setting). All of the IP’s are reported in a single
              "conn" status, whose color is  determined  from  the  result  of
              pinging the IP’s and the best/worst setting.  The default method
              is "best" - so it will report green if  just  one  of  the  IP’s
              respond to ping.

              This is taken directly from the "" connectivity- testing
              script, and is used by bbtest-net when it runs with ping testing
              enabled (the default). See the description of the "badTEST" tag.

              This tag is taken from the "" script,  and  is  used  by
              bbtest-net  when  run  with  the  "--ping" option to enable ping

              The router1,router2,...  is  a  comma-separated  list  of  hosts
              elsewhere  in  the  bb-hosts file. You cannot have any spaces in
              the list - separate hosts with commas.

              This tag changes the color reported for a ping check that fails,
              when  one or more of the hosts in the "route" list is also down.
              A "red" status becomes "yellow" - other  colors  are  unchanged.
              The  status  message will include information about the hosts in
              the router-list that are down, to aid tracking down which router
              is the root cause of the problem.

              Note:  Internally,  the  ping  test  will  still  be  handled as
              "failed", and therefore any other tests run for this  host  will
              report a status of "clear".

              If  the  BBLOCATION  environment  variable  is defined, a tag of
              "route_BBLOCATION:" is recognized by bbtest-net  with  the  same
              effect  as the normal "route:" tag (see above).  This allows you
              to have different route: tags for each BBNET server. The  actual
              text  for  the  tag  then  must match the value you have for the
              BBLOCATION setting.  E.g. with BBLOCATION=dmz, the  tag  becomes

       trace  If  the  connectivity test fails, run a "traceroute" and include
              the output from this in  the  status  message  from  the  failed
              connectivity  test.  Note:  For  this  to  work, you may have to
              define    the    TRACEROUTE    environment     variable,     see

              Similar  to  the  "trace" option, this disables the running of a
              traceroute for the host after a failed connectivity test. It  is
              only  used  if  running  traceroute  is made the default via the
              --trace option.


       These tests perform a simple network test of a service by connecting to
       the port and possibly checking that a banner is shown by the server.

       How   these   tests   operate  are  configured  in  the  bb-services(5)
       configuration file, which controls which port to use for  the  service,
       whether  to  send  any  data  to  the  service,  whether to check for a
       response from the service etc.

       You can modify the behaviour of these tests  on  a  per-test  basis  by
       adding  one  or  more  modifiers  to the test: :NUMBER changes the port
       number from the default to the one you specify for this test.  E.g.  to
       test ssh running on port 8022, specify the test as ssh:8022.

       :s  makes  the  test  silent,  i.e.  it  does  not send any data to the
       service. E.g. to do a silent test of an smtp server, enter smtp:s.

       You can combine these two: ftp:8021:s is valid.

       If you must test a service  from  a  multi-homed  host  (i.e.  using  a
       specific  source  IP-address  instead  of the one your operating system
       provides), you can use the modifier "@IPADDRESS" at the end of the test
       specification,  after  any other modifiers or port number.  "IPADDRESS"
       must be a valid dotted IP-address (not hostname) which is  assigned  to
       the host running the network tests.

       The  name  of  the  test  also  determines the columnname that the test
       result will appear with in the Xymon webpages.

       By prefixing a test with "!" it becomes  a  reverse  test:  Xymon  will
       expect  the  service NOT to be available, and send a green status if it
       does NOT respond. If a connection to the service succeeds,  the  status
       will go red.

       By  prefixing  a  test  with "?" errors will be reported with a "clear"
       status instead of red. This is known as a test for a "dialup"  service,
       and  allows  you  to  run  tests  of  hosts that are not always online,
       without getting alarms while they are off-line.

       ftp ssh telnet smtp pop3 imap nntp rsync clamd oratns qmtp qmqp
              These tags are for testing services  offering  the  FTP,  Secure
              Shell  (ssh),  SMTP,  POP3,  IMAP,  NNTP,  rsync, CLAM antivirus
              daemon (clamd), Oracle TNS listener  (oratns),  qmail  QMTP  and
              QMQP protocols.

       ftps telnets smtps pop3s imaps nntps
              These  tags  are for testing of the SSL-tunneled versions of the
              standard ftp, telnet, smtp, pop3, imap and nntp  protocols.   If
              Xymon  was  configured  with support for SSL, you can test these
              services like any other network service - bbtest-net will  setup
              an  SSL-encrypted session while testing the service.  The server
              certificate is validated and information about it  sent  in  the
              "sslcert"  column.  Note  that  smtps  does  not have a standard
              portnumber assignment, so you will need to enter this  into  the
              bb-services file or your /etc/services file.

       bbd    Test that a Big Brother compatible daemon is running. This check
              works both for the Xymon hobbitd(8) daemon, and the original Big
              Brother bbd daemon.


       These tags are used to setup monitoring of DNS servers.

       dns    Simple  DNS test. It will attempt to lookup the A record for the
              hostname of the DNS server.

       dig    This is an alias for the "dns" test. In  bbtest-net,  the  "dns"
              and   "dig"  tests  are  handled  identically,  so  all  of  the
              facilities for testing described for the  "dns"  test  are  also
              available for the "dig" test.


              The  default  DNS  tests  will  attempt a DNS lookup of the DNS’
              servers own hostname. You can specify the hostname to lookup  on
              a DNS server by listing it on each test.

              The  second  form  of  the  test  allows you to perform multiple
              queries of the DNS server, requesting  different  types  of  DNS
              records.  The TYPE defines the type of DNS data: A (IP-address),
              MX (Mail eXchanger), PTR (reverse), CNAME (alias),  SOA  (Start-
              Of-Authority),  NS  (Name Server) are among the more common ones
              used. The "lookup" is the query. E.g. to lookup the  MX  records
              for  the "" domain, you would use "". Or to
              lookup   the   nameservers    for    the    ""    domain,
              "".   You  can list multiple lookups, separated by
              commas. For the test to end up with a green status, all  lookups
              must succeed.


       ntp    Check  for  a running NTP (Network Time Protocol) server on this
              host. This test uses the "ntpdate" utility to check  for  a  NTP
              server - you should either have ntpdate in your PATH, or set the
              location of the ntpdate program in $BBHOME/etc/bbsys.local

              Check for one or more available  RPC  services.  This  check  is
              indirect in that it only queries the RPC Portmapper on the host,
              not the actual service.

              If only  "rpc"  is  given,  the  test  only  verifies  that  the
              portmapper is available on the remote host. If you want to check
              that  one  or  more  RPC  services  are  registered   with   the
              portmapper, list the names of the desired RPC services after the
              equals-sign.  E.g.  for  a  working  NFS  server  the   "mount",
              "nlockmgr"  and  "nfs"  services  must be available; this can be
              checked with "rpc=mount,nlockmgr,nfs".

              This test uses the rpcinfo tool for the  actual  test;  if  this
              tool is not available in the PATH of bbtest-net, you must define
              the RPCINFO environment variable to  point  at  this  tool.  See


       Simple testing of a http URL is done simply by putting the URL into the
       bb-hosts file. Note that this only applies to  URL’s  that  begin  with
       "http:" or "https:".

       The following items describe more advanced forms of http URL’s.

       Basic Authentication with username/password
              If the URL requires authentication in the form of a username and
              password,  it  is   most   likely   using   the   HTTP   "Basic"
              authentication. bbtest-net support this, and you can provide the
              username and password either by embedding them in the URL e.g.
              or by putting the username and password into the  ~/.netrc  file
              (see ftp(1) for details).

       Authentication with SSL client certificates
              An  SSL  client  certificate can be used for authentication.  To
              use this, the client  certificate  must  be  stored  in  a  PEM-
              formatted  file together with the client certificate key, in the
              $BBHOME/certs/ directory. The URL is then given as
              The "CERT:" part is literal - i.e. you write  C-E-R-T-colon  and
              then the filename of the PEM-formatted certificate.
              A  PEM-formatted  certificate  file  can  be  generated based on
              certificates stored in Microsoft Internet Explorer and  OpenSSL.
              Do as follows:
              From the MSIE Tools-Options menu, pick the Content tab, click on
              Certificates, choose the Personal tab,  select  the  certificate
              and  click Export. Make sure you export the private key also. In
              the Export  File  Format,  choose  PKCS  12  (.PFX),  check  the
              "Include  all  certificates"  checkbox  and  uncheck the "Enable
              strong  protection".   Provide  a  temporary  password  for  the
              exported file, and select a filename for the PFX-file.
              Now  run  "openssl  pkcs12  -in  file.pfx  -out  file.pem". When
              prompted  for  the  "Import  Password",  provide  the  temporary
              password you gave when exporting the certificate. Then provide a
              "PEM pass phrase" (twice) when prompted for one.
              The file.pem file is the one you  should  use  in  the  FILENAME
              field  in  the  URL  - this file must be kept in $BBHOME/certs/.
              The PEM pass phrase must be put into a file named  the  same  as
              the  certificate,  but with extension ".pass". E.g.  if you have
              the PEM certificate in $BBHOME/certs/client.pem,  you  must  put
              the  pass  phrase  into the $BBHOME/certs/client.pass file. Make
              sure to protect this file with Unix permissions,  so  that  only
              the user running Xymon can read it.

       Forcing an HTTP or SSL version
              Some  SSL  sites  will  only  allow  you  to connect, if you use
              specific "dialects" of HTTP  or  SSL.  Normally  this  is  auto-
              negotiated,  but  experience  shows  that  this  fails  on  some

              bbtest-net can be told to use specific dialects, by  adding  one
              or  more  "dialect  names" to the URL scheme, i.e. the "http" or
              "https" in the URL:

              * "2",  e.g. https2:// : use only SSLv2
              * "3",  e.g. https3:// : use only SSLv3
              * "m",  e.g. httpsm:// : use only 128-bit ciphers
              *  "h",   e.g.  httpsh://  :  use  only  >128-bit
              * "10", e.g. http10:// : use HTTP 1.0
              * "11", e.g. http11:// : use HTTP 1.1

              These can be combined where it makes sense, e.g to  force  SSLv2
              and HTTP 1.0 you would use "https210".

       Testing sites by IP-address
              bbtest-net  ignores  the  "testip"  tag normally used to force a
              test to use the IP-address from the bb-hosts file instead of the
              hostname, when it performs http and https tests.

              The  reason  for  this  is  that it interacts badly with virtual
              hosts, especially if these are IP-based as is common with https-

              Instead  the  IP-address  to  connect  to  can  be overridden by
              specifying it as:


              The "=" will case bbtest-net to run the test against  the
              IP-address  "",  but  still  trying  to  access a virtual
              website with the name "".

              The "" must be the last part of the hostname,
              so if you need to combine this with e.g. an explicit portnumber,
              it should be done as


       HTTP Testing via proxy
              bbtest-net supports the Big Brother  syntax  for  specifying  an
              HTTP  proxy  to use when performing http tests. This syntax just
              joins the proxy- and the target-URL into one, e.g.
              would be the syntax for testing the website via  the
              proxy running on "" port 3128.

              If  the  proxy  portnumber  is  not  specified, the default HTTP
              portnumber (80) is used.

              If your proxy  requires  authentication,  you  can  specify  the
              username and password inside the proxy-part of the URL, e.g.
              will authenticate to the proxy using a username of "fred" and  a
              password  of  "Wilma1", before requesting the proxy to fetch the

              Note that it is not possible to test https-sites  via  a  proxy,
              nor  is  it  possible  to  use https for connecting to the proxy

              This tag is used to specify a http/https check, where it is also
              checked that specific content is present in the server response.

              If the URL itself includes a semi-colon, this must be escaped as
              ’%3B’  to  avoid  confusion  over which semicolon is part of the
              URL, and which semicolon acts as a delimiter.

              The data that must be returned can  be  specified  either  as  a
              regular  expression (except that <space> is not allowed) or as a
              message digest (typically using an MD5 sum or SHA-1 hash).

              The regex is pre-processed for backslash "\"  escape  sequences.
              So  you  can really put any character in this string by escaping
              it first:
                 \n     Newline (LF, ASCII 10 decimal)
                 \r     Carriage return (CR, ASCII 13 decimal)
                 \t     TAB (ASCII 8 decimal)
                 \\    Backslash (ASCII 92 decimal)
                 \XX    The character with ASCII hex-value XX

              If you must have whitespace in the regex,  use  the  [[:space:]]
              syntax, e.g. if you want to test for the string "All is OK", use
              "All[[:space:]]is[[:space:]]OK".  Note that this may  depend  on
              your  particular  implementation of the regex functions found in
              your C library. Thanks to Charles Goyard for this tip.

              Note: If you are migrating from the "" script, you  must
              change  the  ’_’ used as wildcards by into ’.’ which is
              the regular-expression wildcard character.

              Message  digests  can  use  whatever  digest   algorithms   your
              libcrypto  implementation  (usually  OpenSSL)  supports.  Common
              message digests are "md5" and "sha1". The digest  is  calculated
              on  the  data portion of the response from the server, i.e. HTTP
              headers are not included in the digest (as they change from  one
              request to the next).

              The  expected  digest value can be computed with the bbdigest(1)

              "cont" tags in bb-hosts result in two status reports: One status
              with the "http" check, and another with the "content" check.

              As with normal URL’s, the extended syntax described above can be
              used e.g. when testing SSL sites that require the use  of  SSLv2
              or strong ciphers.

              The  column  name  for  the  result  of  the content check is by
              default called "content" - you can change the default  with  the
              "--content=NAME"  option  to bbtest-net. See bbtest-net(1) for a
              description of this option.

              If more than one content check is present for a host, the  first
              content check is reported in the column "content", the second is
              reported in the column "content1", the third in "content2"  etc.

              You  can  also  specify  the  columnname  directly  in  the test
              specification,  by  writing  it   as   "cont=COLUMN;http://...".
              Column-names cannot include whitespace or semi-colon.

              The  content-check  status by default includes the full URL that
              was requested, and the HTML data returned by  the  server.   You
              can  hide  the  HTML  data on a per-host (not per-test) basis by
              adding the HIDEHTTP tag to the host entry.

              This syntax  is  deprecated.  You  should  use  the  "cont"  tag
              instead, see above.

              This  tag can be used to test web pages, that use an input form.
              Data can be posted to the form by specifying them in  the  form-
              data  field, and the result can be checked as if it was a normal
              content check (see above for a description of the  cont-tag  and
              the restrictions on how the URL must be writen).

              The  form-data field must be entered in "application/x-www-form-
              urlencoded" format, which is the most commonly used  format  for
              web forms.

              E.g. if you have a web form defined like this:

                 <form action="/cgi-bin/form.cgi" method="post">
                   <p>Given name<input type="text" name="givenname"></p>
                   <p>Surname<input type="text" name="surname"></p>
                   <input type="submit" value="Send">

              and  you  want  to  post the value "John" to the first field and
              "Doe Jr." to the second field, then the formdata field would be


              Note that any spaces in the input value is replaced with ’+’.

              If your form-data requires a  different  content-type,  you  can
              specify  it by beginning the form-data with (content-type=TYPE),
              e.g. "(content-type=text/xml)" followed by the POST  data.  Note
              that  as  with  normal  forms, the POST data should be specified
              using escape-sequences for reserved characters:  "space"  should
              be  entered  as "\x20", double quote as "\x22", newline as "\n",
              carriage-return as "\r", TAB as "\t", backslash  as  "\\".   Any
              byte  value  can  be  entered  using  "\xNN"  with  NN being the
              hexadecimal value, e.g. "\x20" is the space character.

              The [expected_data_regexp|#digesttype:digest]  is  the  expected
              data  returned from the server in response to the POST.  See the
              "cont;" tag above for details. If you  are  only  interested  in
              knowing  if  it  is  possible to submit the form (but don’t care
              about the data), this can be an empty string - but  the  ’;’  at
              the end is required.

              This  tag works just like "cont" tag, but reverses the test.  It
              is green when the "forbidden_data_regexp" is NOT  found  in  the
              response,  and  red when it IS found. So it can be used to watch
              for data that should NOT be present  in  the  response,  e.g.  a
              server error message.

              This  tag works just like "post" tag, but reverses the test.  It
              is green when the "forbidden_data_regexp" is NOT  found  in  the
              response,  and  red when it IS found. So it can be used to watch
              for data that should NOT be present  in  the  response,  e.g.  a
              server error message.

              This is a variant of the content check - instead of checking the
              content data, it checks the type of the data  as  given  by  the
              HTTP  Content-Type:  header.  This  can  used  to check if a URL
              returns e.g. a PDF file, regardless of what is  inside  the  PDF

              Send  SOAP  message  over  HTTP. This is identical to the "cont"
              test, except that the request sent to the server uses a Content-
              type of "application/soap+xml", and it also sends a "SOAPAction"
              header with the URL. SOAPMESSAGE is the SOAP message sent to the
              server.  Since  SOAP messages are usually XML documents, you can
              store this in a separate file by specifying  "file:FILENAME"  as
              the SOAPMESSAGE parameter.  E.g. a test specification of
              will read the SOAP message from the file  /home/foo/msg.xml  and
              post it to the URL

              Note  that  SOAP  XML  documents usually must begin with the XML
              version line, <?xml version="1.0">

              This tag works just like "soap" tag, but reverses the test.   It
              is  green  when  the "forbidden_data_regexp" is NOT found in the
              response, and red when it IS found. So it can be used  to  watch
              for  data  that  should  NOT  be present in the response, e.g. a
              server error message.

              This is used to explicitly test  for  certain  HTTP  statuscodes
              returned  when  the  URL  is  requested.  The  okstatusexpr  and
              nokokstatusexpr   expressions   are   Perl-compatible    regular
              expressions,  e.g.  "2..|302"  will  match  all OK codes and the
              redirect (302) status code. If the URL cannot be  retrived,  the
              status is "999".

              The status display for HTTP checks usually includes the URL, and
              for content checks also the actual data from  the  webpage.   If
              you  would  like  to hide these from view, then the HIDEHTTP tag
              will keep  this  information  from  showing  up  on  the  status

              By  default, Xymon sends an HTTP "User-Agent" header identifying
              it a "Xymon". Some websites require  that  you  use  a  specific
              browser,  typically  Internet  Explorer. To cater for testing of
              such sites, this tag can be used to modify the data sent in  the
              User-Agent header.
              E.g.  to  perform  an  HTTP  test  with Xymon masquerading as an
              Internet  Explorer   6.0   browser,   use   browser="Mozilla/4.0
              (compatible;  MSIE  6.0;  Windows  NT 5.0)".  If you do not know
              what the User-Agent header should be, open up the  browser  that
              works   with   this   particular   site,   and   open   the  URL
              "javascript:document.writeln(navigator.userAgent)"  (just   copy
              this  into the "Open URL" dialog. The text that shows up is what
              the browser sends as the User-Agent header.



       ldaps  Simple check for an LDAP service. This check  merely  looks  for
              any service running on the ldap/ldaps service port, but does not
              perform any actual LDAP transaction.

              Check for an LDAP service by performing an  LDAP  request.  This
              tag  is  in the form of an LDAP URI (cf. RFC 2255). This type of
              LDAP test requires that bbtest-net(1) was built with support for
              LDAP, e.g. via the OpenLDAP library.  The components of the LDAP
              URI are:
                hostport is a host name with an optional ":portnumber"
                dn is the search base
                attrs is a comma separated list of attributes to request
                scope is one of these three strings:
                  base one sub (default=base)
                filter is filter
                exts are recognized set of LDAP and/or API extensions.

              LDAP service check using LDAPv3 and STARTTLS for talking  to  an
              LDAP  server that requires TLS encryption. See bbtest-net(1) for
              a discussion of the different ways of running LDAP servers  with
              SSL/TLS, and which of these are supported by bbtest-net.

              Define  a  username and password to use when binding to the LDAP
              server for ldap URI tests. If  not  specified,  bbtest-net  will
              attempt an anonymous bind.

              Used  with  an LDAP URL test. If the LDAP query fails during the
              search of the directory, the ldap status is normally reported as
              "red"  (alarm).  This tag reduces a search failure to a "yellow"
              (warning) status.


              If you are running an Apache webserver, adding  this  tag  makes
              bbtest-net(1)  collect  performance  statistics  from the Apache
              webserver by querying the URL  http://IP.ADDRESS.OF.HOST/server-
              status?auto.    The  response  is  sent  as  a  data-report  and
              processed by the Xymon hobbitd_rrd module into an RRD  file  and
              an   "apache"   graph.   If   your   webserver   requires   e.g.
              authentication, or runs on  a  different  URL  for  the  server-
              status, you can provide the full URL needed to fetch the server-
              status page, e.g.  apache=http://LOGIN:PASSWORD@
              status?auto  for  a  password  protected  server-status page, or
              apache=   for    a
              server  listening  on port 8080 and with a different path to the
              server-status page.

              Note that you need to  enable  the  server-status  URL  in  your
              Apache configuration. The following configuration is needed:

                  <Location /server-status>
                      SetHandler server-status
                      Order deny,allow
                      Deny from all
                      allow from
                  ExtendedStatus On

              Change  ""  to  the  IP-address of the server that runs
              your network tests.


       If you have certain tags that you want to apply to all hosts,  you  can
       define a host name ".default." and put the tags on that host. Note that
       per-host definitions will override the default ones.

       NOTE: The ".default." host entry will only accept the following tags  -
       others  are silently ignored: NOCOLUMNS, COMMENT, DESCR, CLASS, dialup,
       testip,   nobb2,   nodisp,   noinfo,   notrends,   TRENDS,   NOPROPRED,
       noclear, nosslcert, ssldays, DOWNTIME, depends, noping, noconn,  trace,
       notrace,  HIDEHTTP,  browser, pulldata. Specifically, note that network
       tests, "badTEST" settings, and alternate pageset  relations  cannot  be
       listed on the ".default." host.


       summary ROW.COLUMN IP URL
              If you have multiple Xymon servers, the "summary" directive lets
              you form a hierarchy of servers by sending the overall status of
              this  server  to a remote Xymon server, which then displays this
              in a special summary section. E.g. if your  offices  are  spread
              over  three  locations,  you  can  have  a  Xymon server at each
              office. These branch-office Xymon have a "summary" definition in
              their bb-hosts file that makes them report the overall status of
              their branch Xymon to the central Xymon server you  maintain  at
              the corporate headquarters.

              Multiple "summary" definitions are allowed.

              The  ROW.COLUMN setting defines how this summary is presented on
              the server that receives the summary. The ROW text will be  used
              as  the  heading  for a summary line, and the COLUMN defines the
              name of the column where  this  summary  is  shown  -  like  the
              hostname and testname used in the normal displays. The IP is the
              IP-address of the remote (upstream)  Xymon  server,  where  this
              summary is sent). The URL is the URL of your local Xymon server.

              The URL need not be that of your Xymon server’s main page  -  it
              could  be  the URL of a subpage on the local Xymon server. Xymon
              will report the summary using the color of the page found at the
              URL you specify.  E.g. on your corporate Xymon server you want a
              summary from the Las Vegas office - but you would like  to  know
              both  what  the overall status is, and what is the status of the
              servers on the critical Sales department back-office servers  in
              Las  Vegas.  So you configure the Las Vegas Xymon server to send
              two summaries:

                  summary Vegas.All
                  summary                 Vegas.Sales       

              This gives you one summary line for Baltimore, with two columns:
              An "All" column showing the overall status, and a "Sales" column
              showing  the  status  of the "sales" page on the Baltimore Xymon

              Note: Pages defined using alternate pageset  definitions  cannot
              be used, the URL must point to a webpage from the default set of
              Xymon webpages.


              This option is recognized by  the  hobbitfetch(8)  utility,  and
              causes  it  to  poll  the host for client data. The optional IP-
              address  and  port-number  can  be  used  if   the   client-side
              msgcache(8)  daemon is listening on a non-standard IP-address or




       bbgen(1), bbtest-net(1), bbdigest(1), hobbitserver.cfg(5), xymon(7)