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.
-
-- 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.
+After downloading the source code and necessary libraries (in particular boost)
+and tools (cmake) you should be able to do:
-- Use only int for regular integer numbers that do not require any specific
- size. And document that a variable is non-negative using assertions. Do not
- use unsigned types to say a number will never be negative.
+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 std::size_t for integers that represent sizes of vectors, objects or
- buffers. Thus leaving the size difinition to the platform.
+The default install location is /usr/local, the easiest way to change this is
+through ccmake
-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:
-
-- http://intranet/support_wiki/doku.php?id=entwicklung:codingstyle
-
-
-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.
-
-
-2.4. Error Handling
----------------------------------------
-There are two basic kinds of errors that shall happen in the program, errors
-that the program can recover (expected) and errors that the progam can not or
-should not recover from (exceptional errors). Bellow the description and the
-method adopted to deal with each one:
-- Expected: these errors can occur and must be handled by boolean return values.
- (i.e. if a host is down, if the address was not resolved). This errors can
- happen, but THE PROGRAM MUST CONTINUE TO OPERATE EVEN IF THEY HAPPEN.
-- Exceptional: these are the kinds of errors that should not occur. They must be
- handled by exceptions and THE PROGRAM MUST HALT IF THEY HAPPEN.
-Thus, to keep things as simple as possible, this program adopts just two kinds
-of error detection and handling:
-- Return Boolean Value for expected errors and
-- Handle Exceptions for exceptional errors.
-
-
-2.5. Assertions
----------------------------------------
-Also, it is good to use ASSERTS to document assumptions about:
-- method's argument values. If you expect that a parameter have certain values,
- assert it (preconditions)
-- and if you expect the method deliver a certain value, assert in the end of
- the method (postcondition).
-This is known by programming by contract.
-
-
-
-3. Source Code
+3. Configuration file
=======================================
-In this section is presented an overview of the source code and key design
-decisions.
-
-
-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.
+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.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-hosts-down: an absolute number, which ranges from 0 to the number of
+- 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.
-- limit-ping-fail: percentage of pings to a host that can fail. If the
+- 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.
-
-
-4.2. Host
+- 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