2 =======================================
4 2. Building and Installing
13 =======================================
14 This application provides means to check the availability of remote hosts
15 through pings to them.
19 ---------------------------------------
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).
23 The host's address can be an IP or a DNS.
27 ---------------------------------------
28 There are many ways to invoke the application, the simplest is just type:
30 which uses the configuration values from the configuration file (described in
31 the Configuration File section).
33 Note: like the ordinary ping, pingcheck binary requires root privileges to
34 access control packets. You can run it from sudo:
37 sudo chown root:root pingcheck
38 sudo chmod u+s pingcheck
40 the last method is the common way to provide temporary root privileges for
45 ---------------------------------------
46 Further information about the problem domain can be found in the References
51 ---------------------------------------
52 Most parts are licensed under the GPLv2 + linking exception.
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
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:
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 ../
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
76 The default install location is /usr/local, the easiest way to change this is
81 =======================================
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
84 block. An example file is contained in the conf subdirectory.
88 ---------------------------------------
89 This configurations are shared among and affect all the hosts.
90 - default-source-network-interface: the local network interface from where the
91 ping packages will originate. This option is used for those hosts that set
92 source-network-interface=default
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.
96 You can use the nslookup <host> to figure out the nameserver.
97 - hosts-down-limit: an absolute number, which ranges from 0 to the number of
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.
100 - ping-fail-limit: percentage of pings to a host that can fail. If the
101 percentage of failed pings to a host exceed this number, then the host is
103 - status-notifier-cmd: the command line that is called when a host is down, or
104 up. Accepted variables are:
105 ${status} - down or up
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.
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
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
122 ---------------------------------------
123 (All these settings must always be present!)
124 - name: the DNS or IP of the host to ping. Take in consideration that, if a
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.
127 - port: when using a port based protocol, like TCP, this field specifies in
128 which port to ping the host.
129 - source-network-interface: the local network interface from where the ping
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
135 - ping-protocol: indicates which protocol to use to ping the destination host,
136 the currently supported protocols are TCP (tcp, tcp_ipv6) and ICMP (icmp,
141 =======================================
142 The command line accepts the general configuration file options plus the
144 - config-file: command line to specify a file where the hosts and other
145 configuration information are provided.
146 - daemon: run the application as a daemon.
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.).
149 - log-output: select the place where the log messages will be printed. The
150 available options are CONSOLE, TERMINAL and SYSLOG.
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.
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
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