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