Table of Contents
=======================================
1. Introduction
-2. Configuration File
-3. Command line
-4. References
+2. Building and Installing
+3. Configuration File
+4. Command line
+5. Tools
+6. References
1.1. Rationale
---------------------------------------
-The application uses ICMP echo requests messages, or TCP segments to verify
-whether a given host is available (up) or not (down).
+The application uses ICMP echo requests messages, or TCP SYN segments, to
+verify whether a given host is available (up) or not (down).
The host's address can be an IP or a DNS.
which uses the configuration values from the configuration file (described in
the Configuration File section).
+Note: like the ordinary ping, pingcheck binary requires root privileges to
+access control packets. You can run it from sudo:
+ sudo ./pingcheck
+or setuid:
+ sudo chown root:root pingcheck
+ sudo chmod u+s pingcheck
+ ./pingcheck
+the last method is the common way to provide temporary root privileges for
+an executable.
+
1.3. Resources
---------------------------------------
---------------------------------------
Most parts are licensed under the GPLv2 + linking exception.
-The ICMP code, bost::net::dns and the "boost pinger" are licensed under the
-boost license and include a note about this in the beginning of the source code.
+Parts of the ICMP code are based on the ping example found in the boost Asio
+documentation ((c) Christopher Kohlhoff) but are now heavily modified. The DNS
+resolver mechanism is based on boost::net::dns and is therefore licensed under
+the boost license. Notes about this are included in the beginning of the source
+code.
+
+
+2. Building and Installing
+=======================================
+After downloading the source code and necessary libraries (in particular boost)
+and tools (cmake) you should be able to do:
+
+me@my_linux_host ~/some/dir/pingcheck> mkdir build
+me@my_linux_host ~/some/dir/pingcheck> cd build
+me@my_linux_host ~/some/dir/pingcheck/build> ccmake ../
+ OR
+me@my_linux_host ~/some/dir/pingcheck/build> cmake ../
+me@my_linux_host ~/some/dir/pingcheck/build> make help # show more options
+me@my_linux_host ~/some/dir/pingcheck/build> make
+me@my_linux_host ~/some/dir/pingcheck/build> make check
+me@my_linux_host ~/some/dir/pingcheck/build> make install
+
+The default install location is /usr/local, the easiest way to change this is
+through ccmake
-2. Configuration file
+3. Configuration file
=======================================
In this section are described the configuration items, along with they possible
values and meanings. This section is organized in each major configuration
-block.
+block. An example file is contained in the conf subdirectory.
-2.1. General
+3.1. General
---------------------------------------
This configurations are shared among and affect all the hosts.
-- source-network-interface: the local network interface from where the ping
- packages with originate.
+- default-source-network-interface: the local network interface from where the
+ ping packages will originate. This option is used for those hosts that set
+ source-network-interface=default
- nameserver: the server which the hosts names will be resolved. It is the
lookup server which the application will query first. If left blank or omited,
it will use the /etc/resolv.conf.
success in order to consider the link up, or stable.
- link-down-interval: how long (in minutes) the pings must fail, in order to the
application consider the link down.
-
-
-2.2. Host
+- ratio-random-hosts: expects a value in [0,1]; if <1 will only use the given
+ ratio of hosts, selecting them at random
+- ping-reply-timeout: Amount of time to wait for an EchoReply to an Echo Request
+ before sending the next ping
+- max-address-resolution-attempts: For hosts given as DNS names, will first do
+ a DNS lookup to get corresponding IPs. This number specifies how often that is
+ attempted before declaring the host offline
+- resolved-ip-ttl-threshold: When the TTL for an IP falls below this threshold,
+ a new DNS lookup will be scheduled
+
+
+3.2. Host
---------------------------------------
+(All these settings must always be present!)
- name: the DNS or IP of the host to ping. Take in consideration that, if a
DNS is given, the application pings all IPs in the look up table, however, if
IP is provide, it is the only which will be pinged.
- port: when using a port based protocol, like TCP, this field specifies in
which port to ping the host.
-- interval: the host will be pinged every "interval" seconds.
+- source-network-interface: the local network interface from where the ping
+ packages for a given host will originate. To use the global network
+ interface, specify value as "default"
+- interval: the host will be pinged every "interval" seconds. Can be specified
+ as fixed number (e.g. "30") or as a range (e.g. "30..60"), from which the
+ interval will be picked at random (e.g. 42) at startup
- ping-protocol: indicates which protocol to use to ping the destination host,
- the currently supported protocols are TCP (tcp, tcp_ipv6) and ICMP (icmp, icmpv6).
+ the currently supported protocols are TCP (tcp, tcp_ipv6) and ICMP (icmp,
+ icmpv6).
-
-3. Command line
+4. Command line
=======================================
The command line accepts the general configuration file options plus the
following:
- daemon: run the application as a daemon.
- log-level: apply a filter of which log messages will be printed. The available
options are the default Unix levels (e.g. debug, info, etc.).
+- log-output: select the place where the log messages will be printed. The
+ available options are CONSOLE, TERMINAL and SYSLOG.
+
+5. Tools
+=======================================
+Along with pingcheck, the binary feed_packet_data will be built but not copied
+like the pingcheck binary to the install location (you will find it in your
+build_directory/src/feed_packet_data). It allows direct access to the ICMP/TCP
+parser factories that interpret incoming network data. It can be fed data in
+pcap format or as raw binary data, either from file or stdin.
-4. References
+6. References
=======================================
[1] http://tools.ietf.org/html/rfc792
[2] http://en.wikipedia.org/wiki/Ping
[3] http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol
-[4] http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html
-[5] http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html
-[6] http://www.networkuptime.com/nmap/page4-4.shtml
+[4] http://en.wikipedia.org/wiki/ICMPv6
+[5] http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html
+[6] http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html
+[7] http://www.networkuptime.com/nmap/page4-5.shtml
git://developer.intra2net.com / pingcheck / blobdiff