1.\" Copyright (c) 2005 Nuno Antunes <nuno.antunes@gmail.com> 2.\" Copyright (c) 2007 Alexander Motin <mav@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 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. 13.\" 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 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd January 27, 2021 29.Dt NG_CAR 4 30.Os 31.Sh NAME 32.Nm ng_car 33.Nd Committed Access Rate netgraph node type 34.Sh SYNOPSIS 35.In netgraph/ng_car.h 36.Sh DESCRIPTION 37The 38.Nm car 39node type limits traffic flowing through it using: 40.Pp 41.Bl -bullet -compact 42.It 43Single rate three color marker as described in RFC 2697, 44.It 45Two rate three color marker as described in RFC 2698, 46.It 47RED-like rate limit algorithm used by Cisco, 48.It 49Traffic shaping with RED. 50.El 51.Sh HOOKS 52This node type supports the following hooks: 53.Bl -tag -width ".Va upper" 54.It Va upper 55Hook leading to upper layer protocols. 56.It Va lower 57Hook leading to lower layer protocols. 58.El 59.Pp 60Traffic flowing from 61.Va upper 62to 63.Va lower 64is considered 65.Sy downstream 66traffic. 67Traffic flowing from 68.Va lower 69to 70.Va upper 71is considered 72.Sy upstream 73traffic. 74.Sh MODES OF OPERATION 75Each hook can operate in one of the following modes: 76.Bl -tag -width foo 77.It Dv NG_CAR_SINGLE_RATE 78Single rate three color marker as described in RFC 2697. 79Committed burst packets are counted as green, extended burst packets are 80counted as yellow and exceeding packets are counted as red. 81Committed burst getting refilled with CIR (Committed Information Rate) speed. 82When it is full, exceeded burst getting refilled. 83.It Dv NG_CAR_DOUBLE_RATE 84Two rate three color marker as described in RFC 2698. 85Committed burst packets are counted as green, peak burst packets are counted 86as yellow and exceeding packets are counted as red. 87Committed burst getting refilled with CIR speed. 88Peak burst getting refilled with PIR (Peak Information Rate) speed at the 89same time. 90.It Dv NG_CAR_RED 91Similar to 92.Dv NG_CAR_SINGLE_RATE , 93but with different understanding of extended burst. 94When normal burst exceeded and extended burst is used, packets are counted 95red with probability equal to part of extended burst consumed. 96Extended burst getting refilled first. 97When it is full, committed burst getting refilled. 98This behavior is similar to RED active queue management algorithm. 99.Pp 100This algorithm is more polite to the TCP traffic than NG_CAR_SINGLE_RATE. 101.It Dv NG_CAR_SHAPE 102Committed burst packets are counted as green, exceeding packets are delayed 103by queue with RED management and counted as yellow. 104Packets dropped by queue counted as red. 105Queue parameters are hardcoded: length 99 packets, min_th 8 packets, max_p 100%. 106.Pp 107Traffic shaping is much more polite to the TCP traffic than rate limit on 108links with bandwidth * delay product less than 6-8 TCP segments, but it 109consumes additional system resources for queue processing. 110.El 111.Pp 112By default, all information rates are measured in bits per second and bursts 113are measured in bytes. 114But when NG_CAR_COUNT_PACKETS option is enabled, 115rates are measured in packets per second and bursts are in packets. 116.Sh CONTROL MESSAGES 117This node type supports the generic control messages and the following 118specific messages. 119.Bl -tag -width foo 120.It Dv NGM_CAR_SET_CONF Pq Ic setconf 121Set node configuration to the specified at 122.Vt "struct ng_car_bulkconf" 123.It Dv NGM_CAR_GET_CONF Pq Ic getconf 124Return current node configuration as 125.Vt "struct ng_car_bulkconf" 126.Bd -literal 127struct ng_car_hookconf { 128 uint64_t cbs; /* Committed burst size (bytes) */ 129 uint64_t ebs; /* Exceeded/Peak burst size (bytes) */ 130 uint64_t cir; /* Committed information rate (bits/s) */ 131 uint64_t pir; /* Peak information rate (bits/s) */ 132 uint8_t green_action; /* Action for green packets */ 133 uint8_t yellow_action; /* Action for yellow packets */ 134 uint8_t red_action; /* Action for red packets */ 135 uint8_t mode; /* single/double rate, ... */ 136 uint8_t opt; /* color-aware or color-blind */ 137}; 138 139/* possible actions (..._action) */ 140enum { 141 NG_CAR_ACTION_FORWARD = 1, 142 NG_CAR_ACTION_DROP, 143 NG_CAR_ACTION_MARK 144}; 145 146/* operation modes (mode) */ 147enum { 148 NG_CAR_SINGLE_RATE = 0, 149 NG_CAR_DOUBLE_RATE, 150 NG_CAR_RED, 151 NG_CAR_SHAPE 152}; 153 154/* mode options (bits for opt) */ 155#define NG_CAR_COLOR_AWARE 1 156#define NG_CAR_COUNT_PACKETS 2 157 158struct ng_car_bulkconf { 159 struct ng_car_hookconf upstream; 160 struct ng_car_hookconf downstream; 161}; 162.Ed 163.It Dv NGM_CAR_GET_STATS Pq Ic getstats 164Return node statistics as 165.Vt "struct ng_car_bulkstats" 166.Bd -literal 167struct ng_car_hookstats { 168 uint64_t passed_pkts; /* Counter for passed packets */ 169 uint64_t dropped_pkts; /* Counter for dropped packets */ 170 uint64_t green_pkts; /* Counter for green packets */ 171 uint64_t yellow_pkts; /* Counter for yellow packets */ 172 uint64_t red_pkts; /* Counter for red packets */ 173 uint64_t errors; /* Counter for operation errors */ 174}; 175 176struct ng_car_bulkstats { 177 struct ng_car_hookstats upstream; 178 struct ng_car_hookstats downstream; 179}; 180.Ed 181.It Dv NGM_CAR_CLR_STATS Pq Ic clrstats 182Clear node statistics. 183.It Dv NGM_CAR_GETCLR_STATS Pq Ic getclrstats 184Atomically return and clear node statistics. 185.El 186.Sh SHUTDOWN 187This node shuts down upon receipt of a 188.Dv NGM_SHUTDOWN 189control message, or when all hooks have been disconnected. 190.Sh EXAMPLES 191Limit outgoing data rate over fxp0 Ethernet interface to 20Mbit/s 192and incoming packet rate to 5000pps. 193.Bd -literal -offset indent 194/usr/sbin/ngctl -f- <<-SEQ 195 mkpeer fxp0: car lower lower 196 name fxp0:lower fxp0_car 197 connect fxp0: fxp0_car: upper upper 198 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 } } 199SEQ 200.Ed 201.Sh SEE ALSO 202.Xr netgraph 4 , 203.Xr ngctl 8 204.Rs 205.%A J. Heinanen 206.%T "A Single Rate Three Color Marker" 207.%O RFC 2697 208.Re 209.Rs 210.%A J. Heinanen 211.%T "A Two Rate Three Color Marker" 212.%O RFC 2698 213.Re 214.Sh AUTHORS 215.An Nuno Antunes Aq Mt nuno.antunes@gmail.com 216.An Alexander Motin Aq Mt mav@FreeBSD.org 217.Sh BUGS 218At this moment only DROP and FORWARD actions are implemented. 219