.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
.TH XYMONQ "1" "January 2018" "IT-Eckert" "User Commands"
.SH NAME
xymonq \- a frontend to query the Xymon network- and systems-monitor.
.SH SYNOPSIS
.B xymonq
[ \fI\,-c conf-file\/\fR] \fI\,-q QUERYTYPE \/\fR[\fI\,-P PAGEPATH\/\fR] [\fI\,-H HOSTNAME\/\fR] [\fI\,-T TEST\/\fR] [\fI\,-C COLOR\/\fR[\fI\,,COLOR,\/\fR...]] [\fI\,-X CRITS\/\fR] [\fI\,-f FIELD\/\fR[\fI\,,FIELD,\/\fR...]] [\fI\,-s SECTION\/\fR[\fI\,,SECTION,\/\fR...]] \fI\,| -l \/\fR] [\fI\,-S|-p\/\fR] [\fI\,-h | -V\/\fR] [\fI\,-d\/\fR]
.br
.B xymonq
\fI\,-q clientlog   \/\fR[\fI\,-P PAGEPATH\/\fR] [\fI\,-H HOSTNAME\/\fR] [\fI\,-T TEST\/\fR] [\fI\,-C COLOR\/\fR[\fI\,,COLOR,\/\fR...]] [\fI\,-X CRITS\/\fR] [\fI\,-s SECTION\/\fR[\fI\,,SECTION,\/\fR...]] \fI\,| -l \/\fR]
.br
.B xymonq
\fI\,-q xymondboard \/\fR[\fI\,-P PAGEPATH\/\fR] [\fI\,-H HOSTNAME\/\fR] [\fI\,-T TEST\/\fR] [\fI\,-C COLOR\/\fR[\fI\,,COLOR,\/\fR...]] [\fI\,-X CRITS\/\fR] [\fI\,-f FIELD,\/\fR[\fI\,FIELD,\/\fR...]]
.br
.B xymonq
\fI\,-q hostinfo    \/\fR[\fI\,-P PAGEPATH\/\fR] [\fI\,-H HOSTNAME\/\fR] [\fI\,-T TEST\/\fR] [\fI\,-C COLOR\/\fR[\fI\,,COLOR,\/\fR...]] [\fI\,-X CRITS\/\fR]
.br
.B xymonq
\fI\,-q xymondlog   \/\fR[\fI\,-P PAGEPATH\/\fR] [\fI\,-H HOSTNAME\/\fR] \fI\,{-T TEST | -l} \/\fR[\fI\,-C COLOR\/\fR[\fI\,,COLOR,\/\fR...]] [\fI\,-X CRITS\/\fR]
.br
.B xymonq
\fI\,-q ghostlist \/\fR[\fI\,-a \/\fR[\fI\,-\/\fR]\fI\,AGE\/\fR] [\fI\,-l\/\fR]
.br
.B xymonq
\fI\,-q config \/\fR[\fI\,-f file\/\fR]
.br
.B xymonq
\fI\,-q {ping|version}\/\fR
.SH DESCRIPTION
\fBxymonq\fR is a frontend to send various query-messages via \fBxymon(1)\fR to a Xymon server \fBxymond(8)\fR. All test- (column) information for one or more hosts/tests and internal status information of Xymon can be retrieved.
.PP
xymonq \- A frontend to query the Xymon network\- and systems\-monitor.
.SS "OPTIONS TO SELECT DISPLAYED DATA FOR THE HOSTS:"
.TP
\fB\-q\fR QUERYTYPE
Query to perform to Xymon [clientlog | xymondboard | hostinfo | xymondlog | ghost[list] | config | ping]
.PP
See section \fBQUERYTYPES\fR for details.
.SS "OPTIONS TO SELECT HOSTS:"
.TP
\fB\-P\fR PAGEPATH
A PAGEPATH specification from hosts.cfg(*).
.TP
\fB\-H\fR HOSTNAME
A hostname from hosts.cfg(*).
To read the hosts from stdin use "\-" (all other filters inactive).
.TP
\fB\-T\fR TEST
The name of a TEST, defaults to "info"(*).
.PP
(*) interpreted as a REGEX
.TP
\fB\-C\fR COLOR
only tests with COLOR, may be coma\-separated list like "clear,green",
default: empty=all colors
.TP
\fB\-X\fR CRITS
eXtra CRITERIA, like "ip=", "net=" or "tag=", CRITS are passed as\-is
to xymondboard
.PP
       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)`) is possible too.
.PP
An empty (or missing) option matches every item of that criterium.
.TP
\fB\-L\fR
print evaluated hostlist to stdout and exit
.TP
\fB\-S\fR
print "HOST=hostname" separator\-lines above data (deprecated)
.TP
\fB\-p\fR
prefix each line of output w/ "hostname: ", valid for queries: clientlog, xymondboard, xymondlog
.SS "Options for clientlog:"
.TP
\fB\-f\fR FIELD
fields to print, defaults to "hostname"
.TP
\fB\-s\fR SECTION
one or more section\-names, coma separated
If empty the whole clientlog is printed
.TP
\fB\-l\fR
list available sections only (as they occur)
.SS "Options for xymondboard:"
.TP
\fB\-f\fR FIELD
fields to print, defaults to empty, thus using xymon\-defaults
.SS "Options for xymondlog:"
.TP
\fB\-l\fR
just list available tests for selected host(s)
.SS "Options for ghostlist:"
.TP
\fB\-a\fR [\-]AGE
print only host with report AGE; AGE is a GNU\-date "\-s"\-compatible string)
The "\-" prefix inverts the selection.
.TP
\fB\-l\fR
only print the hostnames instead of the default full "ghostline"
.SS "Options for client:"
.TP
\fB\-f\fR file
The file to retrieve, e.g. "hosts.cfg", "analysis.cfg". Only files ending
with ".cfg" can be fetched. Defaults to "hosts.cfg".
.SS "Global options:"
.TP
\fB\-c\fR 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.
.TP
\fB\-v\fR
verbose output, print the "xymon"\-commandlines
.TP
\fB\-V\fR
print version info
.TP
\fB\-d\fR
enable debug output
.TP
\fB\-h\fR
this help message
.SH QUERYTYPES
This is only a short description of the query types possible. For more detailed information see xymon(1). 

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.
.SH "CONFIG FILE"
The default configuration and some query-settings can be adjusted with a configuration file. The file has to conform to bash(1) 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)-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
.SH 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
.SH AUTHOR
Written by Thomas Eckert
.SH COPYRIGHT
Copyright \(co 2015\-2018 Thomas Eckert, http://www.it\-eckert.com/
.SH "SEE ALSO"
xymon(1), xymon-xmh(5), xymond(8)