[PATCH iproute2/net-next 0/3] Add the tc-sample action

[PATCH iproute2/net-next 0/3] Add the tc-sample action

[Yotam Gigi]

This patchset adds the tc-sample action support and the corresponding man
page. More information about the action and its usage can be found in the
commit message.

Yotam Gigi (3):
  tc: Add support for the sample tc action
  tc: man: Add man entry for the tc-sample action
  tc: man: matchall: Update examples to include sample

 bash-completion/tc               |   8 +-
 include/linux/tc_act/tc_sample.h |  26 ++++++
 man/man8/Makefile                |   2 +-
 man/man8/tc-matchall.8           |  10 +++
 man/man8/tc-sample.8             | 125 ++++++++++++++++++++++++++
 tc/Makefile                      |   1 +
 tc/m_sample.c                    | 186 +++++++++++++++++++++++++++++++++++++++
 7 files changed, 356 insertions(+), 2 deletions(-)
 create mode 100644 include/linux/tc_act/tc_sample.h
 create mode 100644 man/man8/tc-sample.8
 create mode 100644 tc/m_sample.c

-- 
2.4.11

[PATCH iproute2/net-next 1/3] tc: Add support for the sample tc action

[Yotam Gigi]

The sample tc action allows sampling packets matching a classifier. It
peeks randomly packets, and samples them using the psample netlink
channel. The user can specify the psample group, which the packet will be
sampled to, the sampling rate and the packet truncation (to save
kernel-user traffic).

The sampled packets contain informative metadata, for example, the input
interface and the original packet length.

The action syntax:
tc filter add [...] \
	action sample rate <RATE> group <GROUP> [trunc <SIZE>]
	[...]

Where:
  RATE := The sampling rate which is the ratio of packets observed at the
	  data source to the samples generated
  GROUP := the psample module sampling group
  SIZE := optional truncation size

An example for a common usecase of the sample tc action: to sample ingress
traffic from interface eth1, one may use the commands:

tc qdisc add dev eth1 handle ffff: ingress

tc filter add dev eth1 parent ffff: \
       matchall action sample rate 12 group 4

Where the first command adds an ingress qdisc and the second starts
sampling randomly with an average of one sampled packet per 12 packets
on dev eth1 to psample group 4.

Reviewed-by: Jiri Pirko <jiri@mellanox.com>
Signed-off-by: Yotam Gigi <yotamg@mellanox.com>
---
 bash-completion/tc               |   8 +-
 include/linux/tc_act/tc_sample.h |  26 ++++++
 tc/Makefile                      |   1 +
 tc/m_sample.c                    | 186 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 220 insertions(+), 1 deletion(-)
 create mode 100644 include/linux/tc_act/tc_sample.h
 create mode 100644 tc/m_sample.c

diff --git a/bash-completion/tc b/bash-completion/tc
index 79dd5fc..ed2796d 100644
--- a/bash-completion/tc
+++ b/bash-completion/tc
@@ -430,6 +430,12 @@ _tc_action_options()
             _tc_once_attr 'index dev'
             return 0
             ;;
+        sample)
+            _tc_once_attr 'rate'
+            _tc_once_attr 'trunc'
+            _tc_once_attr 'group'
+            return 0
+            ;;
         gact)
             _tc_one_of_list 'reclassify drop continue pass'
             _tc_once_attr 'random'
@@ -671,7 +677,7 @@ _tc()
         action)
             case $subcmd in
                 add|change|replace)
