Provided by: xymon-client_4.3.0~beta2.dfsg-9.1_i386 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)