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

       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

       xymon(1), xymond(1), xymon(7)