# tc-netem

## NAME



           netem - Network Emulator
    


## SYNOPSIS



           **tc qdisc ... dev** _DEVICE_ ] **add netem** _OPTIONS_
    
           _OPTIONS_ := [ _LIMIT_ ] [ _DELAY_ ] [ _LOSS_ ] [ _CORRUPT_ ] [ _DUPLICATION_
           ] [ _REORDERING_ ] [ _RATE_ ] [ _SLOT_ ] [ _SEED_ ]
    
           _LIMIT_ := **limit** _packets_
    
           _DELAY_ := **delay** _TIME_ [ _JITTER_ [ _CORRELATION_ ]]]
                  [ **distribution**{ **uniform** | **normal** | **pareto** | **paretonormal**}
           ]
    
           _LOSS_ := **loss**{ **random** _PERCENT_ [ _CORRELATION_ ]  |
                          **state** _p13_ [ _p31_ [ _p32_ [ _p23_ [ _p14_]]]] |
                          **gemodel** _p_ [ _r_ [ _1-h_ [ _1-k_ ]]] }  [ **ecn**]
    
           _CORRUPT_ := **corrupt** _PERCENT_ [ _CORRELATION_ ]]
    
           _DUPLICATION_ := **duplicate** _PERCENT_ [ _CORRELATION_ ]]
    
           _REORDERING_ := **reorder** _PERCENT_ [ _CORRELATION_ ] [ **gap** _DISTANCE_ ]
    
           _RATE_ := **rate** _RATE_ [ _PACKETOVERHEAD_ [ _CELLSIZE_ [ _CELLOVERHEAD_ ]]]]
    
           _SLOT_ := **slot**{ _MIN_DELAY_ [ _MAX_DELAY_ ] |
                          **distribution**{ **uniform** | **normal** | **pareto** |
           **paretonormal** | _FILE_ } _DELAY JITTER_ }
                        [ **packets** _PACKETS_ ] [ **bytes** _BYTES_ ]
    
           _SEED_ := **seed** _VALUE_
    


## DESCRIPTION



           The **netem** queue discipline provides Network Emulation
           functionality for testing protocols by emulating the properties of
           real-world networks.
    
           The queue discipline provides one or more network impairments to
           packets such as: delay, loss, duplication, and packet corruption.
    


## OPTIONS



           **limit** _COUNT_
                  Limits the maximum number of packets the qdisc may hold
                  when doing delay.
    
           **delay** _TIME_ [ _JITTER_ [ _CORRELATION_ ]]]
                  Delays the packets before sending.  The optional parameters
                  allow introducing a delay variation and a correlation.
                  Delay and jitter values are expressed in milliseconds;
                  Correlation is set by specifying a percent of how much the
                  previous delay will impact the current random value.
    
           **distribution** _TYPE_
                  Specifies a pattern for delay distribution.
    
                  **uniform**
                         Use an equally weighted distribution of packet
                         delays.
    
                  **normal** Use a Gaussian distribution of delays.  Sometimes
                         called a Bell Curve.
    
                  **pareto** Use a Pareto distribution of packet delays.  This is
                         useful to emulate long-tail distributions.
    
                  **paretonormal**
                         This is a mix of **pareto** and **normal** distribution
                         which has properties of both Bell curve and long
                         tail.
    
           **loss** _MODEL_
                  Drop packets based on a loss model.  _MODEL_ can be one of
    
                  **random** _PERCENT_
                         Each packet loss is independent.
    
                  **state** _P13 [ P31 [ P32 [ P23 P14 ]]]_
                         Use a 4-state Markov chain to describe packet loss.
                         _P13_ is the packet loss.  Optional parameters extend
                         the model to 2-state _P31_ , 3-state _P23_ , _P32_ and
                         4-state _P14_.
    
                         The Markov chain states are:
    
                         **1** good packet reception (no loss).
    
                         **2** good reception within a burst.
    
                         **3** burst losses.
    
                         **4** independent losses.
    
                  **gemodel** _PERCENT [ R [ 1-H [ 1-K ]]]_
                         Use a Gilbert-Elliot (burst loss) model based on:
    
                         _PERCENT_
                                probability of starting bad (lossy) state.
    
                         _R_      probability of exiting bad state.
    
                         _1-H_    loss probability in bad state.
    
                         _1-K_    loss probability in good state.
    
           **ecn** Use Explicit Congestion Notification (ECN) to mark packets
                  instead of dropping them.  A loss model has to be used for
                  this to be enabled.
    
           **corrupt** _PERCENT_
                  modifies the contents of the packet at a random position
                  based on _PERCENT_.
    
           **duplicate** _PERCENT_
                  creates a copy of the packet before queuing.
    
           **reorder** _PERCENT_
                  modifies the order of packet in the queue.
    
           **gap** _DISTANCE_
                  sends some packets immediately.  The first packets
                  _(DISTANCE - 1)_ are delayed and the next packet is sent
                  immediately.
    
           **rate** _RATE [ PACKETOVERHEAD [ CELLSIZE_  _[ CELLOVERHEAD ]]]_
                  Delays packets based on packet size to emulate a fixed link
                  speed.  Optional parameters:
    
                  _PACKETOVERHEAD_
                         Specify a per packet overhead in bytes.  Used to
                         simulate additional link layer headers.  A negative
                         value can be used to simlate when the Ethernet
                         header is stripped (e.g. -14) or header compression
                         is used.
    
                  _CELLSIZE_
                         simulate link layer schemes like ATM.
    
                  _CELLOVERHEAD_
                         specify per cell overhead.
    
           Rate throttling impacted by several factors including the kernel
           clock granularity. This will show up in an artificial packet
           compression (bursts).
    
           **slot** _MIN_DELAY [_  _MAX_DELAY_  _]_
                  allows emulating slotted networks.  Defer delivering
                  accumulated packets to within a slot.  Each available slot
                  is configured with a minimum delay to acquire, and an
                  optional maximum delay.
    
           **slot distribution**
                  allows configuring based on distribution similar to
                  **distribution** option for packet delays.
    
                  These slot options can provide a crude approximation of
                  bursty MACs such as DOCSIS, WiFi, and LTE.
    
                  Slot emulation is limited by several factors: the kernel
                  clock granularity, as with a rate, and attempts to deliver
                  many packets within a slot will be smeared by the timer
                  resolution, and by the underlying native bandwidth also.
    
                  It is possible to combine slotting with a rate, in which
                  case complex behaviors where either the rate, or the slot
                  limits on bytes or packets per slot, govern the actual
                  delivered rate.
    
           **seed** _VALUE_
                  Specifies a seed to guide and reproduce the randomly
                  generated loss or corruption events.
    


