2 =======================================
11 =======================================
12 This application provides means to check the availability of remote hosts
13 through pings to them.
17 ---------------------------------------
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).
21 The host's address can be an IP or a DNS.
25 ---------------------------------------
26 There are many ways to invoke the application, the simplest is just type:
28 which uses the configuration values from the configuration file (described in
29 the Configuration File section).
31 Note: like the ordinary ping, pingcheck binary requires root privileges to
32 access control packets. You can run it from sudo:
35 sudo chown root:root pingcheck
36 sudo chmod u+s pingcheck
38 the last method is the common way to provide temporary root privileges for
43 ---------------------------------------
44 Further information about the problem domain can be found in the References
49 ---------------------------------------
50 Most parts are licensed under the GPLv2 + linking exception.
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.
57 =======================================
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
64 ---------------------------------------
65 This configurations are shared among and affect all the hosts.
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.
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.
73 You can use the nslookup <host> to figure out the nameserver.
74 - hosts-down-limit: an absolute number, which ranges from 0 to the number of
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.
77 - ping-fail-limit: percentage of pings to a host that can fail. If the
78 percentage of failed pings to a host exceed this number, then the host is
80 - status-notifier-cmd: the command line that is called when a host is down, or
81 up. Accepted variables are:
82 ${status} - down or up
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.
90 ---------------------------------------
91 - name: the DNS or IP of the host to ping. Take in consideration that, if a
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.
94 - port: when using a port based protocol, like TCP, this field specifies in
95 which port to ping the host.
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.
99 - interval: the host will be pinged every "interval" seconds.
100 - ping-protocol: indicates which protocol to use to ping the destination host,
101 the currently supported protocols are TCP (tcp, tcp_ipv6) and ICMP (icmp, icmpv6).
106 =======================================
107 The command line accepts the general configuration file options plus the
109 - config-file: command line to specify a file where the hosts and other
110 configuration information are provided.
111 - daemon: run the application as a daemon.
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.).
114 - log-output: select the place where the log messages will be printed. The available
115 options are CONSOLE, TERMINAL and SYSLOG.
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
126 [6] http://www.networkuptime.com/nmap/page4-5.shtml