mgen (1)

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}]

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.

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 "\.\mailslotlt;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.

Please refer to the mgen-doc package for more documentation or the online version at http://pf.itd.nrl.navy.mil/mgen/mgen.html .

mgen was written by the Naval Research Laboratory (NRL) PROTocol Engineering Advanced Networking (PROTEAN) group

This manual page was written by Raoul Gunnar Borenius <[email protected]>, for the Debian project (and may be used by others).