Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DUMMYNET(4)	       FreeBSD Kernel Interfaces Manual		   DUMMYNET(4)

     dummynet -- flexible bandwidth manager and	delay emulator

     #include <sys/types.h>
     #include <sys/queue.h>
     #include <netinet/in.h>
     #include <netinet/ip_fw.h>

     setsockopt(raw_socket, IPPROTO_IP,	ipfw option, struct ipfw, size);

     dummynet is a system facility that	permits	the control of traffic going
     through the various network interfaces, by	applying bandwidth and queue
     size limitations, and simulating delays and losses.

     In	its current implementation, packet selection is	done with the ipfw
     program, by means of ``pipe'' rules.  A dummynet pipe is characterized by
     a bandwidth, delay, queue size, and loss rate, which can be configured
     with the ipfw program.  Pipes are numbered	from 1 to 65534, and packets
     can be passed through multiple pipes depending on the ipfw	configuration.

     Dummynet operates at the ip level,	but if bridging	extensions are
     enabled, it is possible to	pass bridged packets through pipes as well.

     Packets are sent to a pipe	using the command

	 ipfw add pipe NNN ....

     and pipes are configured as follows:

	 ipfw pipe NNN config bw B delay D queue Q plr P

     where the bandwidth B can be expressed in bit/s, Kbit/s, Mbit/s, Bytes/s,
     KBytes/s, MBytes/s	, delay	in milliseconds, queue size in packets or
     Bytes, plr	is the fraction	of packets randomly dropped.

     Getting ipfw to work right	is not very intuitive, especially when the
     system is acting as a router or a bridge.

     When acting as a router, the same ruleset is applied on both the input
     and the output path for routed packets, so	you have to make sure that a
     packet does not go	through	the same pipe twice (unless this is what you
     really want).

     When acting as a bridge, the ipfw filter is invoked only once, in the
     input path, for bridged packets.

     Also, when	simulating true	full-duplex channels, be sure to pass traffic
     through two different pipes, depending on the direction.  E.g. a suitable
     rule set for simulating an	asymmetric bidirectional link would be the

	ipfw add pipe 1	ip from	A to B out
	ipfw add pipe 2	ip from	B to A in
	ipfw pipe 1 config bw 1Mbit/s delay 80ms
	ipfw pipe 2 config bw 128Kbit/s	delay 300ms

     The ipfw code is used to select packets that must be subject to band-
     width/queue/delay/losses, and returns the identifier of the ``pipe''
     describing	such limitations.

     Selected packets are first	queued in a bounded size queue,	from which
     they are extracted	at the programmed rate and passed to a second queue
     where delay is simulated.	At the output from the second queue packets
     are reinjected into the protocol stack at the same	point they came	from
     (i.e. ip_input(), ip_output(), bdg_forward() ).  Depending	on the setting
     of	the sysctl variable `net.inet.ip.fw.one_pass', packets coming from a
     pipe can be either	forwarded to their destination,	or passed again
     through the ipfw rules, starting from the one after the matching rule.

     dummynet performs its task	once per timer tick.  The granularity of oper-
     ation is thus controlled by the kernel option

	 options HZ

     whose default value (100) means a granularity of 10ms.  For an accurate
     simulation	of high	data rates it might be necessary to reduce the timer
     granularity to 1ms	or less.  Consider, however, that some interfaces
     using programmed I/O may require a	considerable time to output packets.
     So, reducing the granularity too much might actually cause	ticks to be
     missed thus reducing the accuracy of operation.

     The following options in the kernel configuration file are	related	to
     dummynet operation:

       IPFIREWALL		- enable ipfirewall (required for dummynet).
       IPFIREWALL_VERBOSE	- enable firewall output.
       IPFIREWALL_VERBOSE_LIMIT	- limit	firewall output.
       DUMMYNET			- enable dummynet operation.
       NMBCLUSTERS		- set the amount of network packet buffers
       HZ			- sets the timer granularity

     Generally,	the following options are required:

       options IPFIREWALL
       options DUMMYNET

     additionally, one may want	to increase the	number of mbuf clusters	(used
     to	store network packets) according to the	sum of the bandwidth-delay
     products and queue	sizes of all configured	pipes.

     `net.inet.ip.fw.one_pass' is set to 1 if we want packets to pass through
     the firewall code only once.

     `' is set if we want bridged packets to pass
     through the firewall code.

     The following socket options are used to manage pipes:

     IP_DUMMYNET_CONFIGURE updates a pipe configuration	(or creates a new one.

     IP_DUMMYNET_DEL deletes all pipes having the matching rule	number.

     IP_DUMMYNET_GET returns the pipes matching	the number.

     IP_FW_FLUSH flushes the pipes matching the	number.

     When the kernel security level is greater than 2, only IP_DUMMYNET_GET is

     setsockopt(2), bridge(4), ip(4), ipfw(8), sysctl(8)

     This manpage is not illustrating all the possible ways to use dummynet.

     dummynet was initially implemented	as a testing tool for TCP congestion
     control by	Luigi Rizzo <>, as described on ACM Computer
     Communication Review, Jan.97 issue.  Later	it has been then modified to
     work at the ip and	bridging level,	and integrated with the	IPFW packet

FreeBSD	11.1		      September	28, 1998		  FreeBSD 11.1


Want to link to this manual page? Use this URL:

home | help