xenial (1) mgen.1.gz

Provided by: mgen_5.02+dfsg2-3_amd64 bug

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.

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