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.
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.
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".
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.
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.
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.
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
webserveraqs 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 aq{print $1}aq`
$ 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 "@"