75e7ef74df
PR: 240530 Reviewed by: kp Approved by: kp (mentor) MFC after: 1 month Differential Revision: https://reviews.freebsd.org/D21968
357 lines
9.8 KiB
Groff
357 lines
9.8 KiB
Groff
.\" Copyright 2002-2007 Sandvine Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Subject to the following obligations and disclaimer of warranty, use and
|
|
.\" redistribution of this software, in source or object code forms, with or
|
|
.\" without modifications are expressly permitted by Sandvine Inc.; provided,
|
|
.\" however, that:
|
|
.\" 1. Any and all reproductions of the source or object code must include the
|
|
.\" copyright notice above and the following disclaimer of warranties; and
|
|
.\" 2. No rights are granted, in any manner or form, to use Sandvine Inc.
|
|
.\" trademarks, including the mark "SANDVINE" on advertising, endorsements,
|
|
.\" or otherwise except as such appears in the above copyright notice or in
|
|
.\" the software.
|
|
.\"
|
|
.\" THIS SOFTWARE IS BEING PROVIDED BY SANDVINE "AS IS", AND TO THE MAXIMUM
|
|
.\" EXTENT PERMITTED BY LAW, SANDVINE MAKES NO REPRESENTATIONS OR WARRANTIES,
|
|
.\" EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, INCLUDING WITHOUT LIMITATION,
|
|
.\" ANY AND ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE, OR NON-INFRINGEMENT. SANDVINE DOES NOT WARRANT, GUARANTEE, OR
|
|
.\" MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE
|
|
.\" USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY
|
|
.\" OR OTHERWISE. IN NO EVENT SHALL SANDVINE BE LIABLE FOR ANY DAMAGES
|
|
.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
|
|
.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
|
|
.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF SANDVINE IS ADVISED OF THE POSSIBILITY OF SUCH
|
|
.\" DAMAGE.
|
|
.\"
|
|
.\" Author: Dave Chapeskie
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd January 18, 2021
|
|
.Dt NG_SOURCE 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ng_source
|
|
.Nd netgraph node for traffic generation
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In netgraph/ng_source.h
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm source
|
|
node acts as a source of packets according to the parameters set up
|
|
using control messages and input packets.
|
|
The
|
|
.Nm
|
|
node type is used primarily for testing and benchmarking.
|
|
.Sh HOOKS
|
|
The
|
|
.Nm source
|
|
node has two hooks:
|
|
.Va input
|
|
and
|
|
.Va output .
|
|
The
|
|
.Va output
|
|
hook must remain connected, its disconnection will shutdown the node.
|
|
.Sh OPERATION
|
|
The operation of the node is as follows.
|
|
Packets received on the
|
|
.Va input
|
|
hook are queued internally.
|
|
When
|
|
.Va output
|
|
hook is connected,
|
|
.Nm
|
|
node assumes that its neighbour node is of
|
|
.Xr ng_ether 4
|
|
node type.
|
|
The neighbour is queried for its interface name.
|
|
The
|
|
.Nm
|
|
node then uses queue of the interface for its evil purposes.
|
|
The
|
|
.Nm
|
|
node also disables
|
|
.Va autosrc
|
|
option on neighbour
|
|
.Xr ng_ether 4
|
|
node.
|
|
If interface name cannot be obtained automatically, it should
|
|
be configured explicitly with the
|
|
.Dv NGM_SOURCE_SETIFACE
|
|
control message, and
|
|
.Va autosrc
|
|
should be turned off on
|
|
.Xr ng_ether 4
|
|
node manually.
|
|
.Pp
|
|
If the node is connected to a netgraph network, which does not
|
|
terminate in a real
|
|
.Xr ng_ether 4
|
|
interface, limit the packet injection rate explicitly with the
|
|
.Va NGM_SOURCE_SETPPS
|
|
control message.
|
|
.Pp
|
|
Upon receipt of a
|
|
.Dv NGM_SOURCE_START
|
|
control message the node starts sending
|
|
the previously queued packets out the
|
|
.Va 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
|
|
.Va output
|
|
hook.
|
|
Once the number of packets indicated in the start message has been
|
|
sent, or upon receipt of a
|
|
.Dv NGM_SOURCE_STOP
|
|
message, the node stops sending data.
|
|
.Sh CONTROL MESSAGES
|
|
This node type supports the generic control messages as well as the following,
|
|
which must be sent with the
|
|
.Dv NGM_SOURCE_COOKIE
|
|
attached.
|
|
.Bl -tag -width foo
|
|
.It Dv NGM_SOURCE_GET_STATS Pq Ic getstats
|
|
Returns a structure containing the following fields:
|
|
.Bl -tag -width ".Va elapsedTime"
|
|
.It Va outOctets
|
|
The number of octets/bytes sent out the
|
|
.Va output
|
|
hook.
|
|
.It Va outFrames
|
|
The number of frames/packets sent out the
|
|
.Va output
|
|
hook.
|
|
.It Va queueOctets
|
|
The number of octets queued from the
|
|
.Va input
|
|
hook.
|
|
.It Va queueFrames
|
|
The number of frames queued from the
|
|
.Va input
|
|
hook.
|
|
.It Va startTime
|
|
The time the last start message was received.
|
|
.It Va endTime
|
|
The time the last end message was received or
|
|
the output packet count was reached.
|
|
.It Va elapsedTime
|
|
Either
|
|
.Va endTime Li \- Va startTime
|
|
or current time
|
|
\-
|
|
.Va startTime .
|
|
.El
|
|
.It Dv NGM_SOURCE_CLR_STATS Pq Ic clrstats
|
|
Clears and resets the statistics returned by
|
|
.Ic getstats
|
|
(except
|
|
.Va queueOctets
|
|
and
|
|
.Va queueFrames ) .
|
|
.It Dv NGM_SOURCE_GETCLR_STATS Pq Ic getclrstats
|
|
As
|
|
.Ic getstats
|
|
but clears the statistics at the same time.
|
|
.It Dv NGM_SOURCE_START Pq Ic start
|
|
This message requires a single
|
|
.Vt uint64_t
|
|
parameter which is the number of packets to
|
|
send before stopping.
|
|
Node starts sending the queued packets out the
|
|
.Va output
|
|
hook.
|
|
The
|
|
.Va output
|
|
hook must be connected and node must have
|
|
interface configured.
|
|
.It Dv NGM_SOURCE_STOP Pq Ic stop
|
|
Stops the node if it is active.
|
|
.It Dv NGM_SOURCE_CLR_DATA Pq Ic clrdata
|
|
Clears the packets queued from the
|
|
.Va input
|
|
hook.
|
|
.It Dv NGM_SOURCE_SETIFACE Pq Ic setiface
|
|
This message requires the name of the interface
|
|
to be configured as an argument.
|
|
.It Dv NGM_SOURCE_SETPPS Pq Ic setpps
|
|
This message requires a single
|
|
.Vt uint32_t
|
|
parameter which puts upper limit on the amount of packets
|
|
sent per second.
|
|
.It Dv NGM_SOURCE_SET_TIMESTAMP Pq Ic settimestamp
|
|
This message specifies that a timestamp (in the format of a
|
|
.Vt "struct timeval" )
|
|
should be inserted in the transmitted packets.
|
|
This message requires a structure containing the following fields:
|
|
.Bl -tag -width ".Va offset"
|
|
.It Va offset
|
|
The offset from the beginning of the packet at which the timestamp is to be
|
|
inserted.
|
|
.It Va flags
|
|
Set to 1 to enable the timestamp.
|
|
.El
|
|
.It Dv NGM_SOURCE_GET_TIMESTAMP Pq Ic gettimestamp
|
|
Returns the current timestamp settings in the form of the structure described
|
|
above.
|
|
.It Dv NGM_SOURCE_SET_COUNTER Pq Ic 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:
|
|
.Bl -tag -width ".Va increment"
|
|
.It Va offset
|
|
The offset from the beginning of the packet at which the counter is to be
|
|
inserted.
|
|
.It Va flags
|
|
Set to 1 to enable the counter.
|
|
.It Va width
|
|
The byte width of the counter.
|
|
It may be 1, 2, or 4.
|
|
.It Va next_val
|
|
The value for the next insertion of the counter.
|
|
.It Va min_val
|
|
The minimum value to be used by the counter.
|
|
.It Va max_val
|
|
The maximum value to be used by the counter.
|
|
.It Va increment
|
|
The value to be added to the counter after each insertion.
|
|
It may be negative.
|
|
.It Va index
|
|
The counter to be configured, from 0 to 3.
|
|
.El
|
|
.It Dv NGM_SOURCE_GET_COUNTER Pq Ic getcounter
|
|
This message requires a single
|
|
.Vt uint8_t
|
|
parameter which specifies the counter to query.
|
|
Returns the current counter settings in the form of the structure described
|
|
above.
|
|
.El
|
|
.Sh SHUTDOWN
|
|
This node shuts down upon receipt of a
|
|
.Dv NGM_SHUTDOWN
|
|
control message, when all hooks have been disconnected, or when the
|
|
.Va output
|
|
hook has been disconnected.
|
|
.Sh EXAMPLES
|
|
Attach the node to an
|
|
.Xr ng_ether 4
|
|
node for an interface.
|
|
If
|
|
.Nm ng_ether
|
|
is
|
|
not already loaded you will need to do so.
|
|
For example, these commands
|
|
load the
|
|
.Nm ng_ether
|
|
module and attach the
|
|
.Va output
|
|
hook of a new
|
|
.Nm source
|
|
node to
|
|
.Va orphans
|
|
hook of the
|
|
.Li bge0:
|
|
.Nm ng_ether
|
|
node.
|
|
.Bd -literal -offset indent
|
|
kldload ng_ether
|
|
ngctl mkpeer bge0: source orphans output
|
|
.Ed
|
|
.Pp
|
|
At this point the new node can be referred to as
|
|
.Dq Li bge0:orphans .
|
|
The
|
|
node can be given its own name like this:
|
|
.Pp
|
|
.Dl "ngctl name bge0:orphans src0"
|
|
.Pp
|
|
After which it can be referred to as
|
|
.Dq Li src0: .
|
|
.Pp
|
|
Once created, packets can be sent to the node as raw binary data.
|
|
Each packet must be delivered in a separate netgraph message.
|
|
.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
|
|
.Nm source
|
|
node's
|
|
.Va input
|
|
hook via
|
|
.Xr nghook 8 :
|
|
.Bd -literal -offset indent
|
|
perl -pe 's/(..)[ \et\en]*/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
|
|
.Ed
|
|
.Pp
|
|
To check that the node has queued these packets you can get the node
|
|
statistics:
|
|
.Bd -literal -offset indent
|
|
ngctl msg bge0:orphans getstats
|
|
Args: { queueOctets=64 queueFrames=1 }
|
|
.Ed
|
|
.Pp
|
|
Send as many packets as required out the
|
|
.Va output
|
|
hook:
|
|
.Pp
|
|
.Dl "ngctl msg bge0:orphans start 16"
|
|
.Pp
|
|
Either wait for them to be sent (periodically fetching stats if desired)
|
|
or send the stop message:
|
|
.Pp
|
|
.Dl "ngctl msg bge0:orphans stop"
|
|
.Pp
|
|
Check the statistics (here we use
|
|
.Ic getclrstats
|
|
to also clear the statistics):
|
|
.Bd -literal -offset indent
|
|
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 } }
|
|
.Ed
|
|
.Pp
|
|
The times are from
|
|
.Vt "struct timeval" Ns s ,
|
|
the
|
|
.Va tv_sec
|
|
field is seconds since
|
|
the Epoch and can be converted into a date string via TCL's [clock
|
|
format] or via the
|
|
.Xr date 1
|
|
command:
|
|
.Bd -literal -offset indent
|
|
date -r 1035305880
|
|
Tue Oct 22 12:58:00 EDT 2002
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr netgraph 4 ,
|
|
.Xr ng_echo 4 ,
|
|
.Xr ng_hole 4 ,
|
|
.Xr ng_tee 4 ,
|
|
.Xr ngctl 8 ,
|
|
.Xr nghook 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
node type was implemented in
|
|
.Fx 4.8 .
|
|
.Sh AUTHORS
|
|
.An Dave Chapeskie
|