From 5703331fbb7957ff959aeda921b7aa28a78d2eb8 Mon Sep 17 00:00:00 2001

From: Phil Sutter <psutter@redhat.com>

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 <phil@nwl.cc>

Date:   Fri Oct 23 19:47:10 2015 +0200

    tc: add a man page for flow filter

    Cc: Patrick McHardy <kaber@trash.net>

    Signed-off-by: Phil Sutter <phil@nwl.cc>

---

 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