XYMON

Section: User Commands (1)
Updated: Version 4.3.30: 4 Sep 2019
Index Return to Main Contents

 

xymon - Xymon client communication program

 

xymon [options] RECIPIENT message

 

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.

 

Enable debugging. This prints out details about how the connection to the Xymon server is being established.

When sending the status messages via HTTP, use this server as an HTTP proxy instead of connecting directly to the Xymon server.

Specifies the timeout for connecting to the Xymon server, in seconds. The default is 15 seconds; an XYMON_TIMEOUT environment variable overrides that default (see ENVIRONMENT below), and this option overrides both.

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

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.

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.

 

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".

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.

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.

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.

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.

Re-enables a test that had been disabled.

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.

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.

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

Remove data about a single test (column).

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 data about a single test (column).

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:

The name of the host
The name of the test
Status color (green, yellow, red, blue, clear, purple)
The color xymond recorded at the previous report, whether or not it differed: a test repeating its color reports that same color here. Also accepted as oldcolor, the name it has inside xymond. It is the color xymond recorded, which is not always the one the test sent - a disabled or in-downtime test is recorded blue whatever it reports. none until a status has been reported twice.
The color this test held before its most recent change. It moves only when the color changes, so a test that went green, red, red reports color=red, prevreportcolor=red, prevchangecolor=green - it answers "what was this before it went bad". none until the first change, and it survives a xymond restart. Also accepted as previouscolor.
The test's own color while xymond is recording something other than what it reports; none at every other time. It follows the reports arriving under the substitution, and a test gone silent keeps its last word. That covers a silence, a disable, a modifier, a delayed color change and a DOWNTIME window hiding an alert color -- a green report shows through DOWNTIME, and the field answers none: wherever they differ, color is xymond's and prevgapcolor is the test's own.
For network tests, the flags indicating details about the test (used by xymongen).
Unix timestamp when the current status color began, i.e. the hold-time of the color shown. See "Hold-time and no-data gaps" below.
Unix timestamp when the log message was received.
Unix timestamp when the log message is no longer valid (it goes purple at this time).
Either -1 or Unix timestamp when an active acknowledgement expires.
Either -1 or Unix timestamp when the status is no longer disabled.
IP address where the status was received from.
Either -1 or the cookie value used to acknowledge an alert.
Empty or the acknowledgment message sent when the status was acknowledged. Newline, pipe-signs and backslashes are escaped with a backslash, C-style.
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.

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

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.

Include only tests from hosts found on the PAGEPATH page in the hosts.cfg file.
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.

Include only tests from the host HOSTNAME
Include only tests with the testname TESTNAME
Include only tests where the status color is COLORNAME
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
Include only hosts with a xymon-xmh(5) variable matching this value

Advanced Filtering

Include only tests with full content matching MESSAGE. Use "\s" to escape spaces (or other PCRE strings)
Include only tests with acknowledgement(s) MESSAGE. Use "\s" to escape spaces (or other PCRE strings)
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

Hold-time and no-data gaps

lastchange is the hold-time of the color shown: when that color began, not when a message last moved it. If a test stops reporting and later resumes with the same color, the silence counts as hold-time and the value is unchanged across it - the status did not move while it was out of sight. A gap longer than four times the report validity is not bridged, and a resume with a different color starts a new hold-time. The gap is measured from when the status went stale, itself one report validity after the last report.

This value can therefore move backwards, which matters for the lastchange filter above: a poller asking for changes since its last look will not see a bridged recovery.

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:

The name of the host
The name of the test
Status color (green, yellow, red, blue, clear, purple)
The color xymond recorded at the previous report, whether or not it differed: a test repeating its color reports that same color here. Also accepted as oldcolor, the name it has inside xymond. It is the color xymond recorded, which is not always the one the test sent - a disabled or in-downtime test is recorded blue whatever it reports. none until a status has been reported twice.
The color this test held before its most recent change. It moves only when the color changes, so a test that went green, red, red reports color=red, prevreportcolor=red, prevchangecolor=green - it answers "what was this before it went bad". none until the first change, and it survives a xymond restart. Also accepted as previouscolor.
The test's own color while xymond is recording something other than what it reports; none at every other time. It follows the reports arriving under the substitution, and a test gone silent keeps its last word. That covers a silence, a disable, a modifier, a delayed color change and a DOWNTIME window hiding an alert color -- a green report shows through DOWNTIME, and the field answers none: wherever they differ, color is xymond's and prevgapcolor is the test's own.
For network tests, the flags indicating details about the test (used by xymongen).
Unix timestamp when the current status color began, i.e. the hold-time of the color shown. See "Hold-time and no-data gaps" below.
Unix timestamp when the log message was received.
Unix timestamp when the log message is no longer valid (it goes purple at this time).
Either -1 or Unix timestamp when an active acknowledgement expires.
Either -1 or Unix timestamp when the status is no longer disabled.
IP address where the status was received from.
Either -1 or the cookie value used to acknowledge an alert.
First line of status log.
Empty (if no acknowledgement is active), or the text of the acknowledge message.
Empty (if the status is currently enabled), or the text of the disable message.
The full text of the current status message.
Shows "Y" if there is client data available, "N" if not.
Timestamp when the last client message was received, in Unix "epoch" format.
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.
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.
Number of status-changes that have been recorded for this status since xymond was started.
Lists all active modifiers for this status (i.e. updates sent using a "modify" command).
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.

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

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 a file from the Xymon server's download directory.

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.

Retrieves the current raw client message (hostdata) last sent by HOSTNAME. The optional "section" filter selects specific sections of the data.

Requests that the next client message received from HOSTNAME be saved as hostdata. The request expires after 30 minutes, or after MINUTES when specified (1 to 1440), and is consumed by the next client message. Pending requests are canceled when the host is dropped or renamed, or when xymond restarts. Cached client messages and the hostdata worker must be enabled. Requested saves bypass the recent-save limit, but still require sufficient free space. Requests are rejected when no CLICHG channel reader is connected. A connected reader does not prove that the hostdata worker is running. The response reports whether the request was armed, not whether the hostdata was written to disk. Hostdata is the client data shown as the clientlog service in the web interface.

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

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.

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.

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.

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.

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

 

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 "@"

 

Sets the default request timeout, in seconds, overriding the compiled-in 15 - so it can be set once (e.g. in xymonserver.cfg(5)) rather than passing --timeout= on every call. A non-positive or non-numeric value is reported on stderr and ignored. A --timeout= option on the command line takes precedence.

 

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

 

NAME
SYNOPSIS
DESCRIPTION
OPTIONS AND PARAMETERS
XYMON MESSAGE SYNTAX
EXAMPLE
ENVIRONMENT
SEE ALSO
This document was created by mandoc, using the manual pages.