xenial (1) xymon.1.gz

Provided by: xymon-client_4.3.25-1_amd64 bug

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 messages 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 connection 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  message.  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 parameter,  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
              protocol.  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 command-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 protocol.

       Each  message  must begin with one of the Xymon commands. Where a HOSTNAME 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  status
              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 TESTNAME 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 following 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 interval
              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, without it appearing as a column on the
              Xymon webpages. This is used, for example, to report statistics about a host,  e.g.  vmstat  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 handle 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  interpreted  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 TESTNAME.

       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  particular  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 decide
              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 $XYMONHOME/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 configuration 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 configuration 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 acknowledgement 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 escaped 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 backslash, 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 expressions;  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 components 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 MESSAGE. Use "\s" to escape spaces (or
              other PCRE strings)

              ackmsg=MESSAGE Include only tests with acknowledgement(s) MESSAGE. 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  timestamps  and  with  the  following
              inequalities:  >= > <= < = !=

              These filters are: lastchange, logtime, validtime, acktime, disabletime

              The response is one line for each status that matches the CRITERIA, 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 acknowledgement 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 character. There are  5  fields:  Timestamp  for  when  the  ack  was
              generated  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 flapping; 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. updates 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 encoded: 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
              hostname,testname,color,flags,lastchange,logtime,validtime,acktime,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 report, and is identical to the CRITERIA in the xymondboard command.

              The  response  is one line for each host that matches the CRITERIA, or all hosts if no criteria is
              specified. The line is composed 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 particular 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 messages 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 sections 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 service at sometime in the future. COMMAND is a complete Xymon command 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
              executed, the IP address from which this was sent, and the full command string.
              To  cancel  a previously scheduled command, "schedule cancel JOBID" 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  directory  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 complete 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" configuration 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 webserver'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 "statusmsg.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)