Provided by: xymon_4.3.0~beta2.dfsg-9.1_amd64 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

       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

       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

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

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

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

              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

              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

              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-

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

       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,
              * 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. "TRENDS:*"
              * 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

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

              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 NKTIME=*:0000:1159,*:1300:2359

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


       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

              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


       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

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

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

              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 bbtest-net(1)

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

              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
              *  While  "x"  or  more  successive tests fail, but fewer than "y", the column goes
              * While fewer than "x" successive tests fail, the column stays GREEN.

              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

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

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

       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 hobbitserver.cfg(5)

              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

       :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

       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 hobbitserver.cfg(5)


       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

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

              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 ciphers
              * "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-websites.

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

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

              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

              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

              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

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

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

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

              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
                  soap=echo;;file:/home/foo/msg.xml;.  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

              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



       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-

              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,
       NET, 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 server.

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




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