dagflood(1)

NAME
dagflood - Endace DAG card transmit utility

SYNOPSIS
dagflood [options]

DESCRIPTION
dagflood transmits packets stored as a file containing ERF (Extensible Record Format) records using a DAG card.

OPTIONS

-a

--accuracy
    Make inter-burst delay (-u) include the data reading and copying time. Recommended.

-b

--busywait
    Greatly increases accuracy of inter-burst delay (-u) timing, but loads one CPU core at 100%.

-c NUM

--count NUM
    Transmit file NUM times before exiting.

-d DEVICE

--device DEVICE
    Use the DAG device referred to by DEVICE. Supported syntax includes 0, dag1, and /dev/dag3 to refer to DAG cards, and 0:2, dag1:1, and /dev/dag2:0 to refer to specific streams on cards.

-f FILE

--fname FILE
    Send ERF records from the given FILE.

-h

-?

--help

--usage
    Display usage (help) information.

-j

--odirect
    Use O_DIRECT to improve file read performance on some systems.

-l NUM

--burst-max NUM
    Set maximum data burst length to NUM bytes. Accepts k, m, g suffixes. The default is 1 MiB (1048576 Bytes).

-n NUM

--nsdelay NUM
    Set Replay (-R) inter-packet time stamp delta to NUM nanoseconds. Inverse of -p.

-p RATE

--rate RATE
    Set the Replay (-R) packet rate to RATE packets per second. Accepts k, m, g suffixes.

-r API
    --mode API
    Set the transmit API mode:

    1   Commit bytes.

    2   Copy bytes.

    3   Commit packets.

    These correspond to using the DAG API routines dag_tx_stream_commit_bytes(3), dag_tx_stream_copy_bytes(3), dag_tx_stream_commit_records(3) respectively.

-R

--replay
    Replay file using packet timestamps in hardware (time_mode=relative).

-s SCALE

--scale SCALE
    Scale Replay (-R) transmit rate. Supports decimal points and optional % (1.0x = 100%). Default: 100%.

-S TIME

--start-time TIME
    Start transmitting at TIME in seconds from UNIX Epoch.

-t NUM

--terminate NUM
    Stop transmitting after NUM seconds. Default is to transmit file once.

-u NUM

--delay NUM
    Set the delay between bursts of packets to NUM microseconds.

-v

--verbose
    Increase output verbosity.

-V

--version
    Display version information.

-w NUM

--bandwidth NUM
    Set Replay (-R) transmit bandwidth to NUM bits per second. Supports k,m,and g units.

-x

--no-flush
    Do not flush transmit buffer when exiting. (Default: flush buffer)

EXAMPLES
Sending a file once:
    dagflood -f file.erf -d dag0 -v

Sending a file one hundred times:
    dagflood -f file.erf -d dag0 -c 100 -v

Sending a file for 60 seconds (repeating if necessary):
    dagflood -f file.erf -d dag0 -t 60 -v

Sending a file more slowly, by committing 1kB of records to the card every 0.0005 seconds:
    dagflood -f file.erf -d dag0 -l 1024 -u 500 -a -v

Replaying a file at exactly the captured rate (not available on all cards):
    dagflood -f file.erf -d dag0 -R -v

Replaying a file at twice the captured rate (not available on all cards):
    dagflood -f file.erf -d dag0 -s 2.0 -v

Replaying a file at 10000 packets per second (not available on all cards):
    dagflood -f file.erf -d dag0 -p 10k -v

Replaying a file at 10.5 Mbps (not available on all cards):
    dagflood -f file.erf -d dag0 -w 10.5m -v

Start transmitting the file at 3:30pm today:
    dagflood -f file.erf -d dag0 -S `date +%s -d '3:30pm'` -v

Start transmitting the file in 10 minutes time for 2 minutes:
    dagflood -f file.erf -d dag0 -S `date +%s -d '10 mins'` -t 120 -v

Capturing packets from a DAG card to a file of ERF records with dagsnap(1) for 5 seconds, aligning the records in the file to 64-bit boundaries, and then transmitting them:
    dagsnap -d dag0 -s 5 -o file1.erf
    dagconvert -i file1.erf -o file2.erf -A 8
    dagflood -f file2.erf -d dag1

To generate a file with daggen(1) and then send it with dagflood:
    daggen -f traffic.cfg -x traffic_group_1 -o file.erf
    dagflood -f file.erf -d dag0

NOTES

  Obtaining ERF files
There are several ways to obtain a file of ERF records. One is to use dagsnap(1), to capture network traffic from a DAG card into a file. In this case dagconvert(1) should also be used to make the ERF records 64-bit aligned (ERF records that are not 64-bit aligned will not be transmitted by the firmware).

Another way to get a file of ERF records is to use daggen(1) to generate the file directly. daggen(1) is a packet constructor which reads packet definitions from a configuration file and writes the resulting packets to a file. The complete manual of daggen(1) can be found in the doc directory of DAG software release.

  Transmitting packets
Transmitting packets at full line rate requires a fast read from where the packets are stored. But accessing a file at disk is a slow process, at least from the point of view of dagflood. The way to improve access speed to the file is to have it in memory. dagflood will attempt to read the file containing packets entirely into memory. This means if you want to transmit a 1 GiB file, you'll need at least 1 GiB of free physical memory on your system. If enough memory is available to cache the file dagflood will generally be able to transmit the file contents via the DAG card at the maximum line rate of the DAG card interfaces.

If there is insufficent memory to cache the entire input file in memory, dagflood will print a warning, and will fall back to transmitting the packets at the rate at which it can read the file from disk. On systems with slow disk subsystems this may prevent dagflood from transmitting at line rate.

