---
name: "xymonq"
section: "1"
platform: "linux"
package: "xymonq"
version: "0.8-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/xymonq"
---

# xymonq(1)

a frontend to query the Xymon network- and systems-monitor.

## NAME

xymonq - a frontend to query the Xymon network- and systems-monitor.

## SYNOPSIS

**xymonq** \[ *-c conf-file*\] *-q QUERYTYPE* \[*-P PAGEPATH*\] \[*-H HOSTNAME*\] \[*-T TEST*\] \[*-C COLOR*\[*,COLOR,*...\]\] \[*-X CRITS*\] \[*-f FIELD*\[*,FIELD,*...\]\] \[*-s SECTION*\[*,SECTION,*...\]\] *\| -l* \] \[*-S\|-p*\] \[*-h \| -V*\] \[*-d*\]\
 **xymonq** *-q clientlog*   \[*-P PAGEPATH*\] \[*-H HOSTNAME*\] \[*-T TEST*\] \[*-C COLOR*\[*,COLOR,*...\]\] \[*-X CRITS*\] \[*-s SECTION*\[*,SECTION,*...\]\] *\| -l* \]\
 **xymonq** *-q xymondboard* \[*-P PAGEPATH*\] \[*-H HOSTNAME*\] \[*-T TEST*\] \[*-C COLOR*\[*,COLOR,*...\]\] \[*-X CRITS*\] \[*-f FIELD,*\[*FIELD,*...\]\]\
 **xymonq** *-q hostinfo*    \[*-P PAGEPATH*\] \[*-H HOSTNAME*\] \[*-T TEST*\] \[*-C COLOR*\[*,COLOR,*...\]\] \[*-X CRITS*\]\
 **xymonq** *-q xymondlog*   \[*-P PAGEPATH*\] \[*-H HOSTNAME*\] *{-T TEST \| -l}* \[*-C COLOR*\[*,COLOR,*...\]\] \[*-X CRITS*\]\
 **xymonq** *-q ghostlist* \[*-a* \[*-*\]*AGE*\] \[*-l*\]\
 **xymonq** *-q config* \[*-f file*\]\
 **xymonq** *-q {ping\|version}*

## DESCRIPTION

**xymonq** is a frontend to send various query-messages via **[xymon(1)](/xymon/1.md)** to a Xymon server **[xymond(8)](/xymond/8.md)**. All test- (column) information for one or more hosts/tests and internal status information of Xymon can be retrieved.

xymonq - A frontend to query the Xymon network- and systems-monitor.

### OPTIONS TO SELECT DISPLAYED DATA FOR THE HOSTS:

- **-q** QUERYTYPE

  Query to perform to Xymon \[clientlog \| xymondboard \| hostinfo \| xymondlog \| ghost\[list\] \| config \| ping\]

See section **QUERYTYPES** for details.

### OPTIONS TO SELECT HOSTS:

- **-P** PAGEPATH

  A PAGEPATH specification from hosts.cfg(\*).

- **-H** HOSTNAME

  A hostname from hosts.cfg(\*). To read the hosts from stdin use "-" (all other filters inactive).

- **-T** TEST

  The name of a TEST, defaults to "info"(\*).

(\*) interpreted as a REGEX

- **-C** COLOR

  only tests with COLOR, may be coma-separated list like "clear,green", default: empty=all colors

