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)