dagsnapbis(1)

NAME
dagsnapbis - Endace DAG card capture utility with file rotation.

SYNOPSIS
dagsnapbis [options]

DESCRIPTION
dagsnapbis is a utility for capturing ERF record data directly to disk. Data is collected from Endace DAG cards.

dagsnapbis can create data files based on:
- time
- number of bytes
- or a combination of both time and number of bytes.

dagsnapbis can overwrite data files once:
- a maximum number of bytes have been captured
- a maximum number of data files have been created.

For example, you can define that 5 seconds of data should be captured per file and that only 10 files be kept. Once the tenth file is created the oldest file is deleted and a new file is created. This way only the last 50 seconds of data is stored in 5 second intervals

Data is collected in Extensible Record Format (ERF) which can then be viewed using dagbits(1), or converted to other formats (including pcap(3)) using dagconvert(1).

This utility is closely related to dagsnap(1) however it has been extended to support multi-file capture as stated above.

Disk write performance can be maximized using the -j option, this enables unbuffered (direct) disk IO on most operating systems. A side effect of using the maximize option is that a single ERF pad record (ERF type 48) may be inserted at the start of each capture file to maintain block size alignment. This pad record will be of variable size but no greater than 64k. The payload of the record may contain random data and should be ignored.

All capture files created by this utility are given a name consisting of a date / time stamp, of when the file was created, and an optional user defined name. The format is datetimestamp.name. The date / time stamp will be formatted as follows:

    YYYYMMDD-HHNNSS-EE

    YYYY = Year (with century)
    MM = Month (01-12)
    DD = Day (01-31)
    HH = Hour (00-23)
    NN = Minute (00-59)
    SS = Seconds (00-59)
    EE = Sequence number (00-XXXX)

The sequence number part of the date / time stamp is a unique incrementing number that is appended to differentiate files created in the same second.

OPTIONS

-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.

-h

-?

--help

--usage
    Display usage (help) information.

-f PATH

--capture-dir PATH
    Writes all capture files into the PATH directory. A trailing forward slash is not required. If this option is not specified, all capture files will be stored in the current working directory.

-j

--maxwrite
    Maximize disk writing performance by writing data to disk only in chunks. This option is available on all operating systems, however it's effects may be varied. It is important to note that a side effect of using this option is that a single ERF pad (ERF type 48, see erf(5)) record may be inserted at the start of each individual capture file.

-l

--syslog
    Route all error and warning messages to syslog rather than stderr.

-m NUM

--size-limit NUM
    Each individual capture file will contain approximately NUM number of bytes. The following suffixes can be used; k, m, g, t for kilobytes, megabytes, gigabytes, terabytes.

-o NAME

--name-or-run NAME
    Suffix to append onto the end of all filenames generated by this utility. If not specified it defaults to "erf". Filename format:

        datetimestamp.NAME

-r NUM

--max-files NUM
    The maximum of NUM files to be created. When the limit is reached, the first file in the capture sequence is deleted prior to a new one being created.

-s NUM

--time-limit NUM
    Each individual capture file will contain NUM seconds worth of captured data.

-t NUM

--max-size NUM
    NUM is the maximum number of bytes to be captured over the whole capture set. When the limit is exceeded the first file in the capture sequence will be deleted prior to a new one being created. The following suffixes can be used; k, m, g, t for kilobytes, megabytes, gigabytes, terabytes.

-v

--verbose
    Increase output verbosity. When dagsnapbis is run with this command, three columns of data are reported every second. These columns contain

    1   The cumulative total of data written out from the DAG card.

    2   The buffer occupancy. Small values indicate no packet loss.

    3   The rate at which data is currently being written.

-V

--version
    Display version information.

EXAMPLES
To read from DAG card 0 and save the records into multiple files each with 5 seconds worth of data:
    dagsnapbis -d 0 -s 5

To do the same as above but save the files into the "/captured" directory with a suffix of "mycap.erf":
    dagsnapbis -d 0 -s 5 -f /captured -o mycap.erf

To read from DAG card 1 stream 2 and save the records into a maximum of 10 files, each with 5 seconds worth of data:
    dagsnapbis -d dag1:2 -s 5 -r 10

To read from DAG card 0 and save the records into multiple files each with ~100MB of data and a limit of 5GB for all the files:
    dagsnapbis -d dag0 -m 100m -t 5g

SEE ALSO
dagsnap(1), dagbits(1), dagconvert(1), erf(5)

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

LAST UPDATED
$Author: ben $
$Revision: 7181 $
$Date: 2007-08-02 11:02:31 +1200 (Thu, 02 Aug 2007) $

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