1.\" Copyright 2002-2007 Sandvine Inc. 2.\" All rights reserved. 3.\" 4.\" Subject to the following obligations and disclaimer of warranty, use and 5.\" redistribution of this software, in source or object code forms, with or 6.\" without modifications are expressly permitted by Sandvine Inc.; provided, 7.\" however, that: 8.\" 1. Any and all reproductions of the source or object code must include the 9.\" copyright notice above and the following disclaimer of warranties; and 10.\" 2. No rights are granted, in any manner or form, to use Sandvine Inc. 11.\" trademarks, including the mark "SANDVINE" on advertising, endorsements, 12.\" or otherwise except as such appears in the above copyright notice or in 13.\" the software. 14.\" 15.\" THIS SOFTWARE IS BEING PROVIDED BY SANDVINE "AS IS", AND TO THE MAXIMUM 16.\" EXTENT PERMITTED BY LAW, SANDVINE MAKES NO REPRESENTATIONS OR WARRANTIES, 17.\" EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, 18.\" ANY AND ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 19.\" PURPOSE, OR NON-INFRINGEMENT. SANDVINE DOES NOT WARRANT, GUARANTEE, OR 20.\" MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE 21.\" USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY 22.\" OR OTHERWISE. IN NO EVENT SHALL SANDVINE BE LIABLE FOR ANY DAMAGES 23.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING 24.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 25.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR 26.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY 27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 29.\" THIS SOFTWARE, EVEN IF SANDVINE IS ADVISED OF THE POSSIBILITY OF SUCH 30.\" DAMAGE. 31.\" 32.\" Author: Dave Chapeskie 33.\" $FreeBSD$ 34.\" 35.Dd January 18, 2021 36.Dt NG_SOURCE 4 37.Os 38.Sh NAME 39.Nm ng_source 40.Nd netgraph node for traffic generation 41.Sh SYNOPSIS 42.In sys/types.h 43.In netgraph/ng_source.h 44.Sh DESCRIPTION 45The 46.Nm source 47node acts as a source of packets according to the parameters set up 48using control messages and input packets. 49The 50.Nm 51node type is used primarily for testing and benchmarking. 52.Sh HOOKS 53The 54.Nm source 55node has two hooks: 56.Va input 57and 58.Va output . 59The 60.Va output 61hook must remain connected, its disconnection will shutdown the node. 62.Sh OPERATION 63The operation of the node is as follows. 64Packets received on the 65.Va input 66hook are queued internally. 67When 68.Va output 69hook is connected, 70.Nm 71node assumes that its neighbour node is of 72.Xr ng_ether 4 73node type. 74The neighbour is queried for its interface name. 75The 76.Nm 77node then uses queue of the interface for its evil purposes. 78The 79.Nm 80node also disables 81.Va autosrc 82option on neighbour 83.Xr ng_ether 4 84node. 85If interface name cannot be obtained automatically, it should 86be configured explicitly with the 87.Dv NGM_SOURCE_SETIFACE 88control message, and 89.Va autosrc 90should be turned off on 91.Xr ng_ether 4 92node manually. 93.Pp 94If the node is connected to a netgraph network, which does not 95terminate in a real 96.Xr ng_ether 4 97interface, limit the packet injection rate explicitly with the 98.Va NGM_SOURCE_SETPPS 99control message. 100.Pp 101Upon receipt of a 102.Dv NGM_SOURCE_START 103control message the node starts sending 104the previously queued packets out the 105.Va output 106hook on every clock tick as fast 107as the connected interface will take them. 108While active, on every clock tick the node checks the available space 109in the interface queue and sends that many packets out its 110.Va output 111hook. 112Once the number of packets indicated in the start message has been 113sent, or upon receipt of a 114.Dv NGM_SOURCE_STOP 115message, the node stops sending data. 116.Sh CONTROL MESSAGES 117This node type supports the generic control messages as well as the following, 118which must be sent with the 119.Dv NGM_SOURCE_COOKIE 120attached. 121.Bl -tag -width foo 122.It Dv NGM_SOURCE_GET_STATS Pq Ic getstats 123Returns a structure containing the following fields: 124.Bl -tag -width ".Va elapsedTime" 125.It Va outOctets 126The number of octets/bytes sent out the 127.Va output 128hook. 129.It Va outFrames 130The number of frames/packets sent out the 131.Va output 132hook. 133.It Va queueOctets 134The number of octets queued from the 135.Va input 136hook. 137.It Va queueFrames 138The number of frames queued from the 139.Va input 140hook. 141.It Va startTime 142The time the last start message was received. 143.It Va endTime 144The time the last end message was received or 145the output packet count was reached. 146.It Va elapsedTime 147Either 148.Va endTime Li \- Va startTime 149or current time 150\- 151.Va startTime . 152.El 153.It Dv NGM_SOURCE_CLR_STATS Pq Ic clrstats 154Clears and resets the statistics returned by 155.Ic getstats 156(except 157.Va queueOctets 158and 159.Va queueFrames ) . 160.It Dv NGM_SOURCE_GETCLR_STATS Pq Ic getclrstats 161As 162.Ic getstats 163but clears the statistics at the same time. 164.It Dv NGM_SOURCE_START Pq Ic start 165This message requires a single 166.Vt uint64_t 167parameter which is the number of packets to 168send before stopping. 169Node starts sending the queued packets out the 170.Va output 171hook. 172The 173.Va output 174hook must be connected and node must have 175interface configured. 176.It Dv NGM_SOURCE_STOP Pq Ic stop 177Stops the node if it is active. 178.It Dv NGM_SOURCE_CLR_DATA Pq Ic clrdata 179Clears the packets queued from the 180.Va input 181hook. 182.It Dv NGM_SOURCE_SETIFACE Pq Ic setiface 183This message requires the name of the interface 184to be configured as an argument. 185.It Dv NGM_SOURCE_SETPPS Pq Ic setpps 186This message requires a single 187.Vt uint32_t 188parameter which puts upper limit on the amount of packets 189sent per second. 190.It Dv NGM_SOURCE_SET_TIMESTAMP Pq Ic settimestamp 191This message specifies that a timestamp (in the format of a 192.Vt "struct timeval" ) 193should be inserted in the transmitted packets. 194This message requires a structure containing the following fields: 195.Bl -tag -width ".Va offset" 196.It Va offset 197The offset from the beginning of the packet at which the timestamp is to be 198inserted. 199.It Va flags 200Set to 1 to enable the timestamp. 201.El 202.It Dv NGM_SOURCE_GET_TIMESTAMP Pq Ic gettimestamp 203Returns the current timestamp settings in the form of the structure described 204above. 205.It Dv NGM_SOURCE_SET_COUNTER Pq Ic setcounter 206This message specifies that a counter should be embedded in transmitted 207packets. 208Up to four counters may be independently configured. 209This message requires a structure containing the following fields: 210.Bl -tag -width ".Va increment" 211.It Va offset 212The offset from the beginning of the packet at which the counter is to be 213inserted. 214.It Va flags 215Set to 1 to enable the counter. 216.It Va width 217The byte width of the counter. 218It may be 1, 2, or 4. 219.It Va next_val 220The value for the next insertion of the counter. 221.It Va min_val 222The minimum value to be used by the counter. 223.It Va max_val 224The maximum value to be used by the counter. 225.It Va increment 226The value to be added to the counter after each insertion. 227It may be negative. 228.It Va index 229The counter to be configured, from 0 to 3. 230.El 231.It Dv NGM_SOURCE_GET_COUNTER Pq Ic getcounter 232This message requires a single 233.Vt uint8_t 234parameter which specifies the counter to query. 235Returns the current counter settings in the form of the structure described 236above. 237.El 238.Sh SHUTDOWN 239This node shuts down upon receipt of a 240.Dv NGM_SHUTDOWN 241control message, when all hooks have been disconnected, or when the 242.Va output 243hook has been disconnected. 244.Sh EXAMPLES 245Attach the node to an 246.Xr ng_ether 4 247node for an interface. 248If 249.Nm ng_ether 250is 251not already loaded you will need to do so. 252For example, these commands 253load the 254.Nm ng_ether 255module and attach the 256.Va output 257hook of a new 258.Nm source 259node to 260.Va orphans 261hook of the 262.Li bge0: 263.Nm ng_ether 264node. 265.Bd -literal -offset indent 266kldload ng_ether 267ngctl mkpeer bge0: source orphans output 268.Ed 269.Pp 270At this point the new node can be referred to as 271.Dq Li bge0:orphans . 272The 273node can be given its own name like this: 274.Pp 275.Dl "ngctl name bge0:orphans src0" 276.Pp 277After which it can be referred to as 278.Dq Li src0: . 279.Pp 280Once created, packets can be sent to the node as raw binary data. 281Each packet must be delivered in a separate netgraph message. 282.Pp 283The following example uses a short Perl script to convert the hex 284representation of an ICMP packet to binary and deliver it to the 285.Nm source 286node's 287.Va input 288hook via 289.Xr nghook 8 : 290.Bd -literal -offset indent 291perl -pe 's/(..)[ \et\en]*/chr(hex($1))/ge' <<EOF | nghook src0: input 292ff ff ff ff ff ff 00 00 00 00 00 00 08 00 45 00 29300 54 cb 13 00 00 40 01 b9 87 c0 a8 2b 65 0a 00 29400 01 08 00 f8 d0 c9 76 00 00 45 37 01 73 00 01 29504 0a 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 14 15 29616 17 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 29726 27 28 29 2a 2b 2c 2d 2e 2f 30 31 32 33 34 35 29836 37 299EOF 300.Ed 301.Pp 302To check that the node has queued these packets you can get the node 303statistics: 304.Bd -literal -offset indent 305ngctl msg bge0:orphans getstats 306Args: { queueOctets=64 queueFrames=1 } 307.Ed 308.Pp 309Send as many packets as required out the 310.Va output 311hook: 312.Pp 313.Dl "ngctl msg bge0:orphans start 16" 314.Pp 315Either wait for them to be sent (periodically fetching stats if desired) 316or send the stop message: 317.Pp 318.Dl "ngctl msg bge0:orphans stop" 319.Pp 320Check the statistics (here we use 321.Ic getclrstats 322to also clear the statistics): 323.Bd -literal -offset indent 324ngctl msg bge0:orphans getclrstats 325Args: { outOctets=1024 outFrames=16 queueOctets=64 queueFrames=1 326startTime={ tv_sec=1035305880 tv_usec=758036 } endTime={ tv_sec=1035305880 327tv_usec=759041 } elapsedTime={ tv_usec=1005 } } 328.Ed 329.Pp 330The times are from 331.Vt "struct timeval" Ns s , 332the 333.Va tv_sec 334field is seconds since 335the Epoch and can be converted into a date string via TCL's [clock 336format] or via the 337.Xr date 1 338command: 339.Bd -literal -offset indent 340date -r 1035305880 341Tue Oct 22 12:58:00 EDT 2002 342.Ed 343.Sh SEE ALSO 344.Xr netgraph 4 , 345.Xr ng_echo 4 , 346.Xr ng_hole 4 , 347.Xr ng_tee 4 , 348.Xr ngctl 8 , 349.Xr nghook 8 350.Sh HISTORY 351The 352.Nm 353node type was implemented in 354.Fx 4.8 . 355.Sh AUTHORS 356.An Dave Chapeskie 357