BB(1) | General Commands Manual | BB(1) |
NAME¶
bb - Xymon client communication programSYNOPSIS¶
bb [options] RECIPIENT messageDESCRIPTION¶
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.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).
- 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.
XYMON MESSAGE SYNTAX¶
This section lists the most commonly used messages in the Xymon protocol.- 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.
- 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.
- 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:
- 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.
- 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.
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"
$ $BB http://bb.foo.com/cgi-bin/bbmessage.cgi "status www,foo,com.http green `date` Web OK"
$ WWW=`$BB $BBDISP "query www,foo,com.www" | awk '{print $1}'`
$ if [ "$WWW" = "red" ]; then /etc/init.d/apache restart; fi
$ $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
$ 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)Version 4.2.3: 4 Feb 2009 | Xymon |