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