1.\" Copyright (c) 2019 Lutz Donnerhacke 2.\" Copyright (c) 2004-2008 University of Zagreb 3.\" Copyright (c) 2007-2008 FreeBSD Foundation 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd October 17, 2019 28.Dt NG_PIPE 4 29.Os 30.Sh NAME 31.Nm ng_pipe 32.Nd Traffic manipulating netgraph node type 33.Sh SYNOPSIS 34.In netgraph/ng_pipe.h 35.Sh DESCRIPTION 36The 37.Nm pipe 38node type manipulates traffic by emulating bandwidth and delay, as well as 39random packet losses. 40.Sh HOOKS 41This node type supports the following hooks: 42.Bl -tag -width ".Va upper" 43.It Va upper 44Hook leading to upper layer protocols. 45.It Va lower 46Hook leading to lower layer protocols. 47.El 48.Pp 49Traffic flowing from 50.Va upper 51to 52.Va lower 53is considered 54.Sy downstream 55traffic. 56Traffic flowing from 57.Va lower 58to 59.Va upper 60is considered 61.Sy upstream 62traffic. 63.Sh MODE OF OPERATION 64Data received on a hook - both in upstream and downstream direction - 65is put into an inbound queue. 66If inbound queue is full, discard one frame 67depending on dropping policy (from the head or from the tail of the 68queue). 69.Pp 70There are three mutually exclusive modes for the input queue: 71.Bl -tag -width foo 72.It Dv "First In First Out (FIFO)" 73A single queue holds packets in chronological order. 74.It Dv Weighted fair queuing (WFQ) 75There are multiple queues for different traffic flows (based on IPv4 76IPs). 77The longest queue is truncated if necessary. 78This approach 79assumes that the stalling flow is the flow with the most packets currently 80on hold. 81.It Dv Deficit Round Robin (DRR) 82This mode is similar to WFQ, but packets are not taken out in 83strict chronological order. 84In principle oldest packets come first, 85but not too many packets from the same flow. 86.El 87.Pp 88It is possible to configure a duplication probability. 89As the dice 90decides, the currently active packet stays in the queue while a copy 91of the packet is sent out. 92Nothing prevents a packet from being 93duplicated multiple times. 94.Pp 95Packets are dropped with an increasing probability depending on the 96size of the packet, if a 97.Va ber 98(bit error rate) is configured. 99.Pp 100Surviving packets are delayed by the time the packet would need to 101travel through a link of the configured bandwidth. 102If this outbound 103queue is full, the packet is dropped. 104.Sh CONTROL MESSAGES 105This node type supports the generic control messages and the following 106specific messages. 107.Bl -tag -width foo 108.It Dv NGM_PIPE_SET_CFG Pq Ic setcfg 109Set node configuration to the one specified in 110.Vt "struct ng_pipe_cfg" 111.Pp 112Note: To set a value to zero, specify -1 instead. 113This allows omitting configuration values, which should not be 114modified. 115.It Dv NGM_PIPE_GET_CFG Pq Ic getcfg 116Return current node configuration as 117.Vt "struct ng_pipe_cfg" 118.Bd -literal 119struct ng_pipe_cfg { 120 u_int64_t bandwidth; /* bits per second */ 121 u_int64_t delay; /* additional delay, usec */ 122 u_int32_t header_offset; /* offset of IP header in bytes */ 123 u_int32_t overhead; /* assumed L2 overhead in bytes */ 124 struct ng_pipe_hookcfg downstream; 125 struct ng_pipe_hookcfg upstream; 126}; 127 128/* Config structure for one hook */ 129struct ng_pipe_hookcfg { 130 u_int64_t bandwidth; /* bits per second */ 131 u_int64_t ber; /* avg. interval between bit errors (1 / BER) */ 132 u_int32_t qin_size_limit; /* number of queue items */ 133 u_int32_t qout_size_limit; /* number of queue items */ 134 u_int32_t duplicate; /* probability in % */ 135 u_int32_t fifo; /* 0 = off, 1 = on */ 136 u_int32_t drr; /* 0 = off, 1 = 2048 bytes, or x bytes */ 137 u_int32_t wfq; /* 0 = off, 1 = on */ 138 u_int32_t droptail; /* 0 = off, 1 = on */ 139 u_int32_t drophead; /* 0 = off, 1 = on */ 140}; 141.Ed 142.It Dv NGM_PIPE_GET_STATS Pq Ic getstats 143Return node statistics as 144.Vt "struct ng_pipe_stats" 145.Bd -literal 146/* Statistics structure for one hook */ 147struct ng_pipe_hookstat { 148 u_int64_t fwd_octets; 149 u_int64_t fwd_frames; 150 u_int64_t in_disc_octets; 151 u_int64_t in_disc_frames; 152 u_int64_t out_disc_octets; 153 u_int64_t out_disc_frames; 154}; 155 156/* Statistics structure returned by NGM_PIPE_GET_STATS */ 157struct ng_pipe_stats { 158 struct ng_pipe_hookstat downstream; 159 struct ng_pipe_hookstat upstream; 160}; 161.Ed 162.It Dv NGM_PIPE_CLR_STATS Pq Ic clrstats 163Clear node statistics. 164.It Dv NGM_PIPE_GETCLR_STATS Pq Ic getclrstats 165Atomically return and clear node statistics. 166.It Dv NGM_PIPE_GET_RUN Pq Ic getrun 167Return node statistics as 168.Vt "struct ng_pipe_run" 169.Bd -literal 170/* Runtime structure for one hook */ 171struct ng_pipe_hookrun { 172 u_int32_t fifo_queues; 173 u_int32_t qin_octets; 174 u_int32_t qin_frames; 175 u_int32_t qout_octets; 176 u_int32_t qout_frames; 177}; 178 179/* Runtime structure returned by NGM_PIPE_GET_RUN */ 180struct ng_pipe_run { 181 struct ng_pipe_hookrun downstream; 182 struct ng_pipe_hookrun upstream; 183}; 184.Ed 185.El 186.Sh SHUTDOWN 187This node shuts down upon receipt of a 188.Dv NGM_SHUTDOWN 189control message, or when all hooks have been disconnected. 190.Sh EXAMPLES 191Limit outgoing data rate over fxp0 Ethernet interface to 20Mbps in 192fifo mode and incoming to 50kbps in drr mode and 2% duplicate 193probability. 194.Bd -literal -offset indent 195/usr/sbin/ngctl -f- <<-SEQ 196 mkpeer fxp0: pipe lower lower 197 name fxp0:lower fxp0_pipe 198 connect fxp0: fxp0_pipe: upper upper 199 msg fxp0_pipe: setcfg { downstream={ bandwidth=20000000 fifo=1 } } 200 msg fxp0_pipe: setcfg { upstream={ bandwidth=500000 drr=1 duplicate=2 } } 201SEQ 202.Ed 203.Sh SEE ALSO 204.Xr netgraph 4 , 205.Xr ngctl 8 206.Sh AUTHORS 207.An Lutz Donnerhacke Aq Mt lutz@donnerhacke.de 208.Pq man page 209.Sh BUGS 210Error handling for memory issues is missing. 211If kernel memory cannot be allocated immediately, a kernel panic will 212be triggered. 213Same happens if an mbuf is fragmented within the transport headers. 214