In Xymon, the bb program is also used for administrative purposes, e.g. to rename or delete hosts, or to disable hosts that are down for longer periods of time.
Usually, a client will use "$BBDISP" for the RECIPIENT parameter, as this is defined for the client scripts to automatically contain the correct value.
The RECIPIENT parameter may be a URL for a webserver
that has the bbmessage.cgi or similar script installed. This
tunnels the Xymon messages to the BBDISPLAY server
using standard HTTP protocol. The
bbmessage.cgi(8)
CGI tool (included in Xymon) must be installed on the webserver
for the HTTP transport to work.
If you need to send longer status messages, you can specify "@" as the message: bb will then read the status message from its stdin.
This section lists the most commonly used messages in the Xymon protocol.
Each message must begin with one of the Xymon commands. Where a HOSTNAME is specified, it must have any dots in the hostname changed to commas if the Xymon FQDN setting is enabled (which is the default). So e.g. the host "www.foo.com" would report as "www,foo,com".
hostname The name of the host
testname The name of the test
color Status color (green, yellow, red, blue, clear, purple)
testflags For network tests, the flags indicating details about the test (used by bbgen).
lastchange Unix timestamp when the status color last changed.
logtime Unix timestamp when the log message was received.
validtime Unix timestamp when the log message is no longer valid (it goes purple at this time).
acktime -1, or Unix timestamp when an active acknowledgement expires.
disabletime -1, or Unix timestamp when the status is no longer disabled.
sender IP-address where the status was received from.
cookie -1, or the cookie value used to acknowledge an alert.
ackmsg Empty, or the acknowledgment message sent when the status was acknowledged. Newline, pipe-signs and backslashes are escaped by with a backslash in C-style.
dismsg Empty, or the message sent when the status was disabled. Newline, pipe-signs and backslashes are escaped by with a backslash in C-style.
After the first line comes the full status log in plain text format.
By default - if no CRITERIA is provided - it returns one line for all status messages that are found in Xymon. You can filter the response by selecting a page, a host, a test or a color - wildcards are not supported, so you can pick only one page, host, test or color.
page=PAGEPATH Include only tests from hosts found on the PAGEPATH page in the bb-hosts file.
host=HOSTNAME Include only tests from the host HOSTNAME
test=TESTNAME Include only tests with the testname TESTNAME
color=COLORNAME Include only tests where the status color is COLORNAME
You can filter on e.g. both a hostname and a testname.
The response is one line for each status that matches the CRITERIA, or all statuses if no criteria is specified. The line is composed of a number of fields, separated by a pipe-sign. You can select what fields to retrieve by listing them in the FIELDLIST. The following fields are available:
hostname The name of the host
testname The name of the test
color Status color (green, yellow, red, blue, clear, purple)
flags For network tests, the flags indicating details about the test (used by bbgen).
lastchange Unix timestamp when the status color last changed.
logtime Unix timestamp when the log message was received.
validtime Unix timestamp when the log message is no longer valid (it goes purple at this time).
acktime -1, or Unix timestamp when an active acknowledgement expires.
disabletime -1, or Unix timestamp when the status is no longer disabled.
sender IP-address where the status was received from.
cookie -1, or the cookie value used to acknowledge an alert.
line1 First line of status log.
ackmsg Empty (if no acknowledge is active), or the text of the acknowledge message.
dismsg Empty (if the status is currently enabled), or the text of the disable message.
msg The full text of the current status message.
The ackmsg, dismsg and msg fields have certain characters encoded: Newline is "\n", TAB is "\t", carriage return is "\r", a pipe-sign is "\p", and a backslash is "\\".
If the "fields" parameter is omitted, a default set of hostname,testname,color,flags,lastchange,logtime,validtime,acktime,disabletime,sender,cookie,line1 is used.
Send a normal status message to the BBDISPLAY server, using the
standard Xymon protocol on TCP port 1984:
$ $BB $BBDISP "status www,foo,com.http green `date` Web OK"
Send the same status message, but using HTTP protocol via the
webservers' bbmessage.cgi script:
$ $BB http://bb.foo.com/cgi-bin/bbmessage.cgi "status www,foo,com.http green `date` Web OK"
Use "query" message to determine the color of the "www" test, and
restart Apache if it is red:
$ WWW=`$BB $BBDISP "query www,foo,com.www" | awk '{print $1}'`
$ if [ "$WWW" = "red" ]; then /etc/init.d/apache restart; fi
Use "config" message to update the local bb-dftab file (but only
if we get a response):
$ $BB $BBDISP "config bb-dftab" >/tmp/bb-dftab.new
$ if [ -s /tmp/bb-dftab.new ]; then
mv /tmp/bb-dftab.new $BBHOME/etc/bb-dftab
fi
Send a very large status message that has been built in the file "statusmsg.txt". Instead of providing it on the command line, pass it via stdin to the bb command:
$ cat statusmsg.txt | $BB $BBDISP "@"