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

NAME

       bbproxy - Xymon message proxy

SYNOPSIS

       bbproxy [options] --bbdisplay=$BBDISP

DESCRIPTION

       bbproxy(8)  is  a proxy for forwarding Big Brother messages from one server to another. It
       will typically be needed if you have clients behind a firewall, so they cannot send status
       messages to the Xymon server directly.

       bbproxy  serves three purposes. First, it acts as a regular proxy server, allowing clients
       that cannot connect directly to the Xymon  servers  to  send  data.  Although  bbproxy  is
       optimized  for  handling status messages, it will forward all types of messages, including
       notes- and data-messages.

       Second, it acts as a buffer, smoothing out peak loads if many clients try to  send  status
       messages simultaneously.  bbproxy can absorb messages very quickly, but will queue them up
       internally and forward them to the Xymon server at a reasonable pace.

       Third, bbproxy merges small "status" messages  into  larger  "combo"  messages.  This  can
       dramatically  decrease the number of connections that need to go from bbproxy to the Xymon
       server.  The merging of messages causes "status" messages to be delayed  for  up  to  0.25
       seconds before being sent off to the Xymon server.

OPTIONS

       --bbdisplay=SERVERIP[:PORT][,SERVER2IP[:PORT]]
              Specifies  the  IP-address  and  optional  portnumber  where  incoming messages are
              forwarded to. The default portnumber is 1984, the standard Big Brother port number.
              If   you   have   setup   the   normal   Big   Brother  environment,  you  can  use
              "--bbdisplay=$BBDISP". Up to 3 servers can be specified; incoming messages are sent
              to  all  of them (except "config", "query" and "download" messages, which go to the
              LAST server only). If you have Xymon clients sending their  data  via  this  proxy,
              note  that  the  clients will receive their configuration data from the LAST of the
              servers listed here.  This option is required.

       --bbpager=SERVERIP[:PORT][,SERVER2IP[:PORT]]
              DEPRECATED - this option is only present for compatibility with servers running Big
              Brother,  and  will  be  removed  soon.   Specifies  the  IP-address  and  optional
              portnumber where incoming "page" messages are forwarded to. The default  portnumber
              is  1984,  the  standard  Big Brother port number. If you have setup the normal Big
              Brother environment, you can use  "--bbpager=$BBPAGE".  Up  to  3  servers  can  be
              specified;  incoming  messages  are sent to all of them. If this option is omitted,
              "page" messages are sent to the servers listed in --bbdisplay.

       --listen=LOCALIP[:PORT]
              Specifies the IP-adress where bbproxy listens for incoming connections. By default,
              bbproxy listens on all IP-adresses assigned to the host. If no portnumber is given,
              port 1984 will be used.

       --timeout=N
              Specifies the number of seconds after which  a  connection  is  aborted  due  to  a
              timeout. Default: 10 seconds.

       --report=[PROXYHOSTNAME.]BBSERVICE
              If given, this option causes bbproxy to send a status report every 5 minutes to the
              Xymon server about itself. If you have set the standard  Big  Brother  environment,
              you  can  use  "--report=bbproxy"  to have bbproxy report its status to a "bbproxy"
              column in Big Brother. The default for PROXYHOSTNAME is  the  $MACHINE  environment
              variable,  i.e. the hostname of the server running bbproxy. See REPORT OUTPUT below
              for an explanation of the report contents.

       --lqueue=N
              Size of the listen-queue where incoming  connections  can  queue  up  before  being
              processed.  This  should  be  large  to accomodate bursts of activity from clients.
              Default: 512.

       --daemon
              Run in daemon mode, i.e. detach and run  as  a  background  proces.   This  is  the
              default.

       --no-daemon
              Runs bbproxy as a foreground proces.

       --pidfile=FILENAME
              Specifies  the  location  of  a file containing the proces-ID of the bbproxy daemon
              proces. Default: /var/run/bbproxy.pid.

       --logfile=FILENAME
              Sends all logging output to the specified file instead of stderr.

       --log-details
              Log details (IP-address, message type and hostname) to the logfile.  This can  also
              be enabled and disabled at run-time by sending the bbproxy proces a SIGUSR1 signal.

       --debug
              Enable debugging output.

