xref: /freebsd/share/man/man4/ng_car.4 (revision db5bc6794e7125fb9658a35773474afadc98c378)

.\" 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.