docs/116588: No IPFW tables or dummynet in Handbook
Cristian KLEIN
cristi at net.utcluj.ro
Sun Sep 23 23:10:02 UTC 2007
>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 at 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 ###############################</programlisting>
</sect3>
</sect2>
+
+ <sect2 id="firewalls-ipfw-dummynet">
+ <title>Using Dummy</title>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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:</para>
+ <programlisting>options HZ=1000</programlisting>
+
+ <para>Use the following command to configure a pipe which has 4Kbps
+ and a 100ms delay:</para>
+ <screen>&prompt.root; <userinput>ipfw pipe 10 config bw 4Kbit/s delay 100</userinput></screen>
+
+ <para>To use this pipe, i.e. have some traffic go through it, use the following command:</para>
+ <screen>&prompt.root; <userinput>ipfw -q add pipe 10 all from 10.0.0.0/24 to any</userinput></screen>
+
+ <para>Please note that to properly limit users, one should create separate pipes for download and upload.
+ </para>
+
+ <para>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):</para>
+ <screen>&prompt.root; <userinput>ipfw pipe 10 config bw 4Kbit/s src-ip 0xffffffff</userinput>
+&prompt.root; <userinput>ipfw pipe 11 config bw 4Kbit/s dst-ip 0xffffffff</userinput>
+&prompt.root; <userinput>ipfw -q add pipe 10 all from any to any recv $if_lan</userinput>
+&prompt.root; <userinput>ipfw -q add pipe 11 all from any to any xmit $if_lan</userinput></screen>
+
+ </sect2>
+
+ <sect2 id="firewalls-ipfw-tables">
+ <title>Using Tables</title>
+
+ <para>Tables are a way of refering to multiple IP addresses
+ using a single identifier. They are useful in the following
+ situations:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>you must apply the same rule to a lot of IP addresses
+ (table lookups are fast)</para>
+ </listitem>
+ <listitem>
+ <para>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)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>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.</para>
+
+ <para>These are the commands used to manipulate tables from the shell:</para>
+
+ <para>Clear all IPs from a table:</para>
+ <screen>&prompt.root; <userinput>ipfw table 10 flush</userinput></screen>
+
+ <para>Add a single IP address to a table:</para>
+ <screen>&prompt.root; <userinput>ipfw table 10 add 172.27.0.1</userinput></screen>
+
+ <para>Add a CIDR network to a table:</para>
+ <screen>&prompt.root; <userinput>ipfw table 10 add 192.168.0.0/24</userinput></screen>
+
+ <para>Add a CIDR network to a table and also assign a value to it:</para>
+ <screen>&prompt.root; <userinput>ipfw table 10 add 192.168.0.0/24 100</userinput></screen>
+
+ <para>List the contents of a table:</para>
+ <screen>&prompt.root; <userinput>ipfw table 10 list</userinput></screen>
+
+ <para>To use the table in a firewall rule, type something like this:</para>
+ <screen>&prompt.root; <userinput>ipfw -q add allow tcp from "table(10)" to any</userinput></screen>
+
+ <para>Or, to use the table and the value in a firewall rule, type something like this:</para>
+ <screen>&prompt.root; <userinput>ipfw -q add allow tcp from "table(10,100)" to any</userinput></screen>
+
+ <para>The following listing is an example of how one could use tables in a ruleset:</para>
+
+ <programlisting>#!/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</programlisting>
+
+ <para>Here is another example, in which tables and values are used
+ to group clients into multiple bandwidth limitations
+ depending on their subscription:</para>
+
+ <programlisting>#!/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</programlisting>
+ </sect2>
</sect1>
+
</chapter>
<!--
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list