ng_car.4 (9cce74045b2f402572959611ccc8ffb30d188416) ng_car.4 (db5bc6794e7125fb9658a35773474afadc98c378)
1.\" Copyright (c) 2005 Nuno Antunes <nuno.antunes@gmail.com>
1.\" Copyright (c) 2005 Nuno Antunes <nuno.antunes@gmail.com>
2.\" Copyright (c) 2007 Alexander Motin <mav@FreeBSD.org>
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

--- 20 unchanged lines hidden (view full) ---

31.Sh NAME
32.Nm ng_car
33.Nd Commited Access Rate netgraph node type
34.Sh SYNOPSIS
35.In netgraph/ng_car.h
36.Sh DESCRIPTION
37The
38.Nm car
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

--- 20 unchanged lines hidden (view full) ---

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