1NETEM(8)                             Linux                            NETEM(8)
2
3
4

NAME

6       NetEm - Network Emulator
7

SYNOPSIS

9       tc qdisc ... dev DEVICE ] add netem OPTIONS
10
11       OPTIONS  :=  [ LIMIT ] [ DELAY ] [ LOSS ] [ CORRUPT ] [ DUPLICATION ] [
12       REORDERING ] [ RATE ] [ SLOT ]
13
14       LIMIT := limit packets
15
16       DELAY := delay TIME [ JITTER [ CORRELATION ]]]
17              [ distribution { uniform | normal | pareto |  paretonormal } ]
18
19       LOSS := loss { random PERCENT [ CORRELATION ]  |
20                      state p13 [ p31 [ p32 [ p23 [ p14]]]] |
21                      gemodel p [ r [ 1-h [ 1-k ]]] }  [ ecn ]
22
23       CORRUPT := corrupt PERCENT [ CORRELATION ]]
24
25       DUPLICATION := duplicate PERCENT [ CORRELATION ]]
26
27       REORDERING := reorder PERCENT [ CORRELATION ] [ gap DISTANCE ]
28
29       RATE := rate RATE [ PACKETOVERHEAD [ CELLSIZE [ CELLOVERHEAD ]]]]
30
31       SLOT := slot { MIN_DELAY [ MAX_DELAY ] |
32                      distribution { uniform | normal | pareto |  paretonormal
33       | FILE } DELAY JITTER }
34                    [ packets PACKETS ] [ bytes BYTES ]
35
36
37

DESCRIPTION

39       NetEm  is  an  enhancement of the Linux traffic control facilities that
40       allow to add delay, packet loss, duplication and more other  character‐
41       istics  to packets outgoing from a selected network interface. NetEm is
42       built using the existing Quality Of Service  (QOS)  and  Differentiated
43       Services (diffserv) facilities in the Linux kernel.
44
45

netem OPTIONS

