MGEN(1) | General Commands Manual | MGEN(1) |
NAME¶
mgen - The Multi-Generator for IP network performance testsSYNOPSIS¶
mgen [ ipv4][ipv6][input <scriptFile>][save <saveFile>][ output <logFile>][log <logFile>][binary]
[ txlog][nolog][flush][hostAddr {on|off}]
[ event "<mgen event>"][port <recvPortList>]
[ instance <name>][command <cmdInput>]
[ sink <sinkFile>][block][source <sourceFile>]
[ interface <interfaceName>][ttl <timeToLive>]
[ tos <typeOfService>][label <value>]
[ txbuffer <txSocketBufferSize>]
[ rxbuffer <rxSocketBufferSize>]
[ start <hr:min:sec> [GMT]][offset <sec>]
[ precise {on|off}][ifinfo <ifName>]
[ txcheck][rxcheck][check][stop]
[ convert <binaryLog>][debug <debugLevel>]
[ localtime <localtime>] [queue <queue>]
[ broadcast {on|off}]
DESCRIPTION¶
The Multi-Generator (MGEN) is open source software by the Naval_Research Laboratory (NRL) PROTocol Engineering Advanced Networking (PROTEAN) group which provides the ability to perform IP network performance tests and measurements using UDP and TCP IP traffic. The toolset generates real-time traffic patterns so that the network can be loaded in a variety of ways. The generated traffic can also be received and logged for analyses. Script files are used to drive the generated loading patterns over the course of time. These script files can be used to emulate the traffic patterns of unicast and/or multicast UDP and TCP IP applications. The tool set can be scripted to dynamically join and leave IP multicast groups. MGEN log data can be used to calculate performance statistics on throughput, packet loss rates, communication delay, and more. MGEN currently runs on various Unix-based (including MacOS X) and WIN32 platforms. The principal tool is the mgen program which can generate, receive, and log test traffic. This document provides information on mgen usage, message payload, and script and log file formats. Additional tools are available to facilitate automated script file creation and log file analyses.OPTIONS¶
- ipv4
- Forces mgen to open sockets for IPv4 operation (i.e.
AF_INET domain sockets) only. The default behavior for mgen is to open
sockets with the domain based on environment (e.g. RES_OPTIONS) variables
and the type_of_IP_addresses_used_in_the_script_file_used.
- ipv6
- Forces mgen to open sockets for IPv6 operation (i.e.
AF_INET6 domain sockets) only. The default behavior for mgen is to open
sockets with the domain based on environment (e.g. RES_OPTIONS) variables
and the type_of_IP_addresses_used_in_the_script_file_used.
- input <scriptFile>
- Causes mgen to parse the given <scriptFile> at
startup and schedule any transmission or reception
events_given_in_the_script.
- save <saveFile>
- Causes mgen to save the sequence number state of any
pending transmit flows and the current relative script "offset"
time to <saveFile> in the form of an MGEN script. The
<saveFile> may be used as an additional input script on a subsequent
launch of mgento return mgen to the same state as when previously exited.
See the equivalent global SAVE command_for_further_detail_on_usage.
- output <logFile>
- Cause mgen to output logged information to the indicated
<logFile>. By default, mgen will log to stdout. With the output
command, an existing <logFile> of the same name will be overwritten.
Use the_log_command_to_append_to_an_existing_log_file.
- log <logFile>
- This is the same as the output command except that if
<logFile> already exists, it will be appended instead_of_replaced.
- binary
- Causes mgen to save output logging information in a
smaller-sized binary file format. This option should
come_before_the_output_or_log_command.
- txlog
- This enables transmission logging. This results in SEND
events being added to the log file every time a packet_is_sent_by_mgen.
- nolog
- This_disables_logging_completely.
- flush
- This causes the output log file to be flushed with each
line written. This is useful for real-time monitoring_of_MGEN_logging
- hostAddr {on|off}
- Turning this option on causes mgen to include the
"host" field in MGEN messages sent. The "host" field
contains an educated guess of the machines local IP address to help
identify the source of messages in log files. When the "host"
field is present, MGEN log file SEND and RECV events contain a
"host>" field indicating the sender's original address. This
can be useful when Network Address Translation (NAT)
or_other_tunneling_occurs_in_test_networks.
- event "<mgen event>"
- The event command allows the user to enter the equivalent
of MGEN script lines into mgen via the command-line. Multiple event
commands can be used to pass the equivalent of a multi-line script to
MGEN. Note that MGEN script events generally contain spaces and thus must
be encapsulated in quotes on ommand line. Note that the <eventTime>
may be omitted and the action indicated will be taken by mgen immediately.
When the event command is issued during run-time, the <eventTime>
(if provided) specifies a delay relative to the current time (e.g. the
event will occur with after the_given_delay).
- instance <instanceName>
- If a pre-existing mgen application instance is _not_
already running, this command registers the running mgen program as an
instance identified by the <instanceName>. On UNIX, this corresponds
to a Unix- domain datagram socket named
"/tmp/<instanceName>" being opened and monitored for MGEN
commands (On WIN32, a "mailslot" named
"\.ilslot<instanceName>" is created and used). These
interprocess channels allow for run-time control of mgen processes. This
is the preferred methodology for run-time control of the mgen
application.If an application instance as identified by the
<instanceName> parameter is already running, any subsequent
command-line options are transmitted to the remote instance already
running, and the new mgen instance will then exit.This allows run-time
control of possibly multiple background mgeninstances from the
"shell" or via scripting. The event command may be used to
dispatch MGEN script events_to_mgen_instances_at_run-time.
- command {<path>|STDIN}
- This specifies a file or device which mgen will monitor for
run-time command input. If the "STDIN" key is used, mgenmonitors
the "stdin" (console) input which can provide a crude run-time
user interface for mgen. Commands sent to mgen in this fashion must be
delimited by line-breaks or the ';' character. See the instance command
for a more flexible, and the preferred option for mgen run-time control.
- port <recvPortList>
- Causes mgen to monitor the given port numbers for received
UDP traffic. The format of the <recvPortList> is a comma-delimited
list of individual or inclusive ranges of port values (No spaces allowed
in the list). Note this is the equivalent of a scripted 0.0 LISTEN UDP
<recvPortList> reception event and can also be equivalently achieved
with the event command using the syntax: mgen event "LISTEN UDP
<portList>"Example:mgen port 5000,5002,5005-5009
- sink <sinkFile>
- Causes mgento use the file or device (e.g. stdout)
indicated as a "sink" or destination for transmitted message
flows of protocol type "SINK". I.e., MGEN message flows of type
"SINK" are written to the "sink" device instead of to
a UDP or TCP socket. Piping mgen output to stdout allows MGEN messages to
use alternative transport provided by another process (e.g. ssh, norm,
etc). The special <sinkFile> value "STDOUT" will direct
MGEN SINK flows_to_the_mgen_process_stdout.
- source <sourceFile>
- This is the complement to the sink command. This allows
mgen to directly receive a binary stream of MGEN messaging from the
<sourceFile> which may be the piped stdoutfrom another process (e.g.
ssh, norm, etc). The special <sourceFile> string "STDIN"
causes mgen to get input from its stdin stream. Messages read from the
<sourceFile> (or stream) are time-stamped and logged
in_the_MGEN_log_file_as_usual.
- start <hr:min:sec>[GMT]
- Causes mgen to delay processing events in script file
relative to the indicated absolute time. The optional "GMT"
keyword indicates the time is Greenwich Mean Time instead of the default
local time. This command establishes an absolute time for
the_relative_script_time_of_0.0_seconds.
- offset <sec>
- Causes mgen to skip <sec> seconds of relative time
into the execution of the script file used. Note that if an absolute start
time is given using the start command, the offset into the script will
correspond to that absolute time. The default offset
for_MGEN_is_0.0_seconds.
- precise {on|off}
- When the precise mode is enable, mgen performs polling
(only as needed) to precisely time packet transmission. While this is
sometimes helpful at high packet transmission rates, it comes at a cost of
high CPU utilization by mgen. The default for
this_option_is_"off".
- ifinfo <interfaceName>
- This option can be used to have MGEN print a summary of
statistics to stderr upon exit for the specified network interface. These
stats include counts of frames sent/received. This can be used to augment/
verify MGEN performance with or without logging enabled
- convert <binaryLogFile>
- Causes mgen to convert the indicated <binaryLogFile>
to a text-based log file. The text-based log file information will be
directed to stdout unless you specify a filename with the output or log
command. Mgen will exit after the file conversion is complete.
- interface <interfaceName>
- Causes mgen to set the default network interface for IP
multicast and/or root node flow transmission to <interfaceName>.
<interfaceName> will override any default interface specified within
an mgenscript file. <interfaceName> is a "per socket"
attribute, and in its absence, MGEN will behave according to
the_operating_system's_default_behavior.
- ttl <timeToLive>
- Causes mgen to set the hop count for IP multicast traffic
generated by MGEN. <timeToLive> will override any default ttl
indicated within an mgen script file. <timeToLive> is a "per
socket" attribute. If no ttl option is used, MGEN will behave
according to the operating system's default behavior.
- tos <typeOfService>
- Causes mgen to set the IPv4 type-of-service field (within
the packet header) to <typeOfService>. <typeOfService> will
override any default tos indicated within an mgen script file. As with ttl
and interface, tos is a "per socket" attribute. If no tos option
is used, MGEN will behave according to
the_operating_system's_default_behavior.
- label <value>
- Causes mgen to set <value> as the default flow label
for IPv6 flows. The <value> corresponds to the 28-bit IPv6 flow
label field and may be specified_in_decimal_or_hex.
- txbuffer <bufferSize>
- Causes mgen to set the socket transmit buffer size to a
value ?at least? as large as <bufferSize>. If <bufferSize> is
larger that the maximum allowed by the system, <bufferSize> will be
set to the system maximum.
- rxbuffer <bufferSize>
- Causes mgento set the socket receive buffer size to a value
?at least? as large as <bufferSize>. If <bufferSize> is larger
that the maximum allowed by the system, <bufferSize> will be set to
the system maximum.
- txcheck
- Causes mgen to include an optional 32-bit cyclic redundancy
checksum (CRC) at the end of its messages. The CHECKSUM flag is set to
indicate the presence_of_the_checksum_content.
- rxcheck
- Forces mgen receivers to validate the checksum portion
(last 4 bytes) of MGEN messages whether or not the CHECKSUM flag is set in
the MGEN "flags" message field. Use this option when it is
_known_ that the MGEN sender is supplying checksums to cover the case when
the "flags" field itself is possibly corrupted.
- check
- Sets mgen behavior as if both the txcheck _and_ rxcheck
commands were applied. This is the recommended option when MGEN checksum
operation is desired so that both senders and receivers are
providing_and_validating_checksums,_respectively.
- stop
- This command causes mgen to exit. This is useful for
run-time_control_of_mgen_instances.
- localtime
- This enables logging of events and error messages in
localtime. By default, events are logged in Greenwich_Mean_Time.
- queue <queueSize>
- This global command will cause mgen to buffer
<queueSize> mgen packets for each flow during periods of congestion.
(Note that flow specific limits specified at the transmission event level
will override this global). When the number of pending messages for a flow
exceeds this limit, the message transmission timer will be temporarily
deactivated and any pending messages will transmitted as quickly as
possible. The timer will be reactivated once the pending message count
falls below the queue limit, and message transmission will return to the
previously scheduled rate of transmission. If no global command is
specified, a default <queueSize> of "0" will be in effect
which will result in no queuing behavior, e.g. the transmission timer will
continue to fire at its regularly scheduled interval regardless of
transport congestion. No pending message count will be accumulated and
message transmission will suceed or fail depending on transport
availability. See QUEUE for_more_details_about_the_queueing_mechanism.
- broadcast {on|off}
- Causes MGEN to set the socket option SO_BROADCAST to allow
or disallow sending (and sometimes receiving) broadcasts from the socket.
As with tos, ttl and interface, broadcast is a "per socket"
attribute. By default_BROADCAST_is_set_to_ON.
SEE ALSO¶
Please refer to the mgen-doc package for more documentation or the online version at http://pf.itd.nrl.navy.mil/mgen/mgen.html .AUTHOR¶
mgen was written by the Naval Research Laboratory (NRL) PROTocol Engineering Advanced Networking (PROTEAN) group This manual page was written by Raoul Gunnar Borenius <borenius@dfn.de>, for the Debian project (and may be used by others).June 11, 2011 |