Provided by: xymon-client_4.3.28-3build1_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)