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 to verify if a given host
-is available or not.
+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.
---------------------------------------
There are many ways to invoke the application, the simplest is just type:
./pingcheck
-which uses the configuration values from the configuration file (describled in
+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 describled the configuration items, along with they
-possible values and meanings. This section is organized in each major
-configuration block.
+In this section are described the configuration items, along with they possible
+values and meanings. This section is organized in each major configuration
+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.
+ You can use the nslookup <host> to figure out the nameserver.
- hosts-down-limit: an absolute number, which ranges from 0 to the number of
hosts available. This value represents the minimum number of hosts that have
to fail (i.e. do not reply to the ping) in order to alert any external system.
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.
-- interval: the host will be pinged every "interval" seconds.
-
+- port: when using a port based protocol, like TCP, this field specifies in
+ which port to ping the host.
+- 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).
-3. Command line
+4. Command line
=======================================
The command line accepts the general configuration file options plus the
following:
- config-file: command line to specify a file where the hosts and other
configuration information are provided.
+- 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
+[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