1.\" 2.\" $FreeBSD$ 3.\" 4.Dd Sep 28, 1998 5.Dt DUMMYNET 4 6.Os 7.Sh NAME 8.Nm dummynet 9.Nd Flexible bandwidth manager and delay emulator 10.Sh SYNOPSIS 11.Fd #include <sys/types.h> 12.Fd #include <sys/queue.h> 13.Fd #include <netinet/in.h> 14.Fd #include <netinet/ip_fw.h> 15.Ft int 16.Fn setsockopt raw_socket IPPROTO_IP "ipfw option" "struct ipfw" size 17.Sh DESCRIPTION 18dummynet is a system facility that permits the control of traffic 19going through the various network interfaces, by applying bandwidth 20and queue size limitations, and simulating delays and losses. 21.Pp 22In its current implementation, 23packet selection is done with the 24.Nm ipfw 25program, by means of 26.Dq pipe 27rules. 28A dummynet 29.Em pipe 30is characterized by a bandwidth, delay, queue size, and loss 31rate, which can be configured with the 32.Nm ipfw 33program. 34Pipes are 35numbered from 1 to 65534, and packets can be passed through multiple 36pipes depending on the ipfw configuration. 37.Pp 38Dummynet operates at the ip level, but if bridging extensions are 39enabled, it is possible to pass bridged packets through pipes as well. 40.Sh USAGE 41Packets are sent to a pipe using the command 42.Bd -literal 43 ipfw add pipe NNN .... 44.Ed 45 46and pipes are configured as follows: 47.Bd -literal 48 ipfw pipe NNN config bw B delay D queue Q plr P 49.Ed 50 51where the bandwidth B can be expressed in bit/s, Kbit/s, Mbit/s, 52Bytes/s, KBytes/s, MBytes/s , delay in milliseconds, queue size in 53packets or Bytes, plr is the fraction of packets randomly dropped. 54.Pp 55Getting ipfw to work right is not very intuitive, especially when 56the system is acting as a router or a bridge. 57.Pp 58When acting as a router, the same ruleset is applied on both the 59input and the output path for routed packets, so you have to make 60sure that a packet does not go through the same pipe twice (unless 61this is what you really want). 62.Pp 63When acting as a bridge, the 64.Nm ipfw 65filter is invoked only once, in the input path, 66for bridged packets. 67.Pp 68Also, when simulating true full-duplex channels, be sure to pass 69traffic through two different pipes, depending on the direction. 70E.g. a suitable rule set for simulating an asymmetric bidirectional 71link would be the following: 72.Bd -literal 73 ipfw add pipe 1 ip from A to B out 74 ipfw add pipe 2 ip from B to A in 75 ipfw pipe 1 config bw 1Mbit/s delay 80ms 76 ipfw pipe 2 config bw 128Kbit/s delay 300ms 77.Ed 78 79.Pp 80.Sh OPERATION 81The 82.Nm ipfw 83code is used to select packets that must be subject to 84bandwidth/queue/delay/losses, and returns the identifier of 85the ``pipe'' describing such limitations. 86.Pp 87Selected packets are first queued in a bounded size queue, from which 88they are extracted at the programmed rate and passed to a second queue 89where delay is simulated. 90At the output from the second queue packets 91are reinjected into the protocol stack at the same point they came 92from (i.e. ip_input(), ip_output(), bdg_forward() ). 93Depending on the setting of the sysctl variable 94.Ql net.inet.ip.fw.one_pass , 95packets coming from a pipe can be either forwarded to their 96destination, or passed again through the 97.Nm ipfw 98rules, starting from the one after the matching rule. 99.Pp 100.Nm 101performs its task once per timer tick. 102The granularity of operation is 103thus controlled by the kernel option 104.Bd -literal 105 options HZ 106.Ed 107 108whose default value (100) means a granularity of 10ms. 109For an accurate simulation of high data rates it might be necessary to 110reduce the timer granularity to 1ms or less. 111Consider, however, 112that some interfaces using programmed I/O may require a considerable 113time to output packets. 114So, reducing the granularity too much might 115actually cause ticks to be missed thus reducing the accuracy of 116operation. 117 118.Sh KERNEL OPTIONS 119The following options in the kernel configuration file are related 120to 121.Nm 122operation: 123.Bd -literal 124 IPFIREWALL - enable ipfirewall (required for dummynet). 125 IPFIREWALL_VERBOSE - enable firewall output. 126 IPFIREWALL_VERBOSE_LIMIT - limit firewall output. 127 DUMMYNET - enable dummynet operation. 128 NMBCLUSTER - set the amount of network packet buffers 129 HZ - sets the timer granularity 130.Ed 131.Pp 132Generally, the following options are required: 133.Bd -literal 134 options IPFIREWALL 135 options DUMMYNET 136.Ed 137 138additionally, one may want to increase the number 139of mbuf clusters (used to store network packets) according to the 140sum of the bandwidth-delay products and queue sizes of all configured 141pipes. 142 143 144.Sh SYSCTL VARIABLES 145.Pp 146.Ql net.inet.ip.fw.one_pass 147is set to 1 if we want packets to pass through the firewall code only 148once. 149.Pp 150.Ql net.link.ether.bridge_ipfw 151is set if we want bridged packets to pass through the firewall code. 152.Sh COMMANDS 153The following socket options are used to manage pipes: 154.Pp 155IP_DUMMYNET_CONFIGURE updates a pipe configuration (or creates a 156new one. 157.Pp 158IP_DUMMYNET_DEL deletes all pipes having the matching rule number. 159.Pp 160IP_DUMMYNET_GET returns the pipes matching the number. 161.Pp 162IP_FW_FLUSH flushes the pipes matching the number. 163.Pp 164When the kernel security level is greater than 2, only IP_DUMMYNET_GET 165is allowed. 166.Sh SEE ALSO 167.Xr setsockopt 2 , 168.Xr ip 4 , 169.Xr ipfw 8 , 170.Xr sysctl 8 171.Sh BUGS 172This manpage is not illustrating all the possible ways to use 173dummynet. 174.Sh HISTORY 175.Nm 176was initially implemented as a testing tool for TCP congestion control 177by 178.An Luigi Rizzo Aq luigi@iet.unipi.it , 179as described on ACM Computer 180Communication Review, Jan.97 issue. 181Later it has been then modified 182to work at the ip and bridging level, and integrated with the IPFW 183packet filter. 184