share/man/man4/ng_pipe.4

   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
  38 The
  39 .Nm pipe
  40 node type manipulates traffic by emulating bandwidth and delay, as well as
  41 random packet losses.
  42 .Sh HOOKS
  43 This node type supports the following hooks:
  44 .Bl -tag -width ".Va upper"
  45 .It Va upper
  46 Hook leading to upper layer protocols.
  47 .It Va lower
  48 Hook leading to lower layer protocols.
  49 .El
  50 .Pp
  51 Traffic flowing from
  52 .Va upper
  53 to
  54 .Va lower
  55 is considered
  56 .Sy downstream
  57 traffic.
  58 Traffic flowing from
  59 .Va lower
  60 to
  61 .Va upper
  62 is considered
  63 .Sy upstream
  64 traffic.
  65 .Sh MODE OF OPERATION
  66 Data received on a hook - both in upstream and downstream direction -
  67 is put into an inbound queue.
  68 If inbound queue is full, discard one frame
  69 depending on dropping policy (from the head or from the tail of the
  70 queue).
  71 .Pp
  72 There are three mutually exclusive modes for the input queue:
  73 .Bl -tag -width foo
  74 .It Dv "First In First Out (FIFO)"
  75 A single queue holds packets in chronological order.
  76 .It Dv Weighted fair queuing (WFQ)
  77 There are multiple queues for different traffic flows (based on IPv4
  78 IPs).
  79 The longest queue is truncated if necessary.
  80 This approach
  81 assumes that the stalling flow is the flow with the most packets currently
  82 on hold.
  83 .It Dv Deficit Round Robin (DRR)
  84 This mode is similar to WFQ, but packets are not taken out in
  85 strict chronological order.
  86 In principle oldest packets come first,
  87 but not too many packets from the same flow.
  88 .El
  89 .Pp
  90 It is possible to configure a duplication probability.
  91 As the dice
  92 decides, the currently active packet stays in the queue while a copy
  93 of the packet is sent out.
  94 Nothing prevents a packet from being
  95 duplicated multiple times.
  96 .Pp
  97 Packets are dropped with an increasing probability depending on the
  98 size of the packet, if a
  99 .Va ber
 100 (bit error rate) is configured.
 101 .Pp
 102 Surviving packets are delayed by the time the packet would need to
 103 travel through a link of the configured bandwidth.
 104 If this outbound
 105 queue is full, the packet is dropped.
 106 .Sh CONTROL MESSAGES
 107 This node type supports the generic control messages and the following
 108 specific messages.
 109 .Bl -tag -width foo
 110 .It Dv NGM_PIPE_SET_CFG Pq Ic setcfg
 111 Set node configuration to the one specified in
 112 .Vt "struct ng_pipe_cfg"
 113 .Pp
 114 Note: To set a value to zero, specify -1 instead.
 115 This allows omitting configuration values, which should not be
 116 modified.
 117 .It Dv NGM_PIPE_GET_CFG Pq Ic getcfg
 118 Return current node configuration as
 119 .Vt "struct ng_pipe_cfg"
 120 .Bd -literal
 121 struct 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 */
 131 struct 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
 145 Return node statistics as
 146 .Vt "struct ng_pipe_stats"
 147 .Bd -literal
 148 /* Statistics structure for one hook */
 149 struct 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 */
 159 struct 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
 165 Clear node statistics.
 166 .It Dv NGM_PIPE_GETCLR_STATS Pq Ic getclrstats
 167 Atomically return and clear node statistics.
 168 .It Dv NGM_PIPE_GET_RUN Pq Ic getrun
 169 Return node statistics as
 170 .Vt "struct ng_pipe_run"
 171 .Bd -literal
 172 /* Runtime structure for one hook */
 173 struct 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 */
 182 struct ng_pipe_run {
 183   struct ng_pipe_hookrun  downstream;
 184   struct ng_pipe_hookrun  upstream;
 185 };
 186 .Ed
 187 .El
 188 .Sh SHUTDOWN
 189 This node shuts down upon receipt of a
 190 .Dv NGM_SHUTDOWN
 191 control message, or when all hooks have been disconnected.
 192 .Sh EXAMPLES
 193 Limit outgoing data rate over fxp0 Ethernet interface to 20Mbps in
 194 fifo mode and incoming to 50kbps in drr mode and 2% duplicate
 195 probability.
 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 } }
 203 SEQ
 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
 212 Error handling for memory issues is missing.
 213 If kernel memory cannot be allocated immediately, a kernel panic will
 214 be triggered.
 215 Same happens if an mbuf is fragmented within the transport headers.