Commit | Line | Data |
---|---|---|
f9c5fff0 GMF |
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 | ||
c08bc448 GMF |
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 | |
f9c5fff0 | 30 | the Configuration File section). |
c08bc448 | 31 | |
703f4d65 | 32 | |
c08bc448 GMF |
33 | 1.3. Resources |
34 | --------------------------------------- | |
f9c5fff0 GMF |
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. | |
c08bc448 GMF |
42 | |
43 | ||
44 | ||
45 | 2. Code Conventions | |
703f4d65 GMF |
46 | ======================================= |
47 | This section describes the code conventions that must be followed when maintain | |
48 | this code. | |
49 | ||
50 | ||
c08bc448 GMF |
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 | ||
fc444c5a GMF |
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. | |
c08bc448 GMF |
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 | |
703f4d65 | 74 | --------------------------------------- |
c08bc448 GMF |
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 | ||
09de3c4b GMF |
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 | ||
c5e4bfa1 GMF |
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 | ||
703f4d65 | 119 | |
c08bc448 GMF |
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 | ||
f9c5fff0 GMF |
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 | ||
c08bc448 GMF |
159 | |
160 | 4. Configuration file | |
161 | ======================================= | |
f9c5fff0 | 162 | In this section are describled the configuration items, along with they |
7a073300 GMF |
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. | |
c5e4bfa1 GMF |
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. | |
d52d036a GMF |
176 | - status-notifier-cmd: the command line that is called when a host is down, or |
177 | up. Accepted variables are ${host}, ${status} | |
703f4d65 | 178 | |
703f4d65 | 179 | |
7a073300 GMF |
180 | 4.2. Host |
181 | --------------------------------------- | |
d52d036a | 182 | - name: the DNS or IP of the host to ping. Take in consideration that, if a |
7a073300 GMF |
183 | DNS is given, the application pings all IPs in the look up table, however, if |
184 | IP is provide, it is the only which will be pinged. | |
d52d036a | 185 | - interval: the host will be pinged every "interval" seconds. |
7a073300 GMF |
186 | |
187 | ||
f9c5fff0 GMF |
188 | |
189 | 5. References | |
190 | ======================================= | |
191 | [1] http://tools.ietf.org/html/rfc792 | |
192 | [2] http://en.wikipedia.org/wiki/Ping | |
193 | [3] http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol | |
194 | [4] http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html | |
195 | [5] http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html |