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 and Query Xymon From CLI (Part 2: clientlog) 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 xymondboard, xymondlog or clientlog to the Xymon server.

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

  • xymondboard
  • xymondlog
  • clientlog
  • hostinfo

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
  • ping (aka: version)

Query host data

The host-queries work in two steps that can be used independently or be combined into one invocation:

  1. Select host(s): Select multiple hosts either by hostname, page, testname or color. The hosts can be selected in all the ways provided by xymondboard:

    • REGEX for hostname, pagename, testname
    • list of colors
    • all other options are supported by the free-form -X CRITERIA option.

    The resulting hostlist can be written to stdout for further manipulation or be used directly for the next step.

  2. Display data for hosts: This may be

    • a status as shown on the web interface (using -q xymondlog)
    • all available information for a host/test combination (using -q xymondboard)
    • raw data sent by the xymon-client (using -q clientlog).
    • configration information (the contents of hosts.cfg in a parsable form) for a host (using -q hostinfo)

The hosts can either be used directly from the “selection step” above or be read from stdin.

Selecting hosts

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 using the -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 net, ip and 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 the string 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 with a clientlog-query:

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

The info-test is present for all hosts and combined with fields=hostname ensures that we get each host only once. Without the criterium for test each 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 -T raid 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 disk test. xymondlog requires an exact “hostname.testname”. A loop with the above line and extracting only the root-filesystem (“/”) produces the required result1:

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 (-p):

$ 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 -H -:

$ 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

Configuration

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:

  1. ./.xymonq.cfg
  2. ~/.xymonq.cfg
  3. /etc/xymon/xymonq.cfg
  4. if no file is found: use default values

The default options in xymonq.cfg are:

YMON_CMD="xymon"
XYMON_SRV="127.0.0.1:1984"
QUERYTYPE=""
TEST="info"
FIELDS=""   # for `xymondboard`, uses `xymon(1)` defaults
SECTION=""  # for `clientlog`

Experimental features

To use the experimental “volume-mode” in v0.3+ please place the included .awk-file in the same directory as xymonq.

Status: No further work was invested in this feature up to version v0.8.

Summary

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.

License

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.

Downloads

Version Release Date
0.8 2018-01-26
0.7 2017-12-13
0.6 2017-12-10
0.5 2016-02-06
0.4 2015-10-15
0.3 2015-10-06
0.2 2015-06-23

  1. The grep "/$" is just a very simple example. In most real-life scenarios this post-processing will be more complex.