share/man/man4/ng_source.4

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