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