source: project/wiki/eggref/4/eping @ 30611

Last change on this file since 30611 was 30611, checked in by mikele, 7 years ago
File size: 9.9 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== eping
5
6eping is a Scheme implementation of the ICMP ping utility. Although it can be used like an average OS ping utility, eping is intended to be used programmatically (e.g. for gathering statistics, monitoring). It uses raw sockets thus a privileged account must be used.
7
8<enscript highlight=sh>
9[procedure] (eping HOST #!key (mode 'probe)
10                              (count #f)
11                              (timeout 1000)
12                              (interval 1000)
13                              (ttl 64)
14                              (tos 0)
15                              (dont-fragment #f)
16                              (src-addr #f)
17                              (id #f)
18                              (seq-start 0)
19                              (size 56)
20                              (pattern "")
21                              (recv-min #f)
22                              (lost-max #f)
23                              (cons-recv-min #f)
24                              (cons-lost-max #f)
25                              (msg1 "%i is alive\n")
26                              (msg2 "")
27                              (dotcols 0)
28                              (quiet #t))
29</enscript>
30
31HOST can be either an IPv4 address or a hostname: "192.168.1.1", "example.com", and even 'example.com are all valid hosts.
32
33eping supports four modes of operation: ''probe'' (default), ''stats'', ''dot'' and ''mtu''.
34
35=== Probe mode
36
37In this mode eping returns either true or false if it considers an host alive or unreachable respectively. The default behavior is to consider an host alive as soon as an echo reply is received. If no reply is received in ''count'' attempts (5 by default), the host is considered unreachable. Probe mode is the default one so it can be omitted as parameter.
38
39<enscript highlight=scheme>
40(eping "call-cc.org")
41
42===> #t
43</enscript>
44
45The aliveness criteria can be changed through the five parameters ''count'', ''recv-min'', ''lost-max'', ''cons-recv-min'', ''cons-lost-max'' (see "Parameters" section). As soon as one of these conditions is met eping returns the associated boolean value. If no condition is met in ''count'' attempts ''#f'' is returned.
46
47In non-quiet 'submode' a message is displayed.
48
49<enscript highlight=scheme>
50(eping "call-cc.org" quiet: #f)
51209.172.49.65 is alive
52</enscript>
53
54The output messages can be customized through the ''msg1'' and ''msg2'' parameters.
55
56=== Stats mode
57
58In stats mode eping returns a vector of statistics #(sent lost rtt-min rtt-avg rtt-max rtt-std). The rtt values are expressed in ''ms''.
59
60<enscript highlight=scheme>
61(eping "call-cc.org" mode: 'stats)
62
63===> #(5 0 133 134.2 136 0.92)
64</enscript>
65
66In non-quiet 'submode' the output resembles a standard ping utility:
67
68<enscript highlight=scheme>
69(eping "call-cc.org" mode: 'stats quiet: #f)
7064 bytes from 209.172.49.65: icmp_seq=0 ttl=52 time=139ms
7164 bytes from 209.172.49.65: icmp_seq=1 ttl=52 time=227ms
7264 bytes from 209.172.49.65: icmp_seq=2 ttl=52 time=135ms
7364 bytes from 209.172.49.65: icmp_seq=3 ttl=52 time=170ms
7464 bytes from 209.172.49.65: icmp_seq=4 ttl=52 time=256ms
75
76--- call-cc.org ping statistics ---
775 packets transmitted, 5 packets received, 0% packet loss
78round-trip min/avg/max/stddev = 135.0/185.4/256.0/48.26 ms
79</enscript>
80
81Ctrl-\ (SIGQUIT) can be used to print partial statistics without halting the ping (POSIX platforms only). Ctrl-C can be used to stop and collect the statistics at any moment.
82
83By default 5 packets are sent. The ''count'' option can be used to change this value (0 meaning non-stop operation).
84
85=== Dot mode
86
87In this mode eping returns a single character for each echo request:
88
89 [.] Echo reply received
90 [!] No response
91 [N] Network unreachable
92 [H] Host unreachable
93 [P] Protocol unreachable
94 [F] Packet too big and DF bit set
95 [A] Administratively filtered
96 [T] Time to live exceeded
97 [O] Network/Host unreachable for TOS
98 [U] Unreachable (generic error)
99
100<enscript highlight=scheme>
101(eping "call-cc.org" mode: 'dot quiet: #f timeout: 134 count: 20)
102..!...!....!.!!!....
103</enscript>
104
105The ''dotcols'' parameter can be used to set the number of chars to be printed before a newline. The default behavior (0) inserts a newline only after the last echo request.
106
107<enscript highlight=scheme>
108(eping "call-cc.org mode": 'dot quiet: #f timeout: 134 count: 20 dotcols: 5)
109!...!
110....!
111...!.
112!....
113</enscript>
114
115In quiet 'submode' a string built from the generated characters is returned.
116
117<enscript highlight=scheme>
118(eping "call-cc.org" mode: 'dot count: 3)
119
120===> "..."
121</enscript>
122
123=== MTU mode
124
125In mtu mode eping attempts to discover the MTU along the path. To speed up the process it is advisable to lower the default 1000''ms'' echo requests interval time (''interval'' option).
126
127<enscript highlight=scheme>
128(eping "call-cc.org" mode: 'mtu interval: 250)
129
130===> 1492
131</enscript>
132
133Lossy links may slow down or even prevent the convergence. The ''count'' option can be used to increase the number of attempts (default is 64). If the mtu can't be computed #f is returned.
134
135=== Parameters
136
137==== General
138
139* '''count''' The number of echo requests to be sent. The default is 5 for modes
140  other than ''mtu'' and 64 for ''mtu'' mode. If set to 0 echo requests are sent
141  until a probe condition is met (''probe'' mode), mtu is computed (''mtu'' mode)
142  or SIGINT (Ctrl-C) is received (all modes).
143
144* '''timeout''' The amount of time in ''ms'' to let pass before considering an host
145  unreachable (default is 1000ms).
146
147* '''interval''' The interval in ''ms'' between echo requests (default is
148  1000ms). This value can't be set lower than ''timeout'' (this rule is enforced
149  lowering ''timeout'' in case).
150
151==== IP
152
153* '''ttl''' / '''tos''' Respectively the Time To Live and TOS in the IP header.
154
155* '''dont-fragment''' Sets the Don't Fragment (DF) flag in the IP header.
156
157* '''src-addr''' Binds the ICMP socket to a specific IP address.
158
159==== ICMP
160
161* '''size''' The ICMP payload size.
162
163* '''pattern''' A string used to fill the payload (repeated if necessary).
164
165* '''id''' The Identifier field (0-65535). By default it is generated randomly
166  for every invocation of the eping function.
167
168* '''seq-start''' The initial sequence of the echo requests (0 by default).
169
170==== Probing
171
172* '''recv-min''' Minimum number of received replies before considering an host
173  alive.
174
175* '''lost-max''' Maximum number of missed replies before considering an host
176  unreachable.
177
178* '''cons-recv-min''' Minimum number of consecutive received replies before
179  considering an host alive.
180
181* '''cons-lost-max'''  Maximum number of consecutive missed replies before
182  considering an host unreachable.
183
184==== Output
185
186* '''msg1''' The message displayed when an host is considered alive. The default
187  message is "%i is alive\n" where %i is expanded to the IP address of the host.
188  Similarly %h is interpreted as the hostname.
189
190* '''msg2'''  The message displayed when an host is considered unreachable. By
191  default it is an empty string.
192
193* '''dotcols''' In ''dot'' mode the number of displayed chars before a newline is
194  inserted. By default (0) a newline is inserted only after the last displayed
195  char.
196
197* '''quiet''' By default eping doesn't display anything unless this option is set
198  to ''#f''.
199
200=== Requirements
201
202[[socket]] (>= 0.2.4)
203
204=== Installation
205
206<enscript highlight=bash>
207$ chicken-install eping
208</enscript>
209
210A command-line application is also available:
211
212<enscript highlight=sh>
213$ chicken-install -r eping
214$ cd eping/app
215$ make
216$ ./eping
217eping HOST [-mode probe|stats|dot|mtu]
218           [-count COUNT]
219           [-interval INTERVAL]
220           [-timeout TIMEOUT]
221           [-ttl TTL]
222           [-tos TOS]
223           [-src-addr IP]
224           [-dont-fragment]
225           [-id ID]
226           [-seq-start SEQ]
227           [-size SIZE]
228           [-pattern PATTERN]
229           [-recv-min RMIN]
230           [-lost-max LMAX]
231           [-cons-recv-min CRMIN]
232           [-cons-lost-max CLMAX]
233           [-msg1 MSG1]
234           [-msg2 MSG2]
235           [-dotcols COLS]
236           [-quiet]
237           [-version]
238</enscript>
239
240=== Usage
241
242<enscript highlight=scheme>
243(use eping)
244</enscript>
245
246=== Todo/Wishlist
247
248* hop count mode
249* pattern matching
250* traceroute mode?
251* tcp/udp support?
252* ipv6?
253
254=== About this egg
255
256The source code is hosted at [[https://bitbucket.org/miklam/eping/|Bitbucket]]. Feel free to send pull requests or open an issue there. Alternatively, send an e-mail to the [[mailto://chicken-users@nongnu.org|chicken-users]] mailing list for information or requests.
257
258==== Version History
259
260; 1.0 : Initial release
261
262==== Author
263
264Michele La Monaca
265
266==== License
267
268 Copyright (c) 2013
269 Michele La Monaca (eping@lamonaca.net)
270 All rights reserved.
271 
272 Redistribution and use in source and binary forms, with or without
273 modification, are permitted provided that the following conditions are
274 met:
275 
276 1) Redistributions of source code must retain the above copyright
277 notice, this list of conditions and the following disclaimer.
278 
279 2) Redistributions in binary form must reproduce the above copyright
280 notice, this list of conditions and the following disclaimer in the
281 documentation and/or other materials provided with the distribution.
282 
283 3) Neither the name of the author nor the names of its contributors
284 may be used to endorse or promote products derived from this software
285 without specific prior written permission.
286 
287 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
288 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
289 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
290 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
291 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
292 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
293 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
294 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
295 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
296 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
297 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
298 OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.