On some systems the -j option can increase the performance of reading files from disk, and hence increase the transmit bandwidth. This is done by using the O_DIRECT (see open(2).

  Adjusting packet transmission rate
dagflood works by copying blocks of data from the source file into the DAG transmit stream buffer. By default the blocks are 1MiB (1048576 Bytes), and are copied as quickly as possible. If the source is read from disk this will usually limit the transmit rate. If the source file is cached the file will typically be sent at the maximum line rate of the card.

If the transmitted rate is faster than desired it is possible to insert a delay (-u) between sending each burst (-l) to the card. This delay will lower the average data rate, but results in a burst of data at line rate followed by a period where no data is sent. Using a smaller burst size with a proportionally smaller delay value will tend to reduce the coarseness of the bursts on the line.

An alternative is -R Replay mode, which utilises the Timed Release feature available on most DAG cards. The DAG card will examine the time stamps in the ERF records in hardware and transmit the packets with exactly the same inter-packet delays. This replays the packet trace file at exactly the rate it was captured it with very high precision.

You can also scale up or down the transmission speed using the -s option, set a fixed packet rate with -p, or a fixed bandwidth with -w. All these options rely on the Timed Release feature and imply the -R flag.

For maximum accuracy in Replay modes, use files that only contain packets on one DAG card interface. Files which contain packets captured on multiple DAG card interfaces can be replayed, but the timing accuracy can be affected on a fine time scale by head of queue blocking effects. The packet rate -p and bandwidth adjustments -w are global for the card not per interface, so also work best with files that only contain packets on one interface. The dagconvert(1) tool can be used to set all of the packet interface ids in a file to one interface.

If the Timed Release feature is not available on the DAG card, dagflood will report an error. Card features are dependent on the firmware loaded, so ensure your card is using the latest version; see dagrom(1).

  Setting the start time
The -S option can be used to set the time at which transmission starts. This allows the synchronisation of multiple dagflood instances across multiple DAG cards and even systems, provided that the DAG card clocks are synchronised. This feature relies on the Triggered Timed Release firmware feature which is not available on all DAG cards. If the feature is not present dagflood will return an error and no data will be sent.

The option parameter is the time that the transmission should start represented as seconds from the UNIX Epoch. The date(1) command can be used to produce the correct time format from human rewadable formats, see EXAMPLES.

The transmission start time is determined in hardware using the DAG card clock for ultimate accuracy, not the Operating System clock. If the OS clock and DAG card clock are not synchronised the transmission may not start at the expected time, see dagclock(1).

If the specified start time has already passed, dagflood will report an warning and begin transmission immediately. If the start time has not yet occurred a countdown will be displayed with the -v option.

If the -t option is also used to set the duration of time to transmit, this period will not begin until the start time has been reached.

  Exiting
dagflood by default transmits the file once. After all records in the the input file have been written into the DAG transmit stream buffer, dagflood will wait until the transmit buffer empties before it exits. Normally this will be a short delay, but if the size of the stream buffer is large compared to the link rate it may take several seconds to empty. This is especially noticable if the transmit rate is reduced by using the -R, -p, -s, or -w options. If -v is used the remaining buffer level will be displayed until the buffer is empty. During this time packets are still being transmitted even though the data rate is not reported.

When -t is used to set the length of time to transmit, dagflood will stop transmitting immediately and exit after the specified time without waiting for the buffer to drain.

The -x option causes dagflood to exit without waiting for the buffer to drain regardless of other options. Packet transmission will stop immediately on exit.

Using ctrl-c (SIGTERM) while dagflood is transmitting will cause it to stop writing new data to the transmit stream buffer. Unless -t or -x are used, dagflood will then wait for the data already written to the buffer to drain before exiting. During this time packets are still being transmitted.

To exit dagflood while the buffer is draining use ctrl-c (SIGTERM) again. This will cause dagflood to exit immediately and no further packets will be sent.

DIAGNOSTICS
The most common reason a file will not be sent is that the ERF records in the file are not 64-bit (8-byte) aligned, and are being discarded by the firmware. In such a case dagflood will be report that the file is being transmitted, but nothing will appear on the network link. dagconvert(1) is able to convert an ERF file to be 64-bit aligned with the -A8 switch (the argument is in bytes):
    dagconvert -A8 -T erf:erf < infile.erf > outfile.erf

A common problem when attempting full line-rate transmission is that dagflood appears to take a while to "warm up"; when sending with the verbose (-v) option enabled (so the transmit line rate is continuously displayed), dagflood shows an initial rate that is only several Mbps but this jumps to full line-rate after a period of time that may be as long as a minute. The culprit in this case is that the file is too large to fit into the dagflood internal cache, and is instead transmitted as it is read from the file. The initial read of the transmit file can be very slow, but once the file is cached by the OS, dagflood is able to send at full line-rate. This occurs frequently when the transmit file resides on a network file system, so a workaround is to copy the file to a local hard disk before sending.

SEE ALSO
dagconvert(1), daggen(1), dagsnap(1), dagrom(1), dagclock(1), date(1), dag_tx_stream_commit_bytes(3), dag_tx_stream_copy_bytes(3).

BUGS
Report bugs to <support@endace.com>.

LAST UPDATED
$Author: sfd $
$Revision: 13290 $
$Date: 2010-10-07 10:39:25 +1300 (Thu, 07 Oct 2010) $

COPYRIGHT
(c) 2004-2010 Endace Technology, Hamilton, New Zealand. All Rights Reserved.