aboutsummaryrefslogtreecommitdiff
path: root/doc/ping903q.1
blob: 6e024d73151272fbbf7ad8c639a4c02db954dbcb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
.\" This file is part of ping903 -*- nroff -*-
.\" Copyright (C) 2020 Sergey Poznyakoff
.\"
.\" Ping903 is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" Ping903 is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Ping903.  If not, see <http://www.gnu.org/licenses/>.
.TH PING903Q 8 "February 13, 2020" "PING903Q" "User Commands"
.SH NAME
ping903q \- ping903 query tool
.SH SYNOPSIS
\fBping903q\fR\
 [\fB\-hVv\fR]\
 [\fB\-f \fIFILE\fR]\
 [\fIIP\fR]

or

\fBping903q\fR\
  [\fB\-f \fIFILE\fR]\
  \fB\-H \fIHOST\fR\
  \fB\-c \fIRTA\fB,\fIPCT\fB%\fR\
  \fB\-w \fIRTA\fB,\fIPCT\fB%\fR  
.SH DESCRIPTION
Queries monitoring statistics from the \fBping903\fR daemon.  When
used with a single argument (\fIIP\fR), displays information about
this particular IP address.  Used without arguments, displays
statistics about all IP addresses monitored by the running daemon.
.PP
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
.B \-v
command line option.  When given this option, the program will output
detailed information about round trip times and lost packets.
.PP
By default, the program attempts to connect to the default REST API
port of (localhost:8080).  If the file
.B /etc/ping903.conf
exists, it will look obtain the socket address from the \fBlisten\fR
statement.  See
.BR ping903.conf (5),
for detailed description of the configuration file.
.SS Nagios check mode
When the \fB\-H\fR, \fB\-c\fR, and \fB\-w\fR options are used, the
program enters \fINagios check mode\fR.  In this mode its output
complies with the requirements for external \fBNagios\fR check
programs.
.SH EXIT CODE
When called with one argument, the program exits with code 0 (success)
if the IP is alive and 2 otherwise.
.PP
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.
.PP
Exit codes in nagios check mode:
.TP
.B 0
Success
.TP
.B 1
Warning condition.
.TP
.B 2
Critical condition.
.PP
If any error is encountered, \fBping903q\fR exits with status \fB3\fR.
.SH OPTIONS
.TP
\fB\-f \fIFILE\fR
Read configuration from \fIFILE\fR instead of from the default
.BR /etc/ping903.conf .
.TP
.B \-h
Print a short usage summary.
.TP
.B \-V
Print program version, copyright information, and exit.
.TP
.B \-v
Turn on verbose output.
.SS Options valid in Nagios check mode
The presense of any of these options switches \fBping903q\fR to Nagios
check mode.  For this mode to succeed, all three options must be specified.
.TP
\fB\-H \fIHOST\fR
Sets host name or IP address to query for.
.TP
\fB\-c \fIRTA\fB,\fIPCT\fB%\fR
Sets the critical threshold value.  \fIRTA\fR is the round-trip
average and \fIPCT\fR is the package loss percentage values.  The
critical condition is entered if either the returned round-trip
average becomes greater than or equal to \fIRTA\fR or the lost package
percentage becomes greater than or equal to \fIPCT\fR.  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.
.TP
\fB\-w \fIRTA\fB,\fIPCT\fB%\fR
Sets the warning threshold value.  See above for the discussion of the
arguments.
.SH SEE ALSO
.BR ping903 (8),
.BR Nagios <https://www.nagios.org/>.
.SH COPYRIGHT
Copyright \(co 2020 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:

Return to:

Send suggestions and report system problems to the System administrator.