diff options
Diffstat (limited to 'static/freebsd/man4/ng_source.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ng_source.4 3.html | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/static/freebsd/man4/ng_source.4 3.html b/static/freebsd/man4/ng_source.4 3.html new file mode 100644 index 00000000..d7298def --- /dev/null +++ b/static/freebsd/man4/ng_source.4 3.html @@ -0,0 +1,281 @@ +<table class="head"> + <tr> + <td class="head-ltitle">NG_SOURCE(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">NG_SOURCE(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">ng_source</code> — + <span class="Nd">netgraph node for traffic generation</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">sys/types.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">netgraph/ng_source.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">source</code> node acts as a source of + packets according to the parameters set up using control messages and input + packets. The <code class="Nm">ng_source</code> node type is used primarily + for testing and benchmarking.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HOOKS"><a class="permalink" href="#HOOKS">HOOKS</a></h1> +<p class="Pp">The <code class="Nm">source</code> node has two hooks: + <var class="Va">input</var> and <var class="Va">output</var>. The + <var class="Va">output</var> hook must remain connected, its disconnection + will shutdown the node.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="OPERATION"><a class="permalink" href="#OPERATION">OPERATION</a></h1> +<p class="Pp">The operation of the node is as follows. Packets received on the + <var class="Va">input</var> hook are queued internally. When + <var class="Va">output</var> hook is connected, + <code class="Nm">ng_source</code> node assumes that its neighbour node is of + <a class="Xr">ng_ether(4)</a> node type. The neighbour is queried for its + interface name. The <code class="Nm">ng_source</code> node then uses queue + of the interface for its evil purposes. The + <code class="Nm">ng_source</code> node also disables + <var class="Va">autosrc</var> option on neighbour + <a class="Xr">ng_ether(4)</a> node. If interface name cannot be obtained + automatically, it should be configured explicitly with the + <code class="Dv">NGM_SOURCE_SETIFACE</code> control message, and + <var class="Va">autosrc</var> should be turned off on + <a class="Xr">ng_ether(4)</a> node manually.</p> +<p class="Pp">If the node is connected to a netgraph network, which does not + terminate in a real <a class="Xr">ng_ether(4)</a> interface, limit the + packet injection rate explicitly with the + <var class="Va">NGM_SOURCE_SETPPS</var> control message.</p> +<p class="Pp">Upon receipt of a <code class="Dv">NGM_SOURCE_START</code> control + message the node starts sending the previously queued packets out the + <var class="Va">output</var> 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 <var class="Va">output</var> hook. Once the number of + packets indicated in the start message has been sent, or upon receipt of a + <code class="Dv">NGM_SOURCE_STOP</code> message, the node stops sending + data.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CONTROL_MESSAGES"><a class="permalink" href="#CONTROL_MESSAGES">CONTROL + MESSAGES</a></h1> +<p class="Pp">This node type supports the generic control messages as well as + the following, which must be sent with the + <code class="Dv">NGM_SOURCE_COOKIE</code> attached.</p> +<dl class="Bl-tag"> + <dt id="NGM_SOURCE_GET_STATS"><a class="permalink" href="#NGM_SOURCE_GET_STATS"><code class="Dv">NGM_SOURCE_GET_STATS</code></a> + (<code class="Ic">getstats</code>)</dt> + <dd>Returns a structure containing the following fields: + <dl class="Bl-tag"> + <dt id="outOctets"><var class="Va">outOctets</var></dt> + <dd>The number of octets/bytes sent out the <var class="Va">output</var> + hook.</dd> + <dt id="outFrames"><var class="Va">outFrames</var></dt> + <dd>The number of frames/packets sent out the <var class="Va">output</var> + hook.</dd> + <dt id="queueOctets"><var class="Va">queueOctets</var></dt> + <dd>The number of octets queued from the <var class="Va">input</var> + hook.</dd> + <dt id="queueFrames"><var class="Va">queueFrames</var></dt> + <dd>The number of frames queued from the <var class="Va">input</var> + hook.</dd> + <dt id="startTime"><var class="Va">startTime</var></dt> + <dd>The time the last start message was received.</dd> + <dt id="endTime"><var class="Va">endTime</var></dt> + <dd>The time the last end message was received or the output packet count + was reached.</dd> + <dt id="elapsedTime"><var class="Va">elapsedTime</var></dt> + <dd>Either <var class="Va">endTime</var> <code class="Li">-</code> + <var class="Va">startTime</var> or current time - + <var class="Va">startTime</var>.</dd> + </dl> + </dd> + <dt id="NGM_SOURCE_CLR_STATS"><a class="permalink" href="#NGM_SOURCE_CLR_STATS"><code class="Dv">NGM_SOURCE_CLR_STATS</code></a> + (<code class="Ic">clrstats</code>)</dt> + <dd>Clears and resets the statistics returned by + <code class="Ic">getstats</code> (except <var class="Va">queueOctets</var> + and <var class="Va">queueFrames</var>).</dd> + <dt id="NGM_SOURCE_GETCLR_STATS"><a class="permalink" href="#NGM_SOURCE_GETCLR_STATS"><code class="Dv">NGM_SOURCE_GETCLR_STATS</code></a> + (<code class="Ic">getclrstats</code>)</dt> + <dd>As <code class="Ic">getstats</code> but clears the statistics at the same + time.</dd> + <dt id="NGM_SOURCE_START"><a class="permalink" href="#NGM_SOURCE_START"><code class="Dv">NGM_SOURCE_START</code></a> + (<code class="Ic">start</code>)</dt> + <dd>This message requires a single <var class="Vt">uint64_t</var> parameter + which is the number of packets to send before stopping. Node starts + sending the queued packets out the <var class="Va">output</var> hook. The + <var class="Va">output</var> hook must be connected and node must have + interface configured.</dd> + <dt id="NGM_SOURCE_STOP"><a class="permalink" href="#NGM_SOURCE_STOP"><code class="Dv">NGM_SOURCE_STOP</code></a> + (<code class="Ic">stop</code>)</dt> + <dd>Stops the node if it is active.</dd> + <dt id="NGM_SOURCE_CLR_DATA"><a class="permalink" href="#NGM_SOURCE_CLR_DATA"><code class="Dv">NGM_SOURCE_CLR_DATA</code></a> + (<code class="Ic">clrdata</code>)</dt> + <dd>Clears the packets queued from the <var class="Va">input</var> hook.</dd> + <dt id="NGM_SOURCE_SETIFACE"><a class="permalink" href="#NGM_SOURCE_SETIFACE"><code class="Dv">NGM_SOURCE_SETIFACE</code></a> + (<code class="Ic">setiface</code>)</dt> + <dd>This message requires the name of the interface to be configured as an + argument.</dd> + <dt id="NGM_SOURCE_SETPPS"><a class="permalink" href="#NGM_SOURCE_SETPPS"><code class="Dv">NGM_SOURCE_SETPPS</code></a> + (<code class="Ic">setpps</code>)</dt> + <dd>This message requires a single <var class="Vt">uint32_t</var> parameter + which puts upper limit on the amount of packets sent per second.</dd> + <dt id="NGM_SOURCE_SET_TIMESTAMP"><a class="permalink" href="#NGM_SOURCE_SET_TIMESTAMP"><code class="Dv">NGM_SOURCE_SET_TIMESTAMP</code></a> + (<code class="Ic">settimestamp</code>)</dt> + <dd>This message specifies that a timestamp (in the format of a + <var class="Vt">struct timeval</var>) should be inserted in the + transmitted packets. This message requires a structure containing the + following fields: + <dl class="Bl-tag"> + <dt id="offset"><var class="Va">offset</var></dt> + <dd>The offset from the beginning of the packet at which the timestamp is + to be inserted.</dd> + <dt id="flags"><var class="Va">flags</var></dt> + <dd>Set to 1 to enable the timestamp.</dd> + </dl> + </dd> + <dt id="NGM_SOURCE_GET_TIMESTAMP"><a class="permalink" href="#NGM_SOURCE_GET_TIMESTAMP"><code class="Dv">NGM_SOURCE_GET_TIMESTAMP</code></a> + (<code class="Ic">gettimestamp</code>)</dt> + <dd>Returns the current timestamp settings in the form of the structure + described above.</dd> + <dt id="NGM_SOURCE_SET_COUNTER"><a class="permalink" href="#NGM_SOURCE_SET_COUNTER"><code class="Dv">NGM_SOURCE_SET_COUNTER</code></a> + (<code class="Ic">setcounter</code>)</dt> + <dd>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: + <dl class="Bl-tag"> + <dt id="offset~2"><var class="Va">offset</var></dt> + <dd>The offset from the beginning of the packet at which the counter is to + be inserted.</dd> + <dt id="flags~2"><var class="Va">flags</var></dt> + <dd>Set to 1 to enable the counter.</dd> + <dt id="width"><var class="Va">width</var></dt> + <dd>The byte width of the counter. It may be 1, 2, or 4.</dd> + <dt id="next_val"><var class="Va">next_val</var></dt> + <dd>The value for the next insertion of the counter.</dd> + <dt id="min_val"><var class="Va">min_val</var></dt> + <dd>The minimum value to be used by the counter.</dd> + <dt id="max_val"><var class="Va">max_val</var></dt> + <dd>The maximum value to be used by the counter.</dd> + <dt id="increment"><var class="Va">increment</var></dt> + <dd>The value to be added to the counter after each insertion. It may be + negative.</dd> + <dt id="index"><var class="Va">index</var></dt> + <dd>The counter to be configured, from 0 to 3.</dd> + </dl> + </dd> + <dt id="NGM_SOURCE_GET_COUNTER"><a class="permalink" href="#NGM_SOURCE_GET_COUNTER"><code class="Dv">NGM_SOURCE_GET_COUNTER</code></a> + (<code class="Ic">getcounter</code>)</dt> + <dd>This message requires a single <var class="Vt">uint8_t</var> parameter + which specifies the counter to query. Returns the current counter settings + in the form of the structure described above.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SHUTDOWN"><a class="permalink" href="#SHUTDOWN">SHUTDOWN</a></h1> +<p class="Pp">This node shuts down upon receipt of a + <code class="Dv">NGM_SHUTDOWN</code> control message, when all hooks have + been disconnected, or when the <var class="Va">output</var> hook has been + disconnected.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">Attach the node to an <a class="Xr">ng_ether(4)</a> node for an + interface. If <code class="Nm">ng_ether</code> is not already loaded you + will need to do so. For example, these commands load the + <code class="Nm">ng_ether</code> module and attach the + <var class="Va">output</var> hook of a new <code class="Nm">source</code> + node to <var class="Va">orphans</var> hook of the + <code class="Li">bge0:</code> <code class="Nm">ng_ether</code> node.</p> +<div class="Bd Pp Bd-indent Li"> +<pre>kldload ng_ether +ngctl mkpeer bge0: source orphans output</pre> +</div> +<p class="Pp">At this point the new node can be referred to as + “<code class="Li">bge0:orphans</code>”. The node can be given + its own name like this:</p> +<p class="Pp"></p> +<div class="Bd Bd-indent"><code class="Li">ngctl name bge0:orphans + src0</code></div> +<p class="Pp">After which it can be referred to as + “<code class="Li">src0:</code>”.</p> +<p class="Pp">Once created, packets can be sent to the node as raw binary data. + Each packet must be delivered in a separate netgraph message.</p> +<p class="Pp">The following example uses a short Perl script to convert the hex + representation of an ICMP packet to binary and deliver it to the + <code class="Nm">source</code> node's <var class="Va">input</var> hook via + <a class="Xr">nghook(8)</a>:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>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</pre> +</div> +<p class="Pp">To check that the node has queued these packets you can get the + node statistics:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>ngctl msg bge0:orphans getstats +Args: { queueOctets=64 queueFrames=1 }</pre> +</div> +<p class="Pp">Send as many packets as required out the + <var class="Va">output</var> hook:</p> +<p class="Pp"></p> +<div class="Bd Bd-indent"><code class="Li">ngctl msg bge0:orphans start + 16</code></div> +<p class="Pp">Either wait for them to be sent (periodically fetching stats if + desired) or send the stop message:</p> +<p class="Pp"></p> +<div class="Bd Bd-indent"><code class="Li">ngctl msg bge0:orphans + stop</code></div> +<p class="Pp">Check the statistics (here we use + <code class="Ic">getclrstats</code> to also clear the statistics):</p> +<div class="Bd Pp Bd-indent Li"> +<pre>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 } }</pre> +</div> +<p class="Pp">The times are from <var class="Vt">struct timeval</var>s, the + <var class="Va">tv_sec</var> field is seconds since the Epoch and can be + converted into a date string via TCL's [clock format] or via the + <a class="Xr">date(1)</a> command:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>date -r 1035305880 +Tue Oct 22 12:58:00 EDT 2002</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">netgraph(4)</a>, <a class="Xr">ng_echo(4)</a>, + <a class="Xr">ng_hole(4)</a>, <a class="Xr">ng_tee(4)</a>, + <a class="Xr">ngctl(8)</a>, <a class="Xr">nghook(8)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">ng_source</code> node type was implemented in + <span class="Ux">FreeBSD 4.8</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Dave Chapeskie</span></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 18, 2021</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |