From 2a1314ea52b1d8bc3b4727f4910db0b885a00922 Mon Sep 17 00:00:00 2001 From: luigi Date: Mon, 21 Dec 1998 22:37:53 +0000 Subject: Add manpages for dummynet and bridging --- share/man/man4/Makefile | 3 +- share/man/man4/bridge.4 | 65 +++++++++++++++++ share/man/man4/dummynet.4 | 182 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 249 insertions(+), 1 deletion(-) create mode 100644 share/man/man4/bridge.4 create mode 100644 share/man/man4/dummynet.4 diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 9eeabbd..32a73a2 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1,6 +1,7 @@ # @(#)Makefile 8.1 (Berkeley) 6/18/93 -MAN4= bpf.4 ccd.4 cd.4 ch.4 da.4 ddb.4 divert.4 drum.4 fd.4 fpa.4 \ +MAN4= bpf.4 bridge.4 ccd.4 cd.4 ch.4 da.4 ddb.4 divert.4 drum.4 \ + dummynet.4 fd.4 fpa.4 \ icmp.4 ifmib.4 iic.4 iicbb.4 iicbus.4 iicsmb.4 \ imm.4 inet.4 intro.4 ip.4 ipfirewall.4 \ lkm.4 lo.4 lpbb.4 natm.4 netintro.4 \ diff --git a/share/man/man4/bridge.4 b/share/man/man4/bridge.4 new file mode 100644 index 0000000..5482c0e --- /dev/null +++ b/share/man/man4/bridge.4 @@ -0,0 +1,65 @@ +.\" +.\" $Id$ +.\" +.Dd Sep 28, 1998 +.Dt BRIDGE 4 +.Os +.Sh NAME +.Nm bridge +.Nd Bridging support +.Sh DESCRIPTION +Starting from version 2.2.8, FreeBSD supports bridging on ethernet-type +interfaces. This is achieved using the following option +.Bd -literal + options BRIDGE +.Ed + +in the kernel config file, and is controlled by two +.Nm sysctl +variables: +.Bd -literal + net.link.ether.bridge +.Ed + +Set to 1 to enable bridging, set to 0 to disable it +.Bd -literal + net.link.ether.bridge_ipfw +.Ed + +Set to 1 to enable +.Nm ipfw +filtering on bridged packets. Note that +.Nm ipfw +rules only apply +to IP packets. Non-IP packets are subject to the default +.Nm ipfw +rule (number 65535) which must be an +.Ar allow +rule if we want ARP and other non-IP packets to flow through the +bridge. + + +.Sh BUGS +.Pp +Care must be taken not to construct loops in the bridge topology. +The kernel supports only a primitive form of loop detection, by disabling +some interfaces when a loop is detected. No support for a daemon running the +spanning tree algorithm is currently provided. +.Pp +With bridging active, interfaces are in promiscuous mode, +thus causing some load on the system to receive and filter +out undesired traffic. +.Pp +Extended functionality to enable bridging selectively on clusters +of interfaces is still in the works. +.Pp +Not all interface support bridging -- at the moment it works for +``ed'', ``de'', ``ep'', ``fxp'', ``lnc'' interfaces. +.Sh SEE ALSO +.Xr ip 4 , +.Xr ipfw 8 , +.Xr sysctl 8 . +.Sh HISTORY +.Nm +bridging has been introduced in FreeBSD 2.2.8 +by Luigi Rizzo . 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 +.Fd #include +.Fd #include +.Fd #include +.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 , 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. -- cgit v1.1