| 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) |