From 9a96729c64314fe64d4681d6c27cd84cfdd70592 Mon Sep 17 00:00:00 2001 From: Luigi Rizzo Date: Mon, 28 Oct 2002 07:24:58 +0000 Subject: [PATCH] Remove stale information from these two manpage, and point the readers to the one up-to-date page which is ipfw(8). MFC after: 3 days --- share/man/man4/dummynet.4 | 152 ++++-------------------------- share/man/man4/ipfirewall.4 | 183 ++++-------------------------------- 2 files changed, 36 insertions(+), 299 deletions(-) diff --git a/share/man/man4/dummynet.4 b/share/man/man4/dummynet.4 index 84a930c707df..624f451ebdf5 100644 --- a/share/man/man4/dummynet.4 +++ b/share/man/man4/dummynet.4 @@ -1,120 +1,30 @@ .\" .\" $FreeBSD$ .\" -.Dd September 28, 1998 +.Dd October 28, 2002 .Dt DUMMYNET 4 .Os .Sh NAME .Nm dummynet -.Nd flexible bandwidth manager and delay emulator -.Sh SYNOPSIS -.In sys/types.h -.In sys/queue.h -.In netinet/in.h -.In netinet/ip_fw.h -.Ft int -.Fn setsockopt raw_socket IPPROTO_IP "ipfw option" "struct ipfw" size +.Nd traffic shaper, bandwidth manager and delay emulator .Sh DESCRIPTION -dummynet is a system facility that permits the control of traffic +.Em 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. +and queue size limitations, implementing different scheduling and queue +management policies, and emulating delays and losses. .Pp -In its current implementation, -packet selection is done with the +The user interface for +.Em dummynet +is implemented by the .Nm ipfw -program, by means of -.Dq pipe -rules. -A dummynet -.Em 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 -.Pp -and pipes are configured as follows: -.Bd -literal - ipfw pipe NNN config bw B delay D queue Q plr P -.Ed -.Pp -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 -.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 -.Ql net.inet.ip.fw.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 +program, so the reader is referred to the +.Xr ipfw 8 +manpage for a complete description of the capabilities of .Nm -performs its task once per timer tick. -The granularity of operation is -thus controlled by the kernel option -.Bd -literal - options HZ -.Ed -.Pp -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. +and on how to use it. .Sh KERNEL OPTIONS -The following options in the kernel configuration file are related -to +The following options in the kernel configuration file are related to .Nm operation: .Bd -literal @@ -130,49 +40,25 @@ Generally, the following options are required: .Bd -literal options IPFIREWALL options DUMMYNET + options HZ=1000 # strongly recommended .Ed .Pp 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 -.Ql net.inet.ip.fw.one_pass -is set to 1 if we want packets to pass through the firewall code only -once. -.Pp -.Ql net.link.ether.bridge_ipfw -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 bridge 4 , .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 was initially implemented as a testing tool for TCP congestion control by .An Luigi Rizzo Aq 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. +as described on ACM Computer Communication Review, Jan.97 issue. +Later it has been then modified to work at the ip and bridging +level, integrated with the IPFW packet filter, and extended to +support multiple queueing and scheduling policies. diff --git a/share/man/man4/ipfirewall.4 b/share/man/man4/ipfirewall.4 index 14c714ceb22f..3b4a6a6e2719 100644 --- a/share/man/man4/ipfirewall.4 +++ b/share/man/man4/ipfirewall.4 @@ -2,121 +2,31 @@ .\" $FreeBSD$ .\" .Dd June 22, 1997 -.Dt IPFIREWALL 4 +.Dt IPFW 4 .Os .Sh NAME -.Nm ipfirewall +.Nm ipfw .Nd IP packet filter and traffic accounting -.Sh SYNOPSIS -.In sys/types.h -.In sys/queue.h -.In netinet/in.h -.In netinet/ip_fw.h -.Ft int -.Fn setsockopt raw_socket IPPROTO_IP "ipfw option" "struct ipfw" size .Sh DESCRIPTION -Ipfirewall (alias ipfw) is a system facility which allows filtering, +.Em ipfw +is a system facility which allows filtering, redirecting, and other operations on IP packets travelling through system interfaces. -Packets are matched by applying an ordered list -of pattern rules against each packet until a match is found, at -which point the corresponding action is taken. -Rules are numbered -from 1 to 65534; multiple rules may share the same number. .Pp -There is one rule that always exists, rule number 65535. -This rule -normally causes all packets to be dropped. -Hence, any packet which does not -match a lower numbered rule will be dropped. However, a kernel compile -time option -.Dv IPFIREWALL_DEFAULT_TO_ACCEPT -allows the administrator to change this fixed rule to permit everything. +The user interface for +.Em ipfw +is implemented by the +.Nm ipfw +program, so the reader is referred to the +.Xr ipfw 8 +manpage for a complete description of the capabilities of +.Em ipfw +and how to use it. .Pp -The value passed to -.Fn setsockopt -is a struct ip_fw describing the rule (see below). -In some cases -(such as -.Dv IP_FW_DEL ) , -only the rule number is significant. -.Ss Commands -The following socket options are used to manage the rule list: -.Bl -tag -width "IP_FW_FLUSH" -.It Dv IP_FW_ADD -inserts the rule into the rule list -.It Dv IP_FW_DEL -deletes all rules having the matching rule number -.It Dv IP_FW_GET -returns the (first) rule having the matching rule number -.It Dv IP_FW_ZERO -zeros the statistics associated with all rules having the -matching rule number. -If the rule number is zero, all rules are zeroed. -.It Dv IP_FW_FLUSH -removes all rules (except 65535). -.El -.Pp -When the kernel security level is greater than 2, only -.Dv IP_FW_GET -is allowed. -.Ss Rule Structure -Rules are described by the structures in ip_fw.h. -.Ss Rule Actions -Each rule has an action described by the IP_FW_F_COMMAND bits in the -flags word: -.Bl -tag -width "IP_FW_F_DIVERT" -.It Dv IP_FW_F_DENY -Drop packet and stop processing. -.It Dv IP_FW_F_REJECT -drop packet; send rejection via ICMP or TCP and stop processing. -.It Dv IP_FW_F_ACCEPT -accept packet and stop processing. -.It Dv IP_FW_F_COUNT -increment counters; continue matching -.It Dv IP_FW_F_DIVERT -divert packet to a -.Xr divert 4 -socket and stop processing. -.It Dv IP_FW_F_TEE -Send a copy of this packet to a -.Xr divert 4 -socket and continue processing the original packet at the next rule. -.It Dv IP_FW_F_SKIPTO -skip to rule number -.Va fu_skipto_rule -At this time the target rule number must be greater than the active rule number. -.It Dv IP_FW_F_PIPE -The packet is marked for the use of -.Xr dummynet 4 , -and processing stopped. -.It Dv IP_FW_F_QUEUE -The packet is marked for the use of -.Xr dummynet 4 , -and processing stopped. -.It Dv IP_FW_F_FWD -The packet is accepted but the destination is hijacked. (see -.Xr ipfw 8 ) -.El -.Pp -In the case of -.Dv IP_FW_F_REJECT , -if the -.Va fu_reject_code -is a number -from 0 to 255, then an ICMP unreachable packet is sent back to the -original packet's source IP address, with the corresponding code. -Otherwise, the value must be 256 and the protocol -.Dv IPPROTO_TCP , -in which case a TCP reset packet is sent instead. -.Pp -With -.Dv IP_FW_F_SKIPTO , -all succeeding rules having rule number less -than -.Va fu_skipto_rule -are skipped. -.Ss Kernel Options +.Sh KERNEL OPTIONS +The following options in the kernel configuration file are related to +.Em ipfw +operation: Options in the kernel configuration file: .Bl -tag -width "options IPFIREWALL_VERBOSE_LIMIT" .It Cd options IPFIREWALL @@ -132,49 +42,6 @@ enable sockets .El .Pp -When packets match a rule with the -.Dv IP_FW_F_PRN -bit set, and if -.Dv IPFIREWALL_VERBOSE -has been enabled, -a message is written to -.Pa /dev/klog -with the -.Dv LOG_SECURITY -facility -(see -.Xr syslog 3 ) -for further logging by -.Xr syslogd 8 ; -.Dv IPFIREWALL_VERBOSE_LIMIT -limits the maximum number of times each -rule can cause a log message. -These variables are also -available via the -.Xr sysctl 3 -interface. -.Sh RETURN VALUES -The -.Fn setsockopt -function returns 0 on success. -Otherwise, -1 is returned and the global variable -.Va errno -is set to indicate the error. -.Sh ERRORS -The -.Fn setsockopt -function will fail if: -.Bl -tag -width Er -.It Bq Er EINVAL -The IP option field was improperly formed; -an option field was shorter than the minimum value -or longer than the option buffer provided. -.It Bq Er EINVAL -A structural error in ip_fw structure occurred -(n_src_p+n_dst_p too big, ports set for ALL/ICMP protocols etc.). -.It Bq Er EINVAL -An invalid rule number was used. -.El .Sh SEE ALSO .Xr setsockopt 2 , .Xr divert 4 , @@ -182,19 +49,3 @@ An invalid rule number was used. .Xr ipfw 8 , .Xr sysctl 8 , .Xr syslogd 8 -.Sh BUGS -This man page still needs work. -.Sh HISTORY -The ipfw facility was initially written as package to BSDI -by -.An Daniel Boulet -.Aq danny@BouletFermat.ab.ca . -It has been heavily modified and ported to -.Fx -by -.An Ugen J.S. Antsilevich -.Aq ugen@NetVision.net.il . -.Pp -Several enhancements added by -.An Archie Cobbs -.Aq archie@FreeBSD.org .