ntools

ngen

nrecv

nserver

nclient

nemu

nemud
NAME

ngen - the UDP/TCP generator program of ntools

SYNOPSYS

ngen -if interface -proto udp|tcp -dstip dstip -dstport dstport -rate rate [-size size] [-srcip srcip] [-srcport srcport] [-tos tos] [-prec prec]

ngen -f file

DESCRIPTION

ngen is the UDP/TCP generator program of ntools. It can generate traffic on arbitrary number of UDP/TCP streams. Currently three packet generation profile (distribution) are supported:

  • Fix: fixed packet size and rate
  • On-Off: two states with different packet size, rate and duration
  • Poisson: fixed packet size, exponential inter-packet time
  • TCP: packet generation is controlled by the TCP protocol stack (only for TCP streams)

Frame sizes and rates are specified on layer 2. It means that they include the Ethernet overhead.
On the command line only one stream can be configured with fix distribution.
The program places sequence number and timestamp into the packets, so that nrecv can calculate loss and delay.

Multicast

Multicast traffic is supported with UDP streams. A multicast route must be configured in advance. Otherwise just a multicast destination address must be configured for this feature.

Sending VLAN traffic

There are two options for generating VLAN traffic. First, a regular VLAN interface can be configured with the standard vconfig command, and that interface can be used with the -if option. The other solution is to use the low-level mode, see section LOW-LEVEL MODE.

Support for real-time Linux

ngen supports the CONFIG_PREEMPT_RT kernel patch for precisely timing packet sending. Without this patch ngen has to use active waiting to time packet sending, which will result in constant 100% CPU usage. Upon startup the program checks whether the kernel has the RT support and use it if available.

For more information about the RT patch visit the following link:
https://rt.wiki.kernel.org/index.php/Main_Page

OPTIONS

-f file

The config file. No other options can be specified if a config file is used.

-if interface

The sending interface.

-proto udp | tcp

The protocol can be either UDP or TCP.

-rate rate

The L2 (Ethernet-level) bitrate. It is a number and an optional postfix of 'k' or 'M' for kbps and Mbps respectively.

-size size

The frame size in bytes. The default is 1518. Jumbo frames are allowed up to 9018 bytes.

-srcip srcip

The source IP address. The default is the address of the sending interface.

-dstip dstip

The destination IP address.

-srcport srcport

The source port. The default is 8888.

-dstport dstport

The destination port.

-prec prec

The IP precedence value. Its valid range is 0..7.

-tos tos

The IP Type of Service value. Its valid range is 0..255. Note that for TCP streams the last 2 bits will be cleared by the kernel.

CONFIG FILE

The config file contains any number of stream specifications in the following format. (The maximum number of streams is defined in defs.h, its default value is 100.)

add
{
   if <interface>
   proto udp|tcp
   srcip <srcip-spec>
   dstip <dstip-spec>
   dstmac mac
   vlan vlan
   pbits pbits
   tos|prec tos|prec
   srcport <srcport-spec>
   dstport <dstport-spec>
   distrib <distrib-spec>
}

Anything after a hashmark (#) on a line is treated as comment, and ignored.

IP AND PORT SPECS

The srcip-spec and dstip-spec can be a simple IP address, or an address range in the following format:

range
{
   first first
   inc inc
   num num
}

first is the first IP address in the range. inc is also in IP address notation. The range is created by adding inc successively to the first ip address. The range contains num number of addresses.

The srcport-spec and dstport-spec can be a simple port number, or a port range. It has exactly the same format as an address range, expect that here first and inc are simple numbers.
If an address/port range is specified, then the successive packets are sent with the successive address/port from the range. At the end of the range, the first value is taken.
Ranges are not supported for TCP streams.

DISTRIB SPECS

There are different distrib-spec formats for each distribution.

Fix:

fix
{
   rate rate
   size size
}

rate is the L2 (Ethernet-level) bitrate. It is a number and an optional postfix of 'k' or 'M' for kbps and Mbps respectively. size is the packet size in bytes.

On-off:

on-off
{
   rate1 rate1
   rate2 rate2
   time1 time1
   time2 time2
   size1 size1
   size2 size2
}

The on-off distribution has two sets of parameters for the two states. The rate and size parameters are the same as described above. The time parameters specify the duration of the states in second. Its format is a number and an optional 'm' or 'u' postfix for ms and us respectively.

Poisson:

poisson
{
   size size
   avgint avgint
}

avgint is the average inter-packet time of the poisson distribution in seconds. Its format is a number and an optional 'm' or 'u' postfix for ms and us respectively.

TCP:

tcp

There are no further parameters for this distribution.

LOW-LEVEL MODE

If the dstmac parameter is defined, it enables the low-level mode for the stream. This mode is useful if you want to by-pass the normal routing process. You need this mode if you want to generate VLAN traffic without actually creating the VLAN sub-interfaces. If you want to set the vlan parameter for the stream, then you have to use this mode, and also specify the dstmac parameter. You can also set the p-bits in the VLAN header with the pbits parameter. You can also use this mode if you want to send traffic between interfaces on the same machine through an external device under test. In that case you have to set the dstmac parameter to the MAC address of the receiving interface. You must also specify the srcip parameter, and it cannot be any address on the PC, otherwise the packets will be discarded at the receiver side.

RESTRICTIONS

Only UDP streams can have srcip, dstmac, vlan, pbits parameters. The if, proto, dstip and dstport parameters are mandatory. For udp streams if srcip is not defined, it is set to the address of the sending interface.

NOTES

You must be root to generate UDP streams.

For TCP streams the program tries to send out the packets with the specified rate, but since it uses a normal TCP socket, the sending rate depends on the network condition, and may be much lower then the configured value.

For delay measurements the clock of the machines running ngen and nrecv must be synchronized. An other way is to run both program on the same machine, and use the low-level mode.

It is important that you understand that without the RT patch ngen uses active waiting for timing the packet sending. It means that when you start ngen, the CPU usage goes up to 100%.

EXAMPLES

To generate a 10 Mbps UDP stream to PC 10.0.0.5 port 8000:

ngen -if eth0 -proto udp -dstip 10.0.0.5 -dstport 8000 -rate 10M

A config file with two stream, on the second stream we send to 10 different addresses of 10.0.50.10, 10.0.50.12 ... 10.0.50.28:

add
{
   id stream_1
   if eth0
   proto udp
   dstip 10.0.0.5
   dstport 8000
   distrib fix
   {
      size 500
      rate 500k
   }
}
add
{
   id stream_2
   if eth0
   proto udp
   dstip range
   {
      first 10.0.0.10
      inc 0.0.0.2
      num 10
   }
   dstport 9000
   distrib poisson
   {
      size 1500
      avgint 1m
   }
}
SEE ALSO

ntools, nrecv

AUTHOR

Norbert Vegh,

COPYRIGHT

ntools is (C) 2002-2010 Norbert Vegh.

The program was originally developed in Telia Research AB.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.