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)