## LIMITATIONS



           Netem is limited by the timer granularity in the kernel.  Rate and
           delay maybe impacted by clock interrupts.
    
           Mixing forms of reordering may lead to unexpected results.  For
           any method of reordering to work, some delay is necessary.  If the
           delay is less than the inter-packet arrival time then no
           reordering will be seen.  Due to mechanisms like TSQ (TCP Small
           Queues), for TCP performance test results to be realistic netem
           must be placed on the ingress of the receiver host.
    
           Combining netem with other qdisc is possible but may not always
           work because netem use skb control block to set delays.
    


## EXAMPLES



           # tc qdisc add dev eth0 root netem delay 100ms
               Add fixed amount of delay to all packets going out on device
               eth0.  Each packet will have added delay of 100ms ± 10ms.
    
           # tc qdisc change dev eth0 root netem delay 100ms 10ms 25%
               This causes the added delay of 100ms ± 10ms and the next
               packet delay value will be biased by 25% on the most recent
               delay.  This isn't a true statistical correlation, but an
               approximation.
    
           # tc qdisc change dev eth0 root netem delay 100ms 20ms distribution normal
               This delays packets according to a normal distribution (Bell
               curve) over a range of 100ms ± 20ms.
    
           # tc qdisc change dev eth0 root netem loss 0.1%
               This causes 1/10th of a percent (i.e 1 out of 1000) packets to
               be randomly dropped.
    
               An optional correlation may also be added.  This causes the
               random number generator to be less random and can be used to
               emulate packet burst losses.
    
           # tc qdisc change dev eth0 root netem duplicate 1%
               This causes one percent of the packets sent on eth0 to be
               duplicated.
    
           # tc qdisc change dev eth0 root netem loss 0.3% 25%
               This will cause 0.3% of packets to be lost, and each
               successive probability depends is biased by 25% of the
               previous one.
    
           There are two different ways to specify reordering.  The gap
           method uses a fixed sequence and reorders every Nth packet.
           # tc qdisc change dev eth0 root netem gap 5 delay 10ms
               This causes every 5th (10th, 15th, …) packet to go to be sent
               immediately and every other packet to be delayed by 10ms.
               This is predictable and useful for base protocol testing like
               reassembly.
    
           The reorder form uses a percentage of the packets to get
           misordered.
           # tc qdisc change dev eth0 root netem delay 10ms reorder 25% 50%
           In this example, 25% of packets (with a correlation of 50%) will
           get sent immediately, others will be delayed by 10ms.
    
           Packets will also get reordered if jitter is large enough.
           # tc qdisc change dev eth0 root netem delay 100ms 75ms
               If the first packet gets a random delay of 100ms (100ms base -
               0ms jitter) and the second packet is sent 1ms later and gets a
               delay of 50ms (100ms base - 50ms jitter); the second packet
               will be sent first.  This is because the queue discipline
               tfifo inside netem, keeps packets in order by time to send.
    
           If you don't want this behavior then replace the internal queue
           discipline tfifo with a simple FIFO queue discipline.
           # tc qdisc add dev eth0 root handle 1: netem delay 10ms 100ms
           # tc qdisc add dev eth0 parent 1:1 pfifo limit 1000
    
           Example of using rate control and cells size.
           # tc qdisc add dev eth0 root netem rate 5kbit 20 100 5
               Delay all outgoing packets on device eth0 with a rate of
               5kbit, a per packet overhead of 20 byte, a cellsize of 100
               byte and a per celloverhead of 5 bytes.
    
           It is possible to selectively apply impairment using traffic
           classification.
           # tc qdisc add dev eth0 root handle 1: prio
           # tc qdisc add dev eth0 parent 1:3 handle 30:    tbf rate 20kbit buffer 1600 limit  3000
           # tc qdisc add dev eth0 parent 30:1 handle 31:    netem delay 200ms 10ms distribution normal
           # tc filter add dev eth0 protocol ip parent 1:0 prio 3 u32    match ip dst 65.172.181.4/32 flowid 1:3
               This example uses a priority queueing discipline; a TBF is
               added to do rate control; and a simple netem delay.  A filter
               classifies all packets going to 65.172.181.4 as being priority
               3.
    


## SOURCES



            1. Hemminger S. , "Network Emulation with NetEm", Open Source
               Development Lab, April 2005 
               ⟨http://devresources.linux-
               foundation.org/shemminger/netem/LCA2005_paper.pdf⟩
    
            2. Salsano S., Ludovici F., Ordine A., "Definition of a general
               and intuitive loss model for packet networks and its
               implementation in the Netem module in the Linux kernel",
               available at ⟨http://netgroup.uniroma2.it/NetemCLG⟩
    


* * *