share/man/man4/ng_car.4

   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
  37 The
  38 .Nm car
  39 node type limits traffic flowing through it using:
  40 .Pp
  41 .Bl -bullet -compact
  42 .It
  43 Single rate three color marker as described in RFC 2697,
  44 .It
  45 Two rate three color marker as described in RFC 2698,
  46 .It
  47 RED-like rate limit algorithm used by Cisco,
  48 .It
  49 Traffic shaping with RED.
  50 .El
  51 .Sh HOOKS
  52 This node type supports the following hooks:
  53 .Bl -tag -width ".Va upper"
  54 .It Va upper
  55 Hook leading to upper layer protocols.
  56 .It Va lower
  57 Hook leading to lower layer protocols.
  58 .El
  59 .Pp
  60 Traffic flowing from
  61 .Va upper
  62 to
  63 .Va lower
  64 is considered
  65 .Sy downstream
  66 traffic.
  67 Traffic flowing from
  68 .Va lower
  69 to
  70 .Va upper
  71 is considered
  72 .Sy upstream
  73 traffic.
  74 .Sh MODES OF OPERATION
  75 Each hook can operate in one of the following modes:
  76 .Bl -tag -width foo
  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
  89 same time.
  90 .It Dv NG_CAR_RED
  91 Similar to
  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.
  99 .Pp
 100 This algorithm is more polite to the TCP traffic than NG_CAR_SINGLE_RATE.
 101 .It Dv NG_CAR_SHAPE
 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%.
 106 .Pp
 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.
 110 .El
 111 .Pp
 112 By default, all information rates are measured in bits per second and bursts
 113 are measured in bytes.
 114 But when NG_CAR_COUNT_PACKETS option is enabled,
 115 rates are measured in packets per second and bursts are in packets.
 116 .Sh CONTROL MESSAGES
 117 This node type supports the generic control messages and the following
 118 specific messages.
 119 .Bl -tag -width foo
 120 .It Dv NGM_CAR_SET_CONF Pq Ic setconf
 121 Set node configuration to the specified at
 122 .Vt "struct ng_car_bulkconf"
 123 .It Dv NGM_CAR_GET_CONF Pq Ic getconf
 124 Return current node configuration as
 125 .Vt "struct ng_car_bulkconf"
 126 .Bd -literal
 127 struct 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) */
 140 enum {
 141     NG_CAR_ACTION_FORWARD = 1,
 142     NG_CAR_ACTION_DROP,
 143     NG_CAR_ACTION_MARK
 144 };
 145
 146 /* operation modes (mode) */
 147 enum {
 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
 158 struct 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
 164 Return node statistics as
 165 .Vt "struct ng_car_bulkstats"
 166 .Bd -literal
 167 struct 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
 176 struct 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
 182 Clear node statistics.
 183 .It Dv NGM_CAR_GETCLR_STATS Pq Ic getclrstats
 184 Atomically return and clear node statistics.
 185 .El
 186 .Sh SHUTDOWN
 187 This node shuts down upon receipt of a
 188 .Dv NGM_SHUTDOWN
 189 control message, or when all hooks have been disconnected.
 190 .Sh EXAMPLES
 191 Limit outgoing data rate over fxp0 Ethernet interface to 20Mbit/s
 192 and 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 } }
 199 SEQ
 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
 218 At this moment only DROP and FORWARD actions are implemented.