1UDP-SENDER(1) Udpcast UDP-SENDER(1)
2
6 udp-sender - broadcast file on a LAN
7
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
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
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 --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 --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 Networking options
49 The following networking options should be supplied both on the sender
50 and the receivers:
51 --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 --interface interface
59 Network interface used to send out the data. Default is "eth0"
60 --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 --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 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 The following networking options should be supplied only on the sender:
78 --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 --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 --nopointopoint
93 Don't use point-to-point, even if there is only one single
94 receiver.
95 --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 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 --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 --broadcast
113 Use Ethernet broadcast, rather than multicast. Useful if you have
114 Ethernet cards which don't support multicast.
115 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 -b blocksize
126 Choses the packet size. Default (and also maximum) is 1456.
127 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 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 "udp-sender --async --max-bitrate 10m --fec 8x8"
139 --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 --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 --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 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 --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 --rexmit-hello-interval timeout
189 If set, rebroadcasts the HELLO packet used for initiating the
190 casting each timeout milliseconds.
191 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 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 --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 --streaming
211 Allows receivers to join an ongoing transmission mid through
212 Keyboardless mode
214 The options below help to run a sender in unattended mode.
215 --min-receivers n
217 Automatically start as soon as a minimal number of receivers have
218 connected.
219 --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 --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 --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 --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 --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 --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 --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 Example:
257 "udp-sender -f zozo --min-receivers 5 --min-wait 20 --max-wait 80"
259 · 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 · 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 · 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 Logging and statistics options
272 The options instruct "udp-sender" to log some additional statistics to
273 a file:
274 --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 --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 · Input is piped via a compressor ("-p " option).
286 · The primary input is seekable (file or device)
288 With the "--print-uncompressed-position", options, you can change
290 this behavior:
291 · If flag is 0, uncompressed position will never be printed, even
293 if above conditions are met
294 · If flag is 1, uncompressed position will always be printed,
296 even if above conditions are not met
297 --log file
299 Logs some stuff into file.
300 --no-progress
302 Do not display progress statistics.
303 --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 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 · 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 · forward error correction: each slice has its set of data blocks,
320 and matching FEC blocks.
321 --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 --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 --default-slice-size size
333 Slice size used (starting slice size in half-duplex mode).
334 --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 Tuning the forward error correction
342 There are three parameters on which to act:
343 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 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 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 Considering these, change parameters as follows:
375 · If you observe long stretches of lost packets, increase interleave
377 · If you observe that transfer is slowed down by CPU saturation,
379 decrease redundancy and stripesize proportionnally.
380 · If you observe big variations in packet loss rate, increase
382 redundancy and stripesize proportionnally.
383 · If you just observe high loss, but not necessarily clustered in any
385 special way, increase redundancy or decrease stripesize
386 · 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 · 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
398 udp-receiver
399
401 Alain Knaff
402current January 31, 2020 UDP-SENDER(1)