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

FreeBSD Manual Pages

  
 
  

home | help
XYMON(1)		    General Commands Manual		      XYMON(1)

NAME
       xymon - Xymon client communication program

SYNOPSIS
       xymon [options] RECIPIENT message

DESCRIPTION
       xymon(1)	is the client program used to communicate with a Xymon server.
       It is frequently	used by	Xymon client systems to	send  in  status  mes-
       sages and pager alerts on local tests.

       In  Xymon,  the xymon program is	also used for administrative purposes,
       e.g. to rename or delete	hosts, or to disable hosts that	are  down  for
       longer periods of time.

OPTIONS	AND PARAMETERS
       --debug
	      Enable  debugging. This prints out details about how the connec-
	      tion to the Xymon	server is being	established.

       --proxy=http://PROXYSERVER:PROXYPORT/
	      When sending the status messages via HTTP, use this server as an
	      HTTP proxy instead of connecting directly	to the Xymon server.

       --timeout=N
	      Specifies	 the  timeout  for  connecting to the Xymon server, in
	      seconds. The default is 5	seconds.

       --response
	      The xymon	utility	normally knows when to expect a	response  from
	      the  server,  so	this  option is	not required. However, it will
	      cause any	response from the server to be displayed.

       --merge
	      Merge the	command	line message text with the  data  provided  on
	      standard	input,	and  send the result to	the Xymon server.  The
	      message text provided on the command line	becomes	the first line
	      of the merged message.

       RECIPIENT
	      The  RECIPIENT  parameter	defines	which server receives the mes-
	      sage. If RECIPIENT is given as "0.0.0.0",	then  the  message  is
	      sent  to all of the servers listed in the	XYMSERVERS environment
	      variable.

	      Usually, a client	will use "$XYMSRV" for the  RECIPIENT  parame-
	      ter,  as this is defined for the client scripts to automatically
	      contain the correct value.

	      The RECIPIENT parameter may be a URL for a  webserver  that  has
	      the  xymoncgimsg.cgi  or	similar	script installed. This tunnels
	      the Xymon	messages to the	Xymon server using standard HTTP  pro-
	      tocol.  The xymoncgimsg.cgi(8) CGI tool (included	in Xymon) must
	      be installed on the webserver for	the HTTP transport to work.

       MESSAGE
	      The message parameter is the message to be sent  across  to  the
	      Xymon  server. Messages must be enclosed in quotes, but by doing
	      so they can span multiple	lines. The maximum size	of  a  message
	      is  defined  by  the maximum allowed length of your shell's com-
	      mand-line, and is	typically 8-32 KB.

	      If you need to send longer status	messages, you can specify  "@"
	      as the message: xymon will then read the status message from its
	      stdin.

