aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2020-03-10 11:56:52 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2020-03-10 11:56:52 +0200
commit2f8c073f59b4b352ee5ea2fedd6e7d231e8c1a06 (patch)
tree5aedeead2b29e328d1675473c418aed631df25e5
parent032fd28c0a1d75fd01571dbf2714fd106fa374c0 (diff)
downloadping903-2f8c073f59b4b352ee5ea2fedd6e7d231e8c1a06.tar.gz
ping903-2f8c073f59b4b352ee5ea2fedd6e7d231e8c1a06.tar.bz2
Proof-read the docs. Make configuration file optional.
-rw-r--r--README52
-rw-r--r--doc/ping903.869
-rw-r--r--doc/ping903.conf.519
-rw-r--r--doc/ping903q.112
-rwxr-xr-xexamples/ipadd15
-rwxr-xr-xexamples/ipdel15
-rw-r--r--src/main.c13
7 files changed, 140 insertions, 55 deletions
diff --git a/README b/README
index 5018eb6..94ec8d9 100644
--- a/README
+++ b/README
@@ -13,8 +13,8 @@ REST API.
The daemon reads its settings from a plain text configuration file.
Most settings have sensible defaults, so that the only thing that the
-user must supply to get started is a list of IP addresses to monitor.
-This list is referred to in this document as "ip-list".
+user needs to supply to get started is a list of IP addresses to
+monitor. This list is referred to in this document as "ip-list".
A simple command line client utility (ping903q) allows the user to
communicate with the daemon, obtaining the needed information about
@@ -51,18 +51,31 @@ configuration settings that control the behavior of the server daemon
and, to a certain extent, that of a query tool. The file contains
short annotations before each statement to help you navigate through
it. You will find a detailed discussion of the configuration file in
-the manpage ping903.conf(5). What follows is a short outline intended
+the manpage ping903.conf(5). What follows is a short outline, intended
for quick start.
At the very beginning you can leave most settings at their default
-values. The only statement that you must provide in your
-configuration is
+values. You might wish to supply a list of IP addresses to monitor,
+although even that is not mandatory, since you can add them later,
+when the program is already running. To specify them in configuration
+file, use the "ip-list" statement. Its argument is either the name
+of a file with the IP addresses, or a list of IP addresses as a
+"here-document":
ip-list FILENAME
-Replace FILENAME with the name of the file with IP addresses to
-monitor. In this file, each IP address must occupy a separate line.
-Empty lines, leading and trailing whitespace and comments are ignored.
+or
+
+ ip-list <<EOF
+ ...
+ EOF
+
+(you can use arbitrary word in place of EOF in the latter example,
+the only requirement being that the list end with exactly the same
+word as the one that followed '<<' at its beginning).
+
+In either case, IP addresses must be listed one per line of input.
+Leading and trailing whitespace is ignored, as well as empty lines.
Comments are introduced by a hash sign (#) appearing as the first
non-whitespace character on a line.
@@ -81,7 +94,10 @@ This means that actually the immutable IP list is optional. You may
choose to keep monitored addresses in an external storage (an SQL
database, for example) and load them dynamically after the daemon
has started. A working example program for adding IP addresses from
-a MySQL database is shipped in the examples directory.
+a MySQL database is shipped in the examples directory. A full-fledged
+client package able to add or delete keywords at runtime, both
+individually or in batches and providing another features is available
+from <http://git.gnu.org.ua/cgit/ping903/mangemanche.git>.
Normally, the ip-list file should contain IP addresses of the hosts to
monitor. It is OK, however, to use symbolic DNS names, too. If a
@@ -123,9 +139,10 @@ The access to the HTTP interface is protected by the default access
control library (the files /etc/hosts.allow and /etc/hosts.deny).
Refer to hosts_access(3) for details.
-When you have configured the daemon, start it. Just run ping903.
-Check if there are no errors (on the standard error and in the
-syslog channel "daemon"). To verify if the daemon is operational, run
+When you have finished with the configuration file, start the daemon.
+Just run ping903. Check if there are no errors (on the standard error
+and in the syslog channel "daemon"). To verify if the daemon is
+operational, run
curl http://localhost:8080/config
@@ -158,13 +175,18 @@ following command will returns statistics for two IPs:
To check the current status of all hosts, run
- $ ping903q
+ $ ping903q -a
-without arguments. Note, that depending on your settings the output
-can be huge.
+Note, that depending on your settings the output can be huge.
Please refer to ping903q(1), for a detailed discussion of the tool.
+* System start-up sequence
+
+To configure ping903 to start automatically at the system start-up,
+see the "rc" subdirectory. It contains start up scripts for various
+flavors of GNU/Linux distributions.
+
* Nagios external check
The ping903q tool can be used as a Nagios external check program. The
diff --git a/doc/ping903.8 b/doc/ping903.8
index 0649aa2..bde1f51 100644
--- a/doc/ping903.8
+++ b/doc/ping903.8
@@ -13,7 +13,7 @@
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Ping903. If not, see <http://www.gnu.org/licenses/>.
-.TH PING903 8 "February 14, 2020" "PING903" "System Administration"
+.TH PING903 8 "March 10, 2020" "PING903" "System Administration"
.SH NAME
ping903 \- high-performance ICMP monitoring daemon
.SH SYNOPSIS
@@ -42,13 +42,20 @@ properly functioning and restarts it if it terminates abnormally.
.PP
The monitoring process, in turn, is responsible for periodic polling
of the configured hosts, maintaining the statistics information and
-answering the REST requests.
+answering incoming REST requests.
.PP
The program logs its activities using syslog channel \fBdaemon\fR.
.PP
-The list of IP addresses to monitor is supplied by an \fIip\-list\fR
-file specified in the configuration. Probes for each IP from the list
-are initiated periodically, each
+The set of monitored IP addresses consists of two parts. The
+.I immutable
+IP list is supplied in the configuration file and cannot be altered at
+run-time. The
+.I mutable
+IP list, in contrast, is maintained via the REST API and thus can be
+changed while the server runs. The content of mutable IP list is
+preserved during server restarts.
+.PP
+Probes for each IP from the list are initiated periodically, each
.B probe\-interval
seconds. Each probe consists of
.B ping\-count
@@ -68,32 +75,50 @@ deviation. If more than a predefined number of echo requests (the
failure \fItolerance\fR number) are lost, the status of the IP is
changed to "inactive".
.PP
-The \fBHTTP\fR listener is provided for returning the collected
-statistics. By default the program listens for queries on localhost,
-port 8080. If compiled with the support for \fBlibwrap\fR, the access
-to the HTTP interface can be controlled using files
+An \fBHTTP\fR listener thread is responsible for returning the collected
+statistics and serving other requests. By default the program listens
+for queries on localhost, port 8080. If compiled with the support for
+\fBlibwrap\fR, the access to the HTTP interface can be controlled
+using files
.B /etc/hosts.allow
and
.BR /etc/hosts.deny .
See
.BR hosts_access (5),
for details.
+.PP
+For information about accessing the statistics, see
+.BR ping903q (1).
+.PP
+A utility for maintaining the mutable IP list is available from
+<http://git.gnu.org.ua/cgit/ping903/mangemanche.git>.
.SH CONFIGURATION FILE
-By default, configuration file
-.B /etc/ping903.conf
-is read upon startup. Its location can be changed using the
-.B \-c
-command line option. This file can be used to alter all configurable
-parameters of
-.BR ping903 .
+By default, the configuration is read from the file
+.BR /etc/ping903.conf .
See
.BR ping903.conf (5),
-for a detailed discussion of its syntax and available keywords. Most
-parameters have sensible default values and can in many cases be left
-unchanged. The only setting that must be present in this file is the
-.BR ip\-list
-statement, which defines a file (or files), from which the program
-reads the IP addresses to monitor.
+for a detailed discussion of its syntax and available keywords.
+It is OK if the file does not exist. In this case
+.B ping903
+will use the following built-in defaults:
+.PP
+.RS 4
+.nf
+data\-length 56
+# ip\-list is empty
+ping\-count 10
+ping\-interval 1
+probe\-interval 60
+syslog\-facility daemon
+tolerance 3
+
+listen localhost:8080
+access-log off
+access-log-verbose off
+http\-backlog\-size 128
+# trusted\-ip is empty
+.fi
+.RE
.SH OPTIONS
.TP
\fB\-c \fIFILE\fR
diff --git a/doc/ping903.conf.5 b/doc/ping903.conf.5
index 1889892..cf3432e 100644
--- a/doc/ping903.conf.5
+++ b/doc/ping903.conf.5
@@ -13,7 +13,7 @@
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Ping903. If not, see <http://www.gnu.org/licenses/>.
-.TH PING903.CONF 5 "February 28, 2020" "PING903.CONF" "File Formats Manual"
+.TH PING903.CONF 5 "March 10, 2020" "PING903.CONF" "File Formats Manual"
.SH NAME
ping903.conf \- configuration file for high-performance ICMP monitoring daemon
.SH DESCRIPTION
@@ -37,7 +37,7 @@ ignored otherwise.
.SS Server configuration
.TP
\fBpidfile \fIFILE\fR
-Instructs \fBping903\fR to write its PID the specified file. If
+Instructs \fBping903\fR to write its PID to the specified file. If
running with supervisor process (the default), the supervisor's PID
will be written.
@@ -48,7 +48,7 @@ Configures the syslog facility to use. Valid arguments are
.BR auth ,
.BR authpriv ,
.BR cron ,
-.BR daemon "(default), "
+.BR daemon " (default),"
.BR ftp ,
.BR kern ,
.BR lpr ,
@@ -100,7 +100,7 @@ each 10 are lost.
.TP
\fBdata\-length \fIN\fR
Number of additional bytes to send in each ICMP echo requests (apart from
-the timestamp). Default is 40.
+the timestamp). Default is 56.
.SS HTTP responder configuration
.TP
\fBlisten \fIIPADDR\fB:\fIPORT\fR
@@ -153,7 +153,8 @@ Adds a CIDR to the list of trusted IP networks. This list is used
when determining source IP address of a HTTP connection for the
purpose of logging. By default, each log message contains the client
IP of the connection. If the
-.B X\-Forwarded\-For header is present, its value overrides that IP. If the
+.B X\-Forwarded\-For
+header is present, its value overrides that IP. If the
header contains a comma-delimited list of IP addresses, this list is
processed in right-to-left order, until either a not trusted IP or the
first IP in the list is encountered, whichever occurs first.
@@ -198,8 +199,8 @@ utility.
realm is used by the client to determine what user name and password
to send for a given authenticated area. If \fIREALM\fR contains
whitespace, it must be enclosed in double-quotes. Within a
-double-quoted string any occurrence of double-quote or backslash must
-be escaped by prefixing it with a backslash character.
+double-quoted string any occurrence of a double-quote or backslash
+character must be escaped by prefixing it with a backslash.
These parameters are mandatory only for the very first occurrence of the
\fBauth\fR statements. The statements that follow it may omit the
@@ -231,8 +232,8 @@ auth basic GET /config /etc/ping903/htpasswd "Config Access"
Notice, that an incoming HTTP request is matched against each
\fBauth\fR statement in turn, in the order they appear in the
configuration file, and it is the first matching statement that
-takes effect. Therefore, place more specific METHOD/URL combinations
-before more general ones.
+takes effect. Therefore, be sure to place more specific METHOD/URL
+combinations before more general ones.
.SH SEE ALSO
.BR ping903 (8),
.BR ping903q (1),
diff --git a/doc/ping903q.1 b/doc/ping903q.1
index 84eccee..cf6172e 100644
--- a/doc/ping903q.1
+++ b/doc/ping903q.1
@@ -13,7 +13,7 @@
.\"
.\" 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 1 "March 7, 2020" "PING903Q" "User Commands"
+.TH PING903Q 1 "March 10, 2020" "PING903Q" "User Commands"
.SH NAME
ping903q \- ping903 query tool
.SH SYNOPSIS
@@ -51,7 +51,7 @@ 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
.B /etc/ping903.conf
-exists, it will look obtain the socket address from the \fBlisten\fR
+exists, it will obtain the socket address from the \fBlisten\fR
statement. See
.BR ping903.conf (5),
for detailed description of the configuration file.
@@ -134,11 +134,9 @@ file at startup and to use them when forming the request as described
in \fBBasic authorization\fR above.
.TP
.B \-r
-Resolve host argument to IP address and use the IP address to query
-the server. Using this option you can supply a symbolic host name
-as argument even if the server uses the corresponding IP and still get
-a meaningful result. Otherwise, you can use the matching mode (see
-below).
+Fuzzy matching mode. First, issue a match request looking for IP
+addresses matching each \fIHOST\fR from the command line. Then,
+query statistics for each of the returned IP addresses.
.TP
.B \-V
Print program version, copyright information, and exit.
diff --git a/examples/ipadd b/examples/ipadd
index f001950..e4a2184 100755
--- a/examples/ipadd
+++ b/examples/ipadd
@@ -2,6 +2,21 @@
#! -*-perl-*-
eval 'exec perl -x -S $0 ${1+"$@"}'
if 0;
+# This file is part of Ping903
+# 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/>.
=head1 NAME
diff --git a/examples/ipdel b/examples/ipdel
index fa4cb8f..0762082 100755
--- a/examples/ipdel
+++ b/examples/ipdel
@@ -2,6 +2,21 @@
#! -*-perl-*-
eval 'exec perl -x -S $0 ${1+"$@"}'
if 0;
+# This file is part of Ping903
+# 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/>.
=head1 NAME
diff --git a/src/main.c b/src/main.c
index ab630c6..a31723c 100644
--- a/src/main.c
+++ b/src/main.c
@@ -28,7 +28,6 @@
#include "json.h"
#include "defs.h"
-static char *config_file = DEFAULT_CONFIG_FILE;
int verbose;
enum state {
@@ -244,6 +243,7 @@ int
main(int argc, char **argv)
{
int c;
+ char *config_file = NULL;
int foreground = 0;
int single_process = 0;
@@ -285,7 +285,16 @@ main(int argc, char **argv)
}
pinger_setup();
- if (readconfig(config_file))
+ if (!config_file) {
+ config_file = DEFAULT_CONFIG_FILE;
+ if (access(config_file, F_OK) == 0) {
+ if (readconfig(config_file))
+ exit(EX_CONFIG);
+ } else
+ info("configuration file %s does not exist; "
+ "assuming defaults",
+ config_file);
+ } else if (readconfig(config_file))
exit(EX_CONFIG);
pidfile_check();

Return to:

Send suggestions and report system problems to the System administrator.