1UDP-SENDER(1)                       Udpcast                      UDP-SENDER(1)
2
3
4

NAME

6       udp-sender - broadcast file on a LAN
7

SYNOPSIS

9       udp-sender [--file file] [--full-duplex] [--half-duplex] [--pipe pipe]
10       [--portbase portbase] [--blocksize size] [--interface net-interface]
11       [--mcast-data-address data-mcast-address] [--mcast-rdv-address mcast-
12       rdv-address] [--max-bitrate bitrate] [--pointopoint] [--async] [--log
13       file] [--min-slice-size min] [--max-slice-size max] [--slice-size]
14       [--ttl time-to-live] [--fec stripesxredundancy/stripesize]
15       [--print-seed] [--rexmit-hello-interval interval] [--autostart
16       autostart] [--broadcast] [--min-receivers receivers] [--min-wait sec]
17       [--max-wait sec] [--nokbd] [--retries-until-drop n] [--bw-period n]
18       [--rate-governor module.so:key1=value1,key2=value2] [--stat-period n]
19       [--print-uncompressed-position flag]
20

DESCRIPTION

22       "Udp-sender" is used to broadcast a file (for instance a disk image) to
23       multiple "udp-receivers" on the local LAN. In order to do this, it uses
24       Ethernet multicast or broadcast, so that all receivers profit from the
25       same physical datastream. Thus, sending to 10 destinations does not
26       take more time than it would take to send just 2.
27

OPTIONS

