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