Commit | Line | Data |
---|---|---|
f9c5fff0 GMF |
1 | Table of Contents |
2 | ======================================= | |
3 | 1. Introduction | |
afdd699d GMF |
4 | 2. Configuration File |
5 | 3. Command line | |
6 | 4. References | |
f9c5fff0 GMF |
7 | |
8 | ||
9 | ||
c08bc448 GMF |
10 | 1. Introduction |
11 | ======================================= | |
12 | This application provides means to check the availability of remote hosts | |
13 | through pings to them. | |
14 | ||
15 | ||
16 | 1.1. Rationale | |
17 | --------------------------------------- | |
a7d7778b GMF |
18 | The application uses ICMP echo requests messages, or TCP SYN segments, to |
19 | verify whether a given host is available (up) or not (down). | |
c08bc448 GMF |
20 | |
21 | The host's address can be an IP or a DNS. | |
22 | ||
23 | ||
24 | 1.2. How to use | |
25 | --------------------------------------- | |
26 | There are many ways to invoke the application, the simplest is just type: | |
aca0d1d7 | 27 | ./pingcheck |
12589451 | 28 | which uses the configuration values from the configuration file (described in |
f9c5fff0 | 29 | the Configuration File section). |
c08bc448 | 30 | |
48c8c5dc GMF |
31 | Note: like the ordinary ping, pingcheck binary requires root privileges to |
32 | access control packets. You can run it from sudo: | |
33 | sudo ./pingcheck | |
34 | or setuid: | |
35 | sudo chown root:root pingcheck | |
36 | sudo chmod u+s pingcheck | |
37 | ./pingcheck | |
38 | the last method is the common way to provide temporary root privileges for | |
39 | an executable. | |
40 | ||
703f4d65 | 41 | |
c08bc448 GMF |
42 | 1.3. Resources |
43 | --------------------------------------- | |
f9c5fff0 GMF |
44 | Further information about the problem domain can be found in the References |
45 | section. | |
46 | ||
47 | ||
48 | 1.4. Legal Issues | |
49 | --------------------------------------- | |
96d2fb59 | 50 | Most parts are licensed under the GPLv2 + linking exception. |
c08bc448 | 51 | |
12589451 GMF |
52 | The ICMP code, bost::net::dns and the "boost pinger" are licensed under the |
53 | boost license and include a note about this in the beginning of the source code. | |
c08bc448 GMF |
54 | |
55 | ||
afdd699d | 56 | 2. Configuration file |
c08bc448 | 57 | ======================================= |
12589451 GMF |
58 | In this section are described the configuration items, along with they possible |
59 | values and meanings. This section is organized in each major configuration | |
60 | block. | |
7a073300 GMF |
61 | |
62 | ||
afdd699d | 63 | 2.1. General |
7a073300 GMF |
64 | --------------------------------------- |
65 | This configurations are shared among and affect all the hosts. | |
6265d17e GMF |
66 | - default-source-network-interface: the local network interface from where the |
67 | ping packages will originate. If this configuration is present, all hosts | |
68 | will use this interface as source, otherwise, a per host source-network- | |
69 | interface must be provided. | |
61e224f8 GMF |
70 | - nameserver: the server which the hosts names will be resolved. It is the |
71 | lookup server which the application will query first. If left blank or omited, | |
72 | it will use the /etc/resolv.conf. | |
361552be | 73 | You can use the nslookup <host> to figure out the nameserver. |
a341119a | 74 | - hosts-down-limit: an absolute number, which ranges from 0 to the number of |
c5e4bfa1 GMF |
75 | hosts available. This value represents the minimum number of hosts that have |
76 | to fail (i.e. do not reply to the ping) in order to alert any external system. | |
a341119a | 77 | - ping-fail-limit: percentage of pings to a host that can fail. If the |
c5e4bfa1 GMF |
78 | percentage of failed pings to a host exceed this number, then the host is |
79 | considered down. | |
d52d036a | 80 | - status-notifier-cmd: the command line that is called when a host is down, or |
c1d76f1b GMF |
81 | up. Accepted variables are: |
82 | ${status} - down or up | |
1634f2a1 GMF |
83 | - link-up-interval: how long (in minutes) the pings must be returned with |
84 | success in order to consider the link up, or stable. | |
85 | - link-down-interval: how long (in minutes) the pings must fail, in order to the | |
86 | application consider the link down. | |
703f4d65 | 87 | |
703f4d65 | 88 | |
afdd699d | 89 | 2.2. Host |
7a073300 | 90 | --------------------------------------- |
d52d036a | 91 | - name: the DNS or IP of the host to ping. Take in consideration that, if a |
7a073300 GMF |
92 | DNS is given, the application pings all IPs in the look up table, however, if |
93 | IP is provide, it is the only which will be pinged. | |
48169a4b GMF |
94 | - port: when using a port based protocol, like TCP, this field specifies in |
95 | which port to ping the host. | |
6265d17e GMF |
96 | - source-network-interface: the local network interface from where the ping |
97 | packages for a given host will originate. This setting is used only if the | |
98 | global network interface was not provided. | |
d52d036a | 99 | - interval: the host will be pinged every "interval" seconds. |
42c9d872 | 100 | - ping-protocol: indicates which protocol to use to ping the destination host, |
59bbbed9 | 101 | the currently supported protocols are TCP (tcp, tcp_ipv6) and ICMP (icmp, icmpv6). |
7a073300 GMF |
102 | |
103 | ||
f9c5fff0 | 104 | |
afdd699d GMF |
105 | 3. Command line |
106 | ======================================= | |
107 | The command line accepts the general configuration file options plus the | |
108 | following: | |
109 | - config-file: command line to specify a file where the hosts and other | |
110 | configuration information are provided. | |
078d3cca | 111 | - daemon: run the application as a daemon. |
3625c0e5 GMF |
112 | - log-level: apply a filter of which log messages will be printed. The available |
113 | options are the default Unix levels (e.g. debug, info, etc.). | |
5ba17410 GMF |
114 | - log-output: select the place where the log messages will be printed. The available |
115 | options are CONSOLE, TERMINAL and SYSLOG. | |
afdd699d GMF |
116 | |
117 | ||
118 | ||
119 | 4. References | |
f9c5fff0 GMF |
120 | ======================================= |
121 | [1] http://tools.ietf.org/html/rfc792 | |
122 | [2] http://en.wikipedia.org/wiki/Ping | |
123 | [3] http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol | |
124 | [4] http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html | |
125 | [5] http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html | |
a7d7778b | 126 | [6] http://www.networkuptime.com/nmap/page4-5.shtml |