XYMON MESSAGE SYNTAX
       This section lists the most commonly used messages in the Xymon	proto-
       col.

       Each  message  must begin with one of the Xymon commands. Where a HOST-
       NAME is specified, it must have any dots	in  the	 hostname  changed  to
       commas if the Xymon FQDN	setting	is enabled (which is the default).  So
       the host	"www.foo.com", for example, would report as "www,foo,com".

       status[+LIFETIME][/group:GROUP]	HOSTNAME.TESTNAME  COLOR   <additional
       text>
	      This  sends  in a	status message for a single test (column) on a
	      single host.  TESTNAME is	the name of the	column where this test
	      will  show  up;  any name	is valid except	that using dots	in the
	      testname will not	work.  COLOR must be one of the	valid  colors:
	      "green",	"yellow",  "red"  or  "clear".	 The colors "blue" and
	      "purple" - although valid	colors - should	not be sent in a  sta-
	      tus message, as these are	handled	specially by the Xymon server.
	      As a special case	(for supporting	older clients),	 "client"  can
	      be used as the name of the color.	This causes the	status message
	      to be handled by Xymon as	a "client" data	message, and the TEST-
	      NAME parameter is	used as	the "collector id".
	      The  "additional text" normally includes a local timestamp and a
	      summary of the test result on the	first line. Any	lines  follow-
	      ing the first one	are free-form, and can include any information
	      that may be useful to diagnose the problem being reported.
	      The LIFETIME defines how long this status	is valid  after	 being
	      received by the Xymon server. The	default	is 30 minutes, but you
	      can set any period you like. E.g.	for a custom  test  that  runs
	      once an hour, you	will want to set this to at least 60 minutes -
	      otherwise	the status will	go purple after	30 minutes.  It	 is  a
	      good idea	to set the LIFETIME to slightly	longer than the	inter-
	      val between your tests, to allow for variations in the  time  it
	      takes  your test to complete. The	LIFETIME is in minutes,	unless
	      you add an "h" (hours), "d" (days) or  "w"  (weeks)  immediately
	      after  the  number,  e.g.	"status+5h" for	a status that is valid
	      for 5 hours.
	      The GROUP	option is used to direct alerts	from the status	 to  a
	      specific	group.	It is currently	used for status	generated from
	      the Xymon	clients' data, e.g. to direct  alerts  for  a  "procs"
	      status  to  different people, depending on exactly which process
	      is down.

       notify HOSTNAME.TESTNAME	<message text>
	      This triggers an informational message to	be sent	to  those  who
	      receive alerts for this HOSTNAME+TESTNAME	combination, according
	      to the rules defined  in	alerts.cfg(5)  This  is	 used  by  the
	      enadis.cgi(1)  tool  to notify people about hosts	being disabled
	      or enabled, but can also serve as	a  general  way	 of  notifying
	      server administrators.

       data HOSTNAME.DATANAME<newline><additional text>
	      The "data" message allows	tools to send data about a host, with-
	      out it appearing as a column on  the  Xymon  webpages.  This  is
	      used,  for  example, to report statistics	about a	host, e.g. vm-
	      stat data, which does not	in itself represent something that has
	      a	red, yellow or green identity. It is used by RRD bottom-feeder
	      modules, among others. In	Xymon, data messages  are  by  default
	      processed	 only by the xymond_rrd(8) module. If you want to han-
	      dle data-messages	using an external application, you may want to
	      enable  the  xymond_filestore(8)	module	for  data-messages, to
	      store data-messages in a format  compatible  with	 how  the  Big
	      Brother daemon does.

       disable HOSTNAME.TESTNAME DURATION <additional text>
	      Disables	a  specific test for DURATION minutes. This will cause
	      the status of this test to be listed  as	"blue"	on  the	 Xymon
	      server,  and  no alerts for this host/test will be generated. If
	      DURATION is given	as a number followed by	s/m/h/d, it is	inter-
	      preted as	being in seconds/minutes/hours/days respectively.   To
	      disable a	test until it becomes OK, use "-1" as the DURATION.
	      To  disable  all tests for a host, use an	asterisk "*" for TEST-
	      NAME.

       enable HOSTNAME.TESTNAME
	      Re-enables a test	that had been disabled.

       query HOSTNAME.TESTNAME
	      Query the	Xymon server for the latest status reported  for  this
	      particular  test.	If the host/test status	is known, the response
	      is the first line	of the status report - the current color  will
	      be  the  first  word  on the line. Additional lines of text that
	      might be present on the status message cannot be retrieved.
	      This allows any Xymon client to determine	the status of  a  par-
	      ticular test, whether it is one pertaining to the	host where the
	      client is	running, some other host, or perhaps the result	 of  a
	      combined test from multiple hosts	managed	by combostatus(1) This
	      will typically be	useful to Xymon	client extension scripts, that
	      need to determine	the status of other hosts, for example,	to de-
	      cide if an automatic recovery action should be initiated.

       config FILENAME
	      Retrieve one of the Xymon	configuration files from  the  server.
	      This  command  allows  a	client	to pull	files from the $XYMON-
	      HOME/etc/	directory on the server, allowing  for	semi-automatic
	      updates  of  the	client	configuration. Since the configuration
	      files are	designed to have a common file for  the	 configuration
	      of all hosts in the system - and this is in fact the recommended
	      way of configuring your clients -	this makes it easier  to  keep
	      the configuration	files synchronized.

       drop HOSTNAME
	      Removes  all  data stored	about the host HOSTNAME. It is assumed
	      that you have already deleted the	host from the  hosts.cfg  con-
	      figuration file.

       drop HOSTNAME TESTNAME
	      Remove data about	a single test (column).

       rename OLDHOSTNAME NEWHOSTNAME
	      Rename  all  data	 for a host that has had its name changed. You
	      should do	this after changing the	hostname in the	hosts.cfg con-
	      figuration file.

       rename HOSTNAME OLDTESTNAME NEWTESTNAME
	      Rename data about	a single test (column).

       xymondlog HOSTNAME.TESTNAME
	      Retrieve	the Xymon status-log for a single test.	The first line
	      of the response contains a series	of fields separated by a pipe-
	      sign:

	      hostname The name	of the host

	      testname The name	of the test

	      color Status color (green, yellow, red, blue, clear, purple)

	      testflags	 For network tests, the	flags indicating details about
	      the test (used by	xymongen).

	      lastchange Unix timestamp	when the status	color last changed.

	      logtime Unix timestamp when the log message was received.

	      validtime	Unix timestamp when the	log message is no longer valid
	      (it goes purple at this time).

	      acktime  Either -1 or Unix timestamp when	an active acknowledge-
	      ment expires.

	      disabletime Either -1 or Unix timestamp when the	status	is  no
	      longer disabled.

	      sender IP	address	where the status was received from.

	      cookie  Either  -1  or  the  cookie value	used to	acknowledge an
	      alert.

	      ackmsg Empty or the acknowledgment message sent when the	status
	      was  acknowledged.   Newline, pipe-signs and backslashes are es-
	      caped with a backslash, C-style.

	      dismsg Empty or the message sent when the	status	was  disabled.
	      Newline,	pipe-signs  and	 backslashes  are escaped with a back-
	      slash, C-style.

	      After the	first line comes the full status  log  in  plain  text
	      format.

       xymondxlog HOSTNAME.TESTNAME
	      Retrieves	 an  XML  string containing the	status log as with the
	      "xymondlog" command.

       xymondboard [CRITERIA] [fields=FIELDLIST]
	      Retrieves	a summary of the status	of all known  tests  available
	      to the Xymon daemon.

	      By  default  -  if no CRITERIA is	provided - it returns one line
	      for all status messages that are found in	Xymon. You can	filter
	      the  response  by	 selection specific page, host,	test, color or
	      various other fields. The	PAGEPATH, NETWORK, HOSTNAME, TESTNAME,
	      and  *MSG	parameters are interpreted perl-compatible regular ex-
	      pressions; the COLOR parameter accepts multiple colors separated
	      by commas; the *TIME values accept unix epoch timestamps.	 Other
	      variables	identified in xymon-xmh(5) may also be used.

	      Because host filtration is done  before  test  filtration,  it's
	      more  efficient  (with  very  large  data	sets) to use PAGEPATH,
	      HOSTNAME,	NETWORK, and other XMH_	filters	when possible,	before
	      globally filtering with COLOR, *MSG, *TIME, or TESTNAME.

	      You can filter on, for example, both a hostname and a testname.

	      page=PAGEPATH  Include  only  tests  from	 hosts	found  on  the
	      PAGEPATH page in the hosts.cfg file.

	      net=NETWORK Include only tests from hosts	with this NET: tag

	      ip=IPAddress Include only	tests from hosts with this IP address.
	      This is a	regex, not CIDR.

	      host=HOSTNAME Include only tests from the	host HOSTNAME

	      test=TESTNAME Include only tests with the	testname TESTNAME

	      color=COLORNAME  Include	only  tests  where the status color is
	      COLORNAME

	      tag=TAGNAME Include only hosts with a certain tag	 specified  in
	      the hosts.cfg(5) line.  Note that	only items known to xymon com-
	      ponents are included here; arbitrary text	is not included

	      XMH_string=VALUE Include only hosts with a xymon-xmh(5) variable
	      matching this value

	      Advanced Filtering

	      msg=MESSAGE  Include  only tests with full content matching MES-
	      SAGE. Use	"\s" to	escape spaces (or other	PCRE strings)

	      ackmsg=MESSAGE Include only tests	with  acknowledgement(s)  MES-
	      SAGE. Use	"\s" to	escape spaces (or other	PCRE strings)

	      dismsg=MESSAGE  Include  only tests that have been disabled with
	      strings matching MESSAGE.	 Use "\s" to escape spaces  (or	 other
	      PCRE   strings).	(It  is	 most  efficient  to  pair  this  with
	      color=blue.)

	      Timestamp	Filters

	      Certain fields (explained	below) can be filtered with unix time-
	      stamps and with the following inequalities:  >= >	<= < = !=

	      These filters are: lastchange, logtime, validtime, acktime, dis-
	      abletime

	      The response is one line for each	status that matches the	CRITE-
	      RIA,  or	all  statuses if no criteria is	specified. The line is
	      composed of a number of fields, separated	by  a  pipe-sign.  You
	      can  select  which  fields  to  retrieve	by listing them	in the
	      FIELDLIST. The following fields are available:

	      hostname The name	of the host

	      testname The name	of the test

	      color Status color (green, yellow, red, blue, clear, purple)

	      flags For	network	tests, the flags indicating details about  the
	      test (used by xymongen).

	      lastchange Unix timestamp	when the status	color last changed.

	      logtime Unix timestamp when the log message was received.

	      validtime	Unix timestamp when the	log message is no longer valid
	      (it goes purple at this time).

	      acktime Either -1	or Unix	timestamp when an active  acknowledge-
	      ment expires.

	      disabletime  Either  -1  or Unix timestamp when the status is no
	      longer disabled.

	      sender IP	address	where the status was received from.

	      cookie Either -1 or the cookie  value  used  to  acknowledge  an
	      alert.

	      line1 First line of status log.

	      ackmsg  Empty  (if no acknowledgement is active),	or the text of
	      the acknowledge message.

	      dismsg Empty (if the status is currently enabled), or  the  text
	      of the disable message.

	      msg The full text	of the current status message.

	      client Shows "Y" if there	is client data available, "N" if not.

	      clntstamp	 Timestamp  when the last client message was received,
	      in Unix "epoch" format.

	      acklist List of the current acknowledgements for a test. This is
	      a	text string with multiple fields, delimited by a colon charac-
	      ter. There are 5 fields: Timestamp for when the ack  was	gener-
	      ated and when it expires;	the the	"ack level"; the user who sent
	      the ack; and the acknowledgement text.

	      flapinfo Tells if	the status is flapping.	5 fields, delimited by
	      "/":  A "0" if the status	is not flapping	and "1"	if it is flap-
	      ping; timestamp when the latest status change was	 recorded  and
	      when  the	 first	statuschange  was recorded; and	the two	colors
	      that the status is flapping between.

	      stats Number of status-changes that have been recorded for  this
	      status since xymond was started.

	      modifiers	 Lists	all active modifiers for this status (i.e. up-
	      dates sent using a "modify" command).

	      XMH_* The	XMH-tags refer to the Xymon hosts.cfg(5) configuration
	      settings.	 A full	list of	these can be found in the xymon-xmh(5)
	      man-page.

	      The ackmsg, dismsg and msg fields	have  certain  characters  en-
	      coded:  Newline is "\n", TAB is "\t", carriage return is "\r", a
	      pipe-sign	is "\p", and a backslash is "\\".

	      If the "fields" parameter	is omitted, a  default	set  of	 host-
	      name,testname,color,flags,lastchange,logtime,validtime,ack-
	      time,disabletime,sender,cookie,line1 is used.

       xymondxboard
	      Retrieves	an XML string with the summary of all status  logs  as
	      for the "xymondboard" command.

       hostinfo	[CRITERIA]
	      Retrieves	  the  current	configuration  of  a  host  (i.e.  the
	      hosts.cfg(5) definition).	CRITERIA selects which host(s) to  re-
	      port,  and  is identical to the CRITERIA in the xymondboard com-
	      mand.

	      The response is one line for each	host that matches  the	CRITE-
	      RIA,  or all hosts if no criteria	is specified. The line is com-
	      posed of a number	of fields, separated by	a pipe-sign. The first
	      two  fields  will	always be the hostname and the IP-address. The
	      remaining	fields - if any	- are the hosts.cfg tags in no partic-
	      ular order.

       download	FILENAME
	      Download a file from the Xymon server's download directory.

       client[/COLLECTORID] HOSTNAME.OSTYPE [HOSTCLASS]
	      Used to send a "client" message to the Xymon server. Client mes-
	      sages are	generated by the Xymon client; when sent to the	 Xymon
	      server they are matched against the rules	in the analysis.cfg(5)
	      configuration file, and status messages are  generated  for  the
	      client-side tests.  The COLLECTORID is used when sending client-
	      data that	are additions to the standard client  data.  The  data
	      will be concatenated with	the normal client data.

       clientlog HOSTNAME [section=SECTIONNAME[,SECTIONNAME...]]
	      Retrieves	 the current raw client	message	last sent by HOSTNAME.
	      The optional "section" filter is used to	select	specific  sec-
	      tions of the client data.

       ping   Attempts	to  contact the	Xymon server. If successful, the Xymon
	      server version ID	is reported.

       pullclient
	      This message is used when	fetching client	data  via  the	"pull"
	      mechanism	 implemented  by  xymonfetch(8)	 and  msgcache(8)  for
	      clients that cannot connect directly to the Xymon	server.

       ghostlist
	      Report a list of ghost clients seen by the Xymon server.	Ghosts
	      are  systems  that  report data to the Xymon server, but are not
	      listed in	the hosts.cfg file.

       schedule	[TIMESTAMP COMMAND]
	      Schedules	a command sent to the Xymon server for execution at  a
	      later  time.  E.g.  used to schedule disabling of	a host or ser-
	      vice at sometime in the future. COMMAND is a complete Xymon com-
	      mand  such as the	ones listed above. TIMESTAMP is	the Unix epoch
	      time when	the command will be executed.
	      If no parameters are given, the currently	 scheduled  tasks  are
	      listed  in the response.	The response is	one line per scheduled
	      command, with the	job-id,	the time when the command will be exe-
	      cuted,  the  IP  address	from which this	was sent, and the full
	      command string.
	      To cancel	a previously scheduled command,	"schedule  cancel  JO-
	      BID"  can	 be used. JOBID	is a number provided as	the first item
	      in the output from the schedule list.

       notes FILENAME
	      The message text will  be	 stored	 in  $XYMONHOME/notes/FILENAME
	      which is then used as hyperlinks from hostnames or column	names.
	      This requires that the "storenotes" task is enabled in tasks.cfg
	      (it  is disabled by default). FILENAME cannot contain any	direc-
	      tory path	- these	are stripped automatically.

       usermsg ID
	      These messages will be relayed directly to modules listening  on
	      the  "user"  channel  of	the Xymon daemon. This is intended for
	      custom communication between client-side modules and  the	 Xymon
	      server.

       modify HOSTNAME.TESTNAME	COLOR SOURCE CAUSE
	      Modify the color of a specific status, without generating	a com-
	      plete status message. This is for	backend	processors  (e.g.  RRD
	      graphs)  that  can  override the color of	a status based on some
	      criteria determined outside the normal flow of  a	 status.  E.g.
	      the  normal "conn" status	may appear to be green since it	merely
	      checks on	whether	a host can be ping'ed or not; the RRD  handler
	      can  then	 use a "modify"	command	to override this is the	actual
	      ping responsetime	exceeds	a given	threshold. (See	the "DS"  con-
	      figuration  setting  in  analysis.cfg(5)	for  how  to do	this).
	      SOURCE is	some identification of the module that	generates  the
	      "modify"	message	 -  future  modifications  must	 use  the same
	      source. There may	be several sources that	modify the same	status
	      (the  most  severe  status  then becomes the actual color	of the
	      status). CAUSE is	a one-line text	string explaining  the	reason
	      for overriding the normal	status color - it will be displayed on
	      the status webpage.

