Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XYMONPROXY(8)		    System Manager's Manual		 XYMONPROXY(8)

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 di-
       rectly.

       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 mes-
       sages 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 mes-
       sages causes "status" messages to be delayed for	up to 0.25 seconds be-
       fore 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  configura-
	      tion 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=xymon-
	      proxy"  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  log-
	      file.   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  mes-
	      sages, 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.	xymon-
	      proxy attempts to	merge these into "combo" messages.  The	 "Mes-
	      sages  merged"  is  the  number  of  "status" messages that were
	      merged into a combo message, the "Resulting combos" is the  num-
	      ber 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  Xy-
	      mon 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 num-
	      ber  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	 "con-
	      fig" 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,	calcu-
	      lated  from the messages that have passed	through	the proxy dur-
	      ing the past 5 minutes. This number is computed  from  the  mes-
	      sages  that actually end up establishing a connection to the Xy-
	      mon 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)

Xymon			  Version 4.3.30:  4 Sep 2019		 XYMONPROXY(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | REPORT OUTPUT | SIGNALS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=xymonproxy&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help