Message-ID: <20240111184451.48227-3-stephen@networkplumber.org>
Date: Thu, 11 Jan 2024 10:44:09 -0800
From: Stephen Hemminger <stephen@...workplumber.org>
To: netdev@...r.kernel.org
Cc: Stephen Hemminger <stephen@...workplumber.org>
Subject: [PATCH iproute2-next 2/4] man/tc-gact: move generic action documentation to man page

Convert from free form doc to man page.

Signed-off-by: Stephen Hemminger <stephen@...workplumber.org>
---
 doc/actions/gact-usage | 78 --------------------------------------
 man/man8/tc-gact.8     | 85 ++++++++++++++++++++++++++++++++++++++++++
 man/man8/tc.8          |  1 +
 3 files changed, 86 insertions(+), 78 deletions(-)
 delete mode 100644 doc/actions/gact-usage
 create mode 100644 man/man8/tc-gact.8

diff --git a/doc/actions/gact-usage b/doc/actions/gact-usage
deleted file mode 100644
index 7cf48abbd90a..000000000000
--- a/doc/actions/gact-usage
+++ /dev/null
@@ -1,78 +0,0 @@
-
-gact <ACTION> [RAND] [INDEX]
-
-Where:
-	ACTION := reclassify | drop | continue | pass | ok
-	RAND := random <RANDTYPE> <ACTION> <VAL>
-	RANDTYPE := netrand | determ
-        VAL : = value not exceeding 10000
-        INDEX := index value used
-
-ACTION semantics
-- pass and ok are equivalent to accept
-- continue allows one to restart classification lookup
-- drop drops packets
-- reclassify implies continue classification where we left off
-
-randomization
---------------
-
-At the moment there are only two algorithms. One is deterministic
-and the other uses internal kernel netrand.
-
-Examples:
-
-Rules can be installed on both ingress and egress - this shows ingress
-only
-
-tc qdisc add dev eth0 ingress
-
-# example 1
-tc filter add dev eth0 parent ffff: protocol ip prio 6 u32 match ip src \
-10.0.0.9/32 flowid 1:16 action drop
-
-ping -c 20 10.0.0.9
-
---
-filter u32
-filter u32 fh 800: ht divisor 1
-filter u32 fh 800::800 order 2048 key ht 800 bkt 0 flowid 1:16  (rule hit 32 success 20)
-  match 0a000009/ffffffff at 12 (success 20 )
-        action order 1: gact action drop
-         random type none pass val 0
-         index 1 ref 1 bind 1 installed 59 sec used 35 sec
-         Sent 1680 bytes 20 pkts (dropped 20, overlimits 0 )
-
-----
-
-# example 2
-#allow 1 out 10 randomly using the netrand generator
-tc filter add dev eth0 parent ffff: protocol ip prio 6 u32 match ip src \
-10.0.0.9/32 flowid 1:16 action drop random netrand ok 10
-
-ping -c 20 10.0.0.9
-
-----
-filter protocol ip pref 6 u32 filter protocol ip pref 6 u32 fh 800: ht divisor 1filter protocol ip pref 6 u32 fh 800::800 order 2048 key ht 800 bkt 0 flowid 1:16  (rule hit 20 success 20)
-  match 0a000009/ffffffff at 12 (success 20 )
-        action order 1: gact action drop
-         random type netrand pass val 10
-         index 5 ref 1 bind 1 installed 49 sec used 25 sec
-         Sent 1680 bytes 20 pkts (dropped 16, overlimits 0 )
-
---------
-#alternative: deterministically accept every second packet
-tc filter add dev eth0 parent ffff: protocol ip prio 6 u32 match ip src \
-10.0.0.9/32 flowid 1:16 action drop random determ ok 2
-
-ping -c 20 10.0.0.9
-
-tc -s filter show parent ffff: dev eth0
------
-filter protocol ip pref 6 u32 filter protocol ip pref 6 u32 fh 800: ht divisor 1filter protocol ip pref 6 u32 fh 800::800 order 2048 key ht 800 bkt 0 flowid 1:16  (rule hit 20 success 20)
-  match 0a000009/ffffffff at 12 (success 20 )
-        action order 1: gact action drop
-         random type determ pass val 2
-         index 4 ref 1 bind 1 installed 118 sec used 82 sec
-         Sent 1680 bytes 20 pkts (dropped 10, overlimits 0 )
------
diff --git a/man/man8/tc-gact.8 b/man/man8/tc-gact.8
new file mode 100644
index 000000000000..81aa30eba5a0
--- /dev/null
+++ b/man/man8/tc-gact.8
@@ -0,0 +1,85 @@
+.TH "Generic actions in tc" 8 "11 Jan 2023" "iproute2" "Linux"
+
+.SH NAME
+gact - generic action
+.SH SYNOPSIS
+.in +8
+.ti -8
+.BR tc " ... " "action gact"
+.IR CONTROL " [ " RAND " ] [ " INDEX " ]"
+.ti -8
+.IR CONTROL " := { "
+.BR reclassify " | " drop " | " continue " | " pass " | " pipe " | "
+.br
+.BI "goto chain " "CHAIN_INDEX"
+|
+.br
+.BI "jump " "JUMP_COUNT"
+}
+
+.ti -8
+.IR RAND " := "
+.BI random " RANDTYPE CONTROL VAL"
+.ti -8
+.IR RANDTYPE " := { "
+.BR netrand " | " determ " }"
+.ti -8
+.IR VAL " := number not exceeding 10000"
+.ti -8
+.IR JUMP_COUNT " := absolute jump from start of action list"
+.ti -8
+.IR INDEX " := index value used"
+
+.SH DESCRIPTION
+The
+.B gact
+action allows reclassify, dropping, passing, or accepting packets.
+At the moment there are only two algorithms. One is deterministic
+and the other uses internal kernel netrand.
+
+.SH OPTIONS
+.TP
+.BI random " RANDTYPE CONTROL VAL"
+The probability of taking the action expressed in terms of 1 out of
+.I VAL
+packets.
+
+.TP
+.I CONTROL
+Indicate how
+.B tc
+should proceed if the packet matches.
+For a description of the possible
+.I CONTROL
+values, see
+.BR tc-actions (8).
+
+.SH EXAMPLES
+Apply a rule on ingress to drop packets from a given source address.
+.RS
+.EX
+# tc filter add dev eth0 parent ffff: protocol ip prio 6 u32 match ip src \
+10.0.0.9/32 flowid 1:16 action drop
+.EE
+.RE
+
+Allow 1 out 10 packets from source randomly using the netrand generator
+.RS
+.EX
+# tc filter add dev eth0 parent ffff: protocol ip prio 6 u32 match ip src \
+10.0.0.9/32 flowid 1:16 action drop random netrand ok 10
+.EE
+.RE
+
+Deterministically accept every second packet
+.RS
+.EX
+# tc filter add dev eth0 parent ffff: protocol ip prio 6 u32 match ip src \
+10.0.0.9/32 flowid 1:16 action drop random determ ok 2
+.EE
+.RE
+
+.SH SEE ALSO
+.BR tc (8),
+.BR tc-actions (8),
+.BR tc-u32 (8)
diff --git a/man/man8/tc.8 b/man/man8/tc.8
index e5bef911f21b..3175454b9d60 100644
--- a/man/man8/tc.8
+++ b/man/man8/tc.8
@@ -871,6 +871,7 @@ was written by Alexey N. Kuznetsov and added in Linux 2.2.
 .BR tc-fq_codel (8),
 .BR tc-fq_pie (8),
 .BR tc-fw (8),
+.BR tc-gact (8),
 .BR tc-hfsc (7),
 .BR tc-hfsc (8),
 .BR tc-htb (8),
-- 
2.43.0

Powered by blists - more mailing lists