NG_SOURCE(4)

💖 NG_SOURCE(4) 💖

okay bestie, welcome to the Kernel Interfaces Manual 🌸 — today's main character is ng_source, and she is literally the netgraph node for traffic generation. packet factory energy. no cap. 👑

---

✨ NAME ✨

ng_source — netgraph node for traffic generation

✨ SYNOPSIS ✨

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

✨ DESCRIPTION ✨

so the source node is out here acting as a source of packets 💅 — it does that based on whatever parameters you set up with control messages, plus whatever packets you feed it on the input. the ng_source node type is used primarily for testing and benchmarking. it's the friend you call when you need traffic and you need it now. 🦋

---

🎀 HOOKS 🎀

the source node has two hooks, and they are:

• input
• output

the output hook must remain connected. if it gets disconnected, that's it, the node shuts down. it's giving "you can't sit with us" energy. 😭

---

🌈 OPERATION 🌈

okay so here's how the whole thing goes down. packets received on the input hook get queued internally. 🫶

when the output hook is connected, the ng_source node assumes its neighbour node is of ng_ether(4) node type. she queries that neighbour for its interface name. then the ng_source node uses the queue of that interface for its evil purposes. 😈 she also disables the autosrc option on the neighbour ng_ether(4) node.

but if the interface name can't be obtained automatically, you have to configure it explicitly with the NGM_SOURCE_SETIFACE control message — and you also need to turn off autosrc on the ng_ether(4) node manually. do it yourself, bestie. 🙈

once the interface is configured, upon receipt of an 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 she's 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 an NGM_SOURCE_STOP message — the node stops sending data. periodt. 💅

---

⭐ CONTROL MESSAGES ⭐

this node type supports the generic control messages, plus all the following ones — which must be sent with the NGM_SOURCE_COOKIE attached. don't forget the cookie, it's the whole vibe. 🍓

• 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). those two get to stay. ✨
• NGM_SOURCE_GETCLR_STATS (getclrstats) — as getstats but clears the statistics at the same time. two birds, one iconic message. 🕊️
• 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 the node must have an interface configured. no shortcuts. 👑
• 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 an upper limit on the amount of packets sent per second. pacing, but make it cute. 🧚
• 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 an NGM_SHUTDOWN control message, when all hooks have been disconnected, or when the output hook has been disconnected. three ways to say goodbye. 😭

---

🌸 EXAMPLES 🌸

first up: attach the node to an ng_ether(4) node for an interface. if ng_ether isn't 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 the 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". she can be given her own name like this:

ngctl name bge0:orphans src0

after which it can be referred to as "src0:". glow-up complete. ✨

once created, packets can be sent to the node as raw binary data. each packet must be delivered in a separate netgraph message. one packet per message, no bundling, we don't do that here. 🎀

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, live your truth) 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. vintage, but make it serve. 💜

👑 AUTHORS 👑

Dave Chapeskie

---

and that's the whole page, bestie 🫶 go forth and generate some traffic, responsibly. Debian, March 1, 2007 — mwah 💋 slay 💅🌈