1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15">
<title>Udpcast commandline options</title>
</head>
<body>
<h1>Udpcast commandline options</h1>
<p>This page describes the options for the command line versions of
udpcast. The commandline version of udpcast is 100% compatible with
the boot disk version. You can for instance start the sender from the
bootdisk, but have a receiver run from commandline on the fileserver,
in order to get an archive copy of the sender's disk image. Later you
may start a commandline sender on the fileserver, and bootdisk
receivers on the client boxes, in order to restore their image from
the archived copy. Of course, you may also directly udpcast an image
from a master client to copies, in this case bother sender and
receiver would run from the boot disk.</p>
<p>The boot disk version's menues only give access to the most common
command line option (file name and pipe mode (compressions)). In order
to access the other options, use the "<tt>Additional parameters</tt>"
dialog box to enter them, just like you would type them into a shell
window.</p>
<h1>Udp-sender</h1>
<!--
UDPSENDER
-->
<!-- =cont -->
<!-- =section udp-sender SEE ALSO -->
<!-- =text udp-receiver -->
<!-- =section udp-sender DESCRIPTION -->
<p><tt>Udp-sender</tt> is used to broadcast a file (for instance a disk
image) to multiple <tt>udp-receivers</tt> on the local LAN. In order
to do this, it uses Ethernet multicast or broadcast, so that all
receivers profit from the same physical datastream. Thus, sending to
10 destinations does not take more time than it would take to send
just 2.</p>
<!-- =section udp-sender OPTIONS -->
<h2>Basic options</h2>
<dl>
<dt>--file <i>file</i></dt>
<dd>Reads data to be transmitted from <i>file</i>. If this parameter
is not supplied, data to be transmitted is read from stdin instead.</dd>
<dt>--pipe <i>command</i></dt>
<dd>Sends data through <i>pipe</i> before transmitting it. This is
useful for compressing/decompressing it, or for stripping out unused
blocks. The <i>command</i> gets a direct handle on the input file or
device, and thus may seek inside it, if needed. <tt>Udpcast</tt>
itself also keeps a handle on the file, which is used for an informal
progress display. The <i>command</i>'s stdout is a pipe to udpcast.</dd>
<dt>--autostart <i>n</i></dt>
<dd>Starts transmission after <i>n</i> retransmissions of hello
packet, without waiting for a key stroke. Useful for unattended
operation, where udp-sender is started from a cron-job for a
broadcast/multicast at a scheduled time.</dd>
</dl>
<h2>Networking options</h2>
<p>The following networking options should be supplied both on the sender
and the receivers:</p>
<dl>
<dt>--portbase <i>portbase</i></dt>
<dd>Default ports to use for udpcast. Two ports are used:
<i>portbase</i> and <i>portbase+1</i> . Thus, <i>Portbase</i> must be
even. Default is <tt>9000</tt>. The same <i>portbase</i> must be
specified for both <tt>udp-sender</tt> and <tt>udp-receiver</tt>.</dd>
<dt>--interface <i>interface</i></dt>
<dd>Network interface used to send out the data. Default is <tt>eth0</tt></dd>
<dt>--ttl <i>time to live</i></dt>
<dd>Sets the <i>time-to-live</i> parameter for the multicast
packets. Should theoretically allow to use UDPCast beyond the local
network, but not tested for lack of a multicast router.</dd>
<dt>--mcast-rdv-address <i>address</i></dt>
<dd><p>Uses a non-standard multicast address for the control
(rendez-vous) connection. This address is used by the sender and
receivers to "find" each other. This is <b>not</b> the address that is
used to transfer the actual data.</p>
<p>By default <tt>mcast-rdv-address</tt> is the Ethernet broadcast address
if <tt>ttl</tt> is 1, and <tt>224.0.0.1</tt> otherwise. This setting
should not be used except in very special situations, such as when
<tt>224.0.0.1</tt> cannot be used for policy reasons.</p></dd>
</dl>
<p>The following networking options should be supplied only on the sender:</p>
<dl>
<dt>--mcast-data-address <i>address</i></dt>
<dd>Uses the given address for multicasting the data. If not
specified, the program will automatically derive a multicast address
from its own IP (by keeping the last 27 bits of the IP and then
prepending 232).</dd>
<dt>--pointopoint</dt>
<dd>Point-to-point mode. Only a single receiver is allowed, but the
data will be directly send to this receiver (in unicast mode), rather
than multicast/broadcast all over the place. If no async mode is
chosen, and there happens to be only one receiver, point-to-point is
activated automatically.</dd>
<dt>--nopointopoint</dt>
<dd>Don't use point-to-point, even if there is only one single
receiver.</dd>
<dt>--full-duplex</dt>
<dd><p>Use this option if you use a full-duplex network. T-base-10 or 100
is full duplex if equipped with a switch. Hub based networks, or
T-base-2 networks (coaxial cable) are only <b>half-duplex</b> and you
should not use this option with these networks, or else you may
experience a 10% performance hit.</p>
<p>N.B. On high-latency WAN links, the full-duplex option can lead to
substantial performance improvements, because it allows udp-sender to
send more data while it is still waiting for the previous batch to get
acknowledged.</p></dd>
<dt>--half-duplex</dt>
<dd>Use half duplex mode (needed for Hub based or T-base-2
networks). This is the default behavior in this version of
udpcast.</dd>
<dt>--broadcast</dt>
<dd><p>Use Ethernet broadcast, rather than multicast. Useful if you have
Ethernet cards which don't support multicast.</p>
<p>By default, <tt>udpcast</tt> uses multicast. This allows sending the
data only to those receivers that requested it. Ethernet cards of
machines which <i>don't</i> participate in the transmission
automatically block out the packets at the hardware level. Moreover,
network switches are able to selectively transmit the packets only to
those network ports to which receivers are connected. Both features
thus allow a much more efficient operation than broadcast. This option
should only be supplied on the sender.</p></dd>
<dt>-b <em>blocksize</em></dt>
<dd>Choses the packet size. Default (and also maximum) is 1456.</dd>
</dl>
<h2>Unidirectional mode (without return channel)</h2>
<p>The options described below are useful in situations where no "return
channel" is available, or where such a channel is impractical due to
high latency. In an unidirectional setup (i.e. without return
channel), the sender only sends data but doesn't expect any reply from
the receiver.</p>
<p>Unidirectional options must be used together, or else the transfer
will not work correctly. You may for example use the following command
line:</p>
<p><tt>udp-sender --async --max-bitrate 10m --fec 8x8</tt></p>
<dl>
<dt>--async</dt>
<dd>Asynchronous mode. Do not request confirmations from
the receiver. Best used together with forward error correction and
bandwidth limitation, or else the receiver will abort the reception as
soon as it misses a packet. When the receiver aborts the reception in
such a way, it will print a list of packets lost in the slice causing
the problem. You can use this list to <a href="#fectune">tune the
forward error correction parameters</a>.</dd>
<dt>--max-bitrate <i>bitrate</i></dt>
<dd>Limits bandwidth used by udpcast. Useful in asynchronous mode, or
else the sender may send too fast for the switch and/or receiver to
keep up. Bitrate may be expressed in bits per second (<tt>--bitrate
5000000</tt>), kilobits per second (<tt>--bitrate 5000k</tt>) or
megabits per second (<tt>--bitrate 5m</tt>). This is the raw bitrate,
including packet headers, forward error correction, retransmissions,
etc. Actual payload bitrate will be lower.</dd>
<dt>--fec <i>interleave<tt>x</tt>redundancy<tt>/</tt>stripesize</i></dt>
<dd><p>Enables forward error correction. The goal of forward error
correction is to transmit redundant data, in order to make up for
packets lost in transit. Indeed, in unidirectional mode, the receivers
have no way of requesting retransmission of lost packets, thus the
only way to address packet loss is to include redundant information to
begin with. The algorithm is designed in such a way that if <i>r</i>
redundant packets are transmitted, that those can be used to
compensate for the loss of <i>any</i> r packets in the same FEC group
(stripe).</p>
<p>In order to increase robustness of the FEC algorithm against burst
packet losses, each <i>slice</i> is divided in <i>interleave</i>
stripes. Each stripe has <i>stripesize</i> blocks (if not specified,
stripesize is calculated by diving <i>slice-size</i> by
<i>interleave</i>). For each stripe, <i>redundancy</i> FEC packets are
added. Stripes are organized in such a fashion that consecutive
packets belong to different stripes. This way, we ensure that burst
losses affect different stripes, rather than using all FEC packets of
a single stripe. Example: <tt>--fec 8x8/128</tt></p></dd>
<dt>--rate-governor <i>module.so:key1=value1,key2=value2</i></dt>
<dd><p>Applies a dynamically loadable rate governor. <i>module.so</i> is
the name of the preloadable module, which is followed by a number of
property assignments (<i>key1=value1</i>). The rate governor controls
the transmission rate according to various criteria, such as
congestion information received from a routing or encapsulating
device. See comments in <tt>/usr/include/udpcast/rateGovernor.h</tt>
and example in <tt>examples/rateGovernor</tt> for more details</p></dd>
<dt>--rexmit-hello-interval <i>timeout</i></dt>
<dd><p>If set, rebroadcasts the HELLO packet used for initiating the
casting each <i>timeout</i> milliseconds.</p>
<p>This option is useful together with <i>asyc mode</i>, because with
async mode the receiver won't send a connection request to the sender
(and hence won't get a connection reply). In <i>async mode</i>, the
receivers get all needed information from the <i>hello</i> packet
instead, and are thus particularly dependant on the reception of this
packet, makeing retransmission useful.</p>
<p>This option is also useful on networks where packet loss is so high
that even with connection requests, sender and receiver would not find
each other otherwise.</p></dd>
<dt>--retries-until-drop <i>retries</i></dt>
<dd>How many time to send a REQACK until dropping a receiver. Lower
retrycounts make <tt>udp-sender</tt> faster to react to crashed
receivers, but they also increase the probability of false alerts
(dropping receivers that are not actually crashed, but merely slow to
respond for whatever reason)</dd>
<dt>--streaming</dt>
<dd>Allows receivers to join an ongoing transmission mid through</dd>
</dl>
<h2>Keyboardless mode</h2>
The options below help to run a sender in unattended mode.
<dl>
<dt>--min-receivers <i>n</i></dt>
<dd>Automatically start as soon as a minimal number of receivers have
connected.</dd>
<dt>--min-wait <i>t</i></dt>
<dd>Even when the necessary amount of receivers <i>do</i> have
connected, still wait until <i>t</i> seconds since first receiver
connection have passed.</dd>
<dt>--max-wait <i>t</i></dt>
<dd>When not enough receivers have connected (but at least one), start
anyways when <i>t</i> seconds since first receiver connection have
pased.</dd>
<dt>--nokbd</dt>
<dd>Do not read start signal from keyboard, and do not display any
message telling the user to press any key to start.</dd>
<dt>--start-timeout sec</dt>
<dd>sender aborts at start if it doesn't see a receiver within this
many seconds. Furthermore, transmission of data needs to start within
this delay. Once transmission is started, the timeout no longer
applies.</dd>
<dt>--daemon-mode</dt>
<dd>Do not exit when done, but instead wait for the next batch of
receivers.</dd>
</dl>
<p>Example:</p>
<p><tt>udp-sender -f zozo --min-receivers 5 --min-wait 20 --max-wait 80</tt></p>
<ul>
<li>If one receiver connects at 18h00.00, and 4 more within the next 5
minutes, start at 18h00.20. (5 receivers connected, but min-wait not
yet pased)</li>
<li>If one receiver connects at 18h00.00, and 3 more within the next 5
minutes, then a last one at 18h00.25, start right after.</li>
<li>If one receiver connects at 18h00.00, then 3 more within the next
15 minutes, then no one, start at 18h01.20. (not enough receivers, but
we start anyways after max-wait).</li>
</ul>
<h2>Logging and statistics options</h2>
The options instruct <tt>udp-sender</tt> to log some additional
statistics to a file:
<dl>
<dt>--stat-period <i>seconds</i></dt>
<dd>Every so much milliseconds, print some statistics to stderr: how
much bytes sent so far log, position in uncompressed file (if
applicable), retransmit count... By default, this is printed every
half second.</dd>
<dt> --print-uncompressed-position <i>flag</i></dt>
<dd>By default, udp-sender only prints the position in uncompressed
file if the 2 following conditions are met:
<ul>
<li>Input is piped via a compressor (<tt>-p </tt> option).</li>
<li>The primary input is seekable (file or device)</li>
</ul>
With the <tt>--print-uncompressed-position</tt>, options, you can
change this behavior:
<ul>
<li>If flag is 0, uncompressed position will <b>never</b> be printed,
even if above conditions are met</li>
<li>If flag is 1, uncompressed position will <b>always</b> be
printed, even if above conditions are <b>not</b> met</li>
</ul></dd>
<dt>--log <i>file</i></dt>
<dd>Logs some stuff into <i>file</i>.</dd>
<dt>--bw-period <i>seconds</i></dt>
<dd>Every so much seconds, log instantenous bandwidth seen during that
period. Note: this is different from the bandwidth displayed to stderr
of the receiver, which is the <em>average</em> since start of
transmission.</dd>
</dl>
<!--
UDPRECEIVER
-->
<h1>Udp-receiver</h1>
<!-- =cont -->
<p><tt>Udp-receiver</tt> is used to receive files sent by
<tt>udp-sender</tt> (for instance a disk image).</p>
<!-- =section udp-receiver OPTIONS -->
<h2>Basic options</h2>
<dl>
<dt>--file <i>file</i></dt>
<dd>Writes received data to <i>file</i>. If this parameter is not
supplied, received data is written to stdout instead.</dd>
<dt>--pipe <i>command</i></dt>
<dd>Sends data through <i>pipe</i> after receiving it. This is useful
for decompressing the data, or for filling in unused filesystem blocks
that may have been stripped out by udp-sender. The <i>command</i> gets
a direct handle on the output file or device, and thus may seek inside
it, if needed. <tt>Udpcast</tt> itself also keeps a handle on the
file, which is used for an informational progress display. The
<i>command</i>'s stdin is a pipe from udp-receiver. Example:
<tt>udp-receiver -p "gzip -dc"</tt></dd>
<dt>--log <i>file</i></dt>
<dd>Logs some stuff into <i>file</i>.</dd>
<dt>--nosync</dt>
<dd>Do not open target in synchronous mode. This is the default when writing to a file or a pipe.</dd>
<dt>--sync</dt>
<dd>Write to target in synchronous mode. This is the default when writing to a device (character or block)</dd>
<dt>--nokbd</dt>
<dd>Do not read start signal from keyboard, and do not display any
message telling the user to press any key to start.</dd>
<dt>--start-timeout sec</dt>
<dd>receiver aborts at start if it doesn't see a sender within this many
seconds. Furthermore, the sender needs to start transmission of data within
this delay. Once transmission is started, the timeout no longer applies.</dd>
</dl>
<h2>Networking options</h2>
<dl>
<dt>--portbase <i>portbase</i></dt>
<dd>Default ports to use for udpcast. Two ports are used:
<i>portbase</i> and <i>portbase+1</i> . Thus, <i>Portbase</i> must be
even. Default is <tt>9000</tt>. The same <i>portbase</i> must be
specified for both <tt>udp-sender</tt> and <tt>udp-receiver</tt>.</dd>
<dt>--interface <i>interface</i></dt>
<dd>Network interface used to send out the data. Default is <tt>eth0</tt></dd>
<dt>--ttl <i>ttl</i></dt>
<dd>Time to live for connection request packet (by default connection
request is broadcast to the LAN's broadcast address. If ttl is set,
the connection request is multicast instead to <tt>224.0.0.1</tt> with
the given ttl, which should enable udpcast to work between LANs. Not
tested though.</dd>
<dt>--mcast-rdv-address <i>address</i></dt>
<dd>Uses a non-standard multicast address for the control connection
(which is used by the sender and receivers to "find" each other). This
is <b>not</b> the address that is used to transfer the data. By
default <tt>mcast-rdv-address</tt> is the Ethernet broadcast address if
<tt>ttl</tt> is 1, and <tt>224.0.0.1</tt> otherwise. This setting
should not be used except in very special situations, such as when
<tt>224.0.0.1</tt> cannot be used for policy reasons.</dd>
<dt>--exit-wait <i>milliseconds</i></dt>
<dd>When transmission is over, receiver will wait for this time after
receiving the final REQACK. This is done in order to guard against
loss of the final ACK. Is 500 milliseconds by default.</dd>
<dt>--ignore-lost-data</dt>
<dd>Do not stop reception when data loss is detected, but instead fill
with random data. This is useful for multimedia transmission where
100% integrity is not need.</dd>
</dl>
<h2>Statistics options</h2>
<dl>
<dt>--stat-period <i>seconds</i></dt>
<dd>Every so much milliseconds, print some statistics to stderr: how
much bytes received so far log, position in uncompressed file (if
applicable), overall bitrate... By default, this is printed every
half second.</dd>
<dt> --print-uncompressed-position <i>flag</i></dt>
<dd>By default, udp-receiver only prints the position in uncompressed file
if the 2 following conditions are met:
<ul>
<li>Output is piped via a compressor (<tt>-p </tt> option).</li>
<li>The final output is seekable (file or device)</li>
</ul>
With the <tt>--print-uncompressed-position</tt>, options, you can
change this behavior:
<ul>
<li>If flag is 0, uncompressed position will <b>never</b> be printed,
even if above conditions are met</li>
<li>If flag is 1, uncompressed position will <b>always</b> be
printed, even if above conditions are <b>not</b> met</li>
</ul></dd>
</dl>
<!-- =section udp-sender OPTIONS -->
<h2>Tuning options (sender)</h2>
<p>The following tuning options are all about slice size. Udpcast groups
its data in <i>slices</i>, which are a series of blocks (UDP
packets). These groups are relevant for</p>
<ul>
<li>data retransmission: after each slice, the server asks the
receivers whether they have received all blocks, and if needed retransmits
what has been missing</li>
<li>forward error correction: each slice has its set of data blocks, and
matching FEC blocks.</li>
</ul>
<dl>
<dt>--min-slice-size <i>size</i></dt>
<dd>minimum slice size (expressed in blocks). Default is 16. When
dynamically adjusting slice size (only in non-duplex mode), never use
smaller slices than this. Ignored in duplex mode (default).</dd>
<dt>--max-slice-size <i>size</i></dt>
<dd>maximum slice size (expressed in blocks). Default is 1024. When
dynamically adjusting slice size (only in non-duplex mode), never use
larger slices than this. Ignored in duplex mode (default).</dd>
<dt>--default-slice-size <i>size</i></dt>
<dd>Slice size used (starting slice size in half-duplex mode).</dd>
<dt>--rehello-offset <i>offs</i></dt>
<dd>in streaming mode, how many packets before end of slice the hello
packet will be transferred (default 50). Chose larger values if you
notice that receivers are excessively slow to pick up running
transmission</dd>
</dl>
<a name="fectune"></a>
<h2>Tuning the forward error correction</h2>
<p>There are three parameters on which to act:</p>
<dl>
<dt>redundancy</dt>
<dd>This influences how much extra packets are included per
stripe. The higher this is, the more redundancy there is, which means
that the transmission becomes more robust against loss. However, CPU
time necessary is also proportional to redundancy (a factor to
consider on slow PC's), and of course, a higher redundancy augments
the amount of data to be transmitted.</dd>
<dt>interleave</dt>
<dd>This influences among how many stripes the data is
divided. Higher interleave improves robustness against burst loss
(for example, 64 packets in a row...). It doesn't increase robustness
against randomly spread packet loss. <b>Note</b>: interleave bigger than 8
will force a smaller stripesize, due to the fact that slicesize is limited
to 1024.</dd>
<dt>stripesize</dt>
<dd>How many data blocks there are in a stripe. Due to the algorithm
used, this cannot be more than 128. Reducing stripe size is an
indirect way of augmenting (relative) redundancy, without incurring
the CPU penalty of larger (absolute) redundancy. However, a larger
absolute redundancy is still preferable over a smaller stripesize,
because it improves robustness against clustered losses. For
instance, if 8/128 is preferable over 4/64, because with 8/128 the 8
FEC packets can be used to compensate for the loss of any of the 128
data packets, whereas with 4/64, each group of 4 FEC packets can only
be used against its own set of 64 data packets. If for instance the
first 8 packets were lost, they would be recoverable with 8/128, but
not with 4/64.</dd>
</dl>
Considering these, change parameters as follows:
<ul>
<li>If you observe long stretches of lost packets, increase interleave</li>
<li>If you observe that transfer is slowed down by CPU saturation,
decrease redundancy and stripesize proportionnally.</li>
<li>If you observe big <i>variations</i> in packet loss rate,
increase redundancy and stripesize proportionnally.</li>
<li>If you just observe high loss, but not necessarily clustered in any
special way, increase redundancy or decrease stripesize</li>
<li>Be aware that network equipment or the receiver may be dropping
packets because of a bandwidth which is too high. Try limiting it
using <tt>max-bitrate</tt></li>
<li>The receiver may also be dropping packets because it cannot write
the data to disk fast enough. Use hdparm to optimize disk access on
the receiver. Try playing with the settings in
<tt>/proc/sys/net/core/rmem_default</tt> and
<tt>/proc/sys/net/core/rmem_max</tt>, i.e. setting them to a higher
value.</li>
</ul>
<hr>
</body>
</html>
|