1 2This documented is slightly dated but should give you idea of how things 3work. 4 5What is it? 6----------- 7 8An extension to the filtering/classification architecture of Linux Traffic 9Control. 10Up to 2.6.8 the only action that could be "attached" to a filter was policing. 11i.e you could say something like: 12 13----- 14tc filter add dev lo parent ffff: protocol ip prio 10 u32 match ip src \ 15127.0.0.1/32 flowid 1:1 police mtu 4000 rate 1500kbit burst 90k 16----- 17 18which implies "if a packet is seen on the ingress of the lo device with 19a source IP address of 127.0.0.1/32 we give it a classification id of 1:1 and 20we execute a policing action which rate limits its bandwidth utilization 21to 1.5Mbps". 22 23The new extensions allow for more than just policing actions to be added. 24They are also fully backward compatible. If you have a kernel that doesnt 25understand them, then the effect is null i.e if you have a newer tc 26but older kernel, the actions are not installed. Likewise if you 27have a newer kernel but older tc, obviously the tc will use current 28syntax which will work fine. Of course to get the required effect you need 29both newer tc and kernel. If you are reading this you have the 30right tc ;-> 31 32A side effect is that we can now get stateless firewalling to work with tc. 33Essentially this is now an alternative to iptables. 34I wont go into details of my dislike for iptables at times, but 35scalability is one of the main issues; however, if you need stateful 36classification - use netfilter (for now). 37 38This stuff works on both ingress and egress qdiscs. 39 40Features 41-------- 42 431) new additional syntax and actions enabled. Note old syntax is still valid. 44 45Essentially this is still the same syntax as tc with a new construct 46"action". The syntax is of the form: 47tc filter add <DEVICE> parent 1:0 protocol ip prio 10 <Filter description> 48flowid 1:1 action <ACTION description>* 49 50You can have as many actions as you want (within sensible reasoning). 51 52In the past the only real action was the policer; i.e you could do something 53along the lines of: 54tc filter add dev lo parent ffff: protocol ip prio 10 u32 \ 55match ip src 127.0.0.1/32 flowid 1:1 \ 56police mtu 4000 rate 1500kbit burst 90k 57 58Although you can still use the same syntax, now you can say: 59 60tc filter add dev lo parent 1:0 protocol ip prio 10 u32 \ 61match ip src 127.0.0.1/32 flowid 1:1 \ 62action police mtu 4000 rate 1500kbit burst 90k 63 64" generic Actions" (gact) at the moment are: 65{ drop, pass, reclassify, continue} 66(If you have others, no listed here give me a reason and we will add them) 67+drop says to drop the packet 68+pass and ok (are equivalent) says to accept it 69+reclassify requests for reclassification of the packet 70+continue requests for next lookup to match 71 722)In order to take advantage of some of the targets written by the 73iptables people, a classifier can have a packet being massaged by an 74iptable target. I have only tested with mangler targets up to now. 75(infact anything that is not in the mangling table is disabled right now) 76 77In terms of hooks: 78*ingress is mapped to pre-routing hook 79*egress is mapped to post-routing hook 80I dont see much value in the other hooks, if you see it and email me good 81reasons, the addition is trivial. 82 83Example syntax for iptables targets usage becomes: 84tc filter add ..... u32 <u32 syntax> action ipt -j <iptables target syntax> 85 86example: 87tc filter add dev lo parent ffff: protocol ip prio 8 u32 \ 88match ip dst 127.0.0.8/32 flowid 1:12 \ 89action ipt -j mark --set-mark 2 90 91NOTE: flowid 1:12 is parsed flowid 0x1:0x12. Make sure if you want flowid 92decimal 12, then use flowid 1:c. 93 943) A feature i call pipe 95The motivation is derived from Unix pipe mechanism but applied to packets. 96Essentially take a matching packet and pass it through 97action1 | action2 | action3 etc. 98You could do something similar to this with the tc policer and the "continue" 99operator but this rather restricts it to just the policer and requires 100multiple rules (and lookups, hence quiet inefficient); 101 102as an example -- and please note that this is just an example _not_ The 103Word Youve Been Waiting For (yes i have had problems giving examples 104which ended becoming dogma in documents and people modifying them a little 105to look clever); 106 107i selected the metering rates to be small so that i can show better how 108things work. 109 110The script below does the following: 111- an incoming packet from 10.0.0.21 is first given a firewall mark of 1. 112 113- It is then metered to make sure it does not exceed its allocated rate of 1141Kbps. If it doesnt exceed rate, this is where we terminate action execution. 115 116- If it does exceed its rate, its "color" changes to a mark of 2 and it is 117then passed through a second meter. 118 119-The second meter is shared across all flows on that device [i am suprised 120that this seems to be not a well know feature of the policer; Bert was telling 121me that someone was writing a qdisc just to do sharing across multiple devices; 122it must be the summer heat again; weve had someone doing that every year around 123summer -- the key to sharing is to use a operator "index" in your policer 124rules (example "index 20"). All your rules have to use the same index to 125share.] 126 127-If the second meter is exceeded the color of the flow changes further to 3. 128 129-We then pass the packet to another meter which is shared across all devices 130in the system. If this meter is exceeded we drop the packet. 131 132Note the mark can be used further up the system to do things like policy 133or more interesting things on the egress. 134 135------------------ cut here ------------------------------- 136# 137# Add an ingress qdisc on eth0 138tc qdisc add dev eth0 ingress 139# 140#if you see an incoming packet from 10.0.0.21 141tc filter add dev eth0 parent ffff: protocol ip prio 1 \ 142u32 match ip src 10.0.0.21/32 flowid 1:15 \ 143# 144# first give it a mark of 1 145action ipt -j mark --set-mark 1 index 2 \ 146# 147# then pass it through a policer which allows 1kbps; if the flow 148# doesnt exceed that rate, this is where we stop, if it exceeds we 149# pipe the packet to the next action 150action police rate 1kbit burst 9k pipe \ 151# 152# which marks the packet fwmark as 2 and pipes 153action ipt -j mark --set-mark 2 \ 154# 155# next attempt to borrow b/width from a meter 156# used across all flows incoming on eth0("index 30") 157# and if that is exceeded we pipe to the next action 158action police index 30 mtu 5000 rate 1kbit burst 10k pipe \ 159# mark it as fwmark 3 if exceeded 160action ipt -j mark --set-mark 3 \ 161# and then attempt to borrow from a meter used by all devices in the 162# system. Should this be exceeded, drop the packet on the floor. 163action police index 20 mtu 5000 rate 1kbit burst 90k drop 164--------------------------------- 165 166Now lets see the actions installed with 167"tc filter show parent ffff: dev eth0" 168 169-------- output ----------- 170jroot# tc filter show parent ffff: dev eth0 171filter protocol ip pref 1 u32 172filter protocol ip pref 1 u32 fh 800: ht divisor 1 173filter protocol ip pref 1 u32 fh 800::800 order 2048 key ht 800 bkt 0 flowid 1:15 174 175 action order 1: tablename: mangle hook: NF_IP_PRE_ROUTING 176 target MARK set 0x1 index 2 177 178 action order 2: police 1 action pipe rate 1Kbit burst 9Kb mtu 2Kb 179 180 action order 3: tablename: mangle hook: NF_IP_PRE_ROUTING 181 target MARK set 0x2 index 1 182 183 action order 4: police 30 action pipe rate 1Kbit burst 10Kb mtu 5000b 184 185 action order 5: tablename: mangle hook: NF_IP_PRE_ROUTING 186 target MARK set 0x3 index 3 187 188 action order 6: police 20 action drop rate 1Kbit burst 90Kb mtu 5000b 189 190 match 0a000015/ffffffff at 12 191------------------------------- 192 193Note the ordering of the actions is based on the order in which we entered 194them. In the future i will add explicit priorities. 195 196Now lets run a ping -f from 10.0.0.21 to this host; stop the ping after 197you see a few lines of dots 198 199---- 200[root@jzny hadi]# ping -f 10.0.0.22 201PING 10.0.0.22 (10.0.0.22): 56 data bytes 202.................................................................................................................................................................................................................................................................................................................................................................................................................................................... 203--- 10.0.0.22 ping statistics --- 2042248 packets transmitted, 1811 packets received, 19% packet loss 205round-trip min/avg/max = 0.7/9.3/20.1 ms 206----------------------------- 207 208Now lets take a look at the stats with "tc -s filter show parent ffff: dev eth0" 209 210-------------- 211jroot# tc -s filter show parent ffff: dev eth0 212filter protocol ip pref 1 u32 213filter protocol ip pref 1 u32 fh 800: ht divisor 1 214filter protocol ip pref 1 u32 fh 800::800 order 2048 key ht 800 bkt 0 flowid 1:1 2155 216 217 action order 1: tablename: mangle hook: NF_IP_PRE_ROUTING 218 target MARK set 0x1 index 2 219 Sent 188832 bytes 2248 pkts (dropped 0, overlimits 0) 220 221 action order 2: police 1 action pipe rate 1Kbit burst 9Kb mtu 2Kb 222 Sent 188832 bytes 2248 pkts (dropped 0, overlimits 2122) 223 224 action order 3: tablename: mangle hook: NF_IP_PRE_ROUTING 225 target MARK set 0x2 index 1 226 Sent 178248 bytes 2122 pkts (dropped 0, overlimits 0) 227 228 action order 4: police 30 action pipe rate 1Kbit burst 10Kb mtu 5000b 229 Sent 178248 bytes 2122 pkts (dropped 0, overlimits 1945) 230 231 action order 5: tablename: mangle hook: NF_IP_PRE_ROUTING 232 target MARK set 0x3 index 3 233 Sent 163380 bytes 1945 pkts (dropped 0, overlimits 0) 234 235 action order 6: police 20 action drop rate 1Kbit burst 90Kb mtu 5000b 236 Sent 163380 bytes 1945 pkts (dropped 0, overlimits 437) 237 238 match 0a000015/ffffffff at 12 239------------------------------- 240 241Neat, eh? 242 243 244Wanna write an action module? 245------------------------------ 246Its easy. Either look at the code or send me email. I will document at 247some point; will also accept documentation. 248 249TODO 250---- 251 252Lotsa goodies/features coming. Requests also being accepted. 253At the moment the focus has been on getting the architecture in place. 254Expect new things in the spurious time i have to work on this 255(particularly around end of year when i have typically get time off 256from work). 257 258