6 .Nd Traffic shaper control program
26 .Brq Cm delete | list | show
41 utility is the user interface for controlling the
46 operates by first using a packet filter to classify packets and divide them into
48 using any match pattern that can be used in
51 Depending on local policies, a flow can contain packets for a single
52 TCP connection, or from/to a given host, or entire subnet, or a
55 Packets belonging to the same flow are then passed to either of two
56 different objects, which implement the traffic regulation:
57 .Bl -hang -offset XXXX
59 A pipe emulates a link with given bandwidth, propagation delay,
60 queue size and packet loss rate.
61 Packets are queued in front of the pipe as they come out from the classifier,
62 and then transferred to the pipe according to the pipe's parameters.
66 is an abstraction used to implement the WF2Q+
67 (Worst-case Fair Weighted Fair Queueing) policy, which is
68 an efficient variant of the WFQ policy.
70 The queue associates a
72 and a reference pipe to each flow, and then all backlogged (i.e.,
73 with packets queued) flows linked to the same pipe share the pipe's
74 bandwidth proportionally to their weights.
75 Note that weights are not priorities; a flow with a lower weight
76 is still guaranteed to get its fraction of the bandwidth even if a
77 flow with a higher weight is permanently backlogged.
82 can be used to set hard limits to the bandwidth that a flow can use, whereas
84 can be used to determine how different flow share the available bandwidth.
90 configuration commands are the following:
91 .Bd -ragged -offset indent
92 .Cm pipe Ar number Cm config Ar pipe-configuration
94 .Cm queue Ar number Cm config Ar queue-configuration
97 The following parameters can be configured for a pipe:
99 .Bl -tag -width indent -compact
100 .It Cm bw Ar bandwidth | device
101 Bandwidth, measured in
104 .Brq Cm bit/s | Byte/s .
107 A value of 0 (default) means unlimited bandwidth.
108 The unit must immediately follow the number, as in
110 .Dl "dnctl pipe 1 config bw 300Kbit/s"
112 If a device name is specified instead of a numeric value, as in
114 .Dl "dnctl pipe 1 config bw tun0"
116 then the transmit clock is supplied by the specified device.
121 .It Cm delay Ar ms-delay
122 Propagation delay, measured in milliseconds.
123 The value is rounded to the next multiple of the clock tick
124 (typically 10ms, but it is a good practice to run kernels
126 .Dq "options HZ=1000"
128 the granularity to 1ms or less).
129 Default value is 0, meaning no delay.
132 The following parameters can be configured for a queue:
134 .Bl -tag -width indent -compact
135 .It Cm pipe Ar pipe_nr
136 Connects a queue to the specified pipe.
137 Multiple queues (with the same or different weights) can be connected to
138 the same pipe, which specifies the aggregate rate for the set of queues.
140 .It Cm weight Ar weight
141 Specifies the weight to be used for flows matching this queue.
142 The weight must be in the range 1..100, and defaults to 1.
145 Finally, the following parameters can be configured for both
148 .Bl -tag -width XXXX -compact
149 .It Cm buckets Ar hash-table-size
150 Specifies the size of the hash table used for storing the
152 Default value is 64 controlled by the
155 .Em net.inet.ip.dummynet.hash_size ,
156 allowed range is 16 to 65536.
158 .It Cm mask Ar mask-specifier
159 Packets sent to a given pipe or queue by an
161 rule can be further classified into multiple flows, each of which is then
165 A flow identifier is constructed by masking the IP addresses,
166 ports and protocol types as specified with the
168 options in the configuration of the pipe or queue.
169 For each different flow identifier, a new pipe or queue is created
170 with the same parameters as the original object, and matching packets
175 are used, each flow will get the same bandwidth as defined by the pipe,
178 are used, each flow will share the parent's pipe bandwidth evenly
179 with other flows generated by the same queue (note that other queues
180 with different weights might be connected to the same pipe).
182 Available mask specifiers are a combination of one or more of the following:
185 .Cm dst-ip6 Ar mask ,
187 .Cm src-ip6 Ar mask ,
188 .Cm dst-port Ar mask ,
189 .Cm src-port Ar mask ,
194 where the latter means all bits in all fields are significant.
197 When a packet is dropped by a dummynet queue or pipe, the error
198 is normally reported to the caller routine in the kernel, in the
199 same way as it happens when a device queue fills up. Setting this
200 option reports the packet as successfully delivered, which can be
201 needed for some experimental setups where you want to simulate
202 loss or congestion at a remote router.
204 .It Cm plr Ar packet-loss-rate
208 is a floating-point number between 0 and 1, with 0 meaning no
209 loss, 1 meaning 100% loss.
210 The loss rate is internally represented on 31 bits.
212 .It Cm queue Brq Ar slots | size Ns Cm Kbytes
217 Default value is 50 slots, which
218 is the typical queue size for Ethernet devices.
219 Note that for slow speed links you should keep the queue
220 size short or your traffic might be affected by a significant
222 E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit
223 or 20s of queue on a 30Kbit/s pipe.
224 Even worse effect can result if you get packets from an
225 interface with a much larger MTU, e.g. the loopback interface
226 with its 16KB packets.
228 .It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p
229 Make use of the RED (Random Early Detection) queue management algorithm.
234 point numbers between 0 and 1 (0 not included), while
238 are integer numbers specifying thresholds for queue management
239 (thresholds are computed in bytes if the queue has been defined
240 in bytes, in slots otherwise).
243 also supports the gentle RED variant (gred).
247 variables can be used to control the RED behaviour:
248 .Bl -tag -width indent
249 .It Em net.inet.ip.dummynet.red_lookup_depth
250 specifies the accuracy in computing the average queue
251 when the link is idle (defaults to 256, must be greater than zero)
252 .It Em net.inet.ip.dummynet.red_avg_pkt_size
253 specifies the expected average packet size (defaults to 512, must be
255 .It Em net.inet.ip.dummynet.red_max_pkt_size
256 specifies the expected maximum packet size, only used when queue
257 thresholds are in bytes (defaults to 1500, must be greater than zero).
261 The following options are available:
262 .Bl -tag -width indent
264 While listing, show counter values.
267 command just implies this option.
269 Don't ask for confirmation for commands that can cause problems
272 If there is no tty associated with the process, this is implied.
274 Displays a short help.
276 Only check syntax of the command strings, without actually passing
285 be quiet about actions
288 This is useful for adjusting rules by executing multiple
291 or by processing a file of many
293 rules across a remote login session.
296 is performed in normal (verbose) mode (with the default kernel
297 configuration), it prints a message.
298 Because all rules are flushed, the message might not be delivered
299 to the login session, causing the remote login session to be closed
300 and the remainder of the ruleset to not be processed.
301 Access to the console would then be required to recover.
303 While listing pipes, sort according to one of the four
304 counters (total or current packets or bytes).
309 To ease configuration, rules can be put into a file which is
312 as shown in the last synopsis line.
316 The file will be read line by line and applied as arguments to the
320 Optionally, a preprocessor can be specified using
324 is to be piped through.
325 Useful preprocessors include
331 doesn't start with a slash
333 as its first character, the usual
335 name search is performed.
336 Care should be taken with this in environments where not all
337 file systems are mounted (yet) by the time
339 is being run (e.g. when they are mounted over NFS).
342 has been specified, any additional arguments as passed on to the preprocessor
344 This allows for flexible configuration files (like conditionalizing
345 them on the local hostname) and the use of macros to centralize
346 frequently required arguments like IP addresses.
349 Here are some important points to consider when designing your
353 Remember that you filter both packets going
357 Most connections need packets going in both directions.
359 Remember to test very carefully.
360 It is a good idea to be near the console when doing this.
362 Don't forget the loopback interface.
367 variables controls the behaviour of the
370 These are shown below together with their default value
371 (but always check with the
373 command what value is actually in use) and meaning:
374 .Bl -tag -width indent
375 .It Em net.inet.ip.dummynet.expire : No 1
376 Lazily delete dynamic pipes/queue once they have no pending traffic.
377 You can disable this by setting the variable to 0, in which case
378 the pipes/queues will only be deleted when the threshold is reached.
379 .It Em net.inet.ip.dummynet.hash_size : No 64
380 Default size of the hash table used for dynamic pipes/queues.
381 This value is used when no
383 option is specified when configuring a pipe/queue.
384 .It Em net.inet.ip.dummynet.max_chain_len : No 16
385 Target value for the maximum number of pipes/queues in a hash bucket.
387 .Cm max_chain_len*hash_size
388 is used to determine the threshold over which empty pipes/queues
389 will be expired even when
390 .Cm net.inet.ip.dummynet.expire=0 .
391 .It Em net.inet.ip.dummynet.red_lookup_depth : No 256
392 .It Em net.inet.ip.dummynet.red_avg_pkt_size : No 512
393 .It Em net.inet.ip.dummynet.red_max_pkt_size : No 1500
394 Parameters used in the computations of the drop probability
395 for the RED algorithm.
398 The following rules show some of the applications of
399 for simulations and the like by using
405 To drop random incoming IPv4 and IPv6 ICMP packets with a probability of 5%,
407 .Dl "dnctl pipe 10 config plr 0.05"
409 and add these rules in your pf.conf file:
410 .Dl "dummynet in inet proto icmp all pipe 10"
411 .Dl "dummynet in inet6 proto ipv6-icmp all pipe 10"
413 Should we want to simulate a bidirectional link with bandwidth
414 limitations, the correct way is to create a pipe for each direction:
415 .Dl "dnctl pipe 1 config bw 14Kbit/s queue 10Kbytes"
416 .Dl "dnctl pipe 2 config bw 1Kbit/s queue 10Kbytes"
418 and add these rules in your pf.conf file:
419 .Dl "dummynet in all pipe 1"
420 .Dl "dummynet out all pipe 2"
422 The above can be very useful, e.g. if you want to see how
423 your fancy Web page will look for a residential user who
424 is connected only through a slow link.
425 You should not use only one pipe for both directions, unless
426 you want to simulate a half-duplex medium (e.g. AppleTalk,
429 Note that with the above rules the pipes receive traffic for both the
430 IPv4 and IPv6 protocols.
432 Should we want to verify network performance with the RED queue
433 management algorithm, create this pipe:
434 .Dl "dnctl pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1"
436 and then add these rules to you pf.conf file:
437 .Dl "dummynet all pipe 1"
439 Another typical application of the traffic shaper is to
440 introduce some delay in the communication.
441 This can significantly affect applications which do a lot of Remote
442 Procedure Calls, and where the round-trip-time of the
443 connection often becomes a limiting factor much more than
445 .Dl "dnctl pipe 1 config delay 250ms bw 1Mbit/s"
446 .Dl "dnctl pipe 2 config delay 250ms bw 1Mbit/s"
448 and add these rules in your pf.conf file:
449 .Dl "dummynet in all pipe 1"
450 .Dl "dummynet out all pipe 2"
452 Per-flow queueing can be useful for a variety of purposes.
453 A very simple one is counting traffic:
454 .Dl "dnctl pipe 1 config mask all"
456 and add these statements in your pf.conf file:
457 .Dl "dummynet in quick proto tcp all pipe 1"
458 .Dl "dummynet out quick proto tcp all pipe 1"
459 .Dl "dummynet in quick proto udp all pipe 1"
460 .Dl "dummynet out quick proto udp all pipe 1"
461 .Dl "dummynet in quick all pipe 1"
462 .Dl "dummynet out quick all pipe 1"
464 The above set of rules will create queues (and collect
465 statistics) for all traffic.
466 Because the pipes have no limitations, the only effect is
467 collecting statistics.
468 Note that we need six rules, not just the last two one, because
471 tries to match IP packets it will not consider ports, so we
472 would not see connections on separate ports as different
485 .An Ugen J. S. Antsilevich ,
486 .An Poul-Henning Kamp ,
492 API based upon code written by
498 traffic shaper supported by Akamba Corp.
502 utility first appeared in
507 Stateful extensions were introduced in
projects / apple / network_cmds.git / blob