BBHOSTGREP(1)						      General Commands Manual						     BBHOSTGREP(1)

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 dis-
	      abled, 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)

Xymon							    Version 4.2.3:  4 Feb 2009						     BBHOSTGREP(1)