A node that implements various traffic shaping and rate limiting algorithms.

Approved by:	glebius (mentor)

1 files changed, 176 insertions, 0 deletions

diff --git a/share/man/man4/ng_car.4 b/share/man/man4/ng_car.4
new file mode 100644
index 000000000000..de0d9f678557
--- /dev/null
+++ b/share/man/man4/ng_car.4
@@ -0,0 +1,176 @@
+.\" Copyright (c) 2005 Nuno Antunes <nuno.antunes@gmail.com>
+.\" Copyright (c) 2007 Alexander Motin <mav@freebsd.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd March 11, 2007
+.Dt NG_CAR 4
+.Os
+.Sh NAME
+.Nm ng_car
+.Nd Commited Access Rate netgraph node type
+.Sh SYNOPSIS
+.In netgraph/ng_car.h
+.Sh DESCRIPTION
+The
+.Nm car
+node type limits traffic flowing through it using: 
+.Pp
+.Bl -bullet -compact
+.It
+Single rate three color marker as described on RFC 2697,
+.It
+Two rate three color marker as described on RFC 2698,
+.It
+RED-like rate limit algorithm used by Cisco,
+.It
+Traffic shaping with RED.
+.El
+.Sh HOOKS
+This node type supports the following hooks:
+.Bl -tag -width indent
+.It Va upper
+Hook leading to upper layer protocols.
+.It Va lower
+Hook leading to lower layer protocols.
+.El
+.Pp
+Traffic flowing from
+.Va upper
+to
+.Va lower
+is considered 
+.Sy downstream
+traffic.
+Traffic flowing from 
+.Va lower
+to
+.Va upper 
+is considered 
+.Sy upstream 
+traffic.
+.Sh MODES OF OPERATION
+Each hook can operate in one of modes:
+.Bl -tag -width indent
+.It Dv NG_CAR_SINGLE_RATE
+Single rate three color marker as described on RFC 2697.
+Committed burst packets are counted as green, extended burst packets are counted as yellow
+and exceeding packets are counted as red. Committed burst getting refilled with cir speed. 
+When it is full, exceeded burst getting refilled.
+.It Dv NG_CAR_DOUBLE_RATE
+Two rate three color marker as described on RFC 2698.
+Committed burst packets are counted as green, peak burst packets are counted as yellow
+and exceeding packets are counted as red. Committed burst getting refilled with cir speed. 
+Peak burst getting refilled with pir speed at the same time. 
+.It Dv NG_CAR_RED
+Alike to NG_CAR_SINGLE_RATE, but with different understanding of extended burst.
+When normal burst exceeded and extended burst is used, packets are counted red with 
+probability equal to part of extended burst consumed. Extended burst getting refilled first. 
+When it is full, committed burst getting refilled. This behavior is alike to RED 
+active queue management algorithm.
+.Pp
+This algorithm is more polite to the TCP traffic then NG_CAR_SINGLE_RATE.
+.It Dv NG_CAR_SHAPE
+Committed burst packets are counted as green, exceeding packets are delayed 
+by queue with RED management and counted as yellow. Packets dropped by queue counted as red.
+Queue parameters are hardcoded: length 99 packets, min_th 8 packets, max_p 100%.
+.Pp
+Traffic shaping is much more polite to the TCP traffic then rate limit on links with 
+bandwidth * delay product less then 6-8 TCP segments, but it consumes additional system 
+resources for queue processing.
+.El
+.Sh CONTROL MESSAGES
+This node type supports the generic control messages and the following
+specific messages.
+.Bl -tag -width indent
+.It Dv NGM_CAR_SET_CONF Pq Li setconf
+Set node configuration to the specified at
+.Vt "struct ng_car_bulkconf"
+.It Dv NGM_CAR_GET_CONF Pq Li getconf
+Return current node configuration as
+.Vt "struct ng_car_bulkconf"
+.Bd -literal -offset 4n
+struct ng_car_hookconf {
+	u_int64_t cbs;		/* Committed burst size (bytes) */
+	u_int64_t ebs;		/* Exceeded/Peak burst size (bytes) */
+	u_int64_t cir;		/* Committed information rate (bytes/s) */
+	u_int64_t pir;		/* Peak information rate (bits/s) */
+	u_int8_t green_action;	/* Action for green packets */
+	u_int8_t yellow_action;	/* Action for yellow packets */
+	u_int8_t red_action;	/* Action for red packets */
+	u_int8_t mode;		/* single/double rate, ... */
+	u_int8_t opt;		/* color-aware or color-blind */
+};
+
+struct ng_car_bulkconf {
+	struct ng_car_hookconf upstream;
+	struct ng_car_hookconf downstream;
+};
+.Ed
+.It Dv NGM_CAR_GET_STATS Pq Li getstats
+Return node statistics as
+.Vt "struct ng_car_bulkstats"
+.Bd -literal -offset 4n
+struct ng_car_hookstats {
+	u_int64_t passed_pkts;
+	u_int64_t droped_pkts;
+	u_int64_t green_pkts;
+	u_int64_t yellow_pkts;
+	u_int64_t red_pkts;
+	u_int64_t errors;
+};
+
+struct ng_car_bulkstats {
+	struct ng_car_hookstats upstream;
+	struct ng_car_hookstats downstream;
+};
+.Ed
+.It Dv NGM_CAR_CLR_STATS Pq Li clrstats
+Clear node statistics.
+.It Dv NGM_CAR_GETCLR_STATS Pq Li getclrstats
+Atomicaly return and clear node statistics.
+.El
+.Sh SHUTDOWN
+This node shuts down upon receipt of a
+.Dv NGM_SHUTDOWN
+control message, or when all hooks have been disconnected.
+.Sh SEE ALSO
+.Xr netgraph 4 ,
+.Xr ngctl 8
+.Rs
+.%A J. Heinanen
+.%T "A Single Rate Three Color Marker"
+.%O RFC 2697
+.Re
+.Rs
+.%A J. Heinanen
+.%T "A Two Rate Three Color Marker"
+.%O RFC 2698
+.Re
+.Sh AUTHORS
+.An Nuno Antunes Aq nuno.antunes@gmail.com
+.An Alexander Motin Aq mav@alkar.net
+.Sh BUGS
+For this moment only DROP and FORWARD actions are implemented.