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)