developer.intra2net.com Git - pingcheck/blob - Readme

   1      Table of Contents
   2 =======================================
   3 1. Introduction
   4 2. Code Conventions
   5 3. Source Code
   6 4. Configuration File
   7 5. References
   8
   9
  10
  11 1.   Introduction
  12 =======================================
  13 This application provides means to check the availability of remote hosts
  14 through pings to them.
  15
  16
  17 1.1. Rationale
  18 ---------------------------------------
  19 The application uses ICMP echo requests messages to verify if a given host
  20 is available or not.
  21
  22 The host's address can be an IP or a DNS.
  23
  24
  25 1.2. How to use
  26 ---------------------------------------
  27 There are many ways to invoke the application, the simplest is just type:
  28   ./libpingcheck
  29 which uses the configuration values from the configuration file (describled in
  30 the Configuration File section).
  31
  32
  33 1.3. Resources
  34 ---------------------------------------
  35 Further information about the problem domain can be found in the References
  36 section.
  37
  38
  39 1.4. Legal Issues
  40 ---------------------------------------
  41 All rights reserved to Intra2net AG.
  42
  43
  44
  45 2.   Code Conventions
  46 =======================================
  47 This section describes the code conventions that must be followed when maintain
  48 this code.
  49
  50
  51 2.1. Data Types
  52 ---------------------------------------
  53 This section is a guideline about the type you MUST use when declaring
  54 variables and constants. These types were chose to provide portability and
  55 improve code reradability.
  56
  57 - Use the std::string to represent array of characters.
  58
  59 - Use int32_t, int16_t and int8_t (or their unsigned couter parts) - instead of
  60   int, short and char, respectively - when the variable or constant MUST have a
  61   specific size (e.g. like in the protocol headers). This documents that the
  62   variable has the given number of bits. This states clear the intent of the
  63   original programmer and avoids improper modifications.
  64
  65 - Use only int for regular integer numbers that do not require any specific
  66   size. And document that a variable is non-negative using assertions. Do not
  67   use unsigned types to say a number will never be negative.
  68
  69 - Use std::size_t for integers that represent sizes of vectors, objects or
  70   buffers. Thus leaving the size difinition to the platform.
  71
  72
  73 2.2. Coding Style
  74 ---------------------------------------
  75 The coding style used in this program is in accordance with the Intra2net,
  76 which can be found in the following source:
  77
  78 - http://intranet/support_wiki/doku.php?id=entwicklung:codingstyle
  79
  80
  81 2.3. Versioning
  82 ---------------------------------------
  83 Version is built as follows:
  84   major.minor[-[a|b|rc]]
  85 where:
  86 - major represents big changes in application functionality.
  87 - minor means small changes of bug fixes.
  88 - a, b and rc stand for Alpha, Beta and Release Candidate respectivelly. Though
  89   they are optional and not required in public release.
  90
  91
  92 2.4. Error Handling
  93 ---------------------------------------
  94 There are two basic kinds of errors that shall happen in the program, errors
  95 that the program can recover (expected) and errors that the progam can not or
  96 should not recover from (exceptional errors). Bellow the description and the
  97 method adopted to deal with each one:
  98 - Expected: these errors can occur and must be handled by boolean return values.
  99   (i.e. if a host is down, if the address was not resolved). This errors can
 100   happen, but THE PROGRAM MUST CONTINUE TO OPERATE EVEN IF THEY HAPPEN.
 101 - Exceptional: these are the kinds of errors that should not occur. They must be
 102   handled by exceptions and THE PROGRAM MUST HALT IF THEY HAPPEN.
 103 Thus, to keep things as simple as possible, this program adopts just two kinds
 104 of error detection and handling:
 105 - Return Boolean Value for expected errors and
 106 - Handle Exceptions for exceptional errors.
 107
 108
 109 2.5. Assertions
 110 ---------------------------------------
 111 Also, it is good to use ASSERTS to document assumptions about:
 112 - method's argument values. If you expect that a parameter have certain values,
 113   assert it (preconditions)
 114 - and if you expect the method deliver a certain value, assert in the end of
 115   the method (postcondition).
 116 This is known by programming by contract.
 117
 118
 119
 120 3.   Source Code
 121 =======================================
 122 In this section is presented an overview of the source code and key design
 123 decisions.
 124
 125
 126 3.1. Main directories
 127 ---------------------------------------
 128 The sources are spread over these distincts directories:
 129 - src: contains the main application.
 130 - test: where is located the unit tests.
 131 - conf: keeps default and example configuration files.
 132
 133
 134 3.2. Main concept of application operation
 135 ---------------------------------------
 136 This application makes extensive use of asynchronous timers-handlers from
 137 Boost ASIO. So this section describes briefly how ASIO works. More information
 138 can be found in the References section.
 139
 140 The basic idea is to have a handler which will be called when a timer expires.
 141 After the timer expires, you have to schedule the timer again to call your
 142 handler once more. Given the declaration of the timer:
 143
 144     boost::asio::deadline_timer my_timer( my_io_service );
 145
 146 you must specify when it will expire:
 147
 148     my_timer.expires_at( some_time_in_seconds + seconds( interval_in_seconds ) );
 149
 150 and which method will handle when the timer expires.
 151
 152     my_timer.async_wait( boost::bind( &MyClass::my_handle_method, this ) );
 153
 154 Then, the my_io_service service can be called to perform a loop:
 155
 156     my_io_service.run();
 157
 158
 159
 160 4.   Configuration file
 161 =======================================
 162 In this section are describled the configuration items, along with they
 163 possible values and meanings. This section is organized in each major
 164 configuration block.
 165
 166
 167 4.1. General
 168 ---------------------------------------
 169 This configurations are shared among and affect all the hosts.
 170 - limit-hosts-down: an absolute number, which ranges from 0 to the number of
 171   hosts available. This value represents the minimum number of hosts that have
 172   to fail (i.e. do not reply to the ping) in order to alert any external system.
 173 - limit-ping-fail: percentage of pings to a host that can fail. If the
 174   percentage of failed pings to a host exceed this number, then the host is
 175   considered down.
 176
 177
 178 4.2. Host
 179 ---------------------------------------
 180 - address: the DNS or IP of the host to ping. Take in consideration that, if a
 181   DNS is given, the application pings all IPs in the look up table, however, if
 182   IP is provide, it is the only which will be pinged.
 183
 184
 185
 186 5.   References
 187 =======================================
 188 [1]  http://tools.ietf.org/html/rfc792
 189 [2]  http://en.wikipedia.org/wiki/Ping
 190 [3]  http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol
 191 [4]  http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html
 192 [5]  http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html