- **-X** CRITS

  eXtra CRITERIA, like "ip=", "net=" or "tag=", CRITS are passed as-is to xymondboard

       This is to provide support for new or less often used filter CRITERIA. \`-X\` may be used multiple times (\`-X ip=172.33 -X tag=test\`) or have multiple quoted criteria (\`-X "ip=172.33 tag=test\`).\
        Since Xymon v4.3.19 filtering on the whole message (\`msg=PCRE\`), various timestamps and XMH-values (\`XMH\_string=VALUE\`, e.g. \`XHM\_CLASS=linux\` -- see \`[xymon-xmh(5)](/xymon-xmh/5.md)\`) is possible too.

An empty (or missing) option matches every item of that criterium.

- **-L**

  print evaluated hostlist to stdout and exit

- **-S**

  print "HOST=hostname" separator-lines above data (deprecated)

- **-p**

  prefix each line of output w/ "hostname: ", valid for queries: clientlog, xymondboard, xymondlog

### Options for clientlog:

- **-f** FIELD

  fields to print, defaults to "hostname"

- **-s** SECTION

  one or more section-names, coma separated If empty the whole clientlog is printed

- **-l**

  list available sections only (as they occur)

### Options for xymondboard:

- **-f** FIELD

  fields to print, defaults to empty, thus using xymon-defaults

### Options for xymondlog:

- **-l**

  just list available tests for selected host(s)

### Options for ghostlist:

- **-a** \[-\]AGE

  print only host with report AGE; AGE is a GNU-date "-s"-compatible string) The "-" prefix inverts the selection.

- **-l**

  only print the hostnames instead of the default full "ghostline"

### Options for client:

- **-f** file

  The file to retrieve, e.g. "hosts.cfg", "analysis.cfg". Only files ending with ".cfg" can be fetched. Defaults to "hosts.cfg".

### Global options:

- **-c** conf-file

  use specified config-file, this prevents searching default locations; default-values apply if not specified. Has to be 1st cmdline option in order to allow selectively override values from cmdline.

- **-v**

  verbose output, print the "xymon"-commandlines

- **-V**

  print version info

- **-d**

  enable debug output

- **-h**

  this help message

## QUERYTYPES

This is only a short description of the query types possible. For more detailed information see [xymon(1)](/xymon/1.md).

clientlog\
   Get the raw-data transmitted to the xymon-server. This contains the data gathered by the \`xymonclient\*\`-scripts.

xymondboard\
   Obtain status for one or more hosts w/ extensive filtering on the host-selection side as well as the output-side (-f FIELDS).

hostinfo\
   Retrieve the config from \`hosts.cfg\` about one or more hosts (host-selection like xymondboard).

xymondlog\
   Print full of status-columns as dispayed on the web interface.

config\
   Retrieve a config-file (only ".cfg"-files) from the \`server/etc/\`-dir of the xymon-server.

ghostlist\
   Get information about hosts sending data without being present in the xymon-server configuration.

ping\|version\
   Get version of the xymon-server, this uses the \`ping\`-command.

## CONFIG FILE

The default configuration and some query-settings can be adjusted with a configuration file. The file has to conform to [bash(1)](/bash/1.md) syntax as it is sourced as-is.

Possible settings (default values shown):

  XYMON\_CMD="xymon"             Path and command name for \`xymon\` binary.\
   XYMON\_SRV="127.0.0.1:1984"    Where to find the Xymon server: IP:PORT (recommended) or HOSTNAME:PORT.\
   QUERYTYPE=""                  The default query to execute.\
   TEST="info"                   The test to use for selecting hosts or printing w/ xymondlog.\
   FIELDS="..."                  The fields to print for xymondboard, defaults to [xymon(1)](/xymon/1.md)-defaults.\
   SECTION=""                    Section(s) to print for clientlog. Multiple sections are comma separated.

The config file can be specified via \`-c conf-file\`. If no config-file is specified \`xymonq\` searches the following locations in order, using the first one found:

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

## EXAMPLES

Print a list of all hosts known to xymon (i.e. defined in hosts.cfg)\
   xymonq -L

Examples for clientlog:

  Print the 'clientlog' for all hosts\
     xymonq -q clientlog

  List all sections in 'clientlog' for all hosts on page 'dc1', print "HOST="-separator\
     xymonq -q clientlog -P dc1 -lS

  Print the 'osversion' section for hosts whole hostname matches the regex "bb.\*com"\
     xymonq -q clientlog -H "bb.\*com" -s osversion

Examples for xymondlog:

  List all tests for all hosts on page 'dc1' whose hostname contain 'mx'\
     xymonq -q xymondlog -P dc1 -H mx -l

  Print the 'disk'-status of hosts whose hostname match the PCRE 'bb'\
     xymonq -q xymondlog -H bb -T disk

Examples for xymondboard:

  Identical host-selection as above but show the first line of the 'cpu'-status\
     xymonq -q xymondboard -H bb -T cpu -f line1

Examples for ghostlist:

  Get the "hosts.cfg"-file:\
     xymonq -q config\
     xymonq -q config -f hosts.cfg

  Get "analysis.cfg"-file:\
     xymonq -q config -f analysis.cfg

Examples for ghostlist:

  Print the full ghostlist:\
     xymonq -q ghostlist

  Print the hosts from ghostlist that reported within the last 5 minutes:\
     xymonq -q ghostlist -a "5 minutes ago"

  Print the hostnames only from ghostlist that reported at least 24 hours ago:\
     xymonq -q ghostlist -a "-yesterday" -l

Examples for config:

  Fetch \`hosts.cfg\`:\
     xymonq -q config -f hosts.cfg

## AUTHOR

Written by Thomas Eckert

## COPYRIGHT

Copyright © 2015-2018 Thomas Eckert, http://www.it-eckert.com/

## SEE ALSO

[xymon(1)](/xymon/1.md), [xymon-xmh(5)](/xymon-xmh/5.md), [xymond(8)](/xymond/8.md)