Debian Codegraph @

upstream/debian-unstable/man8/tc-sample.8

raw
1 .TH "Packet sample action in tc" 8 "31 Jan 2017" "iproute2" "Linux"
2
3 .SH NAME
4 sample - packet sampling tc action
5 .SH SYNOPSIS
6 .in +8
7 .ti -8
8
9 .BR tc " ... " "action sample rate"
10 .I RATE
11 .BR "group"
12 .I GROUP
13 .RB "[ " trunc
14 .IR SIZE " ] "
15 .RB "[ " index
16 .IR INDEX " ] "
17 .ti -8
18
19 .BR tc " ... " "action sample index "
20 .I INDEX
21 .ti -8
22
23 .SH DESCRIPTION
24 The
25 .B sample
26 action allows sampling packets matching classifier.
27
28 The packets are chosen randomly according to the
29 .B rate
30 parameter, and are sampled using the
31 .B psample
32 generic netlink channel. The user can also specify packet truncation to save
33 user-kernel traffic. Each sample includes some informative metadata about the
34 original packet, which is sent using netlink attributes, alongside the original
35 packet data.
36
37 The user can either specify the sample action parameters as presented in the
38 first form above, or use an existing sample action using its index, as presented
39 in the second form.
40
41 .SH SAMPLED PACKETS METADATA FIELDS
42 The metadata are delivered to userspace applications using the
43 .B psample
44 generic netlink channel, where each sample includes the following netlink
45 attributes:
46 .TP
47 .BI PSAMPLE_ATTR_IIFINDEX
48 The input interface index of the packet, if there is one.
49 .TP
50 .BI PSAMPLE_ATTR_OIFINDEX
51 The output interface index of the packet. This field is not relevant on ingress
52 sampling
53 .TP
54 .BI PSAMPLE_ATTR_ORIGSIZE
55 The size of the original packet (before truncation)
56 .TP
57 .BI PSAMPLE_ATTR_SAMPLE_GROUP
58 The
59 .B psample
60 group the packet was sent to
61 .TP
62 .BI PSAMPLE_ATTR_GROUP_SEQ
63 A sequence number of the sampled packet. This number is incremented with each
64 sampled packet of the current
65 .B psample
66 group
67 .TP
68 .BI PSAMPLE_ATTR_SAMPLE_RATE
69 The rate the packet was sampled with
70
71 .SH OPTIONS
72 .TP
73 .BI rate " RATE"
74 The packet sample rate.
75 .I "RATE"
76 is the expected ratio between observed packets and sampled packets. For example,
77 .I "RATE"
78 of 100 will lead to an average of one sampled packet out of every 100 observed.
79 .TP
80 .BI trunc " SIZE"
81 Upon set, defines the maximum size of the sampled packets, and causes truncation
82 if needed
83 .TP
84 .BI group " GROUP"
85 The
86 .B psample
87 group the packet will be sent to. The
88 .B psample
89 module defines the concept of groups, which allows the user to match specific
90 sampled packets in the case of multiple sampling rules, thus identify only the
91 packets that came from a specific rule.
92 .TP
93 .BI index " INDEX"
94 Is a unique ID for an action. When creating new action instance, this parameter
95 allows one to set the new action index. When using existing action, this parameter
96 allows one to specify the existing action index. The index must 32bit unsigned
97 integer greater than zero.
98 .SH EXAMPLES
99 Sample one of every 100 packets flowing into interface eth0 to psample group 12:
100
101 .RS
102 .EX
103 tc qdisc add dev eth0 handle ffff: ingress
104 tc filter add dev eth0 parent ffff: matchall \\
105 action sample rate 100 group 12 index 19
106 .EE
107 .RE
108
109 Use the same action instance to sample eth1 too:
110
111 .RS
112 .EX
113 tc qdisc add dev eth1 handle ffff: ingress
114 tc filter add dev eth1 parent ffff: matchall \\
115 action sample index 19
116 .EE
117 .RE
118
119 .SH SEE ALSO
120 .BR tc (8),
121 .BR tc-matchall (8)
122 .BR psample (1)