EXAMPLE
       Send a normal status message to the Xymon server,  using	 the  standard
       Xymon protocol on TCP port 1984:
	  $ $XYMON $XYMSRV "status www,foo,com.http green `date` Web OK"

       Send  the  same	status	message,  but using HTTP protocol via the web-
       server's	xymoncgimsg.cgi	script:
	  $    $XYMON	 http://bb.foo.com/cgi-bin/xymoncgimsg.cgi     "status
       www,foo,com.http	green `date` Web OK"

       Use  "query"  message  to  determine  the  color	of the "www" test, and
       restart Apache if it is red:

	  $ WWW=`$XYMON	$XYMSRV	"query www,foo,com.www"	| awk '{print $1}'`
	  $ if [ "$WWW"	= "red"	]; then	/etc/init.d/apache restart; fi

       Use "config" message to update a	local mytest.cfg file (but only	if  we
       get a response):

	  $ $XYMON $XYMSRV "config mytest.cfg" >/tmp/mytest.cfg.new
	  $ if [ -s /tmp/mytest.cfg.new	]; then
	      mv /tmp/mytest.cfg.new $XYMONHOME/etc/mytest.cfg
	    fi

       Send  a very large status message that has been built in	the file "sta-
       tusmsg.txt". Instead of providing it on the command-line, pass  it  via
       stdin to	the xymon command:

	  $ cat	statusmsg.txt |	$XYMON $XYMSRV "@"

SEE ALSO
       combostatus(1), hosts.cfg(5), xymonserver.cfg(5), xymon(7)

Xymon			  Version 4.3.30:  4 Sep 2019		      XYMON(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS AND PARAMETERS | XYMON MESSAGE SYNTAX | EXAMPLE | SEE ALSO

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

home | help