Blame man/man8/tc-sample.8

Packit Service 3880ab
.TH "Packet sample action in tc" 8 "31 Jan 2017" "iproute2" "Linux"
Packit Service 3880ab
Packit Service 3880ab
.SH NAME
Packit Service 3880ab
sample - packet sampling tc action
Packit Service 3880ab
.SH SYNOPSIS
Packit Service 3880ab
.in +8
Packit Service 3880ab
.ti -8
Packit Service 3880ab
Packit Service 3880ab
.BR tc " ... " "action sample rate"
Packit Service 3880ab
.I RATE
Packit Service 3880ab
.BR "group"
Packit Service 3880ab
.I GROUP
Packit Service 3880ab
.RB "[ " trunc
Packit Service 3880ab
.IR SIZE " ] "
Packit Service 3880ab
.RB "[ " index
Packit Service 3880ab
.IR INDEX " ] "
Packit Service 3880ab
.ti -8
Packit Service 3880ab
Packit Service 3880ab
.BR tc " ... " "action sample index "
Packit Service 3880ab
.I INDEX
Packit Service 3880ab
.ti -8
Packit Service 3880ab
Packit Service 3880ab
.SH DESCRIPTION
Packit Service 3880ab
The
Packit Service 3880ab
.B sample
Packit Service 3880ab
action allows sampling packets matching classifier.
Packit Service 3880ab
Packit Service 3880ab
The packets are chosen randomly according to the
Packit Service 3880ab
.B rate
Packit Service 3880ab
parameter, and are sampled using the
Packit Service 3880ab
.B psample
Packit Service 3880ab
generic netlink channel. The user can also specify packet truncation to save
Packit Service 3880ab
user-kernel traffic. Each sample includes some informative metadata about the
Packit Service 3880ab
original packet, which is sent using netlink attributes, alongside the original
Packit Service 3880ab
packet data.
Packit Service 3880ab
Packit Service 3880ab
The user can either specify the sample action parameters as presented in the
Packit Service 3880ab
first form above, or use an existing sample action using its index, as presented
Packit Service 3880ab
in the second form.
Packit Service 3880ab
Packit Service 3880ab
.SH SAMPLED PACKETS METADATA FIELDS
Packit Service 3880ab
The metadata are delivered to userspace applications using the
Packit Service 3880ab
.B psample
Packit Service 3880ab
generic netlink channel, where each sample includes the following netlink
Packit Service 3880ab
attributes:
Packit Service 3880ab
.TP
Packit Service 3880ab
.BI PSAMPLE_ATTR_IIFINDEX
Packit Service 3880ab
The input interface index of the packet, if there is one.
Packit Service 3880ab
.TP
Packit Service 3880ab
.BI PSAMPLE_ATTR_OIFINDEX
Packit Service 3880ab
The output interface index of the packet. This field is not relevant on ingress
Packit Service 3880ab
sampling
Packit Service 3880ab
.TP
Packit Service 3880ab
.BI PSAMPLE_ATTR_ORIGSIZE
Packit Service 3880ab
The size of the original packet (before truncation)
Packit Service 3880ab
.TP
Packit Service 3880ab
.BI PSAMPLE_ATTR_SAMPLE_GROUP
Packit Service 3880ab
The
Packit Service 3880ab
.B psample
Packit Service 3880ab
group the packet was sent to
Packit Service 3880ab
.TP
Packit Service 3880ab
.BI PSAMPLE_ATTR_GROUP_SEQ
Packit Service 3880ab
A sequence number of the sampled packet. This number is incremented with each
Packit Service 3880ab
sampled packet of the current
Packit Service 3880ab
.B psample
Packit Service 3880ab
group
Packit Service 3880ab
.TP
Packit Service 3880ab
.BI PSAMPLE_ATTR_SAMPLE_RATE
Packit Service 3880ab
The rate the packet was sampled with
Packit Service 3880ab
Packit Service 3880ab
.SH OPTIONS
Packit Service 3880ab
.TP
Packit Service 3880ab
.BI rate " RATE"
Packit Service 3880ab
The packet sample rate.
Packit Service 3880ab
.I "RATE"
Packit Service 3880ab
is the expected ratio between observed packets and sampled packets. For example,
Packit Service 3880ab
.I "RATE"
Packit Service 3880ab
of 100 will lead to an average of one sampled packet out of every 100 observed.
Packit Service 3880ab
.TP
Packit Service 3880ab
.BI trunc " SIZE"
Packit Service 3880ab
Upon set, defines the maximum size of the sampled packets, and causes truncation
Packit Service 3880ab
if needed
Packit Service 3880ab
.TP
Packit Service 3880ab
.BI group " GROUP"
Packit Service 3880ab
The
Packit Service 3880ab
.B psample
Packit Service 3880ab
group the packet will be sent to. The
Packit Service 3880ab
.B psample
Packit Service 3880ab
module defines the concept of groups, which allows the user to match specific
Packit Service 3880ab
sampled packets in the case of multiple sampling rules, thus identify only the
Packit Service 3880ab
packets that came from a specific rule.
Packit Service 3880ab
.TP
Packit Service 3880ab
.BI index " INDEX"
Packit Service 3880ab
Is a unique ID for an action. When creating new action instance, this parameter
Packit Service 3880ab
allows to set the new action index. When using existing action, this parameter
Packit Service 3880ab
allows to specify the existing action index.  The index must 32bit unsigned
Packit Service 3880ab
integer greater than zero.
Packit Service 3880ab
.SH EXAMPLES
Packit Service 3880ab
Sample one of every 100 packets flowing into interface eth0 to psample group 12:
Packit Service 3880ab
Packit Service 3880ab
.RS
Packit Service 3880ab
.EX
Packit Service 3880ab
tc qdisc add dev eth0 handle ffff: ingress
Packit Service 3880ab
tc filter add dev eth0 parent ffff: matchall \\
Packit Service 3880ab
     action sample rate 100 group 12 index 19
Packit Service 3880ab
.EE
Packit Service 3880ab
.RE
Packit Service 3880ab
Packit Service 3880ab
Use the same action instance to sample eth1 too:
Packit Service 3880ab
Packit Service 3880ab
.RS
Packit Service 3880ab
.EX
Packit Service 3880ab
tc qdisc add dev eth1 handle ffff: ingress
Packit Service 3880ab
tc filter add dev eth1 parent ffff: matchall \\
Packit Service 3880ab
     action sample index 19
Packit Service 3880ab
.EE
Packit Service 3880ab
.RE
Packit Service 3880ab
Packit Service 3880ab
.SH SEE ALSO
Packit Service 3880ab
.BR tc (8),
Packit Service 3880ab
.BR tc-matchall (8)
Packit Service 3880ab
.BR psample (1)