| 1 |
.TH "Flow filter in tc" 8 "20 Oct 2015" "iproute2" "Linux" |
| 2 |
|
| 3 |
.SH NAME |
| 4 |
flow \- flow based traffic control filter |
| 5 |
.SH SYNOPSIS |
| 6 |
.TP |
| 7 |
Mapping mode: |
| 8 |
|
| 9 |
.RS |
| 10 |
.in +8 |
| 11 |
.ti -8 |
| 12 |
.BR tc " " filter " ... " "flow map key " |
| 13 |
.IR KEY " [ " OPS " ] [ " OPTIONS " ] " |
| 14 |
.RE |
| 15 |
.TP |
| 16 |
Hashing mode: |
| 17 |
|
| 18 |
.RS |
| 19 |
.in +8 |
| 20 |
.ti -8 |
| 21 |
.BR tc " " filter " ... " "flow hash keys " |
| 22 |
.IR KEY_LIST " [ " |
| 23 |
.B perturb |
| 24 |
.IR secs " ] [ " OPTIONS " ] " |
| 25 |
.RE |
| 26 |
|
| 27 |
.in +8 |
| 28 |
.ti -8 |
| 29 |
.IR OPS " := [ " OPS " ] " OP |
| 30 |
|
| 31 |
.ti -8 |
| 32 |
.IR OPTIONS " := [ " |
| 33 |
.B divisor |
| 34 |
.IR NUM " ] [ " |
| 35 |
.B baseclass |
| 36 |
.IR ID " ] [ " |
| 37 |
.B match |
| 38 |
.IR EMATCH_TREE " ] [ " |
| 39 |
.B action |
| 40 |
.IR ACTION_SPEC " ]" |
| 41 |
|
| 42 |
.ti -8 |
| 43 |
.IR KEY_LIST " := [ " KEY_LIST " ] " KEY |
| 44 |
|
| 45 |
.ti -8 |
| 46 |
.IR OP " := { " |
| 47 |
.BR or " | " and " | " xor " | " rshift " | " addend " } " |
| 48 |
.I NUM |
| 49 |
|
| 50 |
.ti -8 |
| 51 |
.IR ID " := " X : Y |
| 52 |
|
| 53 |
.ti -8 |
| 54 |
.IR KEY " := { " |
| 55 |
.BR src " | " dst " | " proto " | " proto-src " | " proto-dst " | " iif " | " |
| 56 |
.BR priority " | " mark " | " nfct " | " nfct-src " | " nfct-dst " | " |
| 57 |
.BR nfct-proto-src " | " nfct-proto-dst " | " rt-classid " | " sk-uid " | " |
| 58 |
.BR sk-gid " | " vlan-tag " | " rxhash " }" |
| 59 |
.SH DESCRIPTION |
| 60 |
The |
| 61 |
.B flow |
| 62 |
classifier is meant to extend the |
| 63 |
.B SFQ |
| 64 |
hashing capabilities without hard-coding new hash functions. It also allows |
| 65 |
deterministic mappings of keys to classes. |
| 66 |
.SH OPTIONS |
| 67 |
.TP |
| 68 |
.BI action " ACTION_SPEC" |
| 69 |
Apply an action from the generic actions framework on matching packets. |
| 70 |
.TP |
| 71 |
.BI baseclass " ID" |
| 72 |
An offset for the resulting class ID. |
| 73 |
.I ID |
| 74 |
may be |
| 75 |
.BR root ", " none |
| 76 |
or a hexadecimal class ID in the form [\fIX\fB:\fR]\fIY\fR. \fIX\fR must |
| 77 |
match qdisc's/class's major handle (if omitted, the correct value is chosen |
| 78 |
automatically). If the whole \fBbaseclass\fR is omitted, \fIY\fR defaults |
| 79 |
to 1. |
| 80 |
.TP |
| 81 |
.BI divisor " NUM" |
| 82 |
Number of buckets to use for sorting into. Keys are calculated modulo |
| 83 |
.IR NUM . |
| 84 |
.TP |
| 85 |
.BI "hash keys " KEY-LIST |
| 86 |
Perform a |
| 87 |
.B jhash2 |
| 88 |
operation over the keys in |
| 89 |
.IR KEY-LIST , |
| 90 |
the result (modulo the |
| 91 |
.B divisor |
| 92 |
if given) is taken as class ID, optionally offset by the value of |
| 93 |
.BR baseclass . |
| 94 |
It is possible to specify an interval (in seconds) after which |
| 95 |
.BR jhash2 's |
| 96 |
entropy source is recreated using the |
| 97 |
.B perturb |
| 98 |
parameter. |
| 99 |
.TP |
| 100 |
.BI "map key " KEY |
| 101 |
Packet data identified by |
| 102 |
.I KEY |
| 103 |
is translated into class IDs to push the packet into. The value may be mangled by |
| 104 |
.I OPS |
| 105 |
before using it for the mapping. They are applied in the order listed here: |
| 106 |
.RS |
| 107 |
.TP 4 |
| 108 |
.BI and " NUM" |
| 109 |
Perform bitwise |
| 110 |
.B AND |
| 111 |
operation with numeric value |
| 112 |
.IR NUM . |
| 113 |
.TP |
| 114 |
.BI or " NUM" |
| 115 |
Perform bitwise |
| 116 |
.B OR |
| 117 |
operation with numeric value |
| 118 |
.IR NUM . |
| 119 |
.TP |
| 120 |
.BI xor " NUM" |
| 121 |
Perform bitwise |
| 122 |
.B XOR |
| 123 |
operation with numeric value |
| 124 |
.IR NUM . |
| 125 |
.TP |
| 126 |
.BI rshift " NUM" |
| 127 |
Shift the value of |
| 128 |
.I KEY |
| 129 |
to the right by |
| 130 |
.I NUM |
| 131 |
bits. |
| 132 |
.TP |
| 133 |
.BI addend " NUM" |
| 134 |
Add |
| 135 |
.I NUM |
| 136 |
to the value of |
| 137 |
.IR KEY . |
| 138 |
|
| 139 |
.RE |
| 140 |
.RS |
| 141 |
For the |
| 142 |
.BR or ", " and ", " xor " and " rshift |
| 143 |
operations, |
| 144 |
.I NUM |
| 145 |
is assumed to be an unsigned, 32bit integer value. For the |
| 146 |
.B addend |
| 147 |
operation, |
| 148 |
.I NUM |
| 149 |
may be much more complex: It may be prefixed by a minus ('-') sign to cause |
| 150 |
subtraction instead of addition and for keys of |
| 151 |
.BR src ", " dst ", " nfct-src " and " nfct-dst |
| 152 |
it may be given in IP address notation. See below for an illustrating example. |
| 153 |
.RE |
| 154 |
.TP |
| 155 |
.BI match " EMATCH_TREE" |
| 156 |
Match packets using the extended match infrastructure. See |
| 157 |
.BR tc-ematch (8) |
| 158 |
for a detailed description of the allowed syntax in |
| 159 |
.IR EMATCH_TREE . |
| 160 |
.SH KEYS |
| 161 |
In mapping mode, a single key is used (after optional permutation) to build a |
| 162 |
class ID. The resulting ID is deducible in most cases. In hashing more, a number |
| 163 |
of keys may be specified which are then hashed and the output used as class ID. |
| 164 |
This ID is not deducible in beforehand, and may even change over time for a |
| 165 |
given flow if a |
| 166 |
.B perturb |
| 167 |
interval has been given. |
| 168 |
|
| 169 |
The range of class IDs can be limited by the |
| 170 |
.B divisor |
| 171 |
option, which is used for a modulus. |
| 172 |
.TP |
| 173 |
.BR src ", " dst |
| 174 |
Use source or destination address as key. In case of IPv4 and TIPC, this is the |
| 175 |
actual address value. For IPv6, the 128bit address is folded into a 32bit value |
| 176 |
by XOR'ing the four 32bit words. In all other cases, the kernel-internal socket |
| 177 |
address is used (after folding into 32bits on 64bit systems). |
| 178 |
.TP |
| 179 |
.B proto |
| 180 |
Use the layer four protocol number as key. |
| 181 |
.TP |
| 182 |
.B proto-src |
| 183 |
Use the layer four source port as key. If not available, the kernel-internal |
| 184 |
socket address is used instead. |
| 185 |
.TP |
| 186 |
.B proto-dst |
| 187 |
Use the layer four destination port as key. If not available, the associated |
| 188 |
kernel-internal dst_entry address is used after XOR'ing with the packet's |
| 189 |
layer three protocol number. |
| 190 |
.TP |
| 191 |
.B iif |
| 192 |
Use the incoming interface index as key. |
| 193 |
.TP |
| 194 |
.B priority |
| 195 |
Use the packet's priority as key. Usually this is the IP header's DSCP/ECN |
| 196 |
value. |
| 197 |
.TP |
| 198 |
.B mark |
| 199 |
Use the netfilter |
| 200 |
.B fwmark |
| 201 |
as key. |
| 202 |
.TP |
| 203 |
.B nfct |
| 204 |
Use the associated conntrack entry address as key. |
| 205 |
.TP |
| 206 |
.BR nfct-src ", " nfct-dst ", " nfct-proto-src ", " nfct-proto-dst |
| 207 |
These are conntrack-aware variants of |
| 208 |
.BR src ", " dst ", " proto-src " and " proto-dst . |
| 209 |
In case of NAT, these are basically the packet header's values before NAT was |
| 210 |
applied. |
| 211 |
.TP |
| 212 |
.B rt-classid |
| 213 |
Use the packet's destination routing table entry's realm as key. |
| 214 |
.TP |
| 215 |
.B sk-uid |
| 216 |
.TQ |
| 217 |
.B sk-gid |
| 218 |
For locally generated packets, use the user or group ID the originating socket |
| 219 |
belongs to as key. |
| 220 |
.TP |
| 221 |
.B vlan-tag |
| 222 |
Use the packet's vlan ID as key. |
| 223 |
.TP |
| 224 |
.B rxhash |
| 225 |
Use the flow hash as key. |
| 226 |
|
| 227 |
.SH EXAMPLES |
| 228 |
.TP |
| 229 |
Classic SFQ hash: |
| 230 |
|
| 231 |
.EX |
| 232 |
tc filter add ... flow hash \\ |
| 233 |
keys src,dst,proto,proto-src,proto-dst divisor 1024 |
| 234 |
.EE |
| 235 |
.TP |
| 236 |
Classic SFQ hash, but using information from conntrack to work properly in combination with NAT: |
| 237 |
|
| 238 |
.EX |
| 239 |
tc filter add ... flow hash \\ |
| 240 |
keys nfct-src,nfct-dst,proto,nfct-proto-src,nfct-proto-dst \\ |
| 241 |
divisor 1024 |
| 242 |
.EE |
| 243 |
.TP |
| 244 |
Map destination IPs of 192.168.0.0/24 to classids 1-256: |
| 245 |
|
| 246 |
.EX |
| 247 |
tc filter add ... flow map \\ |
| 248 |
key dst addend -192.168.0.0 divisor 256 |
| 249 |
.EE |
| 250 |
.TP |
| 251 |
Alternative to the above: |
| 252 |
|
| 253 |
.EX |
| 254 |
tc filter add ... flow map \\ |
| 255 |
key dst and 0xff |
| 256 |
.EE |
| 257 |
.TP |
| 258 |
The same, but in reverse order: |
| 259 |
|
| 260 |
.EX |
| 261 |
tc filter add ... flow map \\ |
| 262 |
key dst and 0xff xor 0xff |
| 263 |
.EE |
| 264 |
.SH SEE ALSO |
| 265 |
.BR tc (8), |
| 266 |
.BR tc-ematch (8), |
| 267 |
.BR tc-sfq (8) |