man/man8/tc-sample.8

   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 .RE
  71
  72 .SH OPTIONS
  73 .TP
  74 .BI rate " RATE"
  75 The packet sample rate.
  76 .I "RATE"
  77 is the expected ratio between observed packets and sampled packets. For example,
  78 .I "RATE"
  79 of 100 will lead to an average of one sampled packet out of every 100 observed.
  80 .TP
  81 .BI trunc " SIZE"
  82 Upon set, defines the maximum size of the sampled packets, and causes truncation
  83 if needed
  84 .TP
  85 .BI group " GROUP"
  86 The
  87 .B psample
  88 group the packet will be sent to. The
  89 .B psample
  90 module defines the concept of groups, which allows the user to match specific
  91 sampled packets in the case of multiple sampling rules, thus identify only the
  92 packets that came from a specific rule.
  93 .TP
  94 .BI index " INDEX"
  95 Is a unique ID for an action. When creating new action instance, this parameter
  96 allows to set the new action index. When using existing action, this parameter
  97 allows to specify the existing action index.  The index must 32bit unsigned
  98 integer greater than zero.
  99 .SH EXAMPLES
 100 Sample one of every 100 packets flowing into interface eth0 to psample group 12:
 101
 102 .RS
 103 .EX
 104 tc qdisc add dev eth0 handle ffff: ingress
 105 tc filter add dev eth0 parent ffff: matchall \\
 106      action sample rate 100 group 12 index 19
 107 .EE
 108 .RE
 109
 110 Use the same action instance to sample eth1 too:
 111
 112 .RS
 113 .EX
 114 tc qdisc add dev eth1 handle ffff: ingress
 115 tc filter add dev eth1 parent ffff: matchall \\
 116      action sample index 19
 117 .EE
 118 .RE
 119
 120 .EE
 121 .RE
 122 .SH SEE ALSO
 123 .BR tc (8),
 124 .BR tc-matchall (8)
 125 .BR psample (1)