From owner-freebsd-doc@FreeBSD.ORG Sun Sep 23 23:10:02 2007 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 5A9F016A419 for ; Sun, 23 Sep 2007 23:10:02 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 168CD13C448 for ; Sun, 23 Sep 2007 23:10:02 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.14.1/8.14.1) with ESMTP id l8NNA1J5018876 for ; Sun, 23 Sep 2007 23:10:02 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.1/8.14.1/Submit) id l8NNA1T8018875; Sun, 23 Sep 2007 23:10:01 GMT (envelope-from gnats) Resent-Date: Sun, 23 Sep 2007 23:10:01 GMT Resent-Message-Id: <200709232310.l8NNA1T8018875@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Cristian KLEIN Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 3F2EC16A421 for ; Sun, 23 Sep 2007 23:05:29 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21]) by mx1.freebsd.org (Postfix) with ESMTP id 0C10B13C465 for ; Sun, 23 Sep 2007 23:05:29 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (localhost [127.0.0.1]) by www.freebsd.org (8.14.1/8.14.1) with ESMTP id l8NN5S6A085259 for ; Sun, 23 Sep 2007 23:05:28 GMT (envelope-from nobody@www.freebsd.org) Received: (from nobody@localhost) by www.freebsd.org (8.14.1/8.14.1/Submit) id l8NN5SY9085258; Sun, 23 Sep 2007 23:05:28 GMT (envelope-from nobody) Message-Id: <200709232305.l8NN5SY9085258@www.freebsd.org> Date: Sun, 23 Sep 2007 23:05:28 GMT From: Cristian KLEIN To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.1 Cc: Subject: docs/116588: No IPFW tables or dummynet in Handbook X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 23 Sep 2007 23:10:02 -0000 >Number: 116588 >Category: docs >Synopsis: No IPFW tables or dummynet in Handbook >Confidential: no >Severity: serious >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Sun Sep 23 23:10:01 GMT 2007 >Closed-Date: >Last-Modified: >Originator: Cristian KLEIN >Release: 5.5-RELEASE-p13 >Organization: Technical University of Cluj-Napoca >Environment: FreeBSD blah 5.5-RELEASE-p13 FreeBSD 5.5-RELEASE-p13 #2: Thu Jun 28 21:47:16 EEST 2007 cristi@blah:/usr/obj/usr/src/sys/HOSTING-ROUTER i386 >Description: The handbook does not mention anything about how to configure dummynet or how to use tables in IPFW. I personally consider that these two things add a lot of value to IPFW and a least some examples must be included in the Handbook. >How-To-Repeat: >Fix: Apply the attached patch like this: cd /usr/doc/books/handbook/firewalls patch < ipfw-dummynet-tables.patch cd .. make Patch attached with submission follows: --- chapter.sgml.orig Mon Sep 24 00:38:28 2007 +++ chapter.sgml Mon Sep 24 02:02:55 2007 @@ -3355,7 +3355,160 @@ ################ End of IPFW rules file ############################### + + + Using Dummy + + Dummynet is a traffic shaper, bandwidth manager and delay emulator which may + be used to simulate different types of physical links. It can also be + "misused" as a traffic shaper. + + Dummynet offers two objects. Pipes are an abstraction of a given link, having + a certain bandwidth, delay and loss. Queue are an abstraction used to implement + weighted fair queuing. In practice, pipes can be used to set hard limits to the + bandwidth that a flow can use, wheres queues can be used to determine how different + flows share that bandwidth. + + Please note that, in order for dummynet to work correctly, it is highly recommended to + increase the system clock tick. This can be accomplished by adding the following kernel option: + options HZ=1000 + + Use the following command to configure a pipe which has 4Kbps + and a 100ms delay: + &prompt.root; ipfw pipe 10 config bw 4Kbit/s delay 100 + + To use this pipe, i.e. have some traffic go through it, use the following command: + &prompt.root; ipfw -q add pipe 10 all from 10.0.0.0/24 to any + + Please note that to properly limit users, one should create separate pipes for download and upload. + + + Using the above pipe configuration, all LAN users compete for the + same bandwidth. If you would like to assign each of them 4Kbps + download and upload, you may create dynamic pipes based on the + source IP (for uplink) or destination IP (for downlink): + &prompt.root; ipfw pipe 10 config bw 4Kbit/s src-ip 0xffffffff +&prompt.root; ipfw pipe 11 config bw 4Kbit/s dst-ip 0xffffffff +&prompt.root; ipfw -q add pipe 10 all from any to any recv $if_lan +&prompt.root; ipfw -q add pipe 11 all from any to any xmit $if_lan + + + + + Using Tables + + Tables are a way of refering to multiple IP addresses + using a single identifier. They are useful in the following + situations: + + + + you must apply the same rule to a lot of IP addresses + (table lookups are fast) + + + you must apply a lot of rules to some IP addresses + (use tables to add / remove IP addresses from a single location + in the ruleset) + + + + IP addresses contained in a table may also have an optional 32-bit unsigned value + assigned to it. A rule may be written in such a way that it will only match if the IP + found in a table has been assigned a specific value. + + These are the commands used to manipulate tables from the shell: + + Clear all IPs from a table: + &prompt.root; ipfw table 10 flush + + Add a single IP address to a table: + &prompt.root; ipfw table 10 add 172.27.0.1 + + Add a CIDR network to a table: + &prompt.root; ipfw table 10 add 192.168.0.0/24 + + Add a CIDR network to a table and also assign a value to it: + &prompt.root; ipfw table 10 add 192.168.0.0/24 100 + + List the contents of a table: + &prompt.root; ipfw table 10 list + + To use the table in a firewall rule, type something like this: + &prompt.root; ipfw -q add allow tcp from "table(10)" to any + + Or, to use the table and the value in a firewall rule, type something like this: + &prompt.root; ipfw -q add allow tcp from "table(10,100)" to any + + The following listing is an example of how one could use tables in a ruleset: + + #!/bin/sh +# Flush out the list before we begin. +ipfw -q -f flush + +# Set rules command prefix +cmd="ipfw -q add" +table="ipfw -q table" + +# Create a table with all IPs allowed to connect to SSH +$table 1 flush # required +$table 1 add 172.27.0.1 # single IP address +$table 1 add 192.168.0.0/24 # CIDR network + +# Actual rule which allows SSH +$cmd allow from "table(1)" to me 22 keep-state + +# Deny everything else +$cmd deny from any to any + + Here is another example, in which tables and values are used + to group clients into multiple bandwidth limitations + depending on their subscription: + + #!/bin/sh +# Flush out the list before we begin. +ipfw -q -f flush + +# Set rules command prefix +cmd="ipfw -q add" +table="ipfw -q table" +pipe="ipfw -q pipe" +if_net="em0" + +# +# Pipes +# + +# Please note that dynamic pipes will be created for each client. +# In other words, clients DO NOT compete for the bandwidth. + +# First subscription rate. +$pipe 10 config queue 10 bw 512Kbit/s mask src-ip 0xffffffff # uplink +$pipe 11 config queue 10 bw 512Kbit/s mask dst-ip 0xffffffff # downlink + +# Second subscription rate. +$pipe 20 config queue 10 bw 768Kbit/s mask src-ip 0xffffffff # uplink +$pipe 21 config queue 10 bw 768Kbit/s mask dst-ip 0xffffffff # downlink + +# Create a table with all IPs allowed to have Internet connection. +# Note that although it is not required, values are the same +# as the bandwidth which will be given to the client. +$table 1 flush # required +$table 1 add 172.27.0.2 512 # 512Kbps client +$table 1 add 172.27.0.3 768 # 768Kbps client +$table 1 add 172.27.0.4 512 # 512Kbps client + +# Actual rules which classify the traffic +$cmd pipe 10 all from "table(1,512)" to any xmit $if_net +$cmd pipe 11 all from any to "table(1,512)" recv $if_net +$cmd pipe 20 all from "table(1,768)" to any xmit $if_net +$cmd pipe 21 all from any to "table(1,768)" recv $if_net + +# Deny everything else +$cmd deny all from any to any + +