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