-                    local action acwd ACTION_KIND=' gact mirred bpf '
+                    local action acwd ACTION_KIND=' gact mirred bpf sample '
                     for ((acwd=$subcword; acwd < ${#words[@]}-1; acwd++)); do
                         if [[ $ACTION_KIND =~ ' '${words[acwd]}' ' ]]; then
                             action=${words[acwd]}
diff --git a/include/linux/tc_act/tc_sample.h b/include/linux/tc_act/tc_sample.h
new file mode 100644
index 0000000..edc9058
--- /dev/null
+++ b/include/linux/tc_act/tc_sample.h
@@ -0,0 +1,26 @@
+#ifndef __LINUX_TC_SAMPLE_H
+#define __LINUX_TC_SAMPLE_H
+
+#include <linux/types.h>
+#include <linux/pkt_cls.h>
+#include <linux/if_ether.h>
+
+#define TCA_ACT_SAMPLE 26
+
+struct tc_sample {
+	tc_gen;
+};
+
+enum {
+	TCA_SAMPLE_UNSPEC,
+	TCA_SAMPLE_TM,
+	TCA_SAMPLE_PARMS,
+	TCA_SAMPLE_RATE,
+	TCA_SAMPLE_TRUNC_SIZE,
+	TCA_SAMPLE_PSAMPLE_GROUP,
+	TCA_SAMPLE_PAD,
+	__TCA_SAMPLE_MAX
+};
+#define TCA_SAMPLE_MAX (__TCA_SAMPLE_MAX - 1)
+
+#endif
diff --git a/tc/Makefile b/tc/Makefile
index 7fd0c4a..6dd984f 100644
--- a/tc/Makefile
+++ b/tc/Makefile
@@ -51,6 +51,7 @@ TCMODULES += m_vlan.o
 TCMODULES += m_connmark.o
 TCMODULES += m_bpf.o
 TCMODULES += m_tunnel_key.o
+TCMODULES += m_sample.o
 TCMODULES += p_ip.o
 TCMODULES += p_icmp.o
 TCMODULES += p_tcp.o
diff --git a/tc/m_sample.c b/tc/m_sample.c
new file mode 100644
index 0000000..9291109
--- /dev/null
+++ b/tc/m_sample.c
@@ -0,0 +1,186 @@
+/*
+ * m_sample.c		ingress/egress packet sampling module
+ *
+ *		This program is free software; you can distribute it and/or
+ *		modify it under the terms of the GNU General Public License
+ *		as published by the Free Software Foundation; either version
+ *		2 of the License, or (at your option) any later version.
+ *
+ * Authors:	Yotam Gigi <yotamg@mellanox.com>
+ *
+ */
+
+#include <stdio.h>
+#include "utils.h"
+#include "tc_util.h"
+#include "tc_common.h"
+#include <linux/tc_act/tc_sample.h>
+
+static void explain(void)
+{
+	fprintf(stderr, "Usage: sample SAMPLE_CONF\n");
+	fprintf(stderr, "where:\n");
+	fprintf(stderr, "\tSAMPLE_CONF := SAMPLE_PARAMS | SAMPLE_INDEX\n");
+	fprintf(stderr, "\tSAMPLE_PARAMS := rate RATE group GROUP [trunc SIZE] [SAMPLE_INDEX]\n");
+	fprintf(stderr, "\tSAMPLE_INDEX := index INDEX\n");
+	fprintf(stderr, "\tRATE := The ratio of packets observed at the data source to the samples generated.\n");
+	fprintf(stderr, "\tGROUP := the psample sampling group\n");
+	fprintf(stderr, "\tSIZE := the truncation size\n");
+	fprintf(stderr, "\tINDEX := integer index of the sample action\n");
+}
+
+static void usage(void)
+{
+	explain();
+	exit(-1);
+}
+
+static int parse_sample(struct action_util *a, int *argc_p, char ***argv_p,
+			int tca_id, struct nlmsghdr *n)
+{
+	struct tc_sample p = { 0 };
+	bool trunc_set = false;
+	bool group_set = false;
+	bool rate_set = false;
+	char **argv = *argv_p;
+	struct rtattr *tail;
+	int argc = *argc_p;
+	__u32 trunc;
+	__u32 group;
+	__u32 rate;
+
+	if (argc <= 1) {
+		fprintf(stderr, "sample bad argument count %d\n", argc);
+		usage();
+		return -1;
+	}
+
+	if (matches(*argv, "sample") == 0) {
+		NEXT_ARG();
+	} else {
+		fprintf(stderr, "sample bad argument %s\n", *argv);
+		return -1;
+	}
+
+	while (argc > 0) {
+		if (matches(*argv, "rate") == 0) {
+			NEXT_ARG();
+			if (get_unsigned(&rate, *argv, 10) != 0) {
+				fprintf(stderr, "Illegal rate %s\n", *argv);
+				usage();
+				return -1;
+			}
+			rate_set = true;
+		} else if (matches(*argv, "group") == 0) {
+			NEXT_ARG();
+			if (get_unsigned(&group, *argv, 10) != 0) {
+				fprintf(stderr, "Illegal group num %s\n",
+					*argv);
+				usage();
+				return -1;
+			}
+			group_set = true;
+		} else if (matches(*argv, "trunc") == 0) {
+			NEXT_ARG();
+			if (get_unsigned(&trunc, *argv, 10) != 0) {
+				fprintf(stderr, "Illegal truncation size %s\n",
+					*argv);
+				usage();
+				return -1;
+			}
+			trunc_set = true;
+		} else if (matches(*argv, "help") == 0) {
+			usage();
+		} else {
+			break;
+		}
+
+		NEXT_ARG_FWD();
+	}
+
+	p.action = TC_ACT_PIPE;
+	if (argc && !action_a2n(*argv, &p.action, false))
+		NEXT_ARG_FWD();
+
+	if (argc) {
+		if (matches(*argv, "index") == 0) {
+			NEXT_ARG();
+			if (get_u32(&p.index, *argv, 10)) {
+				fprintf(stderr, "sample: Illegal \"index\"\n");
+				return -1;
+			}
+			NEXT_ARG_FWD();
+		}
+	}
+
+	if (!p.index && !group_set) {
+		fprintf(stderr, "param \"group\" not set\n");
+		usage();
+	}
+
+	if (!p.index && !rate_set) {
+		fprintf(stderr, "param \"rate\" not set\n");
+		usage();
+	}
+
+	tail = NLMSG_TAIL(n);
+	addattr_l(n, MAX_MSG, tca_id, NULL, 0);
+	addattr_l(n, MAX_MSG, TCA_SAMPLE_PARMS, &p, sizeof(p));
+	if (rate_set)
+		addattr32(n, MAX_MSG, TCA_SAMPLE_RATE, rate);
+	if (group_set)
+		addattr32(n, MAX_MSG, TCA_SAMPLE_PSAMPLE_GROUP, group);
+	if (trunc_set)
+		addattr32(n, MAX_MSG, TCA_SAMPLE_TRUNC_SIZE, trunc);
+
+	tail->rta_len = (char *)NLMSG_TAIL(n) - (char *)tail;
+
+	*argc_p = argc;
+	*argv_p = argv;
+	return 0;
+}
+
+static int print_sample(struct action_util *au, FILE *f, struct rtattr *arg)
+{
+	struct rtattr *tb[TCA_SAMPLE_MAX + 1];
+	struct tc_sample *p;
+
+	if (arg == NULL)
+		return -1;
+
+	parse_rtattr_nested(tb, TCA_SAMPLE_MAX, arg);
+
+	if (!tb[TCA_SAMPLE_PARMS] || !tb[TCA_SAMPLE_RATE] ||
+	    !tb[TCA_SAMPLE_PSAMPLE_GROUP]) {
+		fprintf(f, "[NULL sample parameters]");
+		return -1;
+	}
+	p = RTA_DATA(tb[TCA_SAMPLE_PARMS]);
+
+	fprintf(f, "sample rate 1/%d group %d",
+		rta_getattr_u32(tb[TCA_SAMPLE_RATE]),
+		rta_getattr_u32(tb[TCA_SAMPLE_PSAMPLE_GROUP]));
+
+	if (tb[TCA_SAMPLE_TRUNC_SIZE])
+		fprintf(f, " trunc_size %d",
+			rta_getattr_u32(tb[TCA_SAMPLE_TRUNC_SIZE]));
+
+	fprintf(f, "\n\tindex %d ref %d bind %d", p->index, p->refcnt,
+		p->bindcnt);
+
+	if (show_stats) {
+		if (tb[TCA_SAMPLE_TM]) {
+			struct tcf_t *tm = RTA_DATA(tb[TCA_SAMPLE_TM]);
+
+			print_tm(f, tm);
+		}
+	}
+	fprintf(f, "\n");
+	return 0;
+}
+
+struct action_util sample_action_util = {
+	.id = "sample",
+	.parse_aopt = parse_sample,
+	.print_aopt = print_sample,
+};
-- 
2.4.11

Re: [PATCH iproute2/net-next 1/3] tc: Add support for the sample tc action

[Florian Fainelli]

On 02/04/2017 11:58 PM, Yotam Gigi wrote:
> The sample tc action allows sampling packets matching a classifier. It
> peeks randomly packets, and samples them using the psample netlink
> channel. The user can specify the psample group, which the packet will be
> sampled to, the sampling rate and the packet truncation (to save
> kernel-user traffic).
> 
> The sampled packets contain informative metadata, for example, the input
> interface and the original packet length.
> 
> The action syntax:
> tc filter add [...] \
> 	action sample rate <RATE> group <GROUP> [trunc <SIZE>]
> 	[...]
> 
> Where:
>   RATE := The sampling rate which is the ratio of packets observed at the
> 	  data source to the samples generated
>   GROUP := the psample module sampling group
>   SIZE := optional truncation size
> 
> An example for a common usecase of the sample tc action: to sample ingress
> traffic from interface eth1, one may use the commands:
> 
> tc qdisc add dev eth1 handle ffff: ingress
> 
> tc filter add dev eth1 parent ffff: \
>        matchall action sample rate 12 group 4
> 
> Where the first command adds an ingress qdisc and the second starts
> sampling randomly with an average of one sampled packet per 12 packets
> on dev eth1 to psample group 4.

The group argument seems to be mandatory from looking at the code, but
what if just wanted to have a port mirroring between, say sw0p1 and
sw0p2 with the sample rate specified instead (without using the psample
netlink channel at all)? Could we make this group an optional argument
instead?

Thanks!
-- 
Florian

RE: [PATCH iproute2/net-next 1/3] tc: Add support for the sample tc action

[Yotam Gigi]

>-----Original Message-----
>From: Florian Fainelli [mailto:f.fainelli@gmail.com]
>Sent: Sunday, February 05, 2017 8:37 PM
>To: Yotam Gigi <yotamg@mellanox.com>; stephen@networkplumber.org;
>netdev@vger.kernel.org; Jiri Pirko <jiri@mellanox.com>; Elad Raz
><eladr@mellanox.com>
>Subject: Re: [PATCH iproute2/net-next 1/3] tc: Add support for the sample tc action
>
>On 02/04/2017 11:58 PM, Yotam Gigi wrote:
>> The sample tc action allows sampling packets matching a classifier. It
>> peeks randomly packets, and samples them using the psample netlink
>> channel. The user can specify the psample group, which the packet will be
>> sampled to, the sampling rate and the packet truncation (to save
>> kernel-user traffic).
>>
>> The sampled packets contain informative metadata, for example, the input
>> interface and the original packet length.
>>
>> The action syntax:
>> tc filter add [...] \
>> 	action sample rate <RATE> group <GROUP> [trunc <SIZE>]
>> 	[...]
>>
>> Where:
>>   RATE := The sampling rate which is the ratio of packets observed at the
>> 	  data source to the samples generated
>>   GROUP := the psample module sampling group
>>   SIZE := optional truncation size
>>
>> An example for a common usecase of the sample tc action: to sample ingress
>> traffic from interface eth1, one may use the commands:
>>
>> tc qdisc add dev eth1 handle ffff: ingress
>>
>> tc filter add dev eth1 parent ffff: \
>>        matchall action sample rate 12 group 4
>>
>> Where the first command adds an ingress qdisc and the second starts
>> sampling randomly with an average of one sampled packet per 12 packets
>> on dev eth1 to psample group 4.
>
>The group argument seems to be mandatory from looking at the code, but
>what if just wanted to have a port mirroring between, say sw0p1 and
>sw0p2 with the sample rate specified instead (without using the psample
>netlink channel at all)? Could we make this group an optional argument
>instead?

The kernel action currently don't support it, and I am not sure it should.

If I understand you correctly, you want to make the sample action identical
to mirred-mirror, only with random behavior. This can be done using the 
matchall and mirred action, plus the 'random' gact keyword. 

The sample action attaches some metadata in addition to the original packet
data, and that cannot be achieved by mirroring the packets, thus making it
unusable for our usecase. In the former version we attached the metadata
using the IFE protocol, but we decided to use a dedicated netlink channel 
instead.

>
>Thanks!
>--
>Florian

Re: [PATCH iproute2/net-next 1/3] tc: Add support for the sample tc action

[Florian Fainelli]

Le 02/05/17 à 12:22, Yotam Gigi a écrit :
>> -----Original Message-----
>> From: Florian Fainelli [mailto:f.fainelli@gmail.com]
>> Sent: Sunday, February 05, 2017 8:37 PM
>> To: Yotam Gigi <yotamg@mellanox.com>; stephen@networkplumber.org;
>> netdev@vger.kernel.org; Jiri Pirko <jiri@mellanox.com>; Elad Raz
>> <eladr@mellanox.com>
>> Subject: Re: [PATCH iproute2/net-next 1/3] tc: Add support for the sample tc action
>>
>> On 02/04/2017 11:58 PM, Yotam Gigi wrote:
>>> The sample tc action allows sampling packets matching a classifier. It
>>> peeks randomly packets, and samples them using the psample netlink
>>> channel. The user can specify the psample group, which the packet will be
>>> sampled to, the sampling rate and the packet truncation (to save
>>> kernel-user traffic).
>>>
>>> The sampled packets contain informative metadata, for example, the input
>>> interface and the original packet length.
>>>
>>> The action syntax:
>>> tc filter add [...] \
>>> 	action sample rate <RATE> group <GROUP> [trunc <SIZE>]
>>> 	[...]
>>>
>>> Where:
>>>   RATE := The sampling rate which is the ratio of packets observed at the
>>> 	  data source to the samples generated
>>>   GROUP := the psample module sampling group
>>>   SIZE := optional truncation size
>>>
>>> An example for a common usecase of the sample tc action: to sample ingress
>>> traffic from interface eth1, one may use the commands:
>>>
>>> tc qdisc add dev eth1 handle ffff: ingress
>>>
>>> tc filter add dev eth1 parent ffff: \
>>>        matchall action sample rate 12 group 4
>>>
>>> Where the first command adds an ingress qdisc and the second starts
>>> sampling randomly with an average of one sampled packet per 12 packets
>>> on dev eth1 to psample group 4.
>>
>> The group argument seems to be mandatory from looking at the code, but
>> what if just wanted to have a port mirroring between, say sw0p1 and
>> sw0p2 with the sample rate specified instead (without using the psample
>> netlink channel at all)? Could we make this group an optional argument
>> instead?
> 
> The kernel action currently don't support it, and I am not sure it should.
> 
> If I understand you correctly, you want to make the sample action identical
> to mirred-mirror, only with random behavior. This can be done using the 
> matchall and mirred action, plus the 'random' gact keyword.

It sounds like we can indeed, with random determ and using the VAL
argument we should be able to configure the capture divider; thanks!

> 
> The sample action attaches some metadata in addition to the original packet
> data, and that cannot be achieved by mirroring the packets, thus making it
> unusable for our usecase. In the former version we attached the metadata
> using the IFE protocol, but we decided to use a dedicated netlink channel 
> instead.

Yeah I see that now, thanks for the explanation!
-- 
Florian

RE: [PATCH iproute2/net-next 1/3] tc: Add support for the sample tc action

[Yotam Gigi]

>-----Original Message-----
>From: Florian Fainelli [mailto:f.fainelli@gmail.com]
>Sent: Sunday, February 05, 2017 10:55 PM
>To: Yotam Gigi <yotamg@mellanox.com>; stephen@networkplumber.org;
>netdev@vger.kernel.org; Jiri Pirko <jiri@mellanox.com>; Elad Raz
><eladr@mellanox.com>
>Subject: Re: [PATCH iproute2/net-next 1/3] tc: Add support for the sample tc action
>
>Le 02/05/17 à 12:22, Yotam Gigi a écrit :
>>> -----Original Message-----
>>> From: Florian Fainelli [mailto:f.fainelli@gmail.com]
>>> Sent: Sunday, February 05, 2017 8:37 PM
>>> To: Yotam Gigi <yotamg@mellanox.com>; stephen@networkplumber.org;
>>> netdev@vger.kernel.org; Jiri Pirko <jiri@mellanox.com>; Elad Raz
>>> <eladr@mellanox.com>
>>> Subject: Re: [PATCH iproute2/net-next 1/3] tc: Add support for the sample tc
>action
>>>
>>> On 02/04/2017 11:58 PM, Yotam Gigi wrote:
>>>> The sample tc action allows sampling packets matching a classifier. It
>>>> peeks randomly packets, and samples them using the psample netlink
>>>> channel. The user can specify the psample group, which the packet will be
>>>> sampled to, the sampling rate and the packet truncation (to save
>>>> kernel-user traffic).
>>>>
>>>> The sampled packets contain informative metadata, for example, the input
>>>> interface and the original packet length.
>>>>
>>>> The action syntax:
>>>> tc filter add [...] \
>>>> 	action sample rate <RATE> group <GROUP> [trunc <SIZE>]
>>>> 	[...]
>>>>
>>>> Where:
>>>>   RATE := The sampling rate which is the ratio of packets observed at the
>>>> 	  data source to the samples generated
>>>>   GROUP := the psample module sampling group
>>>>   SIZE := optional truncation size
>>>>
>>>> An example for a common usecase of the sample tc action: to sample ingress
>>>> traffic from interface eth1, one may use the commands:
>>>>
>>>> tc qdisc add dev eth1 handle ffff: ingress
>>>>
>>>> tc filter add dev eth1 parent ffff: \
>>>>        matchall action sample rate 12 group 4
>>>>
>>>> Where the first command adds an ingress qdisc and the second starts
>>>> sampling randomly with an average of one sampled packet per 12 packets
>>>> on dev eth1 to psample group 4.
>>>
>>> The group argument seems to be mandatory from looking at the code, but
>>> what if just wanted to have a port mirroring between, say sw0p1 and
>>> sw0p2 with the sample rate specified instead (without using the psample
>>> netlink channel at all)? Could we make this group an optional argument
>>> instead?
>>
>> The kernel action currently don't support it, and I am not sure it should.
>>
>> If I understand you correctly, you want to make the sample action identical
>> to mirred-mirror, only with random behavior. This can be done using the
>> matchall and mirred action, plus the 'random' gact keyword.
>
>It sounds like we can indeed, with random determ and using the VAL
>argument we should be able to configure the capture divider; thanks!

You're welcome. It took me some time to find that keyword too :)

>
>>
>> The sample action attaches some metadata in addition to the original packet
>> data, and that cannot be achieved by mirroring the packets, thus making it
>> unusable for our usecase. In the former version we attached the metadata
>> using the IFE protocol, but we decided to use a dedicated netlink channel
>> instead.
>
>Yeah I see that now, thanks for the explanation!
>--
>Florian

[PATCH iproute2/net-next 2/3] tc: man: Add man entry for the tc-sample action

[Yotam Gigi]

In addition to general information about the tc action, the man entry
contains common usage examples and information about the tlv fields packed
within each sampled packet.

Reviewed-by: Jiri Pirko <jiri@mellanox.com>
Signed-off-by: Yotam Gigi <yotamg@mellanox.com>
---
 man/man8/Makefile    |   2 +-
 man/man8/tc-sample.8 | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 126 insertions(+), 1 deletion(-)
 create mode 100644 man/man8/tc-sample.8

diff --git a/man/man8/Makefile b/man/man8/Makefile
index 77d347c..18e76f2 100644
--- a/man/man8/Makefile
+++ b/man/man8/Makefile
@@ -17,7 +17,7 @@ MAN8PAGES = $(TARGETS) ip.8 arpd.8 lnstat.8 routel.8 rtacct.8 rtmon.8 rtpr.8 ss.
 	tc-tcindex.8 tc-u32.8 tc-matchall.8 \
 	tc-connmark.8 tc-csum.8 tc-mirred.8 tc-nat.8 tc-pedit.8 tc-police.8 \
 	tc-simple.8 tc-skbedit.8 tc-vlan.8 tc-xt.8  tc-ife.8 \
-	tc-tunnel_key.8 \
+	tc-tunnel_key.8 tc-sample.8 \
 	devlink.8 devlink-dev.8 devlink-monitor.8 devlink-port.8 devlink-sb.8
 
 all: $(TARGETS)
diff --git a/man/man8/tc-sample.8 b/man/man8/tc-sample.8
new file mode 100644
index 0000000..3e03eba
--- /dev/null
+++ b/man/man8/tc-sample.8
@@ -0,0 +1,125 @@
+.TH "Packet sample action in tc" 8 "31 Jan 2017" "iproute2" "Linux"
+
+.SH NAME
+sample - packet sampling tc action
+.SH SYNOPSIS
+.in +8
+.ti -8
+
+.BR tc " ... " "action sample rate"
+.I RATE
+.BR "group"
+.I GROUP
+.RB "[ " trunc
+.IR SIZE " ] "
+.RB "[ " index
+.IR INDEX " ] "
+.ti -8
+
+.BR tc " ... " "action sample index "
+.I INDEX
+.ti -8
+
+.SH DESCRIPTION
+The
+.B sample
+action allows sampling packets matching classifier.
+
+The packets are chosen randomly according to the
+.B rate
+parameter, and are sampled using the
+.B psample
+generic netlink channel. The user can also specify packet truncation to save
+user-kernel traffic. Each sample includes some informative metadata about the
+original packet, which is sent using netlink attributes, alongside the original
+packet data.
+
+The user can either specify the sample action parameters as presented in the
+first form above, or use an existing sample action using its index, as presented
+in the second form.
+
+.SH SAMPLED PACKETS METADATA FIELDS
+The metadata are delivered to userspace applications using the
+.B psample
+generic netlink channel, where each sample includes the following netlink
+attributes:
+.TP
+.BI PSAMPLE_ATTR_IIFINDEX
+The input interface index of the packet, if there is one.
+.TP
+.BI PSAMPLE_ATTR_OIFINDEX
+The output interface index of the packet. This field is not relevant on ingress
+sampling
+.TP
+.BI PSAMPLE_ATTR_ORIGSIZE
+The size of the original packet (before truncation)
+.TP
+.BI PSAMPLE_ATTR_SAMPLE_GROUP
+The
+.B psample
+group the packet was sent to
+.TP
+.BI PSAMPLE_ATTR_GROUP_SEQ
+A sequence number of the sampled packet. This number is incremented with each
+sampled packet of the current
+.B psample
+group
+.TP
+.BI PSAMPLE_ATTR_SAMPLE_RATE
+The rate the packet was sampled with
+.RE
+
+.SH OPTIONS
+.TP
+.BI rate " RATE"
+The packet sample rate.
+.I "RATE"
+is the expected ratio between observed packets and sampled packets. For example,
+.I "RATE"
+of 100 will lead to an average of one sampled packet out of every 100 observed.
+.TP
+.BI trunc " SIZE"
+Upon set, defines the maximum size of the sampled packets, and causes truncation
+if needed
+.TP
+.BI group " GROUP"
+The
+.B psample
+group the packet will be sent to. The
+.B psample
+module defines the concept of groups, which allows the user to match specific
+sampled packets in the case of multiple sampling rules, thus identify only the
+packets that came from a specific rule.
+.TP
+.BI index " INDEX"
+Is a unique ID for an action. When creating new action instance, this parameter
+allows to set the new action index. When using existing action, this parameter
+allows to specify the existing action index.  The index must 32bit unsigned
+integer greater than zero.
+.SH EXAMPLES
+Sample one of every 100 packets flowing into interface eth0 to psample group 12:
+
+.RS
+.EX
+tc qdisc add dev eth0 handle ffff: ingress
+tc filter add dev eth0 parent ffff: matchall \\
+     action sample rate 100 group 12 index 19
+.EE
+.RE
+
+Use the same action instance to sample eth1 too:
+
+.RS
+.EX
+tc qdisc add dev eth1 handle ffff: ingress
+tc filter add dev eth1 parent ffff: matchall \\
+     action sample index 19
+.EE
+.RE
+
+.EE
+.RE
+.SH SEE ALSO
+.BR tc (8),
+.BR tc-matchall (8)
+.BR psample (1)
-- 
2.4.11

[PATCH iproute2/net-next 3/3] tc: man: matchall: Update examples to include sample

[Yotam Gigi]

Add an example of packet sampling to the tc-matchall man page examples
section. The example uses the matchall classifier and the sample action to
create packet sampling on a port.

Reviewed-by: Jiri Pirko <jiri@mellanox.com>
Signed-off-by: Yotam Gigi <yotamg@mellanox.com>
---
 man/man8/tc-matchall.8 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man/man8/tc-matchall.8 b/man/man8/tc-matchall.8
index f920922..799350a 100644
--- a/man/man8/tc-matchall.8
+++ b/man/man8/tc-matchall.8
@@ -70,6 +70,16 @@ that replaces the root qdisc on device
 where the second command attaches a matchall filters on it that mirrors the
 packets to device eth2.
 
+To sample one of every 100 packets flowing into interface eth0 to psample group
+12:
+.RS
+.EX
+
+tc qdisc add dev eth0 handle ffff: ingress
+tc filter add dev eth0 parent ffff: matchall \\
+     action sample rate 100 group 12
+.EE
+.RE
 
 .EE
 .SH SEE ALSO
-- 
2.4.11

Re: [PATCH iproute2/net-next 0/3] Add the tc-sample action

[Stephen Hemminger]

On Sun,  5 Feb 2017 09:58:51 +0200
Yotam Gigi <yotamg@mellanox.com> wrote:

> This patchset adds the tc-sample action support and the corresponding man
> page. More information about the action and its usage can be found in the
> commit message.
> 
> Yotam Gigi (3):
>   tc: Add support for the sample tc action
>   tc: man: Add man entry for the tc-sample action
>   tc: man: matchall: Update examples to include sample
> 
>  bash-completion/tc               |   8 +-
>  include/linux/tc_act/tc_sample.h |  26 ++++++
>  man/man8/Makefile                |   2 +-
>  man/man8/tc-matchall.8           |  10 +++
>  man/man8/tc-sample.8             | 125 ++++++++++++++++++++++++++
>  tc/Makefile                      |   1 +
>  tc/m_sample.c                    | 186 +++++++++++++++++++++++++++++++++++++++
>  7 files changed, 356 insertions(+), 2 deletions(-)
>  create mode 100644 include/linux/tc_act/tc_sample.h
>  create mode 100644 man/man8/tc-sample.8
>  create mode 100644 tc/m_sample.c
> 

Applied to net-next. I had to fix merge conflict on tc/Makefile