Provided by: hobbit_4.2.0.dfsg-12_i386 bug

NAME

       bb-hosts - Main Hobbit configuration file

SYNOPSIS

       bb-hosts

DESCRIPTION

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

FILE FORMAT

       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  Hobbit  on-line
       documentation  (from  the  Help menu, choose "Configuring Monitoring").
       The following describes  the  possible  settings  in  a  bb-hosts  file
       supported by Hobbit.

TAGS RECOGNIZED BY ALL TOOLS

       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.

BBGEN DISPLAY OPTIONS

       These tags are processed by  the  bbgen(1)  tool  when  generating  the
       Hobbit 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
              Hobbit 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 mkbb.pl 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 Hobbit and  bbgen,  but  both  forms  are
              allowed for backwards compatibility.

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

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

       NAME:hostname
              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"

       CLIENT:hostname
              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   Hobbit
              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.

       NOCOLUMNS:column[,column]
              Used to drop certain of the  status  columns  generated  by  the
              Hobbit  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
              webserver"

       DESCR:Hosttype:Description
              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"

       CLASS:Classname
              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   Hobbit   client   with   the
              "--class=Classname"  option.   If you specify it in the bb-hosts
              file on the Hobbit 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 Hobbit 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.

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

       TRENDS:[*,][![graph,...]]
              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.
              "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.

HOBBIT TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE

       NOTE: The "NK" set of tags is deprecated. They will  be  supported  for
       Hobbit  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.

       NK:testname[,testname]
              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

                12.34.56.78  www.acme.com  # http://www.acme.com/ 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).

       NKTIME=day:starttime:endtime[,day:starttime:endtime]
              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.

HOBBIT TAGS FOR THE WML (WAP) CARDS

       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.

       WML:[+|-]testname[,[+|-]testname]
              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.

HOBBIT STATUS PROPAGATION OPTIONS

       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.

       NOPROPRED:[+|-]testname[,[+|-]testname]
              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.

       NOPROPYELLOW:[+|-]testname[,[+|-]testname]
              Similar to NOPROPRED: tag, but applies to propagating  a  yellow
              status upwards.

       NOPROPPURPLE:[+|-]testname[,[+|-]testname]
              Similar  to  NOPROPRED: tag, but applies to propagating a purple
              status upwards.

       NOPROPACK:[+|-]testname[,[+|-]testname]
              Similar  to  NOPROPRED:  tag,  but  applies  to  propagating  an
              acknowledged status upwards.

HOBBIT AVAILABILITY REPORT OPTIONS

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

       REPORTTIME=day:starttime:endtime[,day:starttime:endtime]
              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
                REPORTTIME=W:0700:2000
              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.

       WARNPCT:percentage
              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%

NETWORK TEST SETTINGS

       NET:location
              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)

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

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

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

       ssldays=WARNDAYS:ALARMDAYS
              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.

       DOWNTIME=day:starttime:endtime:cause[,day:starttime:endtime:cause]
              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 Hobbit reports.

              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.

       SLA=day:starttime:endtime[,day:starttime:endtime]
              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.

       depends=(testA:host1/test1,host2/test2),(testB:host3/test3),[...]
              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

                 depends=(testA:host1/test1,host2/test2)

              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.

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

       badTEST[-weekdays-starttime-endtime]:x:y:z
              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
              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.

               12.34.56.78  www.foo.com  # http://www.foo.com/ 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.

CONNECTIVITY (PING) TEST

       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.

       conn={best,|worst,}IP1[,IP2...]
              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.

       badconn[-weekdays-starttime-endtime]:x:y:z
              This is taken directly from the "fping.sh" 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.

       route:router1,router2,....
              This tag is taken from the "fping.sh" 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".

       route_LOCATION:router1,router2,...
              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)

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

SIMPLE NETWORK TESTS

       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.

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

       By  prefixing  a  test  with "!" it becomes a reverse test: Hobbit 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
              Hobbit 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 Hobbit hobbitd(8) daemon, and the original
              Big Brother bbd daemon.

DNS SERVER TESTS

       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.

       dns=hostname

       dns=TYPE:lookup[,TYPE:lookup...]
              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 "foo.com" domain, you would use "dns=mx:foo.com". Or  to
              lookup    the    nameservers    for    the   "bar.org"   domain,
              "dns=ns:bar.org".  You can list multiple lookups,  separated  by
              commas.  For the test to end up with a green status, all lookups
              must succeed.

