Copyright © 2001-2005 Thomas M. Eastep
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
2005-05-20
Shorewall does not do any type of Traffic Shaping/Bandwidth management itself but it does contain some facilities to intergrate with traffic shaping/control solutions. In order to use traffic shaping with Shorewall, it is essential that you get a copy of the Linux Advanced Routing and Shaping HOWTO, version 0.3.0 or later or The Traffic Control HOWTO. It is also necessary to be running Linux Kernel 2.4.18 or later. Shorewall traffic shaping support consists of the following:
A new TC_ENABLED parameter in /etc/shorewall.conf.
A new CLEAR_TC parameter in /etc/shorewall.conf (Added in Shorewall 1.3.13). When Traffic Shaping is enabled (TC_ENABLED=Yes), the setting of this variable determines whether Shorewall clears the traffic shaping configuration during Shorewall [re]start and Shorewall stop.
/etc/shorewall/tcrules - A file where you can specify firewall marking of packets. The firewall mark value may be used to classify packets for traffic shaping/control.
/etc/shorewall/tcstart - A user-supplied file that is sourced by Shorewall during “shorewall start” and which you can use to define your traffic shaping disciplines and classes. I have provided a sample that does table-driven CBQ shaping but if you read the traffic shaping sections of the HOWTO mentioned above, you can probably code your own faster than you can learn how to use my sample. I personally use HTB (see below). HTB support may eventually become an integral part of Shorewall since HTB is a lot simpler and better-documented than CBQ. As of 2.4.20, HTB is a standard part of the kernel but iproute2 must be patched in order to use it.
In tcstart, when you want to run the “tc” utility, use the run_tc function supplied by shorewall if you want tc errors to stop the firewall.
You can generally use off-the-shelf traffic shaping scripts by simply copying them to /etc/shorewall/tcstart. I use The Wonder Shaper (HTB version) that way (i.e., I just copied wshaper.htb to /etc/shorewall/tcstart and modified it according to the Wonder Shaper README). WARNING: If you use use Masquerading or SNAT (i.e., you only have one external IP address) then listing internal hosts in the NOPRIOHOSTSRC variable in the wshaper[.htb] script won't work. Traffic shaping occurs after SNAT has already been applied so when traffic shaping happens, all outbound traffic will have as a source address the IP addresss of your firewall's external interface.
/etc/shorewall/tcclear - A user-supplied file that is sourced by Shorewall when it is clearing traffic shaping. This file is normally not required as Shorewall's method of clearing qdisc and filter definitions is pretty general.
Shorewall allows you to start traffic shaping when Shorewall itself starts or it allows you to bring up traffic shaping when you bring up your interfaces.
To start traffic shaping when Shorewall starts:
Set TC_ENABLED=Yes and CLEAR_TC=Yes
Supply an /etc/shorewall/tcstart script to configure your traffic shaping rules.
Optionally supply an /etc/shorewall/tcclear script to stop traffic shaping. That is usually unnecessary.
If your tcstart script uses the “fwmark” classifier, you can mark packets using entries in /etc/shorewall/tcrules.
To start traffic shaping when you bring up your network interfaces, you will have to arrange for your traffic shaping configuration script to be run at that time. How you do that is distribution dependent and will not be covered here. You then should:
Set TC_ENABLED=Yes and CLEAR_TC=No
Do not supply /etc/shorewall/tcstart or /etc/shorewall/tcclear scripts.
If your tcstart script uses the “fwmark” classifier, you can mark packets using entries in /etc/shorewall/tcrules.
The fwmark classifier provides a convenient way to classify packets for traffic shaping. The /etc/shorewall/tcrules file provides a means for specifying these marks in a tabular fashion.
Normally, packet marking occurs in the PREROUTING chain before any address rewriting takes place. This makes it impossible to mark inbound packets based on their destination address when SNAT or Masquerading are being used. Beginning with Shorewall 1.3.12, you can cause packet marking to occur in the FORWARD chain by using the MARK_IN_FORWARD_CHAIN option in shorewall.conf.
Important
Unlike entries in /etc/shorewall/rules,
evaluation of entries in /etc/shorewall/tcrules
continues after a match. So the final mark assigned to each packet is
determined by the last matching entry
in the /etc/shorewall/tcrules file.
Important
If you use providers (in /etc/shorewall/providers) with the 'track' option then there are restrictions about how you can mark packets involving those providers; see the Shorewall Routing documentation for details.
Columns in the file are as follows:
MARK - Specifies the mark value is to be assigned in case of a match. This is an integer in the range 1-255. Beginning with Shorewall version 1.3.14, this value may be optionally followed by “:” and either “F” or “P” to designate that the marking will occur in the FORWARD or PREROUTING chains respectively. If this additional specification is omitted, the chain used to mark packets will be determined by the setting of the MARK_IN_FORWARD_CHAIN option in shorewall.conf.
This possible values in this field were expanded in Shorewall version 2.2.0:
If your kernel and iptables include CONNMARK support then you can also mark the connection rather than the packet
The mark value may be optionally followed by "/" and a mask value (used to determine those bits of the connection mark to actually be set).
The mark and optional mask are then followed by one of:
C: Mark the connection in the chain determined by the setting of MARK_IN_FORWARD_CHAIN CF: Mark the conneciton in the FORWARD chain CP: Mark the connection in the PREROUTING chain.
A classification of the form <major>:<minor> where <major> and <minor> are integers. Corresponds to the 'class' specification in these traffic shaping modules:
- atm - cbq - dsmark - pfifo_fast - htb - prio Classification always occurs in the POSTROUTING chain. This feature requires Shorewall 2.2.0 and requires that your kernel and iptables include CLASSIFY target support.
RESTORE[/mask] -- restore the packet's mark from the connection's mark using the supplied mask if any. Your kernel and iptables must include CONNMARK support. As iabove, may be followed by ":P" or ":F
SAVE[/mask] -- save the packet's mark to the connection's mark using the supplied mask if any. Your kernel and iptables must include CONNMARK support. As above, may be followed by ":P" or ":F
CONTINUE -- don't process any more marking rules in the table. As above, may be followed by ":P" or ":F".
SOURCE - The source of the packet. If the packet originates on the firewall, place “$FW” in this column. Otherwise, this is a comma-separated list of interface names, IP addresses, MAC addresses in Shorewall Format and/or Subnets.
Examples
eth0 192.168.2.4,192.168.1.0/24Beginning with Shorewall version 2.2.2, "$fw" may be optionally followed by a colon (":") and a host/net address or an address range.
DEST -- Destination of the packet. Comma-separated list of IP addresses and/or subnets.
PROTO - Protocol - Must be the name of a protocol from /etc/protocol, "ipp2p", a number or "all". For "ipp2p", your kernel and iptables must have ipp2p match support from Netfilter Patch_o_matic_ng.
PORT(S) - Destination Ports. A comma-separated list of Port names (from /etc/services), port numbers or port ranges (e.g., 21:22); if the protocol is “icmp”, this column is interpreted as the destination icmp type(s). If the protocol is "ipp2p", then this column is interpreted as an ipp2p option without the leading "--" (default "ipp2p"). For a list of value ipp2p options, as root type iptables -m ipp2p --help.
CLIENT PORT(S) (Renamed SOURCE PORT(S) in Shorewall 2.2.0) - (Optional) Source port(s). If omitted, any source port is acceptable. Specified as a comma-separate list of port names, port numbers or port ranges.
USER (Added in Shorewall version 1.4.10) - (Optional) This column may only be non-empty if the SOURCE is the firewall itself. When this column is non-empty, the rule applies only if the program generating the output is running under the effective user and/or group. It may contain :
[<user name or number>]:[<group name or number>]
The colon is optionnal when specifying only a user.
Examples : john: / john / :users / john:users
TEST (added in Shorewall version 2.2.0). Defines a test on the existing packet or connection mark. The rule will match only if the test returns true. Tests have the format
[!]<value>[/<mask>][:C]
where
! Inverts the test (not equal) <value> Value of the packet or connection mark. <mask> A mask to be applied to the mark before testing :C Designates a connection mark. If omitted, the packet mark's value is tested.
Example 1.
All packets arriving on eth1 should be marked with 1. All packets arriving on eth2 and eth3 should be marked with 2. All packets originating on the firewall itself should be marked with 3.
#MARK SOURCE DESTINATION PROTO PORT(S) SOURCE PORT(S) USER/GROUP TEST 1 eth1 0.0.0.0/0 all 2 eth2 0.0.0.0/0 all 2 eth3 0.0.0.0/0 all 3 fw 0.0.0.0/0 all
I am currently using the HTB version of The Wonder Shaper (I just copied wshaper.htb to /etc/shorewall/tcstart and modified it as shown in the Wondershaper README). WonderShaper DOES NOT USE THE /etc/shorewall/tcrules file.
I have also run with the following set of hand-crafted rules in my /etc/shorewall/tcstart file.
run_tc qdisc add dev eth0 root handle 1: htb default 30 run_tc class add dev eth0 parent 1: classid 1:1 htb rate 384kbit burst 15k echo “ Added Top Level Class -- rate 384kbit” run_tc class add dev eth0 parent 1:1 classid 1:10 htb rate 140kbit ceil 384kbit burst 15k prio 1 run_tc class add dev eth0 parent 1:1 classid 1:20 htb rate 224kbit ceil 384kbit burst 15k prio 0 run_tc class add dev eth0 parent 1:1 classid 1:30 htb rate 20kbit ceil 384kbit burst 15k quantum 1500 prio 1 echo “ Added Second Level Classes -- rates 140kbit, 224kbit, 20kbit” run_tc qdisc add dev eth0 parent 1:10 pfifo limit 5 run_tc qdisc add dev eth0 parent 1:20 pfifo limit 10 run_tc qdisc add dev eth0 parent 1:30 pfifo limit 5 echo “ Enabled PFIFO on Second Level Classes” run_tc filter add dev eth0 protocol ip parent 1:0 prio 1 handle 1 fw classid 1:10 run_tc filter add dev eth0 protocol ip parent 1:0 prio 0 handle 2 fw classid 1:20 run_tc filter add dev eth0 protocol ip parent 1:0 prio 1 handle 3 fw classid 1:30 echo “ Defined fwmark filters”
My tcrules file that went with this tcstart file is shown in Example 1 above. When I was using these rules:
I wanted to allow up to 140kbits/second for traffic outbound from my DMZ (eth1 -- note that the ceiling is set to 384kbit so outbound DMZ traffic can use all available bandwidth if there is no traffic from the local systems or from my laptop or firewall).
My laptop (which at that time connected via eth3) and local systems (eth2) could use up to 224kbits/second.
My firewall could use up to 20kbits/second.
Once www.shorewall.net was moved off-site, I no longer needed these shaping rules and The Wonder Shaper does all that I now require.