.Dd August 13, 2002
.Dt DNCTL 8
.Os Darwin
.Sh NAME
.Nm dnctl
.Nd Traffic shaper control program
.Sh SYNOPSIS
.Nm
.Op Fl anqs
.Brq Cm list | show
.Nm
.Op Fl f | q
.Cm flush
.Nm
.Op Fl q
.Brq Cm delete 
.Op Ar number ...
.Nm
.Brq Cm pipe | queue
.Ar number
.Cm config
.Ar config-options
.Nm
.Op Fl s Op Ar field
.Brq Cm pipe | queue
.Brq Cm delete | list | show
.Op Ar number ...
.Nm
.Op Fl nq
.Oo
.Fl p Ar preproc
.Oo
.Ar preproc-flags
.Oc
.Oc
.Ar pathname
.Sh DESCRIPTION
.Pp
The
.Nm
utility is the user interface for controlling the
.Xr dummynet 4
traffic shaper. 
.Pp
.Nm dummynet
operates by first using a packet filter to classify packets and divide them into
.Em flows ,
using any match pattern that can be used in
.Nm
rules.
Depending on local policies, a flow can contain packets for a single
TCP connection, or from/to a given host, or entire subnet, or a
protocol type, etc.
.Pp
Packets belonging to the same flow are then passed to either of two
different objects, which implement the traffic regulation:
.Bl -hang -offset XXXX
.It Em pipe
A pipe emulates a link with given bandwidth, propagation delay,
queue size and packet loss rate.
Packets are queued in front of the pipe as they come out from the classifier,
and then transferred to the pipe according to the pipe's parameters.
.Pp
.It Em queue
A queue
is an abstraction used to implement the WF2Q+
(Worst-case Fair Weighted Fair Queueing) policy, which is
an efficient variant of the WFQ policy.
.br
The queue associates a
.Em weight
and a reference pipe to each flow, and then all backlogged (i.e.,
with packets queued) flows linked to the same pipe share the pipe's
bandwidth proportionally to their weights.
Note that weights are not priorities; a flow with a lower weight
is still guaranteed to get its fraction of the bandwidth even if a
flow with a higher weight is permanently backlogged.
.Pp
.El
In practice,
.Em pipes
can be used to set hard limits to the bandwidth that a flow can use, whereas
.Em queues
can be used to determine how different flow share the available bandwidth.
.Pp
The
.Em pipe
and
.Em queue
configuration commands are the following:
.Bd -ragged -offset indent
.Cm pipe Ar number Cm config Ar pipe-configuration
.Pp
.Cm queue Ar number Cm config Ar queue-configuration
.Ed
.Pp
The following parameters can be configured for a pipe:
.Pp
.Bl -tag -width indent -compact
.It Cm bw Ar bandwidth | device
Bandwidth, measured in
.Sm off
.Op Cm K | M
.Brq Cm bit/s | Byte/s .
.Sm on
.Pp
A value of 0 (default) means unlimited bandwidth.
The unit must immediately follow the number, as in
.Pp
.Dl "dnctl pipe 1 config bw 300Kbit/s"
.Pp
If a device name is specified instead of a numeric value, as in
.Pp
.Dl "dnctl pipe 1 config bw tun0"
.Pp
then the transmit clock is supplied by the specified device.
At the moment no 
device supports this
functionality.
.Pp
.It Cm delay Ar ms-delay
Propagation delay, measured in milliseconds.
The value is rounded to the next multiple of the clock tick
(typically 10ms, but it is a good practice to run kernels
with
.Dq "options HZ=1000"
to reduce
the granularity to 1ms or less).
Default value is 0, meaning no delay.
.El
.Pp
The following parameters can be configured for a queue:
.Pp
.Bl -tag -width indent -compact
.It Cm pipe Ar pipe_nr
Connects a queue to the specified pipe.
Multiple queues (with the same or different weights) can be connected to
the same pipe, which specifies the aggregate rate for the set of queues.
.Pp
.It Cm weight Ar weight
Specifies the weight to be used for flows matching this queue.
The weight must be in the range 1..100, and defaults to 1.
.El
.Pp
Finally, the following parameters can be configured for both
pipes and queues:
.Pp
.Bl -tag -width XXXX -compact
.It Cm buckets Ar hash-table-size
Specifies the size of the hash table used for storing the
various queues.
Default value is 64 controlled by the
.Xr sysctl 8
variable
.Em net.inet.ip.dummynet.hash_size ,
allowed range is 16 to 65536.
.Pp
.It Cm mask Ar mask-specifier
Packets sent to a given pipe or queue by an
.Nm
rule can be further classified into multiple flows, each of which is then
sent to a different
.Em dynamic
pipe or queue.
A flow identifier is constructed by masking the IP addresses,
ports and protocol types as specified with the
.Cm mask
options in the configuration of the pipe or queue.
For each different flow identifier, a new pipe or queue is created
with the same parameters as the original object, and matching packets
are sent to it.
.Pp
Thus, when
.Em dynamic pipes
are used, each flow will get the same bandwidth as defined by the pipe,
whereas when
.Em dynamic queues
are used, each flow will share the parent's pipe bandwidth evenly
with other flows generated by the same queue (note that other queues
with different weights might be connected to the same pipe).
.br
Available mask specifiers are a combination of one or more of the following:
.Pp
.Cm dst-ip Ar mask ,
.Cm dst-ip6 Ar mask ,
.Cm src-ip Ar mask ,
.Cm src-ip6 Ar mask ,
.Cm dst-port Ar mask ,
.Cm src-port Ar mask ,
.Cm proto Ar mask
or
.Cm all ,
.Pp
where the latter means all bits in all fields are significant.
.Pp
.It Cm noerror
When a packet is dropped by a dummynet queue or pipe, the error
is normally reported to the caller routine in the kernel, in the
same way as it happens when a device queue fills up. Setting this
option reports the packet as successfully delivered, which can be
needed for some experimental setups where you want to simulate
loss or congestion at a remote router.
.Pp
.It Cm plr Ar packet-loss-rate
Packet loss rate.
Argument
.Ar packet-loss-rate
is a floating-point number between 0 and 1, with 0 meaning no
loss, 1 meaning 100% loss.
The loss rate is internally represented on 31 bits.
.Pp
.It Cm queue Brq Ar slots | size Ns Cm Kbytes
Queue size, in
.Ar slots
or
.Cm KBytes .
Default value is 50 slots, which
is the typical queue size for Ethernet devices.
Note that for slow speed links you should keep the queue
size short or your traffic might be affected by a significant
queueing delay.
E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit
or 20s of queue on a 30Kbit/s pipe.
Even worse effect can result if you get packets from an
interface with a much larger MTU, e.g. the loopback interface
with its 16KB packets.
.Pp
.It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p
Make use of the RED (Random Early Detection) queue management algorithm.
.Ar w_q
and
.Ar max_p
are floating
point numbers between 0 and 1 (0 not included), while
.Ar min_th
and
.Ar max_th
are integer numbers specifying thresholds for queue management
(thresholds are computed in bytes if the queue has been defined
in bytes, in slots otherwise).
The
.Xr dummynet 4
also supports the gentle RED variant (gred).
.Pp
Three
.Xr sysctl 8
variables can be used to control the RED behaviour:
.Bl -tag -width indent
.It Em net.inet.ip.dummynet.red_lookup_depth
specifies the accuracy in computing the average queue
when the link is idle (defaults to 256, must be greater than zero)
.It Em net.inet.ip.dummynet.red_avg_pkt_size
specifies the expected average packet size (defaults to 512, must be
greater than zero)
.It Em net.inet.ip.dummynet.red_max_pkt_size
specifies the expected maximum packet size, only used when queue
thresholds are in bytes (defaults to 1500, must be greater than zero).
.El
.El
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl a
While listing, show counter values.
The
.Cm show
command just implies this option.
.It Fl f
Don't ask for confirmation for commands that can cause problems
if misused,
.No i.e. Cm flush .
If there is no tty associated with the process, this is implied.
.It Fl h
Displays a short help.
.It Fl n
Only check syntax of the command strings, without actually passing
them to the kernel.
.It Fl q
While
.Cm add Ns ing ,
.Cm zero Ns ing ,
.Cm resetlog Ns ging
or
.Cm flush Ns ing ,
be quiet about actions
(implies
.Fl f ) .
This is useful for adjusting rules by executing multiple
.Nm
commands in a script
or by processing a file of many
.Nm
rules across a remote login session.
If a
.Cm flush
is performed in normal (verbose) mode (with the default kernel
configuration), it prints a message.
Because all rules are flushed, the message might not be delivered
to the login session, causing the remote login session to be closed
and the remainder of the ruleset to not be processed.
Access to the console would then be required to recover.
.It Fl s Op Ar field
While listing pipes, sort according to one of the four
counters (total or current packets or bytes).
.It Fl v
Be verbose.
.El
.Pp
To ease configuration, rules can be put into a file which is
processed using
.Nm
as shown in the last synopsis line.
An absolute
.Ar pathname
must be used.
The file will be read line by line and applied as arguments to the
.Nm
utility.
.Pp
Optionally, a preprocessor can be specified using
.Fl p Ar preproc
where
.Ar pathname
is to be piped through.
Useful preprocessors include
.Xr cpp 1
and
.Xr m4 1 .
If
.Ar preproc
doesn't start with a slash
.Pq Ql /
as its first character, the usual
.Ev PATH
name search is performed.
Care should be taken with this in environments where not all
file systems are mounted (yet) by the time
.Nm
is being run (e.g. when they are mounted over NFS).
Once
.Fl p
has been specified, any additional arguments as passed on to the preprocessor
for interpretation.
This allows for flexible configuration files (like conditionalizing
them on the local hostname) and the use of macros to centralize
frequently required arguments like IP addresses.
.El
.Sh CHECKLIST
Here are some important points to consider when designing your
rules:
.Bl -bullet
.It
Remember that you filter both packets going
.Cm in
and
.Cm out .
Most connections need packets going in both directions.
.It
Remember to test very carefully.
It is a good idea to be near the console when doing this.
.It
Don't forget the loopback interface.
.El
.Sh SYSCTL VARIABLES
A set of
.Xr sysctl 8
variables controls the behaviour of the 
.Nm dummynet 
module.
These are shown below together with their default value
(but always check with the
.Xr sysctl 8
command what value is actually in use) and meaning:
.Bl -tag -width indent
.It Em net.inet.ip.dummynet.expire : No 1
Lazily delete dynamic pipes/queue once they have no pending traffic.
You can disable this by setting the variable to 0, in which case
the pipes/queues will only be deleted when the threshold is reached.
.It Em net.inet.ip.dummynet.hash_size : No 64
Default size of the hash table used for dynamic pipes/queues.
This value is used when no
.Cm buckets
option is specified when configuring a pipe/queue.
.It Em net.inet.ip.dummynet.max_chain_len : No 16
Target value for the maximum number of pipes/queues in a hash bucket.
The product
.Cm max_chain_len*hash_size
is used to determine the threshold over which empty pipes/queues
will be expired even when
.Cm net.inet.ip.dummynet.expire=0 .
.It Em net.inet.ip.dummynet.red_lookup_depth : No 256
.It Em net.inet.ip.dummynet.red_avg_pkt_size : No 512
.It Em net.inet.ip.dummynet.red_max_pkt_size : No 1500
Parameters used in the computations of the drop probability
for the RED algorithm.
.El
.Sh EXAMPLES
The following rules show some of the applications of
for simulations and the like by using 
.Em dummynet
rules in
.Xr pf.conf 8
configuration files.
.Pp
To drop random incoming IPv4 and IPv6 ICMP packets with a probability of 5%, 
create a pipe:
.Dl "dnctl pipe 10 config plr 0.05"
.Pp
and add these rules in your pf.conf file:
.Dl "dummynet in inet proto icmp all pipe 10"
.Dl "dummynet in inet6 proto ipv6-icmp all pipe 10"
.Pp
Should we want to simulate a bidirectional link with bandwidth
limitations, the correct way is to create a pipe for each direction:
.Dl "dnctl pipe 1 config bw 14Kbit/s queue 10Kbytes"
.Dl "dnctl pipe 2 config bw 1Kbit/s queue 10Kbytes"
.Pp
and add these rules in your pf.conf file:
.Dl "dummynet in all pipe 1"
.Dl "dummynet out all pipe 2"
.Pp
The above can be very useful, e.g. if you want to see how
your fancy Web page will look for a residential user who
is connected only through a slow link.
You should not use only one pipe for both directions, unless
you want to simulate a half-duplex medium (e.g. AppleTalk,
Ethernet, IRDA).
.Pp
Note that with the above rules the pipes receive traffic for both the 
IPv4 and IPv6 protocols.
.Pp
Should we want to verify network performance with the RED queue
management algorithm, create this pipe:
.Dl "dnctl pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1"
.Pp
and then add these rules to you pf.conf file:
.Dl "dummynet all pipe 1"
.Pp
Another typical application of the traffic shaper is to
introduce some delay in the communication.
This can significantly affect applications which do a lot of Remote
Procedure Calls, and where the round-trip-time of the
connection often becomes a limiting factor much more than
bandwidth:
.Dl "dnctl pipe 1 config delay 250ms bw 1Mbit/s"
.Dl "dnctl pipe 2 config delay 250ms bw 1Mbit/s"
.Pp
and add these rules in your pf.conf file:
.Dl "dummynet in all pipe 1"
.Dl "dummynet out all pipe 2"
.Pp
Per-flow queueing can be useful for a variety of purposes.
A very simple one is counting traffic:
.Dl "dnctl pipe 1 config mask all"
.Pp
and add these statements in your pf.conf file:
.Dl "dummynet in quick proto tcp all pipe 1"
.Dl "dummynet out quick proto tcp all pipe 1"
.Dl "dummynet in quick proto udp all pipe 1"
.Dl "dummynet out quick proto udp all pipe 1"
.Dl "dummynet in quick all pipe 1"
.Dl "dummynet out quick all pipe 1"
.Pp
The above set of rules will create queues (and collect
statistics) for all traffic.
Because the pipes have no limitations, the only effect is
collecting statistics.
Note that we need six rules, not just the last two one, because
when
.Nm
tries to match IP packets it will not consider ports, so we
would not see connections on separate ports as different
ones.
.Sh SEE ALSO
.Xr cpp 1 ,
.Xr dummynet 4 ,
.Xr m4 1 ,
.Xr ip 4 ,
.Xr pfctl 8 ,
.Xr pf.conf 5 ,
.Xr protocols 5 ,
.Xr services 5 ,
.Xr sysctl 8
.Sh AUTHORS
.An Ugen J. S. Antsilevich ,
.An Poul-Henning Kamp ,
.An Alex Nash ,
.An Archie Cobbs ,
.An Luigi Rizzo .
.Pp
.An -nosplit
API based upon code written by
.An Daniel Boulet
for BSDI.
.Pp
Work on
.Xr dummynet 4
traffic shaper supported by Akamba Corp.
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx 2.0 .
.Xr dummynet 4
was introduced in
.Fx 2.2.8 .
Stateful extensions were introduced in
.Fx 4.0 .