Subject: Re: [PATCH] netem/iproute2 solving correlated loss issues [4/5]

From: Fabio Ludovici <[email-masked]>
Date: Fri, 18 Dec 2009 12:30:07 +0100

patch 4/5 : iproute2-2.6.29-1/man/man8/tc-netem.8
diff -uNr iproute2-2.6.29-1/man/man8/tc-netem.8 iproute2-2.6.29-1-netem/man/man8/tc-netem.8
--- iproute2-2.6.29-1/man/man8/tc-netem.8	1970-01-01 01:00:00.000000000 +0100
+++ iproute2-2.6.29-1-netem/man/man8/tc-netem.8	2009-12-11 16:41:25.184219339 +0100
@@ -0,0 +1,258 @@
+.TH NETEM 8 "11 December 2009" "iproute2" "Linux"
+.SH NAME
+NetEm \- Network Emulator
+.SH SYNOPSIS
+.B tc qdisc ... dev
+dev
+.B ] add netem  [ limit 
+packets
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem [ logging 
+LEVEL ]
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem [ delay 
+TIME [ JITTER [CORRELATION]]]
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem [ distribution 
+{uniform|normal|pareto|paretonormal} ]
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem [ drop 
+PERCENT [CORRELATION]]
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem [ loss
+PERCENT [CORRELATION]]
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem  [ query 
+] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem [ loss_GI 
+ploss [burst_length [density [pisol [good_burst_length]]]]
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem [ loss_GI_tran
+p13 p31 [p32 p23 [p14]]
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem  [ loss_bern 
+p 
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem  [ loss_gilb 
+p r [1-h]]
+.B ]
+
+.B tc qdisc ... dev
+dev
+.B ] add netem  [ loss_gilbell 
+p r [1-h [1-k]]
+.B ]
+
+.B tc qdisc ... dev
+dev
+.B ] add netem  [ loss_gilb_4s 
+p r [1-h]]
+
+
+.B tc qdisc ... dev
+dev
+.B ] add netem  [ loss_gilbell_4s 
+p r [1-h [1-k]]
+.B ]
+
+.B tc qdisc ... dev
+dev
+.B ] add netem [ loss_pattern 
+FILENAME [REPETITIONS]]
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem  [ corrupt 
+PERCENT [CORRELATION]]
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem  [ duplicate 
+PERCENT [CORRELATION]]
+.B ] 
+
+.B tc qdisc ... dev
+dev
+.B ] add netem  [ reorder 
+PRECENT [CORRELATION] [ gap DISTANCE ]]
+.B ] 
+
+.SH DESCRIPTION
+NetEm is an enhancment of the Linux traffic control facilities 
+that allow to add delay, packet loss, duplication and more other
+characteristics to packets outgoing from a selected network
+interface. NetEm is build using the existing Quality Of Service (QOS)
+and Differentiated Services (diffserv) facilities in the Linux
+kernel. 
+
+.SH netem OPTIONS
+netem has the following options:
+
+.B limit 
+packets
+
+limits the effect of selected options to the indicated number of next packets. 
+
+.B logging
+LEVEL
+
+sets a logging level. Actually it works for loss_GI, loss_GI_tran, loss_bern, loss_gilb, loss_gilbell, loss_gilb_4s, loss_gilbell_4s, loss_pattern options. If not specified, level 0 will be used which means that no data will be logged. If logging level is 1 for each loss events the kernel logs will include a line like "netem loss event algorithm [type] x RFPLE y" where RFPLE stands for "Received From Previous Loss Event" and it counts the number y of good packets received between two loss events while x is the number of all lost packets and algorithm refers to the selected loss generation algorithm (
+.B GI
+, 
+.B gilbell 
+or 
+.B deterministic). 
+The type label applies only to the GI algorithm and can be 
+.B burst 
+or 
+.B isolated.
+
+.B delay 
+TIME [ JITTER [CORRELATION]]]
+
+adds the chosen delay to the packets outgoing to chosen network interface. The optional parameters allows to introduce a delay variation and a correlation. Delay and jitter values are expressed in ms while correlation is percentage. 
+
+.B distribution 
+{uniform|normal|pareto|paretonormal} 
+ 
+allow the choose the delay distribution. If not specified, the default distribution is normal. Additional parameters allow to consider situations in which network has variable delays depending on traffic flows concurring on the same path, that causes severeal delay peaks and a tail. 
+
+.B drop 
+PERCENT [CORRELATION]
+
+OR
+
+.B loss
+PERCENT [CORRELATION]
+
+using drop or loss is the same. It adds the chosen independent loss probability to packets outgoing from the chosen network interface. It is also possibile to add a correlation, through the proper parameter. However this option is now deprecated due to the noticed bad behaviour. To have introduce independent packet losses, which corresponds to the Bernoulli loss model, please use the loss_bern option.
+
+.B query
+
+enables the query mode. Actually it works for loss_GI, loss_GI_tran\, loss_bern, loss_gilb, loss_gilbell. When the query mode is enabled and one of the supported options are selected, the correspondent transition probabilities and GI parameters are calculated and printed to screen without passing the parameters to the qdisc. So this option works like a parameter converter. If the option is not specified the query mode is disabled so the parameters will be regularly passed to the netem qdisc. 
+
+.B loss_GI 
+ploss [burst_length [density [pisol [good_burst_length]]]]
+
+implements the GI (General and Intuitive) loss model, with the underlying 4-state Markov. The parameter ploss  is mandatory and if used alone corresponds to the Bernoulli model while the optional parameters allows to extend the model to 2-state (burst_length), 3-state (density), and 4-state (pisol). Without specifing good_burst_length the hyphotesis of statistical independence for the losses within the burst will be used.
+
+.B loss_GI_tran
+p13 p31 [p32 p23 [p14]]
+
+implements the GI (General and Intuitive) model using the 4-state Markov transition probabilities as input parameters. The first two parameters p13 and p31 are mandatory and if used alone corresponds to a 2-state model while the optional parameters allows to extend the model to 3-state (p23 and p32) and 4-state (p14). State 1 corresponds to good reception, State 4 to independent losses, State 3 to burst losses and State 2 to good reception within a burst. 
+
+.B loss_bern 
+p
+
+implements the Bernoulli loss model. Allows to introduce, through the p parameter, an independent loss probability to packets outgoing from chosen network interface. This option is equivalent to the old and now deprecated drop / loss
+option used without the correlation parameter. 
+
+.B loss_gilb 
+p r [1-h]
+
+implements the Gilbert loss model through the two mandatory parameters p and r and the optional 1-h. This model has two states: "good" and "bad". If only the mandatory parameters are specified, the Simple Gilbert model will be used, while to use the full Gilbert model it is needed to specify the whole set of three parameters.
+
+.B loss_gilbell 
+p r [1-h [1-k]]
+
+implements the Gilbert-Elliot loss model through the two mandatory parameters p and r and the optional 1-h and 1-k where  1-k is an independent loss probability in the "good" state while 1-h is the loss density within the "bad" state. This model is an enhanced version of the Gilbert model.
+
+.B loss_gilb_4s
+p r [1-h]
+
+implements the Gilbert-4s loss model that is particular version of the GI model which behaviour is very similar to the Gilbert's. The input parameters are the same of the real Gilbert model. The transition probabilities and GI parameters that corresponds to the Gilbert input parameters are calculated and printed to screen. This option is included to study the correspondence between GI model and the models available in the literature, it has no practical use at the moment.
+
+.B loss_gilbell_4s 
+p r [1-h [1-k]]
+
+implements the Gilbert-Elliot-4s loss model that is particular version of the GI model which behaviour is very similar to the Gilbert-Elliot's. The input parameters are the same of the real Gilbert model. The transition probabilities and GI parameters that corresponds to the Gilbert-Elliot input parameters are calculated and printed to screen. This option is included to study the correspondence between GI model and the models available in the literature, it has no practical use at the moment.
+
+.B loss_pattern 
+FILENAME [REPETITIONS]
+
+generates a deterministic loss pattern. It reads from the text file FILENAME a sequence of "1" and "0" where "1" are the loss events and "0" are the regular transmission of packets . The parameter repetitions is optional and is the number of "replicas" of the loss pattern file. It is optional and by default is 0 which means infinite repetition of the loss pattern.
+
+.B corrupt 
+PERCENT [CORRELATION]]
+
+allows the emulate the random noise introducing an error in a random position for a chosen percent of packets. It is also possible to add a correlation through the proper parameter.
+
+.B duplicate 
+PERCENT [CORRELATION]]
+
+using this option the chosen percent of packets is duplicated before queueing them. It is also possible to add a correlation through the proper parameter.
+
+.B reorder 
+PRECENT [CORRELATION] [ gap DISTANCE ]]
+
+there are two ways to use this option:
+
+.B reorder 
+gap 5 10 ms 
+
+in this first example every 5th (10th, 15th) packet is sent immediately while other packets are delayed by 10 ms 
+
+.B reorder 
+25% 50%
+
+in this second example 25% of packets are sent immediately (with correlation of 50%) while the other are delayed by 10 ms.
+
+.SH LIMITATIONS
+The main known limitation of Netem are related to timer granularity, since Linux is not a real-time operating system; to the choice of Pseudo-Random Number Generator (PRNG) and the original loss model. To have a better behavior in emulating losses, the new loss_GI_tran, loss_GI, loss_bern, loss_gilb, loss_gilbell, loss_gilb_4s, loss_gilbell_4s options were added.
+
+
+.SH SOURCES
+.TP
+o
+Hemminger S. , "Network Emulation with NetEm", Open Source Development Lab, April 2005 (http://devresources.linux-foundation.org/shemminger/netem/LCA2005_paper.pdf)
+
+.TP
+o
+Netem page from Linux foundation, (http://www.linuxfoundation.org/en/Net:Netem)
+
+.TP
+o
+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", 
+August 2009 (http://netgroup.uniroma2.it/twiki/pub/Main/netem2/TR-loss-netem.pdf)
+
+
+.SH SEE ALSO
+.BR tc (8)
+
+.SH AUTHOR
+Netem was written by Stephen Hemminger at OSDL and is based on NISTnet. This version includes the new GI (General and Intuitive) loss generator, the Gilbert-Elliot loss generator, the deterministic pattern mode. This options were developed by Networking Group, University of Rome "Tor Vergata" involving Stefano Salsano, Fabio Ludovici, Alessandro Ordine. This manpage was created by Fabio Ludovici <fabio.ludovici AT yahoo DOT it>.
+
+