Debian Codegraph @

upstream/debian-unstable/man8/tc-netem.8

raw
1 .TH NETEM 8 "25 November 2011" "iproute2" "Linux"
2 .SH NAME
3 netem \- Network Emulator
4 .SH SYNOPSIS
5 .B "tc qdisc ... dev"
6 .IR DEVICE " ] "
7 .BR "add netem"
8 .I OPTIONS
9
10 .IR OPTIONS " := [ " LIMIT " ] [ " DELAY " ] [ " LOSS \
11 " ] [ " CORRUPT " ] [ " DUPLICATION " ] [ " REORDERING " ] [ " RATE \
12 " ] [ " SLOT " ] [ " SEED " ]"
13
14 .IR LIMIT " := "
15 .B limit
16 .I packets
17
18 .IR DELAY " := "
19 .BI delay
20 .IR TIME " [ " JITTER " [ " CORRELATION " ]]]"
21 .br
22 [
23 .BR distribution " { "uniform " | " normal " | " pareto " | " paretonormal " } ]"
24
25 .IR LOSS " := "
26 .BR loss " { "
27 .BI random
28 .IR PERCENT " [ " CORRELATION " ] |"
29 .br
30 .RB " " state
31 .IR p13 " [ " p31 " [ " p32 " [ " p23 " [ " p14 "]]]] |"
32 .br
33 .RB " " gemodel
34 .IR p " [ " r " [ " 1-h " [ " 1-k " ]]] } "
35 .RB " [ " ecn " ] "
36
37 .IR CORRUPT " := "
38 .B corrupt
39 .IR PERCENT " [ " CORRELATION " ]]"
40
41 .IR DUPLICATION " := "
42 .B duplicate
43 .IR PERCENT " [ " CORRELATION " ]]"
44
45 .IR REORDERING " := "
46 .B reorder
47 .IR PERCENT " [ " CORRELATION " ] [ "
48 .B gap
49 .IR DISTANCE " ]"
50
51 .IR RATE " := "
52 .B rate
53 .IR RATE " [ " PACKETOVERHEAD " [ " CELLSIZE " [ " CELLOVERHEAD " ]]]]"
54
55 .IR SLOT " := "
56 .BR slot " { "
57 .IR MIN_DELAY " [ " MAX_DELAY " ] |"
58 .br
59 .RB " " distribution " { "uniform " | " normal " | " pareto " | " paretonormal " | "
60 .IR FILE " } " DELAY " " JITTER " } "
61 .br
62 .RB " [ " packets
63 .IR PACKETS " ] [ "
64 .BR bytes
65 .IR BYTES " ]"
66
67 .IR SEED " := "
68 .B seed
69 .I VALUE
70
71 .SH DESCRIPTION
72 The
73 .B netem
74 queue discipline provides Network Emulation functionality
75 for testing protocols by emulating the properties of real-world networks.
76
77 The queue discipline provides one or more network impairments to packets
78 such as: delay, loss, duplication, and packet corruption.
79
80 .SH OPTIONS
81 .TP
82 .BI limit " COUNT"
83 Limits the maximum number of packets the qdisc may hold when doing delay.
84
85 .TP
86 .B delay
87 .IR TIME " [ " JITTER " [ " CORRELATION " ]]]"
88 .br
89 Delays the packets before sending.
90 The optional parameters allow introducing a delay variation and a correlation.
91 Delay and jitter values are expressed in milliseconds;
92 Correlation is set by specifying a percent of how much the previous delay
93 will impact the current random value.
94
95 .TP
96 .BI distribution " TYPE"
97 Specifies a pattern for delay distribution.
98 .RS
99 .TP
100 .B uniform
101 Use an equally weighted distribution of packet delays.
102 .TP
103 .B normal
104 Use a Gaussian distribution of delays.
105 Sometimes called a Bell Curve.
106 .TP
107 .B pareto
108 Use a Pareto distribution of packet delays.
109 This is useful to emulate long-tail distributions.
110 .TP
111 .B paretonormal
112 This is a mix of
113 .B pareto
114 and
115 .B normal
116 distribution which has properties of both Bell curve and long tail.
117 .RE
118
119 .TP
120 .BI loss " MODEL"
121 Drop packets based on a loss model.
122 .I MODEL
123 can be one of
124 .RS
125 .TP
126 .BI random " PERCENT"
127 Each packet loss is independent.
128 .TP
129 .BI state " P13 [ P31 [ P32 [ P23 P14 ]]]"
130 Use a 4-state Markov chain to describe packet loss.
131 .br
132 .I P13
133 is the packet loss.
134 Optional parameters extend the model to 2-state
135 .IR P31 ,
136 3-state
137 .IR P23 ,
138 .I P32
139 and 4-state
140 .IR P14 .
141
142 The Markov chain states are:
143 .RS
144 .TP
145 .B 1
146 good packet reception (no loss).
147 .TP
148 .B 2
149 good reception within a burst.
150 .TP
151 .B 3
152 burst losses.
153 .TP
154 .B 4
155 independent losses.
156 .RE
157
158 .TP
159 .BI gemodel " PERCENT [ R [ 1-H [ 1-K ]]]"
160 Use a Gilbert-Elliot (burst loss) model
161 based on:
162 .RS
163 .TP
164 .I PERCENT
165 probability of starting bad (lossy) state.
166 .TP
167 .I R
168 probability of exiting bad state.
169 .TP
170 .I "1-H"
171 loss probability in bad state.
172 .TP
173 .I "1-K"
174 loss probability in good state.
175 .RE
176 .RE
177
178 .TP
179 .B ecn
180 Use
181 Explicit Congestion Notification (ECN)
182 to mark packets instead of dropping them.
183 A loss model has to be used for this to be enabled.
184 .TP
185 .BI corrupt " PERCENT"
186 modifies the contents of the packet at a random position
187 based on
188 .IR PERCENT .
189 .TP
190 .BI duplicate " PERCENT"
191 creates a copy of the packet before queuing.
192 .TP
193 .BI reorder " PERCENT"
194 modifies the order of packet in the queue.
195 .TP
196 .BI gap " DISTANCE"
197 sends some packets immediately.
198 The first packets
199 .I "(DISTANCE - 1)"
200 are delayed and the next packet is sent immediately.
201
202 .TP
203 .BI rate " RATE [ PACKETOVERHEAD [ CELLSIZE [ CELLOVERHEAD ]]]"
204 Delays packets based on packet size to emulate a fixed link speed.
205 Optional parameters:
206 .RS
207 .TP
208 .I PACKETOVERHEAD
209 Specify a per packet overhead in bytes.
210 Used to simulate additional link layer headers.
211 A negative value can be used to simlate when the Ethernet header is
212 stripped (e.g. -14) or header compression is used.
213 .TP
214 .I CELLSIZE
215 simulate link layer schemes like ATM.
216 .TP
217 .I CELLOVERHEAD
218 specify per cell overhead.
219 .RE
220
221 Rate throttling impacted by several factors including the kernel clock
222 granularity. This will show up in an artificial packet compression (bursts).
223
224 .TP
225 .BI slot " MIN_DELAY [ MAX_DELAY ]"
226 allows emulating slotted networks.
227 Defer delivering accumulated packets to within a slot.
228 Each available slot is configured with a minimum delay to acquire,
229 and an optional maximum delay.
230 .TP
231 .B slot distribution
232 allows configuring based on distribution similar to
233 .B distribution
234 option for packet delays.
235
236 These slot options can provide a crude approximation of bursty MACs such as
237 DOCSIS, WiFi, and LTE.
238
239 Slot emulation is limited by several factors: the kernel clock granularity,
240 as with a rate, and attempts to deliver many packets within a slot will be
241 smeared by the timer resolution, and by the underlying native bandwidth also.
242
243 It is possible to combine slotting with a rate, in which case complex behaviors
244 where either the rate, or the slot limits on bytes or packets per slot, govern
245 the actual delivered rate.
246
247 .TP
248 .BI seed " VALUE"
249 Specifies a seed to guide and reproduce the randomly generated
250 loss or corruption events.
251
252 .SH LIMITATIONS
253 Netem is limited by the timer granularity in the kernel.
254 Rate and delay maybe impacted by clock interrupts.
255 .PP
256 Mixing forms of reordering may lead to unexpected results.
257 For any method of reordering to work, some delay is necessary.
258 If the delay is less than the inter-packet arrival time then
259 no reordering will be seen.
260 Due to mechanisms like TSQ (TCP Small Queues), for TCP performance test
261 results to be realistic netem must be placed on the ingress of the
262 receiver host.
263 .PP
264 Combining netem with other qdisc is possible but may not always
265 work because netem use skb control block to set delays.
266
267 .SH EXAMPLES
268 .PP
269 .EX
270 # tc qdisc add dev eth0 root netem delay 100ms
271 .EE
272 .RS 4
273 Add fixed amount of delay to all packets going out on device eth0.
274 Each packet will have added delay of 100ms ± 10ms.
275 .RE
276 .PP
277 .EX
278 # tc qdisc change dev eth0 root netem delay 100ms 10ms 25%
279 .EE
280 .RS 4
281 This causes the added delay of 100ms ± 10ms
282 and the next packet delay value will be biased by 25% on the most recent delay.
283 This isn't a true statistical correlation, but an approximation.
284 .RE
285 .PP
286 .EX
287 # tc qdisc change dev eth0 root netem delay 100ms 20ms distribution normal
288 .EE
289 .RS 4
290 This delays packets according to a normal distribution (Bell curve)
291 over a range of 100ms ± 20ms.
292 .RE
293 .PP
294 .EX
295 # tc qdisc change dev eth0 root netem loss 0.1%
296 .EE
297 .RS 4
298 This causes 1/10th of a percent (i.e 1 out of 1000) packets to be
299 randomly dropped.
300
301 An optional correlation may also be added.
302 This causes the random number generator to be less random and can be used to emulate packet burst losses.
303 .RE
304 .PP
305 .EX
306 # tc qdisc change dev eth0 root netem duplicate 1%
307 .EE
308 .RS 4
309 This causes one percent of the packets sent on eth0 to be duplicated.
310 .RE
311 .PP
312 .EX
313 # tc qdisc change dev eth0 root netem loss 0.3% 25%
314 .EE
315 .RS 4
316 This will cause 0.3% of packets to be lost,
317 and each successive probability depends is biased by 25% of the previous one.
318 .RE
319 .PP
320 There are two different ways to specify reordering.
321 The gap method uses a fixed sequence and reorders every Nth packet.
322 .EX
323 # tc qdisc change dev eth0 root netem gap 5 delay 10ms
324 .EE
325 .RS 4
326 This causes every 5th (10th, 15th, …) packet to go to be sent immediately
327 and every other packet to be delayed by 10ms.
328 This is predictable and useful for base protocol testing like reassembly.
329 .RE
330 .PP
331 The reorder form uses a percentage of the packets to get misordered.
332 .EX
333 # tc qdisc change dev eth0 root netem delay 10ms reorder 25% 50%
334 .EE
335 In this example, 25% of packets (with a correlation of 50%) will get sent immediately, others will be delayed by 10ms.
336 .PP
337 Packets will also get reordered if jitter is large enough.
338 .EX
339 # tc qdisc change dev eth0 root netem delay 100ms 75ms
340 .EE
341 .RS 4
342 If the first packet gets a random delay of 100ms (100ms base - 0ms jitter)
343 and the second packet is sent 1ms later and gets a delay of 50ms (100ms base - 50ms jitter);
344 the second packet will be sent first.
345 This is because the queue discipline tfifo inside netem,
346 keeps packets in order by time to send.
347 .RE
348 .PP
349 If you don't want this behavior then replace the internal
350 queue discipline tfifo with a simple FIFO queue discipline.
351 .EX
352 # tc qdisc add dev eth0 root handle 1: netem delay 10ms 100ms
353 # tc qdisc add dev eth0 parent 1:1 pfifo limit 1000
354 .EE
355
356 .PP
357 Example of using rate control and cells size.
358 .EX
359 # tc qdisc add dev eth0 root netem rate 5kbit 20 100 5
360 .EE
361 .RS 4
362 Delay all outgoing packets on device eth0 with a rate of 5kbit, a per packet
363 overhead of 20 byte, a cellsize of 100 byte and a per celloverhead of 5 bytes.
364 .RE
365
366 .PP
367 It is possible to selectively apply impairment using traffic classification.
368 .EX
369 # tc qdisc add dev eth0 root handle 1: prio
370 # tc qdisc add dev eth0 parent 1:3 handle 30: \
371 tbf rate 20kbit buffer 1600 limit 3000
372 # tc qdisc add dev eth0 parent 30:1 handle 31: \
373 netem delay 200ms 10ms distribution normal
374 # tc filter add dev eth0 protocol ip parent 1:0 prio 3 u32 \
375 match ip dst 65.172.181.4/32 flowid 1:3
376 .EE
377 .RS 4
378 This example uses a priority queueing discipline;
379 a TBF is added to do rate control; and a simple netem delay.
380 A filter classifies all packets going to 65.172.181.4 as being priority 3.
381 .PP
382 .SH SOURCES
383 .IP " 1. " 4
384 Hemminger S. , "Network Emulation with NetEm", Open Source Development Lab,
385 April 2005
386 .UR http://devresources.linux-foundation.org/shemminger/netem/LCA2005_paper.pdf
387 .UE
388
389 .IP " 2. " 4
390 Salsano S., Ludovici F., Ordine A., "Definition of a general and intuitive loss
391 model for packet networks and its implementation in the Netem module in the
392 Linux kernel", available at
393 .UR http://netgroup.uniroma2.it/NetemCLG
394 .UE
395
396 .SH SEE ALSO
397 .BR tc (8)
398
399 .SH AUTHOR
400 Netem was written by Stephen Hemminger at Linux foundation and was
401 inspired by NISTnet.
402
403 Original manpage was created by Fabio Ludovici
404 <fabio.ludovici at yahoo dot it> and Hagen Paul Pfeifer
405 <[email protected]>.