--- name: "ng_source" section: "4" platform: "linux" package: "freebsd-manpages" version: "6.0-5" release: "Debian 4.0 (Etch)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/ng_source" --- # ng\_source(4) netgraph node for traffic generation ## NAME **ng\_source** – netgraph node for traffic generation ## SYNOPSIS **#include \** **#include \** ## 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)](/ng_ether/4.md) 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)](/ng_ether/4.md) 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)](/ng_ether/4.md) 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. ## 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)](/ng_ether/4.md) 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 need to be sent to the node, the TCL net package can be used to generate these packets: \[Sandvine specific TCL code example omitted\] To feed the output of the above TCL script to the **source** node's *input* hook via [nghook(8)](/nghook/8.md): ``` tcl genPacket | nghook bge0:orphans input ``` 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 timeval*s, 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)](/date/1.md) command: ``` date -r 1035305880 Tue Oct 22 12:58:00 EDT 2002 ``` ## SEE ALSO [netgraph(4)](/netgraph/4.md), [ng\_echo(4)](/ng_echo/4.md), [ng\_hole(4)](/ng_hole/4.md), [ng\_tee(4)](/ng_tee/4.md), [ngctl(8)](/ngctl/8.md), [nghook(8)](/nghook/8.md) ## HISTORY The **ng\_source** node type was implemented in FreeBSD 4.8. ## AUTHORS Dave Chapeskie ⟨dchapeskie@SANDVINE.com⟩