Date: Sun, 20 Oct 2019 20:57:58 +0000 (UTC) From: Christian Brueffer <brueffer@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r353780 - head/share/man/man4 Message-ID: <201910202057.x9KKvwWF016202@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: brueffer Date: Sun Oct 20 20:57:57 2019 New Revision: 353780 URL: https://svnweb.freebsd.org/changeset/base/353780 Log: Add a manpage for ng_pipe(4). Submitted by: Lutz Donnerhacke <lutz_donnerhacke.de> Reviewed by: bcr (previous version) MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D22067 Added: head/share/man/man4/ng_pipe.4 (contents, props changed) Modified: head/share/man/man4/Makefile Modified: head/share/man/man4/Makefile ============================================================================== --- head/share/man/man4/Makefile Sun Oct 20 20:29:17 2019 (r353779) +++ head/share/man/man4/Makefile Sun Oct 20 20:57:57 2019 (r353780) @@ -351,6 +351,7 @@ MAN= aac.4 \ ng_netflow.4 \ ng_one2many.4 \ ng_patch.4 \ + ng_pipe.4 \ ng_ppp.4 \ ng_pppoe.4 \ ng_pptpgre.4 \ Added: head/share/man/man4/ng_pipe.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/ng_pipe.4 Sun Oct 20 20:57:57 2019 (r353780) @@ -0,0 +1,215 @@ +.\" Copyright (c) 2019 Lutz Donnerhacke +.\" Copyright (c) 2004-2008 University of Zagreb +.\" Copyright (c) 2007-2008 FreeBSD Foundation +.\" 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 October 17, 2019 +.Dt NG_PIPE 4 +.Os +.Sh NAME +.Nm ng_pipe +.Nd Traffic manipulating netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_pipe.h +.Sh DESCRIPTION +The +.Nm pipe +node type manipulates traffic by emulating bandwidth and delay, as well as +random packet losses. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va upper" +.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 MODE OF OPERATION +Data received on a hook - both in upstream and downstream direction - +is put into an inbound queue. +If inbound queue is full, discard one frame +depending on dropping policy (from the head or from the tail of the +queue). +.Pp +There are three mutually exclusive modes for the input queue: +.Bl -tag -width foo +.It Dv "First In First Out (FIFO)" +A single queue holds packets in chronological order. +.It Dv Weighted fair queuing (WFQ) +There are multiple queues for different traffic flows (based on IPv4 +IPs). +The longest queue is truncated if necessary. +This approach +assumes that the stalling flow is the flow with the most packets currently +on hold. +.It Dv Deficit Round Robin (DRR) +This mode is similar to WFQ, but packets are not taken out in +strict chronological order. +In principle oldest packets come first, +but not too many packets from the same flow. +.El +.Pp +It is possible to configure a duplication probability. +As the dice +decides, the currently active packet stays in the queue while a copy +of the packet is sent out. +Nothing prevents a packet from being +duplicated multiple times. +.Pp +Packets are dropped with an increasing probability depending on the +size of the packet, if a +.Va ber +(bit error rate) is configured. +.Pp +Surviving packets are delayed by the time the packet would need to +travel through a link of the configured bandwidth. +If this outbound +queue is full, the packet is dropped. +.Sh CONTROL MESSAGES +This node type supports the generic control messages and the following +specific messages. +.Bl -tag -width foo +.It Dv NGM_PIPE_SET_CFG Pq Ic setcfg +Set node configuration to the one specified in +.Vt "struct ng_pipe_cfg" +.Pp +Note: To set a value to zero, specify -1 instead. +This allows omitting configuration values, which should not be +modified. +.It Dv NGM_PIPE_GET_CFG Pq Ic getcfg +Return current node configuration as +.Vt "struct ng_pipe_cfg" +.Bd -literal +struct ng_pipe_cfg { + u_int64_t bandwidth; /* bits per second */ + u_int64_t delay; /* additional delay, usec */ + u_int32_t header_offset; /* offset of IP header in bytes */ + u_int32_t overhead; /* assumed L2 overhead in bytes */ + struct ng_pipe_hookcfg downstream; + struct ng_pipe_hookcfg upstream; +}; + +/* Config structure for one hook */ +struct ng_pipe_hookcfg { + u_int64_t bandwidth; /* bits per second */ + u_int64_t ber; /* errors per 2^48 bits */ + u_int32_t qin_size_limit; /* number of queue items */ + u_int32_t qout_size_limit; /* number of queue items */ + u_int32_t duplicate; /* probability in % */ + u_int32_t fifo; /* 0 = off, 1 = on */ + u_int32_t drr; /* 0 = off, 1 = 2048 bytes, or x bytes */ + u_int32_t wfq; /* 0 = off, 1 = on */ + u_int32_t droptail; /* 0 = off, 1 = on */ + u_int32_t drophead; /* 0 = off, 1 = on */ +}; +.Ed +.It Dv NGM_PIPE_GET_STATS Pq Ic getstats +Return node statistics as +.Vt "struct ng_pipe_stats" +.Bd -literal +/* Statistics structure for one hook */ +struct ng_pipe_hookstat { + u_int64_t fwd_octets; + u_int64_t fwd_frames; + u_int64_t in_disc_octets; + u_int64_t in_disc_frames; + u_int64_t out_disc_octets; + u_int64_t out_disc_frames; +}; + +/* Statistics structure returned by NGM_PIPE_GET_STATS */ +struct ng_pipe_stats { + struct ng_pipe_hookstat downstream; + struct ng_pipe_hookstat upstream; +}; +.Ed +.It Dv NGM_PIPE_CLR_STATS Pq Ic clrstats +Clear node statistics. +.It Dv NGM_PIPE_GETCLR_STATS Pq Ic getclrstats +Atomically return and clear node statistics. +.It Dv NGM_PIPE_GET_RUN Pq Ic getrun +Return node statistics as +.Vt "struct ng_pipe_run" +.Bd -literal +/* Runtime structure for one hook */ +struct ng_pipe_hookrun { + u_int32_t fifo_queues; + u_int32_t qin_octets; + u_int32_t qin_frames; + u_int32_t qout_octets; + u_int32_t qout_frames; +}; + +/* Runtime structure returned by NGM_PIPE_GET_RUN */ +struct ng_pipe_run { + struct ng_pipe_hookrun downstream; + struct ng_pipe_hookrun upstream; +}; +.Ed +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +Limit outgoing data rate over fxp0 Ethernet interface to 20Mbps in +fifo mode and incoming to 50kbps in drr mode and 2% duplicate +probability. +.Bd -literal -offset indent +/usr/sbin/ngctl -f- <<-SEQ + mkpeer fxp0: pipe lower lower + name fxp0:lower fxp0_pipe + connect fxp0: fxp0_pipe: upper upper + msg fxp0_pipe: setcfg { downstream={ bandwidth=20000000 fifo=1 } } + msg fxp0_pipe: setcfg { upstream={ bandwidth=500000 drr=1 duplicate=2 } } +SEQ +.Ed +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ngctl 8 +.Sh AUTHORS +.An Lutz Donnerhacke Aq Mt lutz@donnerhacke.de +.Pq man page +.Sh BUGS +Error handling for memory issues is missing. +If kernel memory cannot be allocated immediately, a kernel panic will +be triggered. +Same happens if an mbuf is fragmented within the transport headers.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201910202057.x9KKvwWF016202>