29   Basic options
30       --file file
31           Reads data to be transmitted from file. If this parameter is not
32           supplied, data to be transmitted is read from stdin instead.
33
34       --pipe command
35           Sends data through pipe before transmitting it. This is useful for
36           compressing/decompressing it, or for stripping out unused blocks.
37           The command gets a direct handle on the input file or device, and
38           thus may seek inside it, if needed. "Udpcast" itself also keeps a
39           handle on the file, which is used for an informal progress display.
40           The command's stdout is a pipe to udpcast.
41
42       --autostart n
43           Starts transmission after n retransmissions of hello packet,
44           without waiting for a key stroke. Useful for unattended operation,
45           where udp-sender is started from a cron-job for a
46           broadcast/multicast at a scheduled time.
47
48   Networking options
49       The following networking options should be supplied both on the sender
50       and the receivers:
51
52       --portbase portbase
53           Default ports to use for udpcast. Two ports are used: portbase and
54           portbase+1 . Thus, Portbase must be even. Default is 9000. The same
55           portbase must be specified for both "udp-sender" and
56           "udp-receiver".
57
58       --interface interface
59           Network interface used to send out the data. Default is "eth0"
60
61       --ttl time to live
62           Sets the time-to-live parameter for the multicast packets. Should
63           theoretically allow to use UDPCast beyond the local network, but
64           not tested for lack of a multicast router.
65
66       --mcast-rdv-address address
67           Uses a non-standard multicast address for the control (rendez-vous)
68           connection. This address is used by the sender and receivers to
69           "find" each other. This is not the address that is used to transfer
70           the actual data.
71
72           By default "mcast-rdv-address" is the Ethernet broadcast address if
73           "ttl" is 1, and 224.0.0.1 otherwise. This setting should not be
74           used except in very special situations, such as when 224.0.0.1
75           cannot be used for policy reasons.
76
77       The following networking options should be supplied only on the sender:
78
79       --mcast-data-address address
80           Uses the given address for multicasting the data. If not specified,
81           the program will automatically derive a multicast address from its
82           own IP (by keeping the last 27 bits of the IP and then prepending
83           232).
84
85       --pointopoint
86           Point-to-point mode. Only a single receiver is allowed, but the
87           data will be directly send to this receiver (in unicast mode),
88           rather than multicast/broadcast all over the place. If no async
89           mode is chosen, and there happens to be only one receiver, point-
90           to-point is activated automatically.
91
92       --nopointopoint
93           Don't use point-to-point, even if there is only one single
94           receiver.
95
96       --full-duplex
97           Use this option if you use a full-duplex network. T-base-10 or 100
98           is full duplex if equipped with a switch. Hub based networks, or
99           T-base-2 networks (coaxial cable) are only half-duplex and you
100           should not use this option with these networks, or else you may
101           experience a 10% performance hit.
102
103           N.B. On high-latency WAN links, the full-duplex option can lead to
104           substantial performance improvements, because it allows udp-sender
105           to send more data while it is still waiting for the previous batch
106           to get acknowledged.
107
108       --half-duplex
109           Use half duplex mode (needed for Hub based or T-base-2 networks).
110           This is the default behavior in this version of udpcast.
111
112       --broadcast
113           Use Ethernet broadcast, rather than multicast. Useful if you have
114           Ethernet cards which don't support multicast.
115
116           By default, "udpcast" uses multicast. This allows sending the data
117           only to those receivers that requested it. Ethernet cards of
118           machines which don't participate in the transmission automatically
119           block out the packets at the hardware level. Moreover, network
120           switches are able to selectively transmit the packets only to those
121           network ports to which receivers are connected. Both features thus
122           allow a much more efficient operation than broadcast. This option
123           should only be supplied on the sender.
124
125       -b blocksize
126           Choses the packet size. Default (and also maximum) is 1456.
127
128   Unidirectional mode (without return channel)
129       The options described below are useful in situations where no "return
130       channel" is available, or where such a channel is impractical due to
131       high latency. In an unidirectional setup (i.e. without return channel),
132       the sender only sends data but doesn't expect any reply from the
133       receiver.
134
135       Unidirectional options must be used together, or else the transfer will
136       not work correctly. You may for example use the following command line:
137
138       "udp-sender --async --max-bitrate 10m --fec 8x8"
139
140       --async
141           Asynchronous mode. Do not request confirmations from the receiver.
142           Best used together with forward error correction and bandwidth
143           limitation, or else the receiver will abort the reception as soon
144           as it misses a packet. When the receiver aborts the reception in
145           such a way, it will print a list of packets lost in the slice
146           causing the problem. You can use this list to tune the forward
147           error correction parameters.
148
149       --max-bitrate bitrate
150           Limits bandwidth used by udpcast. Useful in asynchronous mode, or
151           else the sender may send too fast for the switch and/or receiver to
152           keep up. Bitrate may be expressed in bits per second (--bitrate
153           5000000), kilobits per second ("--bitrate 5000k") or megabits per
154           second ("--bitrate 5m"). This is the raw bitrate, including packet
155           headers, forward error correction, retransmissions, etc. Actual
156           payload bitrate will be lower.
157
158       --fec interleave"x"redundancy"/"stripesize
159           Enables forward error correction. The goal of forward error
160           correction is to transmit redundant data, in order to make up for
161           packets lost in transit. Indeed, in unidirectional mode, the
162           receivers have no way of requesting retransmission of lost packets,
163           thus the only way to address packet loss is to include redundant
164           information to begin with. The algorithm is designed in such a way
165           that if r redundant packets are transmitted, that those can be used
166           to compensate for the loss of any r packets in the same FEC group
167           (stripe).
168
169           In order to increase robustness of the FEC algorithm against burst
170           packet losses, each slice is divided in interleave stripes. Each
171           stripe has stripesize blocks (if not specified, stripesize is
172           calculated by diving slice-size by interleave). For each stripe,
173           redundancy FEC packets are added. Stripes are organized in such a
174           fashion that consecutive packets belong to different stripes. This
175           way, we ensure that burst losses affect different stripes, rather
176           than using all FEC packets of a single stripe. Example: "--fec
177           8x8/128"
178
179       --rate-governor module.so:key1=value1,key2=value2
180           Applies a dynamically loadable rate governor. module.so is the name
181           of the preloadable module, which is followed by a number of
182           property assignments (key1=value1). The rate governor controls the
183           transmission rate according to various criteria, such as congestion
184           information received from a routing or encapsulating device. See
185           comments in "/usr/include/udpcast/rateGovernor.h" and example in
186           "examples/rateGovernor" for more details
187
188       --rexmit-hello-interval timeout
189           If set, rebroadcasts the HELLO packet used for initiating the
190           casting each timeout milliseconds.
191
192           This option is useful together with asyc mode, because with async
193           mode the receiver won't send a connection request to the sender
194           (and hence won't get a connection reply). In async mode, the
195           receivers get all needed information from the hello packet instead,
196           and are thus particularly dependant on the reception of this
197           packet, makeing retransmission useful.
198
199           This option is also useful on networks where packet loss is so high
200           that even with connection requests, sender and receiver would not
201           find each other otherwise.
202
203       --retries-until-drop retries
204           How many time to send a REQACK until dropping a receiver. Lower
205           retrycounts make "udp-sender" faster to react to crashed receivers,
206           but they also increase the probability of false alerts (dropping
207           receivers that are not actually crashed, but merely slow to respond
208           for whatever reason)
209
210       --streaming
211           Allows receivers to join an ongoing transmission mid through
212
213   Keyboardless mode
214       The options below help to run a sender in unattended mode.
215
216       --min-receivers n
217           Automatically start as soon as a minimal number of receivers have
218           connected.
219
220       --min-wait t
221           Even when the necessary amount of receivers do have connected,
222           still wait until t seconds since first receiver connection have
223           passed.
224
225       --max-wait t
226           When not enough receivers have connected (but at least one), start
227           anyways when t seconds since first receiver connection have pased.
228
229       --nokbd
230           Do not read start signal from keyboard, and do not display any
231           message telling the user to press any key to start.
232
233       --start-timeout sec
234           sender aborts at start if it doesn't see a receiver within this
235           many seconds. Furthermore, transmission of data needs to start
236           within this delay. Once transmission is started, the timeout no
237           longer applies.
238
239       --daemon-mode
240           Do not exit when done, but instead wait for the next batch of
241           receivers. If this option is given twice, udp-sender puts itself
242           into the background, closes its standard file descriptors, and acts
243           as a real daemon.
244
245       --pid-file file
246           Allow to specify a pid file. If given together with
247           "--daemon-mode", udp-sender will write its pid into this file. If
248           given together with "--kill", the process with the given pid will
249           be killed.
250
251       --kill
252           Shuts down the udp-sender identified by the pid file (which also
253           must be specified). Kill does not interrupt an ongoing
254           transmission, but instead waits until it is finished.
255
256       Example:
257
258       "udp-sender -f zozo --min-receivers 5 --min-wait 20 --max-wait 80"
259
260       •   If one receiver connects at 18h00.00, and 4 more within the next 5
261           minutes, start at 18h00.20. (5 receivers connected, but min-wait
262           not yet pased)
263
264       •   If one receiver connects at 18h00.00, and 3 more within the next 5
265           minutes, then a last one at 18h00.25, start right after.
266
267       •   If one receiver connects at 18h00.00, then 3 more within the next
268           15 minutes, then no one, start at 18h01.20. (not enough receivers,
269           but we start anyways after max-wait).
270
271   Logging and statistics options
272       The options instruct "udp-sender" to log some additional statistics to
273       a file:
274
275       --stat-period seconds
276           Every so much milliseconds, print some statistics to stderr: how
277           much bytes sent so far log, position in uncompressed file (if
278           applicable), retransmit count... By default, this is printed every
279           half second.
280
281       --print-uncompressed-position flag
282           By default, udp-sender only prints the position in uncompressed
283           file if the 2 following conditions are met:
284
285           •   Input is piped via a compressor ("-p " option).
286
287           •   The primary input is seekable (file or device)
288
289           With the "--print-uncompressed-position", options, you can change
290           this behavior:
291
292           •   If flag is 0, uncompressed position will never be printed, even
293               if above conditions are met
294
295           •   If flag is 1, uncompressed position will always be printed,
296               even if above conditions are not met
297
298       --log file
299           Logs some stuff into file.
300
301       --no-progress
302           Do not display progress statistics.
303
304       --bw-period seconds
305           Every so much seconds, log instantenous bandwidth seen during that
306           period. Note: this is different from the bandwidth displayed to
307           stderr of the receiver, which is the average since start of
308           transmission.
309
310   Tuning options (sender)
311       The following tuning options are all about slice size. Udpcast groups
312       its data in slices, which are a series of blocks (UDP packets). These
313       groups are relevant for
314
315       •   data retransmission: after each slice, the server asks the
316           receivers whether they have received all blocks, and if needed
317           retransmits what has been missing
318
319       •   forward error correction: each slice has its set of data blocks,
320           and matching FEC blocks.
321
322       --min-slice-size size
323           minimum slice size (expressed in blocks). Default is 16. When
324           dynamically adjusting slice size (only in non-duplex mode), never
325           use smaller slices than this. Ignored in duplex mode (default).
326
327       --max-slice-size size
328           maximum slice size (expressed in blocks). Default is 1024. When
329           dynamically adjusting slice size (only in non-duplex mode), never
330           use larger slices than this. Ignored in duplex mode (default).
331
332       --default-slice-size size
333           Slice size used (starting slice size in half-duplex mode).
334
335       --rehello-offset offs
336           in streaming mode, how many packets before end of slice the hello
337           packet will be transferred (default 50). Chose larger values if you
338           notice that receivers are excessively slow to pick up running
339           transmission
340
341   Tuning the forward error correction
342       There are three parameters on which to act:
343
344       redundancy
345           This influences how much extra packets are included per stripe. The
346           higher this is, the more redundancy there is, which means that the
347           transmission becomes more robust against loss. However, CPU time
348           necessary is also proportional to redundancy (a factor to consider
349           on slow PC's), and of course, a higher redundancy augments the
350           amount of data to be transmitted.
351
352       interleave
353           This influences among how many stripes the data is divided. Higher
354           interleave improves robustness against burst loss (for example, 64
355           packets in a row...). It doesn't increase robustness against
356           randomly spread packet loss. Note: interleave bigger than 8 will
357           force a smaller stripesize, due to the fact that slicesize is
358           limited to 1024.
359
360       stripesize
361           How many data blocks there are in a stripe. Due to the algorithm
362           used, this cannot be more than 128. Reducing stripe size is an
363           indirect way of augmenting (relative) redundancy, without incurring
364           the CPU penalty of larger (absolute) redundancy. However, a larger
365           absolute redundancy is still preferable over a smaller stripesize,
366           because it improves robustness against clustered losses. For
367           instance, if 8/128 is preferable over 4/64, because with 8/128 the
368           8 FEC packets can be used to compensate for the loss of any of the
369           128 data packets, whereas with 4/64, each group of 4 FEC packets
370           can only be used against its own set of 64 data packets. If for
371           instance the first 8 packets were lost, they would be recoverable
372           with 8/128, but not with 4/64.
373
374       Considering these, change parameters as follows:
375
376       •   If you observe long stretches of lost packets, increase interleave
377
378       •   If you observe that transfer is slowed down by CPU saturation,
379           decrease redundancy and stripesize proportionnally.
380
381       •   If you observe big variations in packet loss rate, increase
382           redundancy and stripesize proportionnally.
383
384       •   If you just observe high loss, but not necessarily clustered in any
385           special way, increase redundancy or decrease stripesize
386
387       •   Be aware that network equipment or the receiver may be dropping
388           packets because of a bandwidth which is too high. Try limiting it
389           using "max-bitrate"
390
391       •   The receiver may also be dropping packets because it cannot write
392           the data to disk fast enough. Use hdparm to optimize disk access on
393           the receiver. Try playing with the settings in
394           "/proc/sys/net/core/rmem_default" and
395           "/proc/sys/net/core/rmem_max", i.e. setting them to a higher value.
396

SEE ALSO

398       udp-receiver
399

AUTHOR

401       Alain Knaff
402
403
404
405current                        January 22, 2022                  UDP-SENDER(1)
Impressum