PING903Q

NAME
SYNOPSIS
DESCRIPTION
EXIT CODE
OPTIONS
SEE ALSO
COPYRIGHT

---

NAME

ping903q - ping903 query tool

SYNOPSIS

ping903q [-ahVv] [-f FILE] [-R REALM] [HOST...]

ping903q [-N] [-f FILE] [-p PREFIX] [-R REALM] -H HOST -c RTA,PCT% -w RTA,PCT%

ping903q [-f FILE] [-R REALM] -m

DESCRIPTION

Queries the ping903 daemon for monitoring statistics about the given HOSTs. To obtain information about all monitored hosts, use the -a option.

By default a one-line summary is displayed, which informs about the IP and its current status ("alive" vs. "not alive"). Additional information can be requested with the -v command line option. When given this option, the program will output detailed information about round trip times and lost packets.

By default, the program attempts to connect to the default REST API port of (localhost:8080). If the file /etc/ping903.conf exists, it will obtain the socket address from the listen statement. See ping903.conf(5), for detailed description of the configuration file.

Nagios check mode
When the -H, -c, and -w options are used, the program enters Nagios check mode. In this mode its output complies with the requirements for external Nagios check programs.

Match mode
When invoked with the -m option, ping903q checks if HOST is monitored by the server. If so, it prints the matching host names and exits with code 0.

Basic authorization
If the server requires authorization, ping903q will look into the file .ping903.cred in the user home directory in order to find authentication credentials (see ping903.cred(5), for a detailed discussion of the file). The file is scanned for an entry that matches the server name and port (as given in the listen statement of the ping903.conf file) and the authorization realm name presented by the server. If such an entry is found, the user name and password listed in it will be used to send the authorized request.

Using the -R option, you can force using a specific realm for authorization. In this case, the .ping903.cred file is scanned at startup and the credentials found in it are used to authorize the request, without sending unauthorized request first and consulting the reply.

EXIT CODE

When called with one argument, the program exits with code 0 (success) if the IP is alive, 2 if it is not, and 3 if the host status is unknown.

When called without arguments, the program exits with code 0 if all monitored IP addresses are alive, 2 if none of them is reachable and 1 if some of them are.

Exit codes in nagios check mode:

	0		Success
	1		Warning condition.
	2		Critical condition.
	3		Unknown. This code is returned in the following cases: (1) the host is not monitored by the ping903 server, (2) the server replied with a HTTP code other than 200 or the reply was otherwise non-compliant, and (3) if the server has not yet collected enough data for that host and the command line option -N was given.

In match mode, the program exits with code 0 if the requested host is monitored by the server, and with code 2 if it is not.

If any error is encountered, ping903q exits with status 3.

OPTIONS

-a

Query statistics for all monitored hosts.

-f FILE

Read configuration from FILE instead of from the default /etc/ping903.conf.

-h

Print a short usage summary.

-R REALM

Specifies authentication realm to use to authenticate the request. This option causes the program to look up the credentials in the .ping903.cred file at startup and to use them when forming the request as described in Basic authorization above.

	-r		Fuzzy matching mode. First, issue a match request looking for IP addresses matching each HOST from the command line. Then, query statistics for each of the returned IP addresses.
	-V		Print program version, copyright information, and exit.
	-v		Turn on verbose output.

Options specific for Nagios check mode
The presence of any of the three options below switches ping903q to Nagios check mode. For this mode to succeed, all three options must be specified.
-H HOST

Sets host name or IP address to query for.

-c RTA,PCT%

Sets the critical threshold value. RTA is the round-trip average and PCT is the package loss percentage values. The critical condition is entered if either the returned round-trip average becomes greater than or equal to RTA or the lost package percentage becomes greater than or equal to PCT. Note that both parts must be present and must be valid floating-point numbers. Note also that the use of the percent sign is mandatory.

-w RTA,PCT%

Sets the warning threshold value. See above for the discussion of the arguments.

Other options valid in this mode:

-N

By default hosts in initial state (i.e. for which no data has been collected) are treated as "OK" (exit status 0). This option changes the default to treat them as "UNKNOWN" (exit status 3).

-p PREFIX

Supplies the prefix to be displayed before Nagios status string. The default is "PING". The PREFIX string can contain the %h escape sequence, which will be expanded to the name of the host being monitored. E.g. -p ’PING %h’.

Options specific for match mode

-m

Switch to the host match mode.

SEE ALSO

ping903(8), ping903.cred(5), Nagios<https://www.nagios.org/>.

COPYRIGHT

Copyright © 2020 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

---