share/man/man4/ng_source.4

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