Commit | Line | Data |
---|---|---|
f9c5fff0 GMF |
1 | Table of Contents |
2 | ======================================= | |
3 | 1. Introduction | |
e2a8862d CH |
4 | 2. Building and Installing |
5 | 3. Configuration File | |
6 | 4. Command line | |
7 | 5. Tools | |
8 | 6. References | |
f9c5fff0 GMF |
9 | |
10 | ||
11 | ||
c08bc448 GMF |
12 | 1. Introduction |
13 | ======================================= | |
14 | This application provides means to check the availability of remote hosts | |
15 | through pings to them. | |
16 | ||
17 | ||
18 | 1.1. Rationale | |
19 | --------------------------------------- | |
a7d7778b GMF |
20 | The application uses ICMP echo requests messages, or TCP SYN segments, to |
21 | verify whether a given host is available (up) or not (down). | |
c08bc448 GMF |
22 | |
23 | The host's address can be an IP or a DNS. | |
24 | ||
25 | ||
26 | 1.2. How to use | |
27 | --------------------------------------- | |
28 | There are many ways to invoke the application, the simplest is just type: | |
aca0d1d7 | 29 | ./pingcheck |
12589451 | 30 | which uses the configuration values from the configuration file (described in |
f9c5fff0 | 31 | the Configuration File section). |
c08bc448 | 32 | |
48c8c5dc GMF |
33 | Note: like the ordinary ping, pingcheck binary requires root privileges to |
34 | access control packets. You can run it from sudo: | |
35 | sudo ./pingcheck | |
36 | or setuid: | |
37 | sudo chown root:root pingcheck | |
38 | sudo chmod u+s pingcheck | |
39 | ./pingcheck | |
40 | the last method is the common way to provide temporary root privileges for | |
41 | an executable. | |
42 | ||
703f4d65 | 43 | |
c08bc448 GMF |
44 | 1.3. Resources |
45 | --------------------------------------- | |
f9c5fff0 GMF |
46 | Further information about the problem domain can be found in the References |
47 | section. | |
48 | ||
49 | ||
50 | 1.4. Legal Issues | |
51 | --------------------------------------- | |
96d2fb59 | 52 | Most parts are licensed under the GPLv2 + linking exception. |
c08bc448 | 53 | |
e2a8862d CH |
54 | Parts of the ICMP code are based on the ping example found in the boost Asio |
55 | documentation ((c) Christopher Kohlhoff) but are now heavily modified. The DNS | |
56 | resolver mechanism is based on boost::net::dns and is therefore licensed under | |
57 | the boost license. Notes about this are included in the beginning of the source | |
58 | code. | |
c08bc448 GMF |
59 | |
60 | ||
e2a8862d CH |
61 | 2. Building and Installing |
62 | ======================================= | |
63 | After downloading the source code and necessary libraries (in particular boost) | |
64 | and tools (cmake) you should be able to do: | |
65 | ||
66 | me@my_linux_host ~/some/dir/pingcheck> mkdir build | |
67 | me@my_linux_host ~/some/dir/pingcheck> cd build | |
68 | me@my_linux_host ~/some/dir/pingcheck/build> ccmake ../ | |
69 | OR | |
70 | me@my_linux_host ~/some/dir/pingcheck/build> cmake ../ | |
71 | me@my_linux_host ~/some/dir/pingcheck/build> make help # show more options | |
72 | me@my_linux_host ~/some/dir/pingcheck/build> make | |
73 | me@my_linux_host ~/some/dir/pingcheck/build> make check | |
74 | me@my_linux_host ~/some/dir/pingcheck/build> make install | |
75 | ||
76 | The default install location is /usr/local, the easiest way to change this is | |
77 | through ccmake | |
78 | ||
79 | ||
80 | 3. Configuration file | |
c08bc448 | 81 | ======================================= |
12589451 GMF |
82 | In this section are described the configuration items, along with they possible |
83 | values and meanings. This section is organized in each major configuration | |
e2a8862d | 84 | block. An example file is contained in the conf subdirectory. |
7a073300 GMF |
85 | |
86 | ||
e2a8862d | 87 | 3.1. General |
7a073300 GMF |
88 | --------------------------------------- |
89 | This configurations are shared among and affect all the hosts. | |
6265d17e | 90 | - default-source-network-interface: the local network interface from where the |
51808da0 CH |
91 | ping packages will originate. This option is used for those hosts that set |
92 | source-network-interface=default | |
61e224f8 GMF |
93 | - nameserver: the server which the hosts names will be resolved. It is the |
94 | lookup server which the application will query first. If left blank or omited, | |
95 | it will use the /etc/resolv.conf. | |
361552be | 96 | You can use the nslookup <host> to figure out the nameserver. |
a341119a | 97 | - hosts-down-limit: an absolute number, which ranges from 0 to the number of |
c5e4bfa1 GMF |
98 | hosts available. This value represents the minimum number of hosts that have |
99 | to fail (i.e. do not reply to the ping) in order to alert any external system. | |
a341119a | 100 | - ping-fail-limit: percentage of pings to a host that can fail. If the |
c5e4bfa1 GMF |
101 | percentage of failed pings to a host exceed this number, then the host is |
102 | considered down. | |
d52d036a | 103 | - status-notifier-cmd: the command line that is called when a host is down, or |
c1d76f1b GMF |
104 | up. Accepted variables are: |
105 | ${status} - down or up | |
1634f2a1 GMF |
106 | - link-up-interval: how long (in minutes) the pings must be returned with |
107 | success in order to consider the link up, or stable. | |
108 | - link-down-interval: how long (in minutes) the pings must fail, in order to the | |
109 | application consider the link down. | |
51808da0 CH |
110 | - ratio-random-hosts: expects a value in [0,1]; if <1 will only use the given |
111 | ratio of hosts, selecting them at random | |
e2a8862d CH |
112 | - ping-reply-timeout: Amount of time to wait for an EchoReply to an Echo Request |
113 | before sending the next ping | |
114 | - max-address-resolution-attempts: For hosts given as DNS names, will first do | |
115 | a DNS lookup to get corresponding IPs. This number specifies how often that is | |
116 | attempted before declaring the host offline | |
117 | - resolved-ip-ttl-threshold: When the TTL for an IP falls below this threshold, | |
118 | a new DNS lookup will be scheduled | |
703f4d65 | 119 | |
703f4d65 | 120 | |
e2a8862d | 121 | 3.2. Host |
7a073300 | 122 | --------------------------------------- |
51808da0 | 123 | (All these settings must always be present!) |
d52d036a | 124 | - name: the DNS or IP of the host to ping. Take in consideration that, if a |
7a073300 GMF |
125 | DNS is given, the application pings all IPs in the look up table, however, if |
126 | IP is provide, it is the only which will be pinged. | |
48169a4b GMF |
127 | - port: when using a port based protocol, like TCP, this field specifies in |
128 | which port to ping the host. | |
6265d17e | 129 | - source-network-interface: the local network interface from where the ping |
51808da0 CH |
130 | packages for a given host will originate. To use the global network |
131 | interface, specify value as "default" | |
132 | - interval: the host will be pinged every "interval" seconds. Can be specified | |
133 | as fixed number (e.g. "30") or as a range (e.g. "30..60"), from which the | |
134 | interval will be picked at random (e.g. 42) at startup | |
42c9d872 | 135 | - ping-protocol: indicates which protocol to use to ping the destination host, |
e2a8862d CH |
136 | the currently supported protocols are TCP (tcp, tcp_ipv6) and ICMP (icmp, |
137 | icmpv6). | |
7a073300 | 138 | |
f9c5fff0 | 139 | |
e2a8862d | 140 | 4. Command line |
afdd699d GMF |
141 | ======================================= |
142 | The command line accepts the general configuration file options plus the | |
143 | following: | |
144 | - config-file: command line to specify a file where the hosts and other | |
145 | configuration information are provided. | |
078d3cca | 146 | - daemon: run the application as a daemon. |
3625c0e5 GMF |
147 | - log-level: apply a filter of which log messages will be printed. The available |
148 | options are the default Unix levels (e.g. debug, info, etc.). | |
e2a8862d CH |
149 | - log-output: select the place where the log messages will be printed. The |
150 | available options are CONSOLE, TERMINAL and SYSLOG. | |
afdd699d GMF |
151 | |
152 | ||
e2a8862d CH |
153 | 5. Tools |
154 | ======================================= | |
155 | Along with pingcheck, the binary feed_packet_data will be built but not copied | |
156 | like the pingcheck binary to the install location (you will find it in your | |
157 | build_directory/src/feed_packet_data). It allows direct access to the ICMP/TCP | |
158 | parser factories that interpret incoming network data. It can be fed data in | |
159 | pcap format or as raw binary data, either from file or stdin. | |
160 | ||
afdd699d | 161 | |
e2a8862d | 162 | 6. References |
f9c5fff0 GMF |
163 | ======================================= |
164 | [1] http://tools.ietf.org/html/rfc792 | |
165 | [2] http://en.wikipedia.org/wiki/Ping | |
166 | [3] http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol | |
e2a8862d CH |
167 | [4] http://en.wikipedia.org/wiki/ICMPv6 |
168 | [5] http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html | |
169 | [6] http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html | |
170 | [7] http://www.networkuptime.com/nmap/page4-5.shtml |