+ Table of Contents
+=======================================
+1. Introduction
+2. Building and Installing
+3. Configuration File
+4. Command line
+5. Tools
+6. References
+
+
-Code Conventions
+1. Introduction
=======================================
-This section describes the code conventions that must be followed when maintain
-this code.
+This application provides means to check the availability of remote hosts
+through pings to them.
+
+
+1.1. Rationale
+---------------------------------------
+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.
+
+
+1.2. How to use
+---------------------------------------
+There are many ways to invoke the application, the simplest is just type:
+ ./pingcheck
+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
+---------------------------------------
+Further information about the problem domain can be found in the References
+section.
-Data Types
+1.4. Legal Issues
---------------------------------------
+Most parts are licensed under the GPLv2 + linking exception.
+
+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:
-Use std::string to represent array of characters.
+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
-Use int32_t, int16_t and int8_t (and their unsigned couter parts) instead of
-int, short and char, respectively, when the variable or constant MUST have a
-specific size (e.g. like in the protocol headers). This documents that the
-variable have the given number of bits.
+The default install location is /usr/local, the easiest way to change this is
+through ccmake
-Use std::size_t for regular integer numbers that do not require any specific
-size. Thus leaving the size difinition to the platform.
\ No newline at end of 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. An example file is contained in the conf subdirectory.
+
+
+3.1. General
+---------------------------------------
+This configurations are shared among and affect all the hosts.
+- 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.
+- ping-fail-limit: percentage of pings to a host that can fail. If the
+ percentage of failed pings to a host exceed this number, then the host is
+ considered down.
+- status-notifier-cmd: the command line that is called when a host is down, or
+ up. Accepted variables are:
+ ${status} - down or up
+- link-up-interval: how long (in minutes) the pings must be returned with
+ 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.
+- 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.
+- 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).
+
+
+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.
+
+
+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://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