REPORT OUTPUT

       If  enabled  via the "--report" option, bbproxy will send a status message about itself to
       the Xymon server once every 5 minutes.

       The status message includes the following information:

       Incoming messages
              The total number of connections accepted from clients since the proxy started.  The
              "(N  msgs/second)"  is  the  average  number of messages per second over the past 5
              minutes.

       Outbound messages
              The total number of messages sent to the Xymon server.  Note that this is  probably
              smaller  than the number of incoming messages, since bbproxy merges messages before
              sending them.

       Incoming - Combo messages
              The number of "combo" messages received from a client.

       Incoming - Status messages
              The number of "status" messages received from a client.  bbproxy attempts to  merge
              these  into  "combo"  messages.   The  "Messages  merged" is the number of "status"
              messages that were merged into a combo  message,  the  "Resulting  combos"  is  the
              number of "combo" messages that resulted from the merging.

       Incoming - Page messages
              The number of "page" messages received from a client.

       Incoming - Other messages
              The number of other messages (data, notes, ack, query, ...)  messages received from
              a client.

       Proxy ressources - Connection table size
              This is the number of connection table slots  in  the  proxy.   This  measures  the
              number  of  simultaneously active requests that the proxy has handled, and so gives
              an idea about the peak number of clients that the proxy has handled simultaneously.

       Proxy ressources - Buffer space
              This is the number of KB memory allocated for network buffers.

       Timeout details - reading from client
              The number of messages dropped because reading the message from  the  client  timed
              out.

       Timeout details - connecting to server
              The  number of messages dropped, because a connection to the Xymon server could not
              be established.

       Timeout details - sending to server
              The number of messages dropped because the communication to the Xymon server  timed
              out after a connection was established.

       Timeout details - recovered
              When a timeout happens while sending the status message to the server, bbproxy will
              attempt to recover the message and retry sending it to the server after  waiting  a
              few  seconds.   This  number  is the number of messages that were recovered, and so
              were not lost.

       Timeout details - reading from server
              The number of response messages that timed out while attempting to read  them  from
              the server. Note that this applies to the "config" and "query" messages only, since
              all other message types do not get any response from the servers.

       Timeout details - sending to client
              The number of response messages that timed out while attempting to send them to the
              client. Note that this applies to the "config" and "query" messages only, since all
              other message types do not get any response from the servers.

       Average queue time
              The average time it took the proxy  to  process  a  message,  calculated  from  the
              messages  that have passed through the proxy during the past 5 minutes. This number
              is computed from the messages that actually end up establishing a connection to the
              Xymon server, i.e. status messages that were combined into combo-messages do not go
              into the calculation - if they did, it would reduce the average time, since  it  is
              faster to merge messages than send them out over the network.

       If you think the numbers do not add up, here is how they relate.

       The    "Incoming   messages"   should   be   equal   to   the   sum   of   the   "Incoming
       Combo/Status/Page/Other messages", or slightly more because messages in  transit  are  not
       included in the per-type message counts.

       The  "Outbound  messages"  should  be  equal  to  sum  of  the  "Incoming Combo/Page/Other
       messages", plus the "Resulting  combos"  count,  plus  "Incoming  Status  messages"  minus
       "Messages  merged"  (this  latter  number  is  the number of status messages that were NOT
       merged into combos, but sent directly).  The "Outbound messages"  may  be  slightly  lower
       than  that,  because messages in transit are not included in the "Outbound messages" count
       until they have been fully sent.

SIGNALS

       SIGHUP Re-opens the logfile, e.g. after it has been rotated.

       SIGTERM
              Shut down the proxy.

       SIGUSR1
              Toggles logging of individual messages.

SEE ALSO

       bb(1), bbd(1), xymon(7)