Debian Codegraph @

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

raw
1 .TH "Policing action in tc" 8 "20 Jan 2015" "iproute2" "Linux"
2
3 .SH NAME
4 police - policing action
5 .SH SYNOPSIS
6 .in +8
7 .ti -8
8 .BR tc " ... " "action police ["
9 .BI rate " RATE " burst
10 .IR BYTES [\fB/ BYTES "] ] ["
11 .BI pkts_rate " RATE " pkts_burst
12 .IR PACKETS "] ["
13 .B mtu
14 .IR BYTES [\fB/ BYTES "] ] ["
15 .BI peakrate " RATE"
16 ] [
17 .BI overhead " BYTES"
18 ] [
19 .BI linklayer " TYPE"
20 ] [
21 .IR CONTROL " ]"
22
23 .ti -8
24 .BR tc " ... " filter " ... [ " estimator
25 .IR "SAMPLE AVERAGE " ]
26 .BR "action police avrate"
27 .IR RATE " [ " CONTROL " ]"
28
29 .ti -8
30 .IR CONTROL " :="
31 .BI conform-exceed " EXCEEDACT\fR[\fB/\fINOTEXCEEDACT"
32
33 .ti -8
34 .IR EXCEEDACT/NOTEXCEEDACT " := { "
35 .BR pipe " | " ok " | " reclassify " | " drop " | " continue " | " goto " " chain " " CHAIN_INDEX " }"
36 .SH DESCRIPTION
37 The
38 .B police
39 action allows limiting of the byte or packet rate of traffic matched by the
40 filter it is attached to.
41 .P
42 There are two different algorithms available to measure the byte rate: The
43 first one uses an internal dual token bucket and is configured using the
44 .BR rate ", " burst ", " mtu ", " peakrate ", " overhead " and " linklayer
45 parameters. The second one uses an in-kernel sampling mechanism. It can be
46 fine-tuned using the
47 .B estimator
48 filter parameter.
49 .P
50 There is one algorithm available to measure packet rate and it is similar to
51 the first algorithm described for byte rate. It is configured using the
52 .BR pkt_rate " and " pkt_burst
53 parameters.
54 .P
55 At least one of the
56 .BR rate " and " pkt_rate "
57 parameters must be configured.
58 .SH OPTIONS
59 .TP
60 .BI rate " RATE"
61 The maximum byte rate of packets passing this action. Those exceeding it will
62 be treated as defined by the
63 .B conform-exceed
64 option.
65 .TP
66 .BI burst " BYTES\fR[\fB/\fIBYTES\fR]"
67 Set the maximum allowed burst in bytes, optionally followed by a slash ('/')
68 sign and cell size which must be a power of 2.
69 .TP
70 .BI pkt_rate " RATE"
71 The maximum packet rate or packets passing this action. Those exceeding it will
72 be treated as defined by the
73 .B conform-exceed
74 option.
75 .TP
76 .BI pkt_burst " PACKETS"
77 Set the maximum allowed burst in packets.
78 .TP
79 .BI mtu " BYTES\fR[\fB/\fIBYTES\fR]"
80 This is the maximum packet size handled by the policer (larger ones will be
81 handled like they exceeded the configured rate). Setting this value correctly
82 will improve the scheduler's precision.
83 Value formatting is identical to
84 .B burst
85 above. Defaults to unlimited.
86 .TP
87 .BI peakrate " RATE"
88 Set the maximum bucket depletion rate, exceeding
89 .BR rate .
90 .TP
91 .BI avrate " RATE"
92 Make use of an in-kernel bandwidth rate estimator and match the given
93 .I RATE
94 against it.
95 .TP
96 .BI overhead " BYTES"
97 Account for protocol overhead of encapsulating output devices when computing
98 .BR rate " and " peakrate .
99 .TP
100 .BI linklayer " TYPE"
101 Specify the link layer type.
102 .I TYPE
103 may be one of
104 .B ethernet
105 (the default),
106 .BR atm " or " adsl
107 (which are synonyms). It is used to align the precomputed rate tables to ATM
108 cell sizes, for
109 .B ethernet
110 no action is taken.
111 .TP
112 .BI estimator " SAMPLE AVERAGE"
113 Fine-tune the in-kernel packet rate estimator.
114 .IR SAMPLE " and " AVERAGE
115 are time values and control the frequency in which samples are taken and over
116 what timespan an average is built.
117 .TP
118 .BI conform-exceed " EXCEEDACT\fR[\fB/\fINOTEXCEEDACT\fR]"
119 Define how to handle packets which exceed or conform the
120 configured bandwidth limit. Possible values are:
121 .RS
122 .IP continue
123 Don't do anything, just continue with the next action in line.
124 .IP drop
125 Drop the packet immediately.
126 .IP shot
127 This is a synonym to
128 .BR drop .
129 .IP ok
130 Accept the packet. This is the default for conforming packets.
131 .IP pass
132 This is a synonym to
133 .BR ok .
134 .IP reclassify
135 Treat the packet as non-matching to the filter this action is attached to and
136 continue with the next filter in line (if any). This is the default for
137 exceeding packets.
138 .IP pipe
139 Pass the packet to the next action in line.
140 .RE
141 .SH EXAMPLES
142 A typical application of the police action is to enforce ingress traffic rate
143 by dropping exceeding packets. Although better done on the sender's side,
144 especially in scenarios with lack of peer control (e.g. with dial-up providers)
145 this is often the best one can do in order to keep latencies low under high
146 load. The following establishes input bandwidth policing to 1mbit/s using the
147 .B ingress
148 qdisc and
149 .B u32
150 filter:
151
152 .RS
153 .EX
154 # tc qdisc add dev eth0 handle ffff: ingress
155 # tc filter add dev eth0 parent ffff: u32 \\
156 match u32 0 0 \\
157 police rate 1mbit burst 100k
158 .EE
159 .RE
160
161 As an action can not live on it's own, there always has to be a filter involved as link between qdisc and action. The example above uses
162 .B u32
163 for that, which is configured to effectively match any packet (passing it to the
164 .B police
165 action thereby).
166
167 .SH SEE ALSO
168 .BR tc (8)