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.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
34 .Nd Traffic manipulating netgraph node type
36 .In netgraph/ng_pipe.h
40 node type manipulates traffic by emulating bandwidth and delay, as well as
43 This node type supports the following hooks:
44 .Bl -tag -width ".Va upper"
46 Hook leading to upper layer protocols.
48 Hook leading to lower layer protocols.
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
72 There are three mutually exclusive modes for the input queue:
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
79 The longest queue is truncated if necessary.
81 assumes that the stalling flow is the flow with the most packets currently
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.
90 It is possible to configure a duplication probability.
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.
97 Packets are dropped with an increasing probability depending on the
98 size of the packet, if a
100 (bit error rate) is configured.
102 Surviving packets are delayed by the time the packet would need to
103 travel through a link of the configured bandwidth.
105 queue is full, the packet is dropped.
107 This node type supports the generic control messages and the following
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"
114 Note: To set a value to zero, specify -1 instead.
115 This allows omitting configuration values, which should not be
117 .It Dv NGM_PIPE_GET_CFG Pq Ic getcfg
118 Return current node configuration as
119 .Vt "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;
130 /* Config structure for one hook */
131 struct ng_pipe_hookcfg {
132 u_int64_t bandwidth; /* bits per second */
133 u_int64_t ber; /* errors per 2^48 bits */
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 */
144 .It Dv NGM_PIPE_GET_STATS Pq Ic getstats
145 Return node statistics as
146 .Vt "struct ng_pipe_stats"
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;
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;
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"
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;
181 /* Runtime structure returned by NGM_PIPE_GET_RUN */
183 struct ng_pipe_hookrun downstream;
184 struct ng_pipe_hookrun upstream;
189 This node shuts down upon receipt of a
191 control message, or when all hooks have been disconnected.
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
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 } }
209 .An Lutz Donnerhacke Aq Mt lutz@donnerhacke.de
212 Error handling for memory issues is missing.
213 If kernel memory cannot be allocated immediately, a kernel panic will
215 Same happens if an mbuf is fragmented within the transport headers.