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


       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 (bb2.html), and a specially reduced version  of
       bb2.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 bb2.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".

              Note: libssl 1.0.0 in Debian deprecates the  use  of  SSLv2  and
              hence https2 will fall back to testing SSLv3.

       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)