1.\" Copyright 2002 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 <dchapeskie@sandvine.com> 33.\" $FreeBSD$ 34.\" 35.Dd April 5, 2005 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 73node type. 74The neighbor is queried for its interface name. 75.Nm 76node then uses queue of the interface for its evil purposes. 77.Nm 78node also disables 79.Va autosrc 80option on neighbour 81.Xr ng_ether 82node. 83If interface name can't be obtained automatically, it should 84be configured explicitly with help of 85.Dv NGM_SOURCE_SETIFACE 86control message, and 87.Va autosrc 88should be turned off on 89.Xr ng_ether 90node manually. 91.Pp 92Once interface is configured, upon receival of 93.Dv NGM_SOURCE_START 94control message the node starts sending 95the previously queued packets out the 96.Va output 97hook on every clock tick as fast 98as the connected interface will take them. 99While active, on every clock tick the node checks the available space 100in the interface queue and sends that many packets out its 101.Va output 102hook. 103Once the number of packets indicated in the start message have been 104sent, or upon reception of a stop message, the node stops sending data. 105.Sh CONTROL MESSAGES 106This node type supports the generic control messages as well as the following, 107which must be sent with the 108.Dv NGM_SOURCE_COOKIE 109attached. 110.Bl -tag -width indent 111.It Dv NGM_SOURCE_GET_STATS Pq Ic getstats 112Returns a structure containing the following fields: 113.Bl -tag -width indent 114.It Va outOctets 115The number of octets/bytes sent out the 116.Dv output 117hook. 118.It Va outFrames 119The number of frames/packets sent out the 120.Dv output 121hook. 122.It Va queueOctets 123The number of octets queued from the 124.Dv input 125hook. 126.It Va queueFrames 127The number of frames queued from the 128.Dv input 129hook. 130.It Va startTime 131The time the last start message was received. 132.It Va endTime 133The time the last end message was received or 134the output packet count was reached. 135.It Va elapsedTime 136Either 137.Va endTime Li \- Va startTime 138or current time 139\- 140.Va startTime . 141.El 142.It Dv NGM_SOURCE_CLR_STATS Pq Ic clrstats 143Clears and resets the statistics returned by 144.Ic getstats 145(except 146.Va queueOctets 147and 148.Va queueFrames ) . 149.It Dv NGM_SOURCE_GETCLR_STATS Pq Ic getclrstats 150As 151.Ic getstats 152but clears the statistics at the same time. 153.It Dv NGM_SOURCE_START Pq Ic start 154This message requires a single 155.Vt uint64_t 156parameter which is the number of packets to 157send before stopping. 158Node starts sending the queued packets out the output hook. 159The output hook must be connected and node must have 160interface configured. 161.It Dv NGM_SOURCE_STOP Pq Ic stop 162Stops the node if it is active. 163.It Dv NGM_SOURCE_CLR_DATA Pq Ic clrdata 164Clears the packets queued from the 165.Dv input 166hook. 167.It Dv NGM_SOURCE_SETIFACE Pq Ic setiface 168This message requires a string argument - name of the interface 169to be configured. 170.El 171.Sh SHUTDOWN 172This node shuts down upon receipt of a 173.Dv NGM_SHUTDOWN 174control message, when all hooks has been disconnected, or when the 175.Va output 176hook has been disconnected. 177.Sh EXAMPLES 178Attach the node to an 179.Xr ng_ether 4 180node for an interface. 181If 182.Nm ng_ether 183is 184not already loaded you will need to do so. 185For example, these commands 186load the 187.Nm ng_ether 188module and attach the 189.Dv output 190hook of a new 191.Nm source 192node to 193.Dv orphans 194hook of the 195.Li bge0: 196.Nm ng_ether 197node. 198.Bd -literal -offset indent 199kldload ng_ether 200ngctl mkpeer bge0: source orphans output 201.Ed 202.Pp 203At this point the new node can be referred to as 204.Dq Li bge0:orphans . 205The 206node can be given its own name like this: 207.Pp 208.Dl "ngctl name bge0:orphans src0" 209.Pp 210After which it can be referred to as 211.Dq Li src0: . 212.Pp 213Once created, packets need to be sent to the node, the TCL net package 214can be used to generate these packets: 215.Pp 216[Sandvine specific TCL code example omitted] 217.Pp 218To feed the output of the above TCL script to the 219.Nm source 220node's 221.Dv input 222hook via 223.Xr nghook 8 : 224.Pp 225.Dl "tcl genPacket | nghook bge0:orphans input" 226.Pp 227To check that the node has queued these packets you can get the node 228statistics: 229.Bd -literal -offset indent 230ngctl msg bge0:orphans getstats 231Args: { queueOctets=64 queueFrames=1 } 232.Ed 233.Pp 234Send as many packets as required out the 235.Dv output 236hook: 237.Pp 238.Dl "ngctl msg bge0:orphans start 16" 239.Pp 240Either wait for them to be sent (periodically fetching stats if desired) 241or send the stop message: 242.Pp 243.Dl "ngctl msg bge0:orphans stop" 244.Pp 245Check the statistics (here we use 246.Ic getclrstats 247to also clear the statistics): 248.Bd -literal -offset indent 249ngctl msg bge0:orphans getclrstats 250Args: { outOctets=1024 outFrames=16 queueOctets=64 queueFrames=1 251startTime={ tv_sec=1035305880 tv_usec=758036 } endTime={ tv_sec=1035305880 252tv_usec=759041 } elapsedTime={ tv_usec=1005 } } 253.Ed 254.Pp 255The times are from 256.Vt "struct timeval" Ns s , 257the 258.Va tv_sec 259field is seconds since 260the Epoch and can be converted into a date string via TCL's [clock 261format] or via the 262.Xr date 1 263command: 264.Bd -literal -offset indent 265date -r 1035305880 266Tue Oct 22 12:58:00 EDT 2002 267.Ed 268.Sh SEE ALSO 269.Xr netgraph 4 , 270.Xr ng_echo 4 , 271.Xr ng_hole 4 , 272.Xr ng_tee 4 , 273.Xr ngctl 8 , 274.Xr nghook 8 275.Sh HISTORY 276The 277.Nm 278node type was implemented in 279.Fx 4.8 . 280.Sh AUTHORS 281.An Dave Chapeskie Aq dchapeskie@SANDVINE.com 282