File mgen.1 of Package mgen
.\" Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH MGEN 1 "June 11, 2011"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh disable hyphenation
.\" .hy enable hyphenation
.\" .ad l left justify
.\" .ad b justify to both left and right margins
.\" .nf disable filling
.\" .fi enable filling
.\" .br insert line break
.\" .sp <n> insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.\"Text automatically generated by txt2man
.SH NAME
mgen - The Multi-Generator for IP network performance tests
.SH SYNOPSIS
.B mgen
[\fIipv4\fR][\fIipv6\fR][\fIinput <scriptFile>\fR][\fIsave <saveFile>\fR]
[\fIoutput <logFile>\fR][\fIlog <logFile>\fR][\fIbinary\fR]
[\fItxlog\fR][\fInolog\fR][\fIflush\fR][\fIhostAddr {on|off}\fR]
[\fIevent "<mgen event>"\fR][\fIport <recvPortList>\fR]
[\fIinstance <name>\fR][\fIcommand <cmdInput>\fR]
[\fIsink <sinkFile>\fR][\fIblock\fR][\fIsource <sourceFile>\fR]
[\fIinterface <interfaceName>\fR][\fIttl <timeToLive>\fR]
[\fItos <typeOfService>\fR][\fIlabel <value>\fR]
[\fItxbuffer <txSocketBufferSize>\fR]
[\fIrxbuffer <rxSocketBufferSize>\fR]
[\fIstart <hr:min:sec> [GMT]\fR][\fIoffset <sec>\fR]
[\fIprecise {on|off}\fR][\fIifinfo <ifName>\fR]
[\fItxcheck\fR][\fIrxcheck\fR][\fIcheck\fR][\fIstop\fR]
[\fIconvert <binaryLog>\fR][\fIdebug <debugLevel>\fR]
[\fIlocaltime <localtime>\fR] [\fIqueue\fP <\fIqueue\fP>\fR]
[\fIbroadcast {on|off}\fR]
.SH 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 \fBmgen\fP program which can generate, receive, and
log test traffic. This document provides information on \fBmgen\fP usage,
message payload, and script and log file formats. Additional tools are
available to facilitate automated script file creation and log file analyses.
.SH OPTIONS
.TP
\fBipv4\fR
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.
.TP
\fBipv6\fR
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.
.TP
\fBinput <scriptFile>\fR
Causes mgen to parse the given <scriptFile> at
startup and schedule any transmission or reception
events_given_in_the_script.
.TP
\fBsave <saveFile>\fR
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.
.TP
\fBoutput <logFile>\fR
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.
.TP
\fBlog <logFile>\fR
This is the same as the output command except that
if <logFile> already exists, it will be appended
instead_of_replaced.
.TP
\fBbinary\fR
Causes mgen to save output logging information in a
smaller-sized binary file format. This option should
come_before_the_output_or_log_command.
.TP
\fBtxlog\fR
This enables transmission logging. This results in
SEND events being added to the log file every time a
packet_is_sent_by_mgen.
.TP
\fBnolog\fR
This_disables_logging_completely.
.TP
\fBflush\fR
This causes the output log file to be flushed with
each line written. This is useful for real-time
monitoring_of_MGEN_logging
.TP
\fBhostAddr {on|off}\fR
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.
.TP
\fBevent "<\fBmgen\fP event>"\fR
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).
.TP
\fBinstance <instanceName>\fR
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
"\\.\mailslot\<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.
.TP
\fBcommand {<path>|STDIN}\fR
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.
.TP
\fBport <recvPortList>\fR
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
.TP
\fBsink <sinkFile>\fR
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.
.TP
\fBsource <sourceFile>\fR
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.
.TP
\fBstart <hr:min:sec>[GMT]\fR
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.
.TP
\fBoffset <sec>\fR
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.
.TP
\fBprecise {on|off}\fR
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".
.TP
\fBifinfo <interfaceName>\fR
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
.TP
\fBconvert <binaryLogFile>\fR
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.
.TP
\fBinterface <interfaceName>\fR
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.
.TP
\fBttl <timeToLive>\fR
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.
.TP
\fBtos <typeOfService>\fR
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.
.TP
\fBlabel <value>\fR
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.
.TP
\fBtxbuffer <bufferSize>\fR
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.
.TP
\fBrxbuffer <bufferSize>\fR
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.
.TP
\fBtxcheck\fR
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.
.TP
\fBrxcheck\fR
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.
.TP
\fBcheck\fR
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.
.TP
\fBstop\fR
This command causes mgen to exit. This is useful for
run-time_control_of_mgen_instances.
.TP
\fBlocaltime\fR
This enables logging of events and error messages in
localtime. By default, events are logged in
Greenwich_Mean_Time.
.TP
\fBqueue <queueSize>\fR
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.
.TP
\fBbroadcast {on|off}\fR
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.
.SH "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 .
.br
.SH AUTHOR
mgen was written by the Naval Research Laboratory (NRL) PROTocol
Engineering Advanced Networking (PROTEAN) group
.PP
This manual page was written by Raoul Gunnar Borenius <borenius@dfn.de>,
for the Debian project (and may be used by others).
