Ubuntu Manpage: xymonproxy - Xymon message proxy

NAME

       xymonproxy - Xymon message proxy

SYNOPSIS

       xymonproxy [options] --server=$XYMSRV

DESCRIPTION

       xymonproxy(8) is a proxy for forwarding Xymon 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.

       xymonproxy  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
       xymonproxy  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.  xymonproxy can absorb messages very quickly, but will queue them
       up internally and forward them to the Xymon server at a reasonable pace.

       Third, xymonproxy merges small "status" messages into larger "combo"  messages.  This  can
       dramatically  decrease  the  number  of connections that need to go from xymonproxy 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

--server=SERVERIP[:PORT][,SERVER2IP[:PORT]]
Specifies the IP-address and optional portnumber where incoming messages are
forwarded to. The default portnumber is 1984, the standard Xymon port number. If
you have setup the normal Xymon environment, you can use "--server=$XYMSRV". 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.

--listen=LOCALIP[:PORT]
Specifies the IP-adress where xymonproxy listens for incoming connections. By
default, xymonproxy listens on all IP-addresses 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.]SERVICE
If given, this option causes xymonproxy to send a status report every 5 minutes to
the Xymon server about itself. If you have set the standard Xymon environment, you
can use "--report=xymonproxy" to have xymonproxy report its status to a
"xymonproxy" column in Xymon. The default for PROXYHOSTNAME is the $MACHINE
environment variable, i.e. the hostname of the server running xymonproxy. 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 accommodate bursts of activity from clients.
Default: 512.

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

--no-daemon
Runs xymonproxy as a foreground process.

--pidfile=FILENAME
Specifies the location of a file containing the process-ID of the xymonproxy daemon
process. Default: /var/run/xymonproxy.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 xymonproxy process a SIGUSR1
signal.

--debug
Enable debugging output.

REPORT OUTPUT

If enabled via the "--report" option, xymonproxy 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 xymonproxy 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. xymonproxy 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 - Other messages
The number of other messages (data, notes, ack, query, ...) messages received from
a client.

Proxy resources - 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 resources - 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, xymonproxy
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