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