nrecv - the UDP/TCP receiver program of ntools


nrecv -if interface -proto udp|tcp [-srcip srcip] [-dstip dstip] [-srcport srcport] [-dstport dstport] [-int statinterval] [-log logfile] [-statfile statfile] [-timestamp] [-delay] [-jitter] [-tos tos] [-prec prec] [-percentile] [-p1 percentile1] [-p2 percentile2] [-p3 percentile3] [-mcast]


nrecv is the UDP/TCP receiver program of ntools that provides statistics about static UDP and TCP streams generated by ngen. The program supports arbitrary number of streams wich can be specified by filters. The parameters can be passed either on the command line interface, or can be placed in a config file. On the command line only one stream can be configured.

The output of the program provides the following fields for each stream:

  • ID
  • the number of received packets
  • the number of lost and misordered packets
  • the number of misordered packets
  • L2 (Ethernet-level) rate for UDP streams, and goodput for TCP streams, both in Mbps
  • delay in ms
  • jitter (min delay, max delay, and difference in ms)
  • delay percentiles in ms
  • flags for special events: F - indicating that foreign frames were received on the stream (not generated by ngen), C - indicating that the measured delay is invalid, mostly due to clock sync problem


Multicast receiving is supported for UDP streams with the -mcast option. If it is specified the receiver will first join the multicast group specified with the destination address.

Receiving VLAN traffic

There are two options for receiving 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 physical interface for the -if option, and use the vlan filter in the configuration file.
Note, that if you use a VLAN interface for the -if option, then the VLAN header is not counted to the received bytes and rate, as it is not seen by nrecv.

Support for real-time Linux

nrecv supports the CONFIG_PREEMPT_RT kernel patch for more precise delay and jitter measurements. With this patch nrecv can achieve consistent sub-ms resolution in the measurements. 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:


-f file

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

-if interface

The receiving interface.

-proto udp | tcp

The protocol can be either UDP or TCP.

-if interface

The interface where nrecv will listen for packets. This option is valid only if the protocol is UDP. The deault is eth0.

-srcip srcip

The source IP address filter.

-dstip dstip

The destination IP address filter.

-srcport srcport

The source port filter.

-dstport dstport

The destination port filter.

-prec prec

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

-tos tos

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


If specified, the program measures delay.


If specified, the program measures jitter.

-int statinterval

Sets the statistical interval in second. Its format is a number and an optional postfix of 'm' for ms. The program generates statistics in each interval. The default is 1 second.


If specified the program will timestamp each statistics line.

-statfile statfile

If this parameter is set, the program also saves the statistics to the given file.

-log logfile

If this parameter is set, the program logs data about every captured packet to the given file.


To enable delay percentile measurement. p1, p2 and p3 defines 3 different delay percentiles that can be measured for specific streams. The percentiles shall be given as floating point numbers. A 99.9 delay percentile value of 10 ms for example means that 99.9% of packets had less latency than 10 ms.

-p1 percentile1

The first percentile value.

-p2 percentile2

The second percentile value.

-p3 percentile3

The third percentile value.


To enable multicast receiving.


The config file has two parts: a global section and a stream section. The global section must preceed the stream section, and has the following options:

   interval statinterval
   statfile statfile
   logfile logfile
   p1 percentile1
   p2 percentile2
   p3 percentile3

statinterval, timestamp, statfile, percentile, p1, p2 and p3 are the same as described above. logfile specifies the file to save packet-level logging, but does not enable logging for any streams. The log option enables packet-level logging for all streams.

The stream section starts with the streams keyword, and may contain any number of stream specifications enclosed in square braces. (The maximum number of streams is defined in defs.h, its default value is 100.) A stream specification contains some stream settings and some filter options. Some of the options are mandatory, some optional.

   id id
   if interface
   logdelay delay
   vlan <vlan>
   pbits <pbits>
   srcip <srcip-spec>
   dstip <dstip-spec>
   proto udp|tcp
   prec prec
   tos tos
   srcport <srcport-spec>
   dstport <dstport-spec>

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

id sets the name for the stream that is used in the statistics. if specifies the interface where this stream is to be captured. log will enable logging for all packets of the stream. logloss enables logging only for lost frames for the stream. logdelay will enable logging for those packets in the stream that have bigger delay than the specified value. percentile will enable delay percentile measurement for the stream. delay and jitter enables delay and jitter measurement for the stream. The rest are filters that the packet must match to belong to the stream. vlan specifies on which 802.1q VLAN the packets shall be captured. pbits filters packets with a specific 802.1p p-bits.


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

   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 packet matches the filter if its address/port is within the given range.


Only UDP streams can have vlan, pbits, srcip, dstip, prec, tos and srcport filters. The proto filter is mandatory, and TCP streams must have dstport filter.
Ranges are not supported for TCP streams.


The log file contains one line for each captured packet. The line has the following fields for received packets:

  • timestamp
  • stream ID
  • status: OK (normal frame), LOSS (frame loss), DUPLIC (frame duplication), MISORD (frame misorder)
  • the sequence number placed by ngen
  • number of lost frames before this one
  • Frame length (with Ethernet overhead)
  • the measured delay in ms (CLOCK indicates clock sync problem)

You must be root to capture UDP streams.
Note that the accuracy of the measurements depends on the CPU speed, and also the CPU load. It is advisable to tune the PC for performance, and shut down all unnecessary daemons/processes. It is also recommended to verify that DMA is enabled on the hard drive with the "hdparm /dev/hda" command.

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 ngen in lowlevel mode.


To capture a UDP stream on the eth0 interface at port 8000:

nrecv -if eth0 -proto udp -dstport 8000

A config file to capture two streams, on the second one we emulate an address range of, ...

   id stream_1
   if eth0
   proto udp
   dstport 8000
   id stream_2
   if eth1
   proto udp
   dstip range
      num 10
   dstport 9000

ntools, ngen


Norbert Vegh,


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.