From owner-svn-src-all@freebsd.org Sun Oct 20 20:57:58 2019 Return-Path: Delivered-To: svn-src-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id D79AB169DC7; Sun, 20 Oct 2019 20:57:58 +0000 (UTC) (envelope-from brueffer@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 46xBtZ5P1Hz4LPZ; Sun, 20 Oct 2019 20:57:58 +0000 (UTC) (envelope-from brueffer@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 9D25019837; Sun, 20 Oct 2019 20:57:58 +0000 (UTC) (envelope-from brueffer@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id x9KKvwTC016203; Sun, 20 Oct 2019 20:57:58 GMT (envelope-from brueffer@FreeBSD.org) Received: (from brueffer@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id x9KKvwWF016202; Sun, 20 Oct 2019 20:57:58 GMT (envelope-from brueffer@FreeBSD.org) Message-Id: <201910202057.x9KKvwWF016202@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: brueffer set sender to brueffer@FreeBSD.org using -f From: Christian Brueffer Date: Sun, 20 Oct 2019 20:57:58 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r353780 - head/share/man/man4 X-SVN-Group: head X-SVN-Commit-Author: brueffer X-SVN-Commit-Paths: head/share/man/man4 X-SVN-Commit-Revision: 353780 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 20 Oct 2019 20:57:58 -0000 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 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.