Provided by: xymon-client_4.3.0~beta2.dfsg-9.1_amd64 bug

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)