Table of Contents
=======================================
1. Introduction
-2. Code Conventions
-3. Source Code
-4. Configuration File
-5. 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.
1.2. How to use
---------------------------------------
There are many ways to invoke the application, the simplest is just type:
- ./libpingcheck
-which uses the configuration values from the configuration file (describled in
+ ./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
---------------------------------------
1.4. Legal Issues
---------------------------------------
-All rights reserved to Intra2net AG.
+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. Code Conventions
+2. Building and Installing
=======================================
-This section describes the code conventions that must be followed when maintain
-this code.
-
-
-2.1. Data Types
----------------------------------------
-This section is a guideline about the type you MUST use when declaring
-variables and constants. These types were chose to provide portability and
-improve code reradability.
-
-- Use the std::string to represent array of characters.
+After downloading the source code and necessary libraries (in particular boost)
+and tools (cmake) you should be able to do:
-- Use int32_t, int16_t and int8_t (or 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 has the given number of bits. This states clear the intent of the
- original programmer and avoids improper modifications.
-
-- Use int or uint for regular integer numbers that do not require any specific
- size.
-
-- Use std::size_t for integers that represent sizes of vectors, objects or
- buffers. Thus leaving the size difinition to the platform.
-
-
-2.2. Coding Style
----------------------------------------
-The coding style used in this program is in accordance with the Intra2net,
-which can be found in the following source:
+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
-- http://intranet/support_wiki/doku.php?id=entwicklung:codingstyle
+The default install location is /usr/local, the easiest way to change this is
+through ccmake
-2.3. Versioning
----------------------------------------
-Version is built as follows:
- major.minor[-[a|b|rc]]
-where:
-- major represents big changes in application functionality.
-- minor means small changes of bug fixes.
-- a, b and rc stand for Alpha, Beta and Release Candidate respectivelly. Though
- they are optional and not required in public release.
-
-
-
-3. Source Code
+3. Configuration file
=======================================
-In this section is presented an overview of the source code and key design
-decisions.
+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. Main directories
----------------------------------------
-The sources are spread over these distincts directories:
-- src: contains the main application.
-- test: where is located the unit tests.
-- conf: keeps default and example configuration files.
-
-
-3.2. Main concept of application operation
----------------------------------------
-This application makes extensive use of asynchronous timers-handlers from
-Boost ASIO. So this section describes briefly how ASIO works. More information
-can be found in the References section.
-
-The basic idea is to have a handler which will be called when a timer expires.
-After the timer expires, you have to schedule the timer again to call your
-handler once more. Given the declaration of the timer:
-
- boost::asio::deadline_timer my_timer( my_io_service );
-
-you must specify when it will expire:
-
- my_timer.expires_at( some_time_in_seconds + seconds( interval_in_seconds ) );
-
-and which method will handle when the timer expires.
-
- my_timer.async_wait( boost::bind( &MyClass::my_handle_method, this ) );
-
-Then, the my_io_service service can be called to perform a loop:
-
- my_io_service.run();
-
-
-
-4. 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.
-
-
-4.1. General
+3.1. General
---------------------------------------
This configurations are shared among and affect all the hosts.
-- limit-to-notify: range from 0 to the number of hosts available. This value
- represents minimum number of hosts that have to fail (i.e. do not reply the
- ping) in order to alert any external system.
-
-
-4.2. Host
+- 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
---------------------------------------
-- address: the DNS or IP of the host to ping. Take in consideration that, if a
+(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.
-
-5. 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