Provided by: hobbit-client_4.2.0.dfsg-12_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 Hobbit 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  Hobbit  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 Hobbit
       (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 Hobbit bb-hosts(5) file.

FILES

       $BBHOSTS
              The Hobbit bb-hosts file

SEE ALSO

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