Provided by: xymon-client_4.3.0~beta2.dfsg-9.1_amd64 bug

NAME

       bbhostgrep - pick out lines in bb-hosts

SYNOPSIS

       bbhostgrep --help
       bbhostgrep --version
       bbhostgrep [--noextras] [--test-untagged] [--bbdisp] [--bbnet] TAG [TAG...]

DESCRIPTION

       bbhostgrep(1)  is  for use by extension scripts that need to pick out the entries in a bb-
       hosts file that are relevant to the script.

       The utility accepts test names as parameters, and will then parse the  bb-hosts  file  and
       print  out the host entries that have at least one of the wanted tests specified. Tags may
       be given with a trailing asterisk '*', e.g. "bbhostgrep http*" is needed to find all  http
       and https tags.

       The  bbhostgrep utility supports the use of "include" directives inside the bb-hosts file,
       and will find matching tags in all included files.

       If the DOWNTIME or SLA tags are used  in  the  bb-hosts(5)  file,  these  are  interpreted
       relative  to  the current time.  bbhostgrep then outputs a "INSIDESLA" or "OUTSIDESLA" tag
       for easier use by scripts that want to check if the current time is inside or outside  the
       expected uptime window.

OPTIONS

       --noextras
              Remove the "testip", "dialup", "INSIDESLA" and "OUTSIDESLA" tags from the output.

       --test-untagged
              When  using  the BBLOCATION environment variable to test only hosts on a particular
              network segment, bbtest-net will ignore hosts that do not have any "NET:x" tag.  So
              only hosts that have a NET:$BBLOCATION tag will be tested.
              With  this  option,  hosts  with  no NET: tag are included in the test, so that all
              hosts that either have a matching NET: tag, or no NET: tag at all are tested.

       --no-down[=TESTNAME]
              bbhostgrep will query the Xymon server for the current status of the  "conn"  test,
              and  if  TESTNAME is specified also for the current state of the specified test. If
              the status of the "conn" test for a  host  is  non-green,  or  the  status  of  the
              TESTNAME  test  is  disabled, then this host is ignored and will not be included in
              the output.  This can be used to ignore hosts that are down,  or  hosts  where  the
              custom test is disabled.

       --bbdisp
              Search the bb-hosts file following include statements as a BBDISPLAY server would.

       --bbnet
              Search the bb-hosts file following include statements as a BBNET server would.

EXAMPLE

       If your bb-hosts file looks like this

          192.168.1.1   www.test.com  # ftp telnet !oracle
          192.168.1.2   db1.test.com  # oracle
          192.168.1.3   mail.test.com # smtp

       and you have a custom Xymon extension script that performs the "oracle" test, then running
       "bbhostgrep oracle" would yield

          192.168.1.1   www.test.com  # !oracle
          192.168.1.2   db1.test.com  # oracle

       so the script can quickly find the hosts that are of interest.

       Note that the reverse-test modifier - "!oracle" - is included in  the  output;  this  also
       applies  to  the  other  test  modifiers  defined  by  Xymon  (the  dialup and always-true
       modifiers).

       If your extension scripts use more than one tag, just list all of the interesting tags  on
       the command line.

       bbhostgrep  also  supports  the  "NET:location"  tag used by bbtest-net, so if your script
       performs network checks then it will see only the hosts that are  relevant  for  the  test
       location that the script currently executes on.

USE IN EXTENSION SCRIPTS

       To  integrate  bbhostgrep  into  an  existing script, look for the line in the script that
       grep's in the $BBHOSTS file.  Typically it will look somewhat like this:

          $GREP -i "^[0-9].*#.*TESTNAME" $BBHOSTS | ... code to handle test

       Instead of the grep, we will use bbhostgrep. It then becomes

          $BBHOME/bin/bbhostgrep TESTNAME | ... code to handle test

       which is simpler, less error-prone and more efficient.

ENVIRONMENT VARIABLES

       BBLOCATION
              If  set,  bbhostgrep  outputs  only  lines  from  bb-hosts  that  have  a  matching
              NET:$BBLOCATION setting.

       BBHOSTS
              Filename for the Xymon bb-hosts(5) file.

FILES

       $BBHOSTS
              The Xymon bb-hosts file

SEE ALSO

       bb-hosts(5), hobbitserver.cfg(5)