From 5703331fbb7957ff959aeda921b7aa28a78d2eb8 Mon Sep 17 00:00:00 2001 From: Phil Sutter Date: Thu, 18 Feb 2016 15:45:21 +0100 Subject: [PATCH] tc: add a man page for flow filter Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1286711 Upstream Status: iproute2.git commit 334ddc9b4d526 commit 334ddc9b4d526d0fe4487464c1c4e0c0fcb35a30 Author: Phil Sutter Date: Fri Oct 23 19:47:10 2015 +0200 tc: add a man page for flow filter Cc: Patrick McHardy Signed-off-by: Phil Sutter --- man/man8/tc-flow.8 | 265 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 man/man8/tc-flow.8 diff --git a/man/man8/tc-flow.8 b/man/man8/tc-flow.8 new file mode 100644 index 0000000..f1b7e2a --- /dev/null +++ b/man/man8/tc-flow.8 @@ -0,0 +1,265 @@ +.TH "Flow filter in tc" 8 "20 Oct 2015" "iproute2" "Linux" + +.SH NAME +flow \- flow based traffic control filter +.SH SYNOPSIS +.TP +Mapping mode: + +.RS +.in +8 +.ti -8 +.BR tc " " filter " ... " "flow map key " +.IR KEY " [ " OPS " ] [ " OPTIONS " ] " +.RE +.TP +Hashing mode: + +.RS +.in +8 +.ti -8 +.BR tc " " filter " ... " "flow hash keys " +.IR KEY_LIST " [ " +.B perturb +.IR secs " ] [ " OPTIONS " ] " +.RE + +.in +8 +.ti -8 +.IR OPS " := [ " OPS " ] " OP + +.ti -8 +.IR OPTIONS " := [ " +.B divisor +.IR NUM " ] [ " +.B baseclass +.IR ID " ] [ " +.B match +.IR EMATCH_TREE " ] [ " +.B action +.IR ACTION_SPEC " ]" + +.ti -8 +.IR KEY_LIST " := [ " KEY_LIST " ] " KEY + +.ti -8 +.IR OP " := { " +.BR or " | " and " | " xor " | " rshift " | " addend " } " +.I NUM + +.ti -8 +.IR ID " := " X : Y + +.ti -8 +.IR KEY " := { " +.BR src " | " dst " | " proto " | " proto-src " | " proto-dst " | " iif " | " +.BR priority " | " mark " | " nfct " | " nfct-src " | " nfct-dst " | " +.BR nfct-proto-src " | " nfct-proto-dst " | " rt-classid " | " sk-uid " | " +.BR sk-gid " | " vlan-tag " | " rxhash " }" +.SH DESCRIPTION +The +.B flow +classifier is meant to extend the +.B SFQ +hashing capabilities without hard-coding new hash functions. It also allows +deterministic mappings of keys to classes. +.SH OPTIONS +.TP +.BI action " ACTION_SPEC" +Apply an action from the generic actions framework on matching packets. +.TP +.BI baseclass " ID" +An offset for the resulting class ID. +.I ID +may be +.BR root ", " none +or a hexadecimal class ID in the form [\fIX\fB:\fR]\fIY\fR. If \fIX\fR is +omitted, it is assumed to be zero. +.TP +.BI divisor " NUM" +Number of buckets to use for sorting into. Keys are calculated modulo +.IR NUM . +.TP +.BI "hash keys " KEY-LIST +Perform a +.B jhash2 +operation over the keys in +.IR KEY-LIST , +the result (modulo the +.B divisor +if given) is taken as class ID, optionally offset by the value of +.BR baseclass . +It is possible to specify an interval (in seconds) after which +.BR jhash2 's +entropy source is recreated using the +.B perturb +parameter. +.TP +.BI "map key " KEY +Packet data identified by +.I KEY +is translated into class IDs to push the packet into. The value may be mangled by +.I OPS +before using it for the mapping. They are applied in the order listed here: +.RS +.TP 4 +.BI and " NUM" +Perform bitwise +.B AND +operation with numeric value +.IR NUM . +.TP +.BI or " NUM" +Perform bitwise +.B OR +operation with numeric value +.IR NUM . +.TP +.BI xor " NUM" +Perform bitwise +.B XOR +operation with numeric value +.IR NUM . +.TP +.BI rshift " NUM" +Shift the value of +.I KEY +to the right by +.I NUM +bits. +.TP +.BI addend " NUM" +Add +.I NUM +to the value of +.IR KEY . + +.RE +.RS +For the +.BR or ", " and ", " xor " and " rshift +operations, +.I NUM +is assumed to be an unsigned, 32bit integer value. For the +.B addend +operation, +.I NUM +may be much more complex: It may be prefixed by a minus ('-') sign to cause +subtraction instead of addition and for keys of +.BR src ", " dst ", " nfct-src " and " nfct-dst +it may be given in IP address notation. See below for an illustrating example. +.RE +.TP +.BI match " EMATCH_TREE" +Match packets using the extended match infrastructure. See +.BR tc-ematch (8) +for a detailed description of the allowed syntax in +.IR EMATCH_TREE . +.SH KEYS +In mapping mode, a single key is used (after optional permutation) to build a +class ID. The resulting ID is deducible in most cases. In hashing more, a number +of keys may be specified which are then hashed and the output used as class ID. +This ID is not deducible in beforehand, and may even change over time for a +given flow if a +.B perturb +interval has been given. + +The range of class IDs can be limited by the +.B divisor +option, which is used for a modulus. +.TP +.BR src ", " dst +Use source or destination address as key. In case of IPv4 and TIPC, this is the +actual address value. For IPv6, the 128bit address is folded into a 32bit value +by XOR'ing the four 32bit words. In all other cases, the kernel-internal socket +address is used (after folding into 32bits on 64bit systems). +.TP +.B proto +Use the layer four protocol number as key. +.TP +.B proto-src +Use the layer four source port as key. If not available, the kernel-internal +socket address is used instead. +.TP +.B proto-dst +Use the layer four destination port as key. If not available, the associated +kernel-internal dst_entry address is used after XOR'ing with the packet's +layer three protocol number. +.TP +.B iif +Use the incoming interface index as key. +.TP +.B priority +Use the packet's priority as key. Usually this is the IP header's DSCP/ECN +value. +.TP +.B mark +Use the netfilter +.B fwmark +as key. +.TP +.B nfct +Use the associated conntrack entry address as key. +.TP +.BR nfct-src ", " nfct-dst ", " nfct-proto-src ", " nfct-proto-dst +These are conntrack-aware variants of +.BR src ", " dst ", " proto-src " and " proto-dst . +In case of NAT, these are basically the packet header's values before NAT was +applied. +.TP +.B rt-classid +Use the packet's destination routing table entry's realm as key. +.TP +.B sk-uid +.TQ +.B sk-gid +For locally generated packets, use the user or group ID the originating socket +belongs to as key. +.TP +.B vlan-tag +Use the packet's vlan ID as key. +.TP +.B rxhash +Use the flow hash as key. + +.SH EXAMPLES +.TP +Classic SFQ hash: + +.EX +tc filter add ... flow hash \\ + keys src,dst,proto,proto-src,proto-dst divisor 1024 +.EE +.TP +Classic SFQ hash, but using information from conntrack to work properly in combination with NAT: + +.EX +tc filter add ... flow hash \\ + keys nfct-src,nfct-dst,proto,nfct-proto-src,nfct-proto-dst \\ + divisor 1024 +.EE +.TP +Map destination IPs of 192.168.0.0/24 to classids 1-257: + +.EX +tc filter add ... flow map \\ + key dst addend -192.168.0.0 divisor 256 +.EE +.TP +Alternative to the above: + +.EX +tc filter add ... flow map \\ + key dst and 0xff +.EE +.TP +The same, but in reverse order: + +.EX +tc filter add ... flow map \\ + key dst and 0xff xor 0xff +.EE +.SH SEE ALSO +.BR tc (8), +.BR tc-ematch (8), +.BR tc-sfq (8) -- 1.8.3.1