47       netem has the following options:
48
49
50   limit packets
51       maximum number of packets the qdisc may hold queued at a time.
52
53
54   delay
55       adds  the chosen delay to the packets outgoing to chosen network inter‐
56       face. The optional parameters allows to introduce a delay variation and
57       a  correlation.  Delay and jitter values are expressed in ms while cor‐
58       relation is percentage.
59
60
61   distribution
62       allow the user to choose the delay distribution. If not specified,  the
63       default distribution is Normal. Additional parameters allow to consider
64       situations in which network has variable delays  depending  on  traffic
65       flows  concurring on the same path, that causes several delay peaks and
66       a tail.
67
68
69   loss random
70       adds an independent loss probability to the packets outgoing  from  the
71       chosen network interface. It is also possible to add a correlation, but
72       this option is now deprecated due to the noticed bad behavior.
73
74
75   loss state
76       adds packet losses according to the 4-state Markov using the transition
77       probabilities  as  input parameters. The parameter p13 is mandatory and
78       if used alone corresponds to the Bernoulli model. The optional  parame‐
79       ters allows to extend the model to 2-state (p31), 3-state (p23 and p32)
80       and 4-state (p14).  State 1 corresponds to good reception, State  4  to
81       independent  losses, State 3 to burst losses and State 2 to good recep‐
82       tion within a burst.
83
84
85   loss gemodel
86       adds packet losses according to the Gilbert-Elliot loss  model  or  its
87       special  cases  (Gilbert,  Simple  Gilbert  and  Bernoulli). To use the
88       Bernoulli model, the only needed parameter is p while the  others  will
89       be  set  to  the  default values r=1-p, 1-h=1 and 1-k=0. The parameters
90       needed for the Simple Gilbert model are two  (p  and  r),  while  three
91       parameters (p, r, 1-h) are needed for the Gilbert model and four (p, r,
92       1-h and 1-k) are needed for the Gilbert-Elliot model. As known, p and r
93       are  the  transition probabilities between the bad and the good states,
94       1-h is the loss probability in the bad state and 1-k is the loss proba‐
95       bility in the good state.
96
97
98   ecn
99       can be used optionally to mark packets instead of dropping them. A loss
100       model has to be used for this to be enabled.
101
102
103   corrupt
104       allows the emulation of random noise introducing an error in  a  random
105       position  for a chosen percent of packets. It is also possible to add a
106       correlation through the proper parameter.
107
108
109   duplicate
110       using this option the chosen percent of packets  is  duplicated  before
111       queuing  them.  It  is  also  possible to add a correlation through the
112       proper parameter.
113
114
115   reorder
116       to use reordering, a delay option must be specified. There are two ways
117       to use this option (assuming 'delay 10ms' in the options list).
118
119       reorder 25% 50% gap 5
120       in  this  first  example,  the first 4 (gap - 1) packets are delayed by
121       10ms and subsequent packets are sent immediately with a probability  of
122       0.25  (with correlation of 50% ) or delayed with a probability of 0.75.
123       After a packet is reordered, the process restarts i.e. the next 4 pack‐
124       ets  are delayed and subsequent packets are sent immediately or delayed
125       based on reordering probability. To cause a  repeatable  pattern  where
126       every  5th  packet is reordered reliably, a reorder probability of 100%
127       can be used.
128
129       reorder 25% 50%
130       in this second example 25% of packets are sent immediately (with corre‐
131       lation of 50%) while the others are delayed by 10 ms.
132
133
134   rate
135       delay  packets based on packet size and is a replacement for TBF.  Rate
136       can be specified in common units (e.g. 100kbit).  Optional  PACKETOVER‐
137       HEAD  (in  bytes) specify an per packet overhead and can be negative. A
138       positive value can be used to simulate additional link layer headers. A
139       negative  value  can  be  used  to artificial strip the Ethernet header
140       (e.g. -14) and/or simulate a link layer header compression scheme.  The
141       third  parameter  -  an unsigned value - specify the cellsize. Cellsize
142       can be used to simulate link layer schemes. ATM for example has an pay‐
143       load cellsize of 48 bytes and 5 byte per cell header. If a packet is 50
144       byte then ATM must use two cells: 2 * 48 bytes payload including 2 *  5
145       byte header, thus consume 106 byte on the wire. The last optional value
146       CELLOVERHEAD can be used to specify per cell overhead  -  for  our  ATM
147       example  5.  CELLOVERHEAD can be negative, but use negative values with
148       caution.
149
150       Note that rate throttling is limited by  several  factors:  the  kernel
151       clock  granularity  avoid  a  perfect shaping at a specific level. This
152       will show up in an  artificial  packet  compression  (bursts).  Another
153       influence factor are network adapter buffers which can also add artifi‐
154       cial delay.
155
156
157   slot
158       defer delivering accumulated packets to within a slot.  Each  available
159       slot can be configured with a minimum delay to acquire, and an optional
160       maximum delay.  Alternatively it can be configured with  the  distribu‐
161       tion similar to distribution for delay option. Slot delays can be spec‐
162       ified in  nanoseconds,  microseconds,  milliseconds  or  seconds  (e.g.
163       800us).  Values for the optional parameters BYTES will limit the number
164       of bytes delivered per slot, and/or PACKETS will limit  the  number  of
165       packets delivered per slot.
166
167       These  slot  options  can  provide a crude approximation of bursty MACs
168       such as DOCSIS, WiFi, and LTE.
169
170       Note that slotting is limited by  several  factors:  the  kernel  clock
171       granularity,  as  with  a  rate,  and  attempts to deliver many packets
172       within a slot will be smeared by  the  timer  resolution,  and  by  the
173       underlying native bandwidth also.
174
175       It  is  possible to combine slotting with a rate, in which case complex
176       behaviors where either the rate, or the slot limits on bytes or packets
177       per slot, govern the actual delivered rate.
178
179

LIMITATIONS

181       The  main  known  limitation of Netem are related to timer granularity,
182       since Linux is not a real-time operating system.
183
184

EXAMPLES

186       tc qdisc add dev eth0 root netem rate 5kbit 20 100 5
187           delay all outgoing packets on device eth0 with a rate of  5kbit,  a
188           per  packet  overhead  of 20 byte, a cellsize of 100 byte and a per
189           celloverhead of 5 byte:
190
191

SOURCES

193        1. Hemminger S. , "Network Emulation with NetEm", Open Source Develop‐
194           ment    Lab,    April    2005    (http://devresources.linux-founda
195           tion.org/shemminger/netem/LCA2005_paper.pdf)
196
197
198        2. Netem  page   from   Linux   foundation,   (http://www.linuxfounda
199           tion.org/en/Net:Netem)
200
201
202        3. Salsano  S.,  Ludovici  F., Ordine A., "Definition of a general and
203           intuitive loss model for packet networks and its implementation  in
204           the  Netem  module  in  the Linux kernel", available at http://net
205           group.uniroma2.it/NetemCLG
206
207

SEE ALSO

209       tc(8), tc-tbf(8)
210
211

AUTHOR

213       Netem was written by Stephen Hemminger at Linux foundation and is based
214       on NISTnet.  This manpage was created by Fabio Ludovici <fabio.ludovici
215       at yahoo dot it> and Hagen Paul Pfeifer <hagen@jauu.net>
216
217
218
219iproute2                       25 November 2011                       NETEM(8)
Impressum