[iproute PATCH v2 0/8] Follow-up to my action man pages series

[iproute PATCH v2 0/8] Follow-up to my action man pages series

[Phil Sutter]

The following patch series aims at addressing feedback provided by Jamal
and Alexei. Thanks a lot for your input!

Changes since v1:
- Rebased onto current master.
- Dropped some leftover TODO note from tc-skbedit.8

Phil Sutter (8):
  doc/tc-filters.tex: Drop overly subjective paragraphs
  tc: connmark, pedit: Rename BRANCH to CONTROL
  man: tc-csum.8: Add an example
  man: tc-mirred.8: Reword man page a bit, add generic mirror example
  man: tc-police.8: Emphasize on the two rate control mechanisms
  man: tc-skbedit.8: Elaborate a bit on TX queues
  tc/m_vlan.c: mention CONTROL option in help text
  man: tc-vlan.8: Describe CONTROL option

 doc/tc-filters.tex     | 23 ++++-----------------
 man/man8/tc-connmark.8 |  6 +++---
 man/man8/tc-csum.8     | 15 ++++++++++++++
 man/man8/tc-mirred.8   | 26 ++++++++++++++++-------
 man/man8/tc-pedit.8    |  6 +++---
 man/man8/tc-police.8   | 29 ++++++++++++++++++++++----
 man/man8/tc-skbedit.8  | 12 +++++++++++
 man/man8/tc-vlan.8     | 56 +++++++++++++++++++++++++++++++++++++++++++++++++-
 tc/m_connmark.c        |  4 ++--
 tc/m_pedit.c           |  4 ++--
 tc/m_vlan.c            |  3 ++-
 11 files changed, 142 insertions(+), 42 deletions(-)

-- 
2.7.2

[iproute PATCH v2 1/8] doc/tc-filters.tex: Drop overly subjective paragraphs

[Phil Sutter]

Cc: Alexei Starovoitov <alexei.starovoitov@gmail.com>
Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 doc/tc-filters.tex | 23 ++++-------------------
 1 file changed, 4 insertions(+), 19 deletions(-)

diff --git a/doc/tc-filters.tex b/doc/tc-filters.tex
index 59127d6672ed7..54cc0c9920ce2 100644
--- a/doc/tc-filters.tex
+++ b/doc/tc-filters.tex
@@ -18,10 +18,6 @@
 \date{January 2016}
 \maketitle
 
