Ubuntu Manpage: mgen - The Multi-Generator for IP network performance tests

NAME

       mgen - The Multi-Generator for IP network performance tests

SYNOPSIS

       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.

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                                   MGEN(1)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

SEE ALSO

AUTHOR