aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ping903.cred.54
-rw-r--r--maint/README.org549
-rw-r--r--maint/style.css85
-rw-r--r--src/remoteip.c4
4 files changed, 638 insertions, 4 deletions
diff --git a/doc/ping903.cred.5 b/doc/ping903.cred.5
index b2e187a..ede1b2b 100644
--- a/doc/ping903.cred.5
+++ b/doc/ping903.cred.5
@@ -13,9 +13,9 @@
13.\" 13.\"
14.\" You should have received a copy of the GNU General Public License 14.\" You should have received a copy of the GNU General Public License
15.\" along with Ping903. If not, see <http://www.gnu.org/licenses/>. 15.\" along with Ping903. If not, see <http://www.gnu.org/licenses/>.
16.TH PING903.CRED 5 "February 27, 2020" "PING903.CONF" "File Formats Manual" 16.TH PING903.CRED 5 "March 22, 2020" "PING903.CRED" "File Formats Manual"
17.SH NAME 17.SH NAME
18ping903.conf \- Credentials storage for ping903 18ping903.cred \- Credentials storage for ping903
19.SH DESCRIPTION 19.SH DESCRIPTION
20The file 20The file
21.B .ping903.conf 21.B .ping903.conf
diff --git a/maint/README.org b/maint/README.org
new file mode 100644
index 0000000..4374649
--- /dev/null
+++ b/maint/README.org
@@ -0,0 +1,549 @@
1* Overview
2
3Ping903 is designed to periodically monitor a very large number of
4remote hosts using ICMP ECHO packets. The system is built using the
5client-server architecture. The main component (*ping903*) is a daemon
6that sits in memory and wakes up periodically to send certain number
7of ICMP echo packets to a preconfigured number of hosts and to collect
8replies. The resulting round-trip statistics is made available via
9REST API.
10
11The daemon reads its settings from a plain text configuration file.
12Most settings have sensible defaults, so that the only thing that the
13user needs to supply to get started is a list of IP addresses to
14monitor. This list is referred to in this document as /ip-list/.
15
16A simple command line client utility (*ping903q*) allows the user to
17communicate with the daemon, obtaining the needed information about
18each host in particular, or all monitored hosts at once. This utility
19can operate in several modes. In particular, it can be used as
20Nagios external check tool, instead of the standard *check_ping* utility.
21
22The package and its companion packages are available for download from
23https://download.gnu.org.ua/release/ping903.
24
25For the recent news, visit the package development site at
26https://puszcza.gnu.org.ua/projects/ping903.
27
28The git repository is available at
29http://git.gnu.org.ua/cgit/ping903.git.
30
31
32* Installation
33
34To build *ping903* you will need *GNU Libmicrohttpd library*. It is
35available for download from http://ftp.gnu.org/gnu/libmicrohttpd.
36
37When building from source package, usual incantations apply:
38
39#+BEGIN_SRC shell-script
40 ./configure
41 make
42 make install
43#+END_SRC
44
45This will install the package under */usr/local*. That is, the server
46will be installed as */usr/local/sbin/ping903*, the client program as
47*/usr/local/bin/ping903q*, etc. You can give a number of options to
48*./configure* in order to customize your installation, in particular to
49alter the default installation paths. For example, to install to the
50*/usr* file hierarchy, use
51
52#+BEGIN_SRC shell-script
53 ./configure --prefix=/usr
54#+END_SRC
55
56Please refer to the =INSTALL= document in the source directory for a
57discussion of available options to configure and their effect.
58
59After installing the package, copy the file *src/ping903.conf* to
60*/etc/ping903.conf* and edit it to your liking. This file contains
61configuration settings that control the behavior of the server daemon
62and, to a certain extent, that of a query tool. Short annotations
63before each statement will help you navigate through it. You will
64find a detailed discussion of the configuration file in the manpage
65[[http://man.gnu.org.ua/manpage/?5+ping903.conf][ping903.conf]](5). What follows is a short outline, intended for quick
66start.
67
68At the very beginning you can leave most settings at their default
69values. You might wish to supply a list of IP addresses to monitor,
70although even that is not mandatory, since you can add them later,
71when the program is already running. To specify them in configuration
72file, use the =ip-list= statement. Its argument is either the name
73of a file with the IP addresses, or a list of IP addresses as a
74/here-document/:
75
76#+BEGIN_SRC shell-script
77 ip-list FILENAME
78#+END_SRC
79
80or
81
82#+BEGIN_SRC shell-script
83 ip-list <<EOF
84 ...
85 EOF
86#+END_SRC
87
88(you can use arbitrary word in place of =EOF= in the latter example,
89the only requirement being that the list end with exactly the same
90word as the one that followed =<<= at its beginning).
91
92In either case, IP addresses must be listed one per line of input.
93Leading and trailing whitespace is ignored, as well as empty lines.
94Comments are introduced by a hash sign (#) appearing as the first
95non-whitespace character on a line.
96
97You are not required to keep all your IP addresses in a single file.
98If necessary, you can scatter them among several files and name each
99of them in a separate =ip-list= statement.
100
101IP addresses listed in ip-list files form the /immutable/ IP list,
102called so because it cannot be altered while the program is running.
103The REST API allows the user to add any number of IP addresses at
104runtime as well as remove any of IP addresses added this way. These
105addresses form the /mutable/ IP list. Mutable IP list is preserved
106across program restarts.
107
108This means that actually the immutable IP list is optional. You may
109choose to keep all monitored addresses in an external storage (an SQL
110database, for example) and load them dynamically after the daemon
111has started. A working example program for adding IP addresses from
112a MySQL database is shipped in the [[http://git.gnu.org.ua/cgit/ping903.git/tree/examples][examples]] directory. A full-fledged
113client package able to add or delete keywords at runtime, both
114individually or in batches and providing another features is available
115from <http://git.gnu.org.ua/cgit/ping903/mangemanche.git>.
116
117Normally, the ip-list file should contain IP addresses of the hosts to
118monitor. It is OK, however, to use symbolic DNS names, too. If a
119hostname resolves to a single A record, such usage is equivalent to
120placing that IP in the ip-list. However, if the hostname resolves to
121multiple IPs, only first one will be used.
122
123By default, the server will wake up each minute and send 10 echo
124requests within 1 second intervals to each registered IP. If the
125number of collected replies is less than 7, the IP will be declared as
126dead ("alive": false, in the returned JSON). Otherwise it is
127considered alive ("alive": true).
128
129The following settings control these parameters:
130
131- probe-interval N ::
132 Interval between wake-ups in seconds.
133 Default *N=60*.
134- ping-count N ::
135 Number of ICMP packets to send within each probe.
136 Default *N=10*.
137- ping-interval N ::
138 Interval in seconds between two sequential echo requests.
139 Default *N=1*.
140- tolerance N ::
141 Maximum number of lost requests after which the host is considered
142 dead.
143 Default *N=3*.
144
145Another statement worth your attention is =listen=. It configures the
146IP address and port on which the server will listen for incoming HTTP
147requests. The default is *localhost:8080*. Change this setting if
148this port is already occupied on your system or if you wish to make
149ping903 accessible from outside.
150
151The access to the HTTP interface is protected by the default access
152control library (the files */etc/hosts.allow* and */etc/hosts.deny*).
153Refer to [[http://man.gnu.org.ua/manpage/?3+hosts_access][hosts_access]](3) for details.
154
155When you have finished with the configuration file, run *ping903* to
156start the daemon. Check if there are no errors (on the standard
157error and in the syslog channel *daemon*). To verify if the daemon is
158operational, run
159
160#+BEGIN_SRC shell-script
161 curl http://localhost:8080/config
162#+END_SRC
163
164This should return the running configuration.
165
166Within the next =probe-interval= seconds the server will collect
167enough statistics to answer your queries. You can request information
168about any particular IP from your ip-list by running
169
170#+BEGIN_SRC shell-script
171 ping903q IP
172#+END_SRC
173
174This will return the current status of the IP, e.g.
175
176#+BEGIN_SRC shell-script
177 $ ping903q 203.0.113.1
178 203.0.113.1 is alive
179#+END_SRC
180
181To get the detailed statistics use the *-v* option. The result will be
182formatted in a [[http://man.gnu.org.ua/manpage/?8+ping][ping]](8)-like manner:
183
184#+BEGIN_SRC shell-script
185 $ ping903q -v 203.0.113.1
186 203.0.113.1 is alive
187 --- 203.0.113.1 ping statistics ---
188 10 packets transmitted, 10 received, 0% packet loss, time 9414ms
189 rtt min/avg/max/mdev = 41.212/41.265/41.374/0.046 ms
190#+END_SRC
191
192In both cases, any number of IP addresses can be given. E.g. the
193following command will returns statistics for two IPs:
194
195#+BEGIN_SRC shell-script
196 $ ping903q -v 203.0.113.1 203.0.113.5
197#+END_SRC
198
199To check the current status of all hosts, run
200
201#+BEGIN_SRC shell-script
202 $ ping903q -a
203#+END_SRC
204
205Note, that depending on your settings the output can be huge.
206
207Please refer to [[http://man.gnu.org.ua/manpage/?1+ping903q][ping903q]](1), for a detailed discussion of the tool.
208
209* System start-up sequence
210
211To configure *ping903* to start automatically at the system start-up,
212see the [[http://git.gnu.org.ua/cgit/ping903.git/tree/rc][rc]] subdirectory. It contains start up scripts for various
213flavors of GNU/Linux distributions. Please refer to the *README* file
214in this directory for detailed instructions.