Provided by: xymon_4.3.30-1_amd64 bug

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)