NAME

     ng_source — netgraph node for traffic generation

SYNOPSIS

     #include <sys/types.h>
     #include <netgraph/ng_source.h>

DESCRIPTION

     The source node acts as a source of packets according to the parameters set up using control
     messages and input packets.  The ng_source node type is used primarily for testing and
     benchmarking.

HOOKS

     The source node has two hooks: input and output.  The output hook must remain connected, its
     disconnection will shutdown the node.

OPERATION

     The operation of the node is as follows.  Packets received on the input hook are queued
     internally.  When output hook is connected, ng_source node assumes that its neighbour node
     is of ng_ether(4) node type.  The neighbour is queried for its interface name.  The
     ng_source node then uses queue of the interface for its evil purposes.  The ng_source node
     also disables autosrc option on neighbour ng_ether(4) node.  If interface name cannot be
     obtained automatically, it should be configured explicitly with the NGM_SOURCE_SETIFACE
     control message, and autosrc should be turned off on ng_ether(4) node manually.

     Once interface is configured, upon receipt of a NGM_SOURCE_START control message the node
     starts sending the previously queued packets out the output hook on every clock tick as fast
     as the connected interface will take them.  While active, on every clock tick the node
     checks the available space in the interface queue and sends that many packets out its output
     hook.  Once the number of packets indicated in the start message has been sent, or upon
     receipt of a NGM_SOURCE_STOP message, the node stops sending data.

CONTROL MESSAGES

     This node type supports the generic control messages as well as the following, which must be
     sent with the NGM_SOURCE_COOKIE attached.

     NGM_SOURCE_GET_STATS (getstats)
          Returns a structure containing the following fields:

          outOctets    The number of octets/bytes sent out the output hook.

          outFrames    The number of frames/packets sent out the output hook.

          queueOctets  The number of octets queued from the input hook.

          queueFrames  The number of frames queued from the input hook.

          startTime    The time the last start message was received.

          endTime      The time the last end message was received or the output packet count was
                       reached.

          elapsedTime  Either endTime - startTime or current time - startTime.

     NGM_SOURCE_CLR_STATS (clrstats)
          Clears and resets the statistics returned by getstats (except queueOctets and
          queueFrames).

     NGM_SOURCE_GETCLR_STATS (getclrstats)
          As getstats but clears the statistics at the same time.

     NGM_SOURCE_START (start)
          This message requires a single uint64_t parameter which is the number of packets to
          send before stopping.  Node starts sending the queued packets out the output hook.  The
          output hook must be connected and node must have interface configured.

     NGM_SOURCE_STOP (stop)
          Stops the node if it is active.

     NGM_SOURCE_CLR_DATA (clrdata)
          Clears the packets queued from the input hook.

     NGM_SOURCE_SETIFACE (setiface)
          This message requires the name of the interface to be configured as an argument.

     NGM_SOURCE_SETPPS (setpps)
          This message requires a single uint32_t parameter which puts upper limit on the amount
          of packets sent per second.

     NGM_SOURCE_SET_TIMESTAMP (settimestamp)
          This message specifies that a timestamp (in the format of a struct timeval) should be
          inserted in the transmitted packets.  This message requires a structure containing the
          following fields:

          offset  The offset from the beginning of the packet at which the timestamp is to be
                  inserted.

          flags   Set to 1 to enable the timestamp.

     NGM_SOURCE_GET_TIMESTAMP (gettimestamp)
          Returns the current timestamp settings in the form of the structure described above.

     NGM_SOURCE_SET_COUNTER (setcounter)
          This message specifies that a counter should be embedded in transmitted packets.  Up to
          four counters may be independently configured.  This message requires a structure
          containing the following fields:

          offset     The offset from the beginning of the packet at which the counter is to be
                     inserted.

          flags      Set to 1 to enable the counter.

          width      The byte width of the counter.  It may be 1, 2, or 4.

          next_val   The value for the next insertion of the counter.

          min_val    The minimum value to be used by the counter.

          max_val    The maximum value to be used by the counter.

          increment  The value to be added to the counter after each insertion.  It may be
                     negative.

          index      The counter to be configured, from 0 to 3.

     NGM_SOURCE_GET_COUNTER (getcounter)
          This message requires a single uint8_t parameter which specifies the counter to query.
          Returns the current counter settings in the form of the structure described above.

SHUTDOWN

     This node shuts down upon receipt of a NGM_SHUTDOWN control message, when all hooks have
     been disconnected, or when the output hook has been disconnected.

EXAMPLES

     Attach the node to an ng_ether(4) node for an interface.  If ng_ether is not already loaded
     you will need to do so.  For example, these commands load the ng_ether module and attach the
     output hook of a new source node to orphans hook of the bge0: ng_ether node.

           kldload ng_ether
           ngctl mkpeer bge0: source orphans output

     At this point the new node can be referred to as “bge0:orphans”.  The node can be given its
     own name like this:

           ngctl name bge0:orphans src0

     After which it can be referred to as “src0:”.

     Once created, packets can be sent to the node as raw binary data.  Each packet must be
     delivered in a separate netgraph message.

     The following example uses a short Perl script to convert the hex representation of an ICMP
     packet to binary and deliver it to the source node's input hook via nghook(8):

           perl -pe 's/(..)[ \t\n]*/chr(hex($1))/ge' <<EOF | nghook src0: input
           ff ff ff ff ff ff 00 00 00 00 00 00 08 00 45 00
           00 54 cb 13 00 00 40 01 b9 87 c0 a8 2b 65 0a 00
           00 01 08 00 f8 d0 c9 76 00 00 45 37 01 73 00 01
           04 0a 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 14 15
           16 17 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25
           26 27 28 29 2a 2b 2c 2d 2e 2f 30 31 32 33 34 35
           36 37
           EOF

     To check that the node has queued these packets you can get the node statistics:

           ngctl msg bge0:orphans getstats
           Args:   { queueOctets=64 queueFrames=1 }

     Send as many packets as required out the output hook:

           ngctl msg bge0:orphans start 16

     Either wait for them to be sent (periodically fetching stats if desired) or send the stop
     message:

           ngctl msg bge0:orphans stop

     Check the statistics (here we use getclrstats to also clear the statistics):

           ngctl msg bge0:orphans getclrstats
           Args:   { outOctets=1024 outFrames=16 queueOctets=64 queueFrames=1
           startTime={ tv_sec=1035305880 tv_usec=758036 } endTime={ tv_sec=1035305880
           tv_usec=759041 } elapsedTime={ tv_usec=1005 } }

     The times are from struct timevals, the tv_sec field is seconds since the Epoch and can be
     converted into a date string via TCL's [clock format] or via the date(1) command:

           date -r 1035305880
           Tue Oct 22 12:58:00 EDT 2002

SEE ALSO

     netgraph(4), ng_echo(4), ng_hole(4), ng_tee(4), ngctl(8), nghook(8)

HISTORY

     The ng_source node type was implemented in FreeBSD 4.8.

AUTHORS

     Dave Chapeskie