From: Hagen Paul Pfeifer Date: Fri, 25 Nov 2011 03:47:56 +0000 (+0000) Subject: netem: add man-page X-Git-Tag: v3.2.0~19 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cd72dcf13c8a4948ee5706794714287eeff62c90;p=thirdparty%2Fiproute2.git netem: add man-page Signed-off-by: Hagen Paul Pfeifer --- diff --git a/man/man8/tc-netem.8 b/man/man8/tc-netem.8 new file mode 100644 index 000000000..c8ed29268 --- /dev/null +++ b/man/man8/tc-netem.8 @@ -0,0 +1,272 @@ +.TH NETEM 8 "25 November 2011" "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 ] [ loss_GI +ploss [burst_length [density [pisol [good_burst_length]]]] +.B ] + +.B tc qdisc ... dev +dev +.B ] add netem [ query ] [ loss_4state +[p13 [p31 [p32 [p23 [p14]]]]] +.B ] + +.B tc qdisc ... dev +dev +.B ] add netem [ loss_gilb_ell +p [r [1-h [1-k]]] +.B ] + +.B tc qdisc ... dev +dev +.B ] add netem [ loss_gilb_ell_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 enhancement 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 with loss_GI, loss_4state, loss_bern, +loss_gilb, loss_gilb_ell, loss_gilb_ell_4s, loss_pattern options. The default +value is level 0, which means that no data will be logged. When logging level +is set to 1 the kernel logs will include a line like "netem loss event +algorithm [type] x RFPLE y" for each loss event. The acronym RFPLE means +"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 (4-state, gilb_ell +or deterministic). The type label applies only to the GI algorithm and can be +burst or 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] + +adds an independent loss probability to the packets outgoing from the chosen +network interface. It is also possibile to add a correlation, but this option +is now deprecated due to the noticed bad behaviour. + +.B query + +enables the query mode. It applies to loss_GI and loss_4state options. If it is +used with the loss_GI option, the transition probabilities which correspond to +the input intuitive parameters are calculated and printed to screen, without +copying them in the netem qdisc. Similarly, if it is used with the loss_4state +option, it calculates and prints the intuitive parameters that corresponds to +the input transition probabilities. + +.B loss_GI +ploss [burst_length [density [pisol [good_burst_length]]]] + +adds packet losses according to the GI (General and Intuitive) loss model, +using the intuitive parameters. The parameter ploss is mandatory while the +others are optional. The intuitive parameters are converted to the transition +probabilities of the 4-state Markov model. If the only parameter specified is +ploss, it corresponds to the Bernoulli model while the optional parameters +allow to extend the model to 2-state (burst_length), 3-state (density), and +4-state (pisol). If the good_burst_length is not specified the hyphotesis of +statistical independence for the losses within the burst will be used. + +.B loss_4state +p13 [p31 [p32 [p23 [p14]]]] + +adds packet losses according to the 4-state Markov using the transition +probabilities as input parameters. The parameters p13 is mandatory and if used +alone corresponds to the Bernoulli model. The optional parameters allows to +extend the model to 2-state (p31), 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_gilb_ell +p [r [1-h [1-k]]] + +adds packet losses according to the Gilbert-Elliot loss model or its special +cases (Gilbert, Simple Gilbert and Bernoulli). To use the Bernoulli model, the +only needed parameter is p while the the others will be set to the default +values r=1-p, 1-h=1 and 1-k=0. The parameters needed for the Simple Gilbert +model are two (p and r), while three parameters (p, r, 1-h) are needed for the +Gilbert model and four (p, r, 1-h and 1-k) are needed for the Gilbert-Elliot +model. As known, p and r are the transition probabilities between the bad and +the good states, 1-h is the loss probability in the bad state and 1-k is the +loss probability in the good state. + +.B loss_gilb_ell_4s +p [r [1-h [1-k]]] + +adds packet losses according to the Gilbert-Elliot-4s loss model. It is a +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-Elliot +model or its special cases. The transition probabilities and GI parameters that +corresponds to the Gilbert-Elliot input parameters are calculated and, if the +query mode is enabled, 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] + +adds packet losses according to 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. + +.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", available at http://netgroup.uniroma2.it/NetemCLG + +.SH SEE ALSO +.BR tc (8), +.BR tc-tbf (8) + +.SH AUTHOR +Netem was written by Stephen Hemminger at OSDL and is based on NISTnet. This +manpage was created by Fabio Ludovici and +Hagen Paul Pfeifer