BBPROXY(8)						      System Manager's Manual							BBPROXY(8)

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  mes-
       sages 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 stan-
	      dard 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 config-
	      uration 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 mes-
	      sages 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 "Incom-
       ing 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)

Xymon							    Version 4.2.3:  4 Feb 2009							BBPROXY(8)