Add manpages for dummynet and bridging

1 files changed, 182 insertions, 0 deletions

diff --git a/share/man/man4/dummynet.4 b/share/man/man4/dummynet.4
new file mode 100644
index 0000000..caefdef
--- /dev/null
+++ b/share/man/man4/dummynet.4
@@ -0,0 +1,182 @@
+.\"
+.\"     $Id$
+.\"
+.Dd Sep 28, 1998
+.Dt DUMMYNET 4
+.Os
+.Sh NAME
+.Nm dummynet
+.Nd Flexible bandwidth manager and delay emulator
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/queue.h>
+.Fd #include <netinet/in.h>
+.Fd #include <netinet/ip_fw.h>
+.Ft int
+.Fn setsockopt raw_socket IPPROTO_IP "ipfw option" "struct ipfw" size
+.Sh DESCRIPTION
+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.
+.Pp
+In its current implementation,
+packet selection is done with the
+.Nm ipfw
+program, by means of
+.Nm ``pipe''
+rules.
+A dummynet
+.Nm pipe
+is characterized by a bandwidth, delay, queue size, and loss
+rate, which can be configured with the
+.Nm ipfw
+program. Pipes are
+numbered from 1 to 65534, and packets can be passed through multiple
+pipes depending on the ipfw configuration.
+.Pp
+Dummynet operates at the ip level, but if bridging extensions are
+enabled, it is possible to pass bridged packets through pipes as well.
+.Sh USAGE
+Packets are sent to a pipe using the command
+.Bd -literal
+    ipfw add pipe NNN ....
+.Ed
+
+and pipes are configured as follows:
+.Bd -literal
+    ipfw pipe NNN config bw B delay D queue Q plr P
+.Ed
+
+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.
+.Pp
+Getting ipfw to work right is not very intuitive, especially when
+the system is acting as a router or a bridge.
+.Pp
+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).
+.Pp
+When acting as a bridge, the
+.Nm ipfw
+filter is invoked only once, in the input path,
+for bridged packets.
+.Pp
+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 following:
+.Bd -literal
+   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
+.Ed
+
+.Pp
+.Sh OPERATION
+The
+.Nm ipfw
+code is used to select packets that must be subject to
+bandwidth/queue/delay/losses, and returns the identifier of
+the ``pipe'' describing such limitations.
+.Pp
+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
+   sys.net.inet.ipfw.one_pass
+Packets coming from a pipe can be either forwarded to their
+destination, or passed again through the
+.Nm ipfw
+rules, starting from the one after the matching rule.
+.Pp
+.Nm dummynet
+performs its task once per timer tick. The granularity of operation is
+thus controlled by the kernel option
+.Bd -literal
+    options HZ
+.Ed
+
+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.
+
+.Sh KERNEL OPTIONS
+The following options in the kernel configuration file are related
+to
+.Nm dummynet
+operation:
+.Bd -literal
+  IPFIREWALL               - enable ipfirewall (required for dummynet).
+  IPFIREWALL_VERBOSE       - enable firewall output.
+  IPFIREWALL_VERBOSE_LIMIT - limit firewall output.
+  DUMMYNET                 - enable dummynet operation.
+  NMBCLUSTER               - set the amount of network packet buffers
+  HZ                       - sets the timer granularity
+.Ed
+.Pp
+Generally, the following options are required:
+.Bd -literal
+  options IPFIREWALL
+  options DUMMYNET
+.Ed
+
+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.
+
+
+.Sh SYSCTL VARIABLES
+.Pp
+.Bd -literal
+    net.inet.ip.fw.one_pass
+.Ed
+
+is set to 1 if we want packets to pass through the firewall code only
+once.
+.Bd -literal
+   net.link.ether.bridge_ipfw
+.Ed
+
+is set if we want bridged packets to pass through the firewall code.
+
+.Sh COMMANDS
+The following socket options are used to manage pipes:
+.Pp
+IP_DUMMYNET_CONFIGURE updates a pipe configuration (or creates a
+new one.
+.Pp
+IP_DUMMYNET_DEL deletes all pipes having the matching rule number.
+.Pp
+IP_DUMMYNET_GET returns the pipes matching the number.
+.Pp
+IP_FW_FLUSH flushes the pipes matching the number.
+.Pp
+When the kernel security level is greater than 2, only IP_DUMMYNET_GET
+is allowed.
+.Sh SEE ALSO
+.Xr setsockopt 2 ,
+.Xr ip 4 ,
+.Xr ipfw 8 ,
+.Xr sysctl 8 .
+.Sh BUGS
+This manpage is not illustrating all the possible ways to use
+dummynet.
+.Sh HISTORY
+.Nm
+dummynet
+was initially implemented as a testing tool for TCP congestion control
+by Luigi Rizzo <luigi@iet.unipi.it>, 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 filter.