diff options
-rw-r--r-- | doc/ping903.cred.5 | 4 | ||||
-rw-r--r-- | maint/README.org | 549 | ||||
-rw-r--r-- | maint/style.css | 85 | ||||
-rw-r--r-- | src/remoteip.c | 4 |
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 |
18 | ping903.conf \- Credentials storage for ping903 | 18 | ping903.cred \- Credentials storage for ping903 |
19 | .SH DESCRIPTION | 19 | .SH DESCRIPTION |
20 | The file | 20 | The 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 | |||
3 | Ping903 is designed to periodically monitor a very large number of | ||
4 | remote hosts using ICMP ECHO packets. The system is built using the | ||
5 | client-server architecture. The main component (*ping903*) is a daemon | ||
6 | that sits in memory and wakes up periodically to send certain number | ||
7 | of ICMP echo packets to a preconfigured number of hosts and to collect | ||
8 | replies. The resulting round-trip statistics is made available via | ||
9 | REST API. | ||
10 | |||
11 | The daemon reads its settings from a plain text configuration file. | ||
12 | Most settings have sensible defaults, so that the only thing that the | ||
13 | user needs to supply to get started is a list of IP addresses to | ||
14 | monitor. This list is referred to in this document as /ip-list/. | ||
15 | |||
16 | A simple command line client utility (*ping903q*) allows the user to | ||
17 | communicate with the daemon, obtaining the needed information about | ||
18 | each host in particular, or all monitored hosts at once. This utility | ||
19 | can operate in several modes. In particular, it can be used as | ||
20 | Nagios external check tool, instead of the standard *check_ping* utility. | ||
21 | |||
22 | The package and its companion packages are available for download from | ||
23 | https://download.gnu.org.ua/release/ping903. | ||
24 | |||
25 | For the recent news, visit the package development site at | ||
26 | https://puszcza.gnu.org.ua/projects/ping903. | ||
27 | |||
28 | The git repository is available at | ||
29 | http://git.gnu.org.ua/cgit/ping903.git. | ||
30 | |||
31 | |||
32 | * Installation | ||
33 | |||
34 | To build *ping903* you will need *GNU Libmicrohttpd library*. It is | ||
35 | available for download from http://ftp.gnu.org/gnu/libmicrohttpd. | ||
36 | |||
37 | When building from source package, usual incantations apply: | ||
38 | |||
39 | #+BEGIN_SRC shell-script | ||
40 | ./configure | ||
41 | make | ||
42 | make install | ||
43 | #+END_SRC | ||
44 | |||
45 | This will install the package under */usr/local*. That is, the server | ||
46 | will 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 | ||
49 | alter 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 | |||
56 | Please refer to the =INSTALL= document in the source directory for a | ||
57 | discussion of available options to configure and their effect. | ||
58 | |||
59 | After installing the package, copy the file *src/ping903.conf* to | ||
60 | */etc/ping903.conf* and edit it to your liking. This file contains | ||
61 | configuration settings that control the behavior of the server daemon | ||
62 | and, to a certain extent, that of a query tool. Short annotations | ||
63 | before each statement will help you navigate through it. You will | ||
64 | find 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 | ||
66 | start. | ||
67 | |||
68 | At the very beginning you can leave most settings at their default | ||
69 | values. You might wish to supply a list of IP addresses to monitor, | ||
70 | although even that is not mandatory, since you can add them later, | ||
71 | when the program is already running. To specify them in configuration | ||
72 | file, use the =ip-list= statement. Its argument is either the name | ||
73 | of 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 | |||
80 | or | ||
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, | ||
89 | the only requirement being that the list end with exactly the same | ||
90 | word as the one that followed =<<= at its beginning). | ||
91 | |||
92 | In either case, IP addresses must be listed one per line of input. | ||
93 | Leading and trailing whitespace is ignored, as well as empty lines. | ||
94 | Comments are introduced by a hash sign (#) appearing as the first | ||
95 | non-whitespace character on a line. | ||
96 | |||
97 | You are not required to keep all your IP addresses in a single file. | ||
98 | If necessary, you can scatter them among several files and name each | ||
99 | of them in a separate =ip-list= statement. | ||
100 | |||
101 | IP addresses listed in ip-list files form the /immutable/ IP list, | ||
102 | called so because it cannot be altered while the program is running. | ||
103 | The REST API allows the user to add any number of IP addresses at | ||
104 | runtime as well as remove any of IP addresses added this way. These | ||
105 | addresses form the /mutable/ IP list. Mutable IP list is preserved | ||
106 | across program restarts. | ||
107 | |||
108 | This means that actually the immutable IP list is optional. You may | ||
109 | choose to keep all monitored addresses in an external storage (an SQL | ||
110 | database, for example) and load them dynamically after the daemon | ||
111 | has started. A working example program for adding IP addresses from | ||
112 | a MySQL database is shipped in the [[http://git.gnu.org.ua/cgit/ping903.git/tree/examples][examples]] directory. A full-fledged | ||
113 | client package able to add or delete keywords at runtime, both | ||
114 | individually or in batches and providing another features is available | ||
115 | from <http://git.gnu.org.ua/cgit/ping903/mangemanche.git>. | ||
116 | |||
117 | Normally, the ip-list file should contain IP addresses of the hosts to | ||
118 | monitor. It is OK, however, to use symbolic DNS names, too. If a | ||
119 | hostname resolves to a single A record, such usage is equivalent to | ||
120 | placing that IP in the ip-list. However, if the hostname resolves to | ||
121 | multiple IPs, only first one will be used. | ||
122 | |||
123 | By default, the server will wake up each minute and send 10 echo | ||
124 | requests within 1 second intervals to each registered IP. If the | ||
125 | number of collected replies is less than 7, the IP will be declared as | ||
126 | dead ("alive": false, in the returned JSON). Otherwise it is | ||
127 | considered alive ("alive": true). | ||
128 | |||
129 | The 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 | |||
145 | Another statement worth your attention is =listen=. It configures the | ||
146 | IP address and port on which the server will listen for incoming HTTP | ||
147 | requests. The default is *localhost:8080*. Change this setting if | ||
148 | this port is already occupied on your system or if you wish to make | ||
149 | ping903 accessible from outside. | ||
150 | |||
151 | The access to the HTTP interface is protected by the default access | ||
152 | control library (the files */etc/hosts.allow* and */etc/hosts.deny*). | ||
153 | Refer to [[http://man.gnu.org.ua/manpage/?3+hosts_access][hosts_access]](3) for details. | ||
154 | |||
155 | When you have finished with the configuration file, run *ping903* to | ||
156 | start the daemon. Check if there are no errors (on the standard | ||
157 | error and in the syslog channel *daemon*). To verify if the daemon is | ||
158 | operational, run | ||
159 | |||
160 | #+BEGIN_SRC shell-script | ||
161 | curl http://localhost:8080/config | ||
162 | #+END_SRC | ||
163 | |||
164 | This should return the running configuration. | ||
165 | |||
166 | Within the next =probe-interval= seconds the server will collect | ||
167 | enough statistics to answer your queries. You can request information | ||
168 | about any particular IP from your ip-list by running | ||
169 | |||
170 | #+BEGIN_SRC shell-script | ||
171 | ping903q IP | ||
172 | #+END_SRC | ||
173 | |||
174 | This 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 | |||
181 | To get the detailed statistics use the *-v* option. The result will be | ||
182 | formatted 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 | |||
192 | In both cases, any number of IP addresses can be given. E.g. the | ||
193 | following 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 | |||
199 | To check the current status of all hosts, run | ||
200 | |||
201 | #+BEGIN_SRC shell-script | ||
202 | $ ping903q -a | ||
203 | #+END_SRC | ||
204 | |||
205 | Note, that depending on your settings the output can be huge. | ||
206 | |||
207 | Please 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 | |||
211 | To configure *ping903* to start automatically at the system start-up, | ||
212 | see the [[http://git.gnu.org.ua/cgit/ping903.git/tree/rc][rc]] subdirectory. It contains start up scripts for various | ||
213 | flavors of GNU/Linux distributions. Please refer to the *README* file | ||
214 | in this directory for detailed instructions. | ||