The Xymon systems and network monitor provides very good mechanisms to access
the monitoring data from the command line.
In the two articles
Query Xymon From CLI
Query Xymon From CLI (Part 2:
the most often used ones were presented.
It was shown how information for hosts and tests can be queried by sending one
of the three basic messages
clientlog to the
These three commands provide the functionality to get most data out of Xymon. But some of them allow data from multiple hosts and/or tests to be selected and others need the exact host and test to be specified. This often requires some scripting with selecting hosts, loops, … to get the desired results.
xymonq combines the functionality of the query messages into one tool to reduce these scripting needs and make the basic queries more convenient. In a lot of cases the output will be further evaluated (with a script sic), some examples are given below.
xymonq provides a command line interface to run
queries for monitored hosts.
In addition the following host independent queries are available:
config: fetch a config-file from the xymon-server
ghostlist: get a list of the reported ghosts – optionally with a time filter
Query host data
The host-queries work in two steps that can be used independently or be combined into one invocation:
Select host(s): Select multiple hosts either by hostname, page, testname or color. The hosts can be selected in all the ways provided by
- REGEX for hostname, pagename, testname
- list of colors
- all other options are supported by the free-form
The resulting hostlist can be written to stdout for further manipulation or be used directly for the next step.
Display data for hosts: This may be
- a status as shown on the web interface (using
- all available information for a host/test combination (using
- raw data sent by the xymon-client (using
- configration information (the contents of
hosts.cfgin a parsable form) for a host (using
- a status as shown on the web interface (using
The hosts can either be used directly from the “selection step” above or be read from stdin.
The host-selection uses
xymondboard internally. All CRITERIA for this message
can be used. For pagename, hostname, testname and color there exist direct
options. All other — even completely newly added criteria — can be added
-X CRITS option.
Select all hosts where the hostname contains the string “bb” from page(s) containing the string “dc1” that have a “disk” test with colors “yellow” or “green” and print the to stdout:
$ xymonq -H bb -P dc1 -T disk -C yellow,green -L
Around Xymon v4.3.18 the new criteria
tag were added. We can
use these (or any other new ceriteria) with the
-X CRITS-option. Again list
the matching hosts:
$ xymonq -X 'net=loc1 ip=192\.168\.' -L
Specify the Display Data
List the available tests for one or more hosts with
xymondlog. The option
-H bb is interpreted as a REGEX, so all hosts from
hosts.cfg that contain
bb are selected. In the test-setup only one host matches:
$ xymonq -q xymondlog -H bb -l bbd conn cpu disk files http info inode memory msgs ports procs ssh sslcert trends xymond xymongen xymonnet
Similarly the available sections in the raw client message can be listed
$ xymonq -q clientlog -H bb -l [date] [uname] [osversion] [uptime] [who] [df] [inode] [mount] [free] [ifconfig] [route] [netstat] [ports] [ifstat] [ps] [top] [vmstat] [clientversion] [clock]
Use Cases and Examples
Selecting and Printing Hosts
A list of a specific set of hosts is needed, maybe as input for some other tool. Let it be all hosts in datacenter 1, that are on the xymon page “dc1”. With out-of-the-box Xymon this can be done with the following command
$ xymon 127.0.0.1 "xymondboard page=dc1 test=info fields=hostname"
info-test is present for all hosts and combined with
ensures that we get each host only once. Without the criterium for
and every test for all the hosts on page “dc1” would be listed — leading to a
lot of duplicate hostname-lines.
xymonq takes care of these things. The same result as above can be achieved with:
$ xymonq -P dc1 -L
This list of hosts can be further manipulated in all the usual ways (piped through grep, written to a file, …).
Also additional criteria for hostnames
-H hostname-PCRE or tests
can be added to these queries.
Getting disk information
Now the disk status of “/” for these hosts has to be examined for some
reason. This can be done with
xymondlog to get the whole status for the
xymondlog requires an exact “hostname.testname”. A loop with the
above line and extracting only the root-filesystem (“/”) produces the required
for my_host in $(xymon 127.0.0.1 "xymondboard page=dc1 test=info fields=hostname"); do xymon 127.0.0.1 "xymondlog $my_host.disk" | grep "/$" done
With xymonq the loop is integrated already and thus simply reads:
$ xymonq -q xymondlog -P dc1 -T disk | grep "/$"
The same data can be retrieved from the
df-section of the raw client message:
for my_host in $(xymon 127.0.0.1 "xymondboard page=dc1 test=info fields=hostname"); do xymon 127.0.0.1 "clientlog $my_host section=df" | grep "/$" done`
and again the much shorter version with xymonq
xymonq -q clientlog -P dc1 -s df | grep "/$"
Checking for a specific OS version on all hosts in datacenter 1 — prefix the output with the hostname (
$ xymonq -q clientlog -P dc1 -s osversion -p
or the kernel version
$ xymonq -q clientlog -P dc1 -s uname -p
Using external hostlists
If the selection of hosts is done by some other means, e.g. manually, generated by another system or a saved list from xymonq, this can be fed to stdin by using
$ cat some-hosts.txt | xymonq -q xymondboard -H - -f line1
Obviously xymonq can be used as the “hostname generator” too (using the list-hostname
-L-option), allowing for further filtering or injection of hosts:
xymonq -P some-page -L | fgrep -v "not-this-one" | xymonq -q xymondboard -H - -f line1 (xymonq -P some-page -L; echo "add-this-one" ) | xymonq -q xymondboard -H - -f line1
The connection parameters, the path to the xymon binary and optionally a
default querytype, field- and section-list can be configured in the
configuration file. The config file can be specified w/
-c file on the
cmdline and is searched in the following locations (the first one found is
used) if not:
- if no file is found: use default values
The default options in
YMON_CMD="xymon" XYMON_SRV="127.0.0.1:1984" QUERYTYPE="" TEST="info" FIELDS="" # for `xymondboard`, uses `xymon(1)` defaults SECTION="" # for `clientlog`
To use the experimental “volume-mode” in v0.3+ please place the included
.awk-file in the same directory as
Status: No further work was invested in this feature up to version v0.8.
I consider xymonq stable as of v0.8 (in the sense that it can be relied on for scripting). Why not 1.0 then? There are some improvements in the pipeline that I would like to ship with 1.0, so stay tuned.
Quick queries of the data reported to Xymon are now possible without hacking long commandlines or digging through the shell history.
Building lists of hosts for use with other tools, getting the current state for a bunch of machine (open network connections, disk-uage, …) is accomplished very fast with xymonq without the need to ssh into the hosts.
Copying and distribution of this package (xymonq), with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This package is offered as-is, without any warranty.
grep "/$"is just a very simple example. In most real-life scenarios this post-processing will be more complex.↩