-TC, the Traffic Control utility, has been there for a very long time - forever
-in my humble perception. It is still (and has ever been if I'm not mistaken) the
-only tool to configure QoS in Linux.
-
 Standard practice when transmitting packets over a medium which may block (due
 to congestion, e.g.) is to use a queue which temporarily holds these packets. In
 Linux, this queueing approach is where QoS happens: A Queueing Discipline
@@ -496,21 +492,10 @@ kernel itself doesn't.
 
 \section*{Conclusion}
 
-My personal impression is that although the \cmd{tc} utility is an absolute
-necessity for anyone aiming at doing QoS in Linux professionally, there are way
-too many loose ends and trip wires present in it's environment. Contributing to
-this is the fact, that much of the non-essential functionality is redundantly
-available in netfilter. Another problem which adds weight to the first one is a
-general lack of documentation. Of course, there are many HOWTOs and guides in
-the internet, but since it's often not clear how up to date these are, I prefer
-the usual resources such as man or info pages. Surely nothing one couldn't fix
-in hindsight, but quality certainly suffers if the original author of the code
-does not or can not contribute to that.
-
-All that being said, once the steep learning curve has been mastered, the
-conglomerate of (classful) qdiscs, filters and actions provides a highly
-sophisticated and flexible infrastructure to perform QoS, which plays nicely
-along with routing and firewalling setups.
+Once the steep learning curve has been mastered, the conglomerate of (classful)
+qdiscs, filters and actions provides a highly sophisticated and flexible
+infrastructure to perform QoS, which plays nicely along with routing and
+firewalling setups.
 
 
 \section*{Further Reading}
-- 
2.7.2

[iproute PATCH v2 2/8] tc: connmark, pedit: Rename BRANCH to CONTROL

[Phil Sutter]

As Jamal suggested, BRANCH is the wrong name, as these keywords go
beyond simple branch control - e.g. loops are possible, too. Therefore
rename the non-terminal to CONTROL instead which should be more
appropriate.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/tc-connmark.8 | 6 +++---
 man/man8/tc-pedit.8    | 6 +++---
 tc/m_connmark.c        | 4 ++--
 tc/m_pedit.c           | 4 ++--
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/man/man8/tc-connmark.8 b/man/man8/tc-connmark.8
index bb4cf7543dfdb..44f29f508d673 100644
--- a/man/man8/tc-connmark.8
+++ b/man/man8/tc-connmark.8
@@ -6,12 +6,12 @@ connmark - netfilter connmark retriever action
 .in +8
 .ti -8
 .BR tc " ... " "action connmark " [ " zone"
-.IR u16_zone_index " ] [ " BRANCH " ] ["
+.IR u16_zone_index " ] [ " CONTROL " ] ["
 .BI index " u32_index "
 ]
 
 .ti -8
-.IR BRANCH " := { " reclassify " | " pipe " | " drop " | " continue " | " ok " }"
+.IR CONTROL " := { " reclassify " | " pipe " | " drop " | " continue " | " ok " }"
 .SH DESCRIPTION
 The connmark action is used to restore the connection's mark value into the
 packet's fwmark.
@@ -22,7 +22,7 @@ Specify the conntrack zone when doing conntrack lookups for packets.
 .I u16_zone_index
 is a 16bit unsigned decimal value.
 .TP
-.I BRANCH
+.I CONTROL
 How to continue after executing this action.
 .RS
 .TP
diff --git a/man/man8/tc-pedit.8 b/man/man8/tc-pedit.8
index c30927ec50954..c34520c046a6c 100644
--- a/man/man8/tc-pedit.8
+++ b/man/man8/tc-pedit.8
@@ -6,7 +6,7 @@ pedit - generic packet editor action
 .in +8
 .ti -8
 .BR tc " ... " "action pedit munge " {
-.IR RAW_OP " | " LAYERED_OP " } [ " BRANCH " ]"
+.IR RAW_OP " | " LAYERED_OP " } [ " CONTROL " ]"
 
 .ti -8
 .IR RAW_OP " := "
@@ -45,7 +45,7 @@ pedit - generic packet editor action
 .IR RVAL " ]"
 
 .ti -8
-.IR BRANCH " := {"
+.IR CONTROL " := {"
 .BR reclassify " | " pipe " | " drop " | " shot " | " continue " | " pass " }"
 .SH DESCRIPTION
 The
@@ -165,7 +165,7 @@ This optional extra part of
 .I CMD_SPEC
 allows to exclude bits from being changed.
 .TP
-.I BRANCH
+.I CONTROL
 The following keywords allow to control how the tree of qdisc, classes,
 filters and actions is further traversed after this action.
 .RS
diff --git a/tc/m_connmark.c b/tc/m_connmark.c
index 2414f321c1f8f..b1c7d3af54cc4 100644
--- a/tc/m_connmark.c
+++ b/tc/m_connmark.c
@@ -27,10 +27,10 @@
 static void
 explain(void)
 {
-	fprintf(stderr, "Usage: ... connmark [zone ZONE] [BRANCH] [index <INDEX>]\n");
+	fprintf(stderr, "Usage: ... connmark [zone ZONE] [CONTROL] [index <INDEX>]\n");
 	fprintf(stderr, "where :\n"
 		"\tZONE is the conntrack zone\n"
-		"\tBRANCH := reclassify|pipe|drop|continue|ok\n");
+		"\tCONTROL := reclassify|pipe|drop|continue|ok\n");
 }
 
 static void
diff --git a/tc/m_pedit.c b/tc/m_pedit.c
index ca78a83dd9d9d..9fe1a7ae3b90c 100644
--- a/tc/m_pedit.c
+++ b/tc/m_pedit.c
@@ -35,7 +35,7 @@ static int pedit_debug;
 static void
 explain(void)
 {
-	fprintf(stderr, "Usage: ... pedit munge <MUNGE> [<BRANCH>]\n");
+	fprintf(stderr, "Usage: ... pedit munge <MUNGE> [CONTROL]\n");
 	fprintf(stderr,
 		"Where: MUNGE := <RAW>|<LAYERED>\n"
 		"\t<RAW>:= <OFFSETC>[ATC]<CMD>\n \t\tOFFSETC:= offset <offval> <u8|u16|u32>\n "
@@ -43,7 +43,7 @@ explain(void)
 		"\t\tNOTE: maskval is a 32 bit hex number\n \t\tNOTE: shiftval is a is a shift value\n "
 		"\t\tCMD:= clear | invert | set <setval>| retain\n \t<LAYERED>:= ip <ipdata> | ip6 <ip6data> \n "
 		" \t\t| udp <udpdata> | tcp <tcpdata> | icmp <icmpdata>\n"
-		"\t<BRANCH>:= reclassify | pipe | drop | continue | pass\n"
+		"\tCONTROL:= reclassify | pipe | drop | continue | pass\n"
 		"For Example usage look at the examples directory\n");
 
 }
-- 
2.7.2

[iproute PATCH v2 3/8] man: tc-csum.8: Add an example

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/tc-csum.8 | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/man/man8/tc-csum.8 b/man/man8/tc-csum.8
index 9d00aae346af0..3a64c82f09ba8 100644
--- a/man/man8/tc-csum.8
+++ b/man/man8/tc-csum.8
@@ -49,6 +49,21 @@ UDPLite header
 .TP
 .B SWEETS
 These are merely syntactic sugar and ignored internally.
+.SH EXAMPLES
+The following performs stateless NAT for incoming packets from 192.168.1.100 to
+new destination 18.52.86.120 (0x12345678 in hex). Assuming these are UDP
+packets, both IP and UDP checksums have to be recalculated:
+
+.RS
+.EX
+# tc qdisc add dev eth0 ingress handle ffff:
+# tc filter add eth0 prio 1 protocol ip parent ffff: \\
+	u32 match ip src 192.168.1.100/32 flowid :1 \\
+	action pedit munge ip dst set 0x12345678 pipe \\
+	csum ip and udp
+.EE
+.RE
+
 .SH SEE ALSO
 .BR tc (8),
 .BR tc-pedit (8)
-- 
2.7.2

[iproute PATCH v2 4/8] man: tc-mirred.8: Reword man page a bit, add generic mirror example

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/tc-mirred.8 | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/man/man8/tc-mirred.8 b/man/man8/tc-mirred.8
index 52d98bc416563..bba96e0e5d8c0 100644
--- a/man/man8/tc-mirred.8
+++ b/man/man8/tc-mirred.8
@@ -21,11 +21,9 @@ mirred - mirror/redirect action
 .SH DESCRIPTION
 The
 .B mirred
-action allows to redirect or mirror packets to another network interface on the
-same system. It is typically used in combination with the
-.B ifb
-pseudo device to create a shrared instance where QoS happens, but serves well
-for debugging or monitoring purposes, too.
+action allows packet mirroring (copying) or redirecting (stealing) the packet it
+receives. Mirroring is what is sometimes referred to as Switch Port Analyzer
+(SPAN) and is commonly used to analyze and/or debug flows.
 .SH OPTIONS
 .TP
 .B ingress
@@ -67,9 +65,23 @@ debugging purposes:
 .EE
 .RE
 
-Use an
+Mirror all incoming ICMP packets on eth0 to a dummy interface for examination
+with e.g. tcpdump:
+
+.RS
+.EX
+# ip link add dummy0 type dummy
+# ip link set dummy0 up
+# tc qdisc add dev eth0 handle ffff: ingress
+# tc filter add dev eth0 parent ffff: protocol ip \\
+	u32 match ip protocol 1 0xff \\
+	action mirred egress mirror dev dummy0
+.EE
+.RE
+
+Using an
 .B ifb
-interface to send ingress traffic on eth0 through an instance of
+interface, it is possible to send ingress traffic through an instance of
 .BR sfq :
 
 .RS
-- 
2.7.2

[iproute PATCH v2 5/8] man: tc-police.8: Emphasize on the two rate control mechanisms

[Phil Sutter]

As Jamal pointed out, there are two different approaches to bandwidth
measurement. Try to make this clear by separating them in synopsis and
also documenting the way to fine-tune avrate.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/tc-police.8 | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/man/man8/tc-police.8 b/man/man8/tc-police.8
index 2b1537ec52875..5c5a632335dc9 100644
--- a/man/man8/tc-police.8
+++ b/man/man8/tc-police.8
@@ -12,13 +12,21 @@ police - policing action
 .IR BYTES [\fB/ BYTES "] ] ["
 .BI peakrate " RATE"
 ] [
-.BI avrate " RATE"
-] [
 .BI overhead " BYTES"
 ] [
 .BI linklayer " TYPE"
 ] [
-.BI conform-exceed " EXCEEDACT\fR[\fB/\fIEXCEEDACT\fR]"
+.IR CONTROL " ]"
+
+.ti -8
+.BR tc " ... " filter " ... [ " estimator
+.IR "SAMPLE AVERAGE " ]
+.BR "action police avrate"
+.IR RATE " [ " CONTROL " ]"
+
+.ti -8
+.IR CONTROL " :="
+.BI conform-exceed " EXCEEDACT\fR[\fB/\fIEXCEEDACT"
 
 .ti -8
 .IR EXCEEDACT " := { "
@@ -27,7 +35,14 @@ police - policing action
 The
 .B police
 action allows to limit bandwidth of traffic matched by the filter it is
-attached to.
+attached to. Basically there are two different algorithms available to measure
+the packet rate: The first one uses an internal dual token bucket and is
+configured using the
+.BR rate ", " burst ", " mtu ", " peakrate ", " overhead " and " linklayer
+parameters. The second one uses an in-kernel sampling mechanism. It can be
+fine-tuned using the
+.B estimator
+filter parameter.
 .SH OPTIONS
 .TP
 .BI rate " RATE"
@@ -73,6 +88,12 @@ cell sizes, for
 .B ethernet
 no action is taken.
 .TP
+.BI estimator " SAMPLE AVERAGE"
+Fine-tune the in-kernel packet rate estimator.
+.IR SAMPLE " and " AVERAGE
+are time values and control the frequency in which samples are taken and over
+what timespan an average is built.
+.TP
 .BI conform-exceed " EXCEEDACT\fR[\fB/\fIEXCEEDACT\fR]"
 Define how to handle packets which exceed (and, if the second
 .I EXCEEDACT
-- 
2.7.2

[iproute PATCH v2 6/8] man: tc-skbedit.8: Elaborate a bit on TX queues

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/tc-skbedit.8 | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/man/man8/tc-skbedit.8 b/man/man8/tc-skbedit.8
index b585a4d4253ba..e6902960eee27 100644
--- a/man/man8/tc-skbedit.8
+++ b/man/man8/tc-skbedit.8
@@ -17,6 +17,18 @@ The
 action allows to change a packet's associated meta data. It complements the
 .B pedit
 action, which in turn allows to change parts of the packet data itself.
+
+The most unique feature of
+.B skbedit
+is it's ability to decide over which queue of an interface with multiple
+transmit queues the packet is to be sent out. The number of available transmit
+queues is reflected by sysfs entries within
+.I /sys/class/net/<interface>/queues
+with name
+.I tx-N
+(where
+.I N
+is the actual queue number).
 .SH OPTIONS
 .TP
 .BI queue_mapping " QUEUE_MAPPING"
-- 
2.7.2

[iproute PATCH v2 7/8] tc/m_vlan.c: mention CONTROL option in help text

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 tc/m_vlan.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tc/m_vlan.c b/tc/m_vlan.c
index 8d97963f351bc..3233d207375bf 100644
--- a/tc/m_vlan.c
+++ b/tc/m_vlan.c
@@ -22,9 +22,10 @@
 static void explain(void)
 {
 	fprintf(stderr, "Usage: vlan pop\n");
-	fprintf(stderr, "       vlan push [ protocol VLANPROTO ] id VLANID\n");
+	fprintf(stderr, "       vlan push [ protocol VLANPROTO ] id VLANID [CONTROL]\n");
 	fprintf(stderr, "       VLANPROTO is one of 802.1Q or 802.1AD\n");
 	fprintf(stderr, "            with default: 802.1Q\n");
+	fprintf(stderr, "       CONTROL := reclassify | pipe | drop | continue | pass\n");
 }
 
 static void usage(void)
-- 
2.7.2

[iproute PATCH v2 8/8] man: tc-vlan.8: Describe CONTROL option

[Phil Sutter]

This should be made generic and part of a common tc-actions man page.
Though leave it here for now to not confuse readers of the example which
uses it.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/tc-vlan.8 | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/man/man8/tc-vlan.8 b/man/man8/tc-vlan.8
index e650b72d3b395..4bfd72b129aaf 100644
--- a/man/man8/tc-vlan.8
+++ b/man/man8/tc-vlan.8
@@ -6,13 +6,17 @@ vlan - vlan manipulation module
 .in +8
 .ti -8
 .BR tc " ... " "action vlan" " { " pop " |"
-.IR PUSH " }"
+.IR PUSH " } [ " CONTROL " ]"
 
 .ti -8
 .IR PUSH " := "
 .BR push " [ " protocol
 .IR VLANPROTO " ]"
 .BI id " VLANID"
+
+.ti -8
+.IR CONTROL " := { "
+.BR reclassify " | " pipe " | " drop " | " continue " | " pass " }"
 .SH DESCRIPTION
 The
 .B vlan
@@ -50,5 +54,55 @@ for hexadecimal interpretation, etc.).
 .BI protocol " VLANPROTO"
 Choose the VLAN protocol to use. At the time of writing, the kernel accepts only
 .BR 802.1Q " or " 802.1ad .
+.TP
+.I CONTROL
+How to continue after executing this action.
+.RS
+.TP
+.B reclassify
+Restarts classification by jumping back to the first filter attached to this
+action's parent.
+.TP
+.B pipe
+Continue with the next action, this is the default.
+.TP
+.B drop
+Packet will be dropped without running further actions.
+.TP
+.B continue
+Continue classification with next filter in line.
+.TP
+.B pass
+Return to calling qdisc for packet processing. This ends the classification
+process.
+.RE
+.SH EXAMPLES
+The following example encapsulates incoming ICMP packets on eth0 from 10.0.0.2
+into VLAN ID 123:
+
+.RS
+.EX
+#tc qdisc add dev eth0 handle ffff: ingress
+#tc filter add dev eth0 parent ffff: pref 11 protocol ip \\
+	u32 match ip protocol 1 0xff flowid 1:1 \\
+	u32 match ip src 10.0.0.2 flowid 1:1 \\
+	action vlan push id 123
+.EE
+.RE
+
+Here is an example of the
+.B pop
+function: Incoming VLAN packets on eth0 are decapsulated and the classification
+process then restarted for the plain packet:
+
+.RS
+.EX
+#tc qdisc add dev eth0 handle ffff: ingress
+#tc filter add dev $ETH parent ffff: pref 1 protocol 802.1Q \\
+	u32 match u32 0 0 flowid 1:1 \\
+	action vlan pop reclassify
+.EE
+.RE
+
 .SH SEE ALSO
 .BR tc (8)
-- 
2.7.2