NAME
bb - Xymon client communication program
SYNOPSIS
bb [options] RECIPIENT message
DESCRIPTION
bb(1) is the client program used to communicate with a Xymon server. It
is frequently used by Xymon client systems to send in status messages
and pager alerts on local tests.
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.
OPTIONS AND PARAMETERS
--debug
Enable debugging. This prints out details about how the
connection to the BBDISPLAY server is being established.
--proxy=http://PROXYSERVER:PROXYPORT/
When sending the status messages via HTTP, use this server as an
HTTP proxy instead of connecting directly to the BBDISPLAY
server.
--timeout=N
Specifies the timeout for connecting to the Xymon server, in
seconds. The default is 5 seconds.
RECIPIENT
The RECIPIENT parameter defines which server receives the
message. If RECIPIENT is given as "0.0.0.0", then the message is
sent to all of the servers listed in the BBDISPLAYS or BBPAGERS
environment variable (for "status" and "page" messages,
respectively).
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.
MESSAGE
The message parameter is the message to be sent across to the
Xymon server. Messages must be enclosed in quotes, but by doing
so they can span multiple lines. The maximum size of a message
is defined by the maximum allowed length of your shell’s
commandline, and is typically 8-32 KB.
If you need to send longer status messages, you can specify "@"
as the message: bb will then read the status message from its
stdin.
XYMON MESSAGE SYNTAX
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".
status[+LIFETIME][/group:GROUP] HOSTNAME.TESTNAME COLOR <additional
text>
This sends in a status message for a single test (column) on a
single host. TESTNAME is the name of the column where this test
will show up; any name is valid except that using dots in the
testname will not work. COLOR must be one of the valid colors:
"green", "yellow", "red" or "clear". The colors "blue" and
"purple" - although valid colors - should not be sent in a
status-message, as these are handled specially by the Xymon
server.
The "additional text" normally includes a local timestamp and a
summary of the test result on the first line. Any lines
following the first one are free-form, and can include any
information that may be useful to diagnose the problem being
reported.
The LIFETIME defines how long this status is valid after being
received by the Xymon server. The default is 30 minutes, but you
can set any period you like. E.g. for a custom test that runs
once an hour, you will want to set this to at least 60 minutes -
otherwise the status will go purple after 30 minutes. It is a
good idea to set the LIFETIME to sligtly more than the interval
between your tests, to allow for variations in the time it takes
your test to complete. The LIFETIME is in minutes, unless you
add an "h" (hours), "d" (days) or "w" (weeks) immediately after
the number, e.g. "status+5h" for a status that is valid for 5
hours.
The GROUP option is used to direct alerts from the status to a
specific group. It is currently used for status generated from
the Xymon clients’ data, e.g. to direct alerts for a "procs"
status to different people, depending on exactly which process
is down.
notify HOSTNAME.TESTNAME <message text>
This triggers an informational message to be sent to those who
receive alerts for this HOSTNAME+TESTNAME combination, according
to the rules defined in hobbit-alerts.cfg(5) This is used by the
hobbit-enadis.cgi(1) tool to notify people about hosts being
disabled or enabled, but can also serve as a general way of
notifying server administrators.
data HOSTNAME.DATANAME<newline><additional text>
The "data" message allows tools to send data about a host,
without it appearing as a column on the Xymon webpages. This is
used e.g. to report statistics about a host, e.g. vmstat data
which does not in itself represent something that has a red,
yellow or green identity. It is used by RRD bottom-feeder
modules, among others. In Xymon, data messages are by default
processed only by the hobbitd_rrd(8) module. If you want to
handle data-messages by an external application, you may want to
enable the hobbitd_filestore(8) module for data-messages, to
store data-messages in a format compatible with how the Big
Brother daemon does.
disable HOSTNAME.TESTNAME DURATION <additional text>
Disables a specific test for DURATION minutes. This will cause
the status of this test to be listed as "blue" on the BBDISPLAY
server, and no alerts for this host/test will be generated. If
DURATION is given as a number followed by s/m/h/d, it is
interpreted as being in seconds/minutes/hours/days respectively.
To disable all tests for a host, use an asterisk "*" for
TESTNAME.
enable HOSTNAME.TESTNAME
Re-enables a test that had been disabled.
query HOSTNAME.TESTNAME
Query the BBDISPLAY server for the latest status reported for
this particular test. If the host/test status is known, the
response is the first line of the status report - the current
color will be the first word on the line. Additional lines of
text that might be present on the status-message cannot be
retrieved.
This allows any Xymon client to determine the status of a
particular test, whether it is one pertaining to the host where
the client is running, some other host, or perhaps the result of
a combined test from multiple hosts managed by bbcombotest(1)
This will typically be useful to Xymon client extension scripts,
that need to determine the status of other hosts e.g. to decide
if an automatic recovery action should be initiated.
config FILENAME
Retrieve one of the Xymon configuration files from the server.
This command allows a client to pull files from the $BBHOME/etc/
directory on the server, allowing for semi-automatic updates of
the client configuration. Since the configuration files are
designed to have a common file for the configuration of all
hosts in the system - and this is in fact the recommended way of
configuring your clients - this makes it easier to keep the
configuration files synchronized.
drop HOSTNAME
Removes all data stored about the host HOSTNAME. It is assumed
that you have already deleted the host from the bb-hosts
configuration file.
drop HOSTNAME TESTNAME
Remove data about a single test (column).
rename OLDHOSTNAME NEWHOSTNAME
Rename all data for a host that changes its name. You should do
this before changing the hostname in the bb-hosts configuration
file.
rename HOSTNAME OLDTESTNAME NEWTESTNAME
Rename data about a single test (column).
hobbitdlog HOSTNAME.TESTNAME
Retrieve the Xymon status-log for a single test. The first line
of the response contain a series of fields separated by a pipe-
sign:
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.
hobbitdxlog HOSTNAME.TESTNAME
Retrieves an XML-string with the status log as for the
"hobbitdlog" command.
hobbitdboard [CRITERIA] [fields=FIELDLIST]
Retrieves a summary of the status of all known tests available
to the Xymon daemon.
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.
hobbitdxboard
Retrieves an XML-string with the summary of all status logs as
for the "hobbitdboard" command.
download FILENAME
Download a file from the Xymon servers’ download directory.
client HOSTNAME.OSTYPE [HOSTCLASS]
Used to send a "client" message to the Xymon server. Client
messages are generated by the Xymon client; when sent to the
Xymon server they are matched against the rules in the hobbit-
clients.cfg(5) configuration file, and status messages are
generated for the client-side tests.
clientlog HOSTNAME [section=SECTIONNAME[,SECTIONNAME...]]
Retrieves the current raw client message last sent by HOSTNAME.
The optional "section" filter is used to select specific
sections of the client data.
ping Attempts to contact the Xymon server. If successful, the Xymon
server version ID is reported.
pullclient
This message is used when fetching client data via the "pull"
mechanism implemented by hobbitfetch(8) and msgcache(8) for
clients that cannot connect directly to the Xymon server.
ghostlist
Report a list of ghost clients seen by the Xymon server. Ghosts
are systems that report data to the Xymon server, but are not
listed in the bb-hosts file.
schedule [TIMESTAMP COMMAND]
Schedules an command sent to the Xymon server for execution at a
later time. E.g. used to schedule disabling of a host or
service at sometime in the future. COMMAND is a complete Xymon
command such as the ones listed above. TIMESTAMP is the Unix
epoch time when the command will be executed.
If no parameters are given, the currently scheduled tasks are
listed in the response. The response is one line per scheduled
command, with the job-id, the time when the command will be
executed, the IP address from which this was sent, and the full
command string.
To cancel an previously scheduled command, "schedule cancel
JOBID" can be used. JOBID is a number provided as the first item
in the output from the schedule list.
EXAMPLE
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 "@"
NOTES
This man-page describes the bb client program provided as part of Xymon
. This implementation provides features not present in the standard Big
Brother bb client - specifically, the support for sending messages over
HTTP, and many commands such as "query" and "config" are not part of
the bb client shipped with Big Brother.
SEE ALSO
bbcombotest(1), bb-hosts(5), hobbitserver.cfg(5), xymon(7)