1 .\" Copyright (c) 2005 Nuno Antunes <nuno.antunes@gmail.com>
2 .\" Copyright (c) 2007 Alexander Motin <mav@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd Committed Access Rate netgraph node type
39 node type limits traffic flowing through it using:
43 Single rate three color marker as described in RFC 2697,
45 Two rate three color marker as described in RFC 2698,
47 RED-like rate limit algorithm used by Cisco,
49 Traffic shaping with RED.
52 This node type supports the following hooks:
53 .Bl -tag -width ".Va upper"
55 Hook leading to upper layer protocols.
57 Hook leading to lower layer protocols.
74 .Sh MODES OF OPERATION
75 Each hook can operate in one of the following modes:
77 .It Dv NG_CAR_SINGLE_RATE
78 Single rate three color marker as described in RFC 2697.
79 Committed burst packets are counted as green, extended burst packets are
80 counted as yellow and exceeding packets are counted as red.
81 Committed burst getting refilled with CIR (Committed Information Rate) speed.
82 When it is full, exceeded burst getting refilled.
83 .It Dv NG_CAR_DOUBLE_RATE
84 Two rate three color marker as described in RFC 2698.
85 Committed burst packets are counted as green, peak burst packets are counted
86 as yellow and exceeding packets are counted as red.
87 Committed burst getting refilled with CIR speed.
88 Peak burst getting refilled with PIR (Peak Information Rate) speed at the
92 .Dv NG_CAR_SINGLE_RATE ,
93 but with different understanding of extended burst.
94 When normal burst exceeded and extended burst is used, packets are counted
95 red with probability equal to part of extended burst consumed.
96 Extended burst getting refilled first.
97 When it is full, committed burst getting refilled.
98 This behavior is similar to RED active queue management algorithm.
100 This algorithm is more polite to the TCP traffic than NG_CAR_SINGLE_RATE.
102 Committed burst packets are counted as green, exceeding packets are delayed
103 by queue with RED management and counted as yellow.
104 Packets dropped by queue counted as red.
105 Queue parameters are hardcoded: length 99 packets, min_th 8 packets, max_p 100%.
107 Traffic shaping is much more polite to the TCP traffic than rate limit on
108 links with bandwidth * delay product less than 6-8 TCP segments, but it
109 consumes additional system resources for queue processing.
111 By default, all information rates are measured in bits per second and bursts
112 are measured in bytes.
113 But when NG_CAR_COUNT_PACKETS option is enabled,
114 rates are measured in packets per second and bursts are in packets.
116 This node type supports the generic control messages and the following
119 .It Dv NGM_CAR_SET_CONF Pq Ic setconf
120 Set node configuration to the specified at
121 .Vt "struct ng_car_bulkconf"
122 .It Dv NGM_CAR_GET_CONF Pq Ic getconf
123 Return current node configuration as
124 .Vt "struct ng_car_bulkconf"
126 struct ng_car_hookconf {
127 uint64_t cbs; /* Committed burst size (bytes) */
128 uint64_t ebs; /* Exceeded/Peak burst size (bytes) */
129 uint64_t cir; /* Committed information rate (bits/s) */
130 uint64_t pir; /* Peak information rate (bits/s) */
131 uint8_t green_action; /* Action for green packets */
132 uint8_t yellow_action; /* Action for yellow packets */
133 uint8_t red_action; /* Action for red packets */
134 uint8_t mode; /* single/double rate, ... */
135 uint8_t opt; /* color-aware or color-blind */
138 /* possible actions (..._action) */
140 NG_CAR_ACTION_FORWARD = 1,
144 /* operation modes (mode) */
146 NG_CAR_SINGLE_RATE = 0,
152 /* mode options (opt) */
153 #define NG_CAR_COUNT_PACKETS 2
155 struct ng_car_bulkconf {
156 struct ng_car_hookconf upstream;
157 struct ng_car_hookconf downstream;
160 .It Dv NGM_CAR_GET_STATS Pq Ic getstats
161 Return node statistics as
162 .Vt "struct ng_car_bulkstats"
164 struct ng_car_hookstats {
165 uint64_t passed_pkts; /* Counter for passed packets */
166 uint64_t droped_pkts; /* Counter for dropped packets */
167 uint64_t green_pkts; /* Counter for green packets */
168 uint64_t yellow_pkts; /* Counter for yellow packets */
169 uint64_t red_pkts; /* Counter for red packets */
170 uint64_t errors; /* Counter for operation errors */
173 struct ng_car_bulkstats {
174 struct ng_car_hookstats upstream;
175 struct ng_car_hookstats downstream;
178 .It Dv NGM_CAR_CLR_STATS Pq Ic clrstats
179 Clear node statistics.
180 .It Dv NGM_CAR_GETCLR_STATS Pq Ic getclrstats
181 Atomically return and clear node statistics.
184 This node shuts down upon receipt of a
186 control message, or when all hooks have been disconnected.
188 Limit outgoing data rate over fxp0 Ethernet interface to 20Mbit/s
189 and incoming packet rate to 5000pps.
190 .Bd -literal -offset indent
191 /usr/sbin/ngctl -f- <<-SEQ
192 mkpeer fxp0: car lower lower
193 name fxp0:lower fxp0_car
194 connect fxp0: fxp0_car: upper upper
195 msg fxp0_car: setconf { downstream={ cir=20000000 cbs=2500000 ebs=2500000 greenAction=1 yellowAction=1 redAction=2 mode=2 } upstream={ cir=5000 cbs=100 ebs=100 greenAction=1 yellowAction=1 redAction=2 mode=2 opt=2 } }
203 .%T "A Single Rate Three Color Marker"
208 .%T "A Two Rate Three Color Marker"
212 .An Nuno Antunes Aq Mt nuno.antunes@gmail.com
213 .An Alexander Motin Aq Mt mav@FreeBSD.org
215 At this moment only DROP and FORWARD actions are implemented.