OTHER NETWORK TESTS

       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

       rpc[=rpcservice1,rpcservice2,...]
              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)

HTTP TESTS

       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.
                  http://USERNAME:PASSWORD@www.sample.com/
              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
                  http://CERT:FILENAME@www.sample.com/
              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 Hobbit 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://www.sample.com/ : use only SSLv2
              * "3",  e.g. https3://www.sample.com/ : use only SSLv3
              * "m",  e.g. httpsm://www.sample.com/ : use only 128-bit ciphers
              *  "h",   e.g.  httpsh://www.sample.com/  :  use  only  >128-bit
              ciphers
              * "10", e.g. http10://www.sample.com/ : use HTTP 1.0
              * "11", e.g. http11://www.sample.com/ : use HTTP 1.1

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

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

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

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

                   http://www.sample.com=1.2.3.4/index.html

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

              The "=ip.address.of.host" 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://www.sample.com:3128=1.2.3.4/index.html

       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.
                  http://webproxy.sample.com:3128/http://www.foo.com/
              would  be the syntax for testing the www.foo.com website via the
              proxy running on "webproxy.sample.com" 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.
                  http://fred:Wilma1@webproxy.sample.com:3128/http://www.foo.com/
              will  authenticate to the proxy using a username of "fred" and a
              password of "Wilma1", before requesting the proxy to  fetch  the
              www.foo.com 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.

       cont[=COLUMN];URL;[expected_data_regexp|#digesttype:digest]
              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 "cont2.sh" script, you must
              change the ’_’ used as wildcards by cont2.sh 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)
              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-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.

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

       post[=COLUMN];URL;form-data;[expected_data_regexp|#digesttype:digest]
              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">
                 </form>

              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

                  givenname=John&surname=Doe+Jr.

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

              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.

       nocont[=COLUMN];URL;forbidden_data_regexp
              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.

       nopost[=COLUMN];URL;form-data;expected_data_regexp
              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.

       type[=COLUMN];URL;expected_content_type
              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.

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

       browser=BROWSERNAME
              By default, Hobbit sends an HTTP "User-Agent" header identifying
              it  a  "Hobbit".  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  Hobbit  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.

LDAP (DIRECTORY SERVER) TESTS

       ldap

       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.

       ldap://hostport/dn[?attrs[?scope[?filter[?exts]]]]
              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.

       ldaps://hostport/dn[?attrs[?scope[?filter[?exts]]]]
              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.

       ldaplogin=username:password
              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.

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

PERFORMANCE MONITORING TESTS

       apache[=URL]
              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 Hobbit 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@10.0.0.1/server-
              status?auto for a  password  protected  server-status  page,  or
              apache=http://10.0.0.1:8080/apache/server-status?auto    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 127.0.0.1
                  </Location>
                  ExtendedStatus On

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

DEFAULT HOST

       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,
       NOPROPYELLOW,  NOPROPPURPLE,  NOPROPACK,  REPORTTIME,   WARNPCT,   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.

SENDING SUMMARIES TO REMOTE HOBBIT SERVERS

       summary ROW.COLUMN IP URL
              If you have multiple Hobbit  servers,  the  "summary"  directive
              lets  you  form  a  hierarchy  of servers by sending the overall
              status of this server to a  remote  Hobbit  server,  which  then
              displays this in a special summary section. E.g. if your offices
              are spread over three locations, you can have a Hobbit server at
              each  office.  These  branch-office  Hobbits  have  a  "summary"
              definition in their bb-hosts file that  makes  them  report  the
              overall  status  of  their  branch  Hobbit to the central Hobbit
              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) Hobbit server, where this
              summary is sent). The URL  is  the  URL  of  your  local  Hobbit
              server.

              The  URL need not be that of your Hobbit server’s main page - it
              could be the URL of a subpage on the local Hobbit server. Hobbit
              will report the summary using the color of the page found at the
              URL you specify.  E.g. on your corporate Hobbit 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 Hobbit server to  send
              two summaries:

                  summary Vegas.All 10.0.1.1 http://vegas.foo.com/hobbit/
                  summary                 Vegas.Sales                 10.0.1.1
              http://vegas.foo.com/hobbit/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  Hobbit
              server.

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

OTHER TAGS

       pulldata[=[IP][:port]]
              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-number.

FILES

       ~hobbit/server/etc/bb-hosts

SEE ALSO

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