man/man8/tc-netem.8

   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
  13 .IR LIMIT " := "
  14 .B limit
  15 .I packets
  16
  17 .IR DELAY " := "
  18 .BI delay
  19 .IR TIME " [ " JITTER " [ " CORRELATION " ]]]"
  20 .br
  21        [
  22 .BR distribution " { "uniform " | " normal " | " pareto " |  " paretonormal " } ]"
  23
  24 .IR LOSS " := "
  25 .BR loss " { "
  26 .BI random
  27 .IR PERCENT " [ " CORRELATION " ]  |"
  28 .br
  29 .RB "               " state
  30 .IR p13 " [ " p31 " [ " p32 " [ " p23 " [ " p14 "]]]] |"
  31 .br
  32 .RB "               " gemodel
  33 .IR p " [ " r " [ " 1-h " [ " 1-k " ]]]"
  34 .BR " }"
  35
  36 .IR CORRUPT " := "
  37 .B corrupt
  38 .IR PERCENT " [ " CORRELATION " ]]"
  39
  40 .IR DUPLICATION " := "
  41 .B duplicate
  42 .IR PERCENT " [ " CORRELATION " ]]"
  43
  44 .IR REORDERING " := "
  45 .B reorder
  46 .IR PERCENT " [ " CORRELATION " ] [ "
  47 .B gap
  48 .IR DISTANCE " ]"
  49
  50 .IR RATE " := "
  51 .B rate
  52 .IR RATE " [ " PACKETOVERHEAD " [ " CELLSIZE " [ " CELLOVERHEAD " ]]]]"
  53
  54
  55 .SH DESCRIPTION
  56 NetEm is an enhancement of the Linux traffic control facilities
  57 that allow to add delay, packet loss, duplication and more other
  58 characteristics to packets outgoing from a selected network
  59 interface. NetEm is built using the existing Quality Of Service (QOS)
  60 and Differentiated Services (diffserv) facilities in the Linux
  61 kernel.
  62
  63 .SH netem OPTIONS
  64 netem has the following options:
  65
  66 .SS limit packets
  67
  68 limits the effect of selected options to the indicated number of next packets.
  69
  70 .SS delay
  71 adds the chosen delay to the packets outgoing to chosen network interface. The
  72 optional parameters allows to introduce a delay variation and a correlation.
  73 Delay and jitter values are expressed in ms while correlation is percentage.
  74
  75 .SS distribution
  76 allow the user to choose the delay distribution. If not specified, the default
  77 distribution is Normal. Additional parameters allow to consider situations in
  78 which network has variable delays depending on traffic flows concurring on the
  79 same path, that causes several delay peaks and a tail.
  80
  81 .SS loss random
  82 adds an independent loss probability to the packets outgoing from the chosen
  83 network interface. It is also possible to add a correlation, but this option
  84 is now deprecated due to the noticed bad behavior.
  85
  86 .SS loss state
  87 adds packet losses according to the 4-state Markov using the transition
  88 probabilities as input parameters. The parameter p13 is mandatory and if used
  89 alone corresponds to the Bernoulli model. The optional parameters allows to
  90 extend the model to 2-state (p31), 3-state (p23 and p32) and 4-state (p14).
  91 State 1 corresponds to good reception, State 4 to independent losses, State 3
  92 to burst losses and State 2 to good reception within a burst.
  93
  94 .SS loss gemodel
  95 adds packet losses according to the Gilbert-Elliot loss model or its special
  96 cases (Gilbert, Simple Gilbert and Bernoulli). To use the Bernoulli model, the
  97 only needed parameter is p while the others will be set to the default
  98 values r=1-p, 1-h=1 and 1-k=0. The parameters needed for the Simple Gilbert
  99 model are two (p and r), while three parameters (p, r, 1-h) are needed for the
 100 Gilbert model and four (p, r, 1-h and 1-k) are needed for the Gilbert-Elliot
 101 model. As known, p and r are the transition probabilities between the bad and
 102 the good states, 1-h is the loss probability in the bad state and 1-k is the
 103 loss probability in the good state.
 104
 105 .SS corrupt
 106 allows the emulation of random noise introducing an error in a random position
 107 for a chosen percent of packets. It is also possible to add a correlation
 108 through the proper parameter.
 109
 110 .SS duplicate
 111 using this option the chosen percent of packets is duplicated before queuing
 112 them. It is also possible to add a correlation through the proper parameter.
 113
 114 .SS reorder
 115 there are two ways to use this option:
 116
 117 .B "reorder gap"
 118 .I 5 10
 119 .br
 120 in this first example every 5th (10th, 15th) packet is sent immediately while
 121 other packets are delayed by 10 ms
 122
 123 .B reorder
 124 .I 25% 50%
 125 .br
 126 in this second example 25% of packets are sent immediately (with correlation of
 127 50%) while the other are delayed by 10 ms.
 128
 129 .SS rate
 130 delay packets based on packet size and is a replacement for
 131 .IR TBF .
 132 Rate can be
 133 specified in common units (e.g. 100kbit). Optional
 134 .I PACKETOVERHEAD
 135 (in bytes) specify an per packet overhead and can be negative. A positive value can be
 136 used to simulate additional link layer headers. A negative value can be used to
 137 artificial strip the Ethernet header (e.g. -14) and/or simulate a link layer
 138 header compression scheme. The third parameter - an unsigned value - specify
 139 the cellsize. Cellsize can be used to simulate link layer schemes. ATM for
 140 example has an payload cellsize of 48 bytes and 5 byte per cell header. If a
 141 packet is 50 byte then ATM must use two cells: 2 * 48 bytes payload including 2
 142 * 5 byte header, thus consume 106 byte on the wire.  The last optional value
 143 .I CELLOVERHEAD
 144 can be used to specify per cell overhead - for our ATM example 5.
 145 .I CELLOVERHEAD
 146 can be negative, but use negative values with caution.
 147
 148 Note that rate throttling is limited by several factors: the kernel clock
 149 granularity avoid a perfect shaping at a specific level. This will show up in
 150 an artificial packet compression (bursts). Another influence factor are network
 151 adapter buffers which can also add artificial delay.
 152
 153 .SH LIMITATIONS
 154 The main known limitation of Netem are related to timer granularity, since
 155 Linux is not a real-time operating system.
 156
 157 .SH EXAMPLES
 158 .PP
 159 tc qdisc add dev eth0 root netem rate 5kbit 20 100 5
 160 .RS 4
 161 delay all outgoing packets on device eth0 with a rate of 5kbit, a per packet
 162 overhead of 20 byte, a cellsize of 100 byte and a per celloverhead of 5 byte:
 163 .RE
 164
 165 .SH SOURCES
 166 .IP " 1. " 4
 167 Hemminger S. , "Network Emulation with NetEm", Open Source Development Lab,
 168 April 2005
 169 (http://devresources.linux-foundation.org/shemminger/netem/LCA2005_paper.pdf)
 170
 171 .IP " 2. " 4
 172 Netem page from Linux foundation, (http://www.linuxfoundation.org/en/Net:Netem)
 173
 174 .IP " 3. " 4
 175 Salsano S., Ludovici F., Ordine A., "Definition of a general and intuitive loss
 176 model for packet networks and its implementation in the Netem module in the
 177 Linux kernel", available at http://netgroup.uniroma2.it/NetemCLG
 178
 179 .SH SEE ALSO
 180 .BR tc (8),
 181 .BR tc-tbf (8)
 182
 183 .SH AUTHOR
 184 Netem was written by Stephen Hemminger at Linux foundation and is based on NISTnet.
 185 This manpage was created by Fabio Ludovici <fabio.ludovici at yahoo dot it> and
 186 Hagen Paul Pfeifer <hagen@jauu.net>