'\" '\" $Id: dagsnapbis.1 7181 2007-08-01 23:02:31Z ben $ '\" .TH dagsnapbis 1 "July 2007" "Endace" "Endace Software Command Manual" . .SH NAME .B dagsnapbis - Endace DAG card capture utility with file rotation. . .SH SYNOPSIS .B dagsnapbis .RI [ options ] . .SH DESCRIPTION .B dagsnapbis is a utility for capturing ERF record data directly to disk. Data is collected from Endace DAG cards. . .P .B dagsnapbis can create data files based on: .br .ns - time .br .ns - number of bytes .br .ns - or a combination of both time and number of bytes. . .P .B dagsnapbis can overwrite data files once: .br .ns - a maximum number of bytes have been captured .br .ns - a maximum number of data files have been created. . .P 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 . .P Data is collected in Extensible Record Format (ERF) which can then be viewed using .BR dagbits (1), or converted to other formats (including .BR pcap (3)) using .BR dagconvert (1). . .P This utility is closely related to .BR dagsnap (1) however it has been extended to support multi-file capture as stated above. . .P Disk write performance can be maximized using the .BR -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. . .P 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: . .P .RS YYYYMMDD-HHNNSS-EE .P . YYYY = Year (with century) .br .ns MM = Month (01-12) .br .ns DD = Day (01-31) .br .ns HH = Hour (00-23) .br .ns NN = Minute (00-59) .br .ns SS = Seconds (00-59) .br .ns EE = Sequence number (00-XXXX) .RE .P . 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. .SH OPTIONS . .TP .BI "-d " DEVICE .br .ns .TP .BI "--device " DEVICE .br .ns Use the DAG device referred to by .IR DEVICE . Supported syntax includes .BR 0 ", " dag1 ", and " /dev/dag3 to refer to DAG cards, and .BR 0:2 ", " dag1:1 ", and " /dev/dag2:0 to refer to specific streams on cards. . .TP .B -h .br .ns .TP .B -? .br .ns .TP .B --help .br .ns .TP .B --usage .br .ns Display usage (help) information. . .TP .BI "-f " PATH .br .ns .TP .BI "--capture-dir " PATH .br .ns Writes all capture files into the .I 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. . .TP .B -j .br .ns .TP .B --maxwrite .br .ns 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 .BR erf "(5))" record may be inserted at the start of each individual capture file. .TP .B -l .br .ns .TP .B --syslog .br .ns Route all error and warning messages to syslog rather than stderr. . .TP .BI "-m " NUM .br .ns .TP .BI "--size-limit " NUM .br .ns Each individual capture file will contain approximately .I NUM number of bytes. The following suffixes can be used; k, m, g, t for kilobytes, megabytes, gigabytes, terabytes. . .TP .BI "-o " NAME .br .ns .TP .BI "--name-or-run " NAME .br .ns Suffix to append onto the end of all filenames generated by this utility. If not specified it defaults to "erf". Filename format: .RS .RS .P .RI "datetimestamp." "NAME" .RE .RE . .TP .BI "-r " NUM .br .ns .TP .BI "--max-files " NUM .br .ns The maximum of .I 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. . .TP .BI "-s " NUM .br .ns .TP .BI "--time-limit " NUM .br .ns Each individual capture file will contain .I NUM seconds worth of captured data. . .TP .BI "-t " NUM .br .ns .TP .BI "--max-size " NUM .br .ns .I 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. . .TP .B -v .br .ns .TP .B --verbose .br .ns Increase output verbosity. When .B dagsnapbis is run with this command, three columns of data are reported every second. These columns contain .RS .TP .B 1 The cumulative total of data written out from the DAG card. .TP .B 2 The buffer occupancy. Small values indicate no packet loss. .TP .B 3 The rate at which data is currently being written. .RE . .TP .B -V .br .ns .TP .BR --version .br .ns Display version information. . .SH EXAMPLES To read from DAG card 0 and save the records into multiple files each with 5 seconds worth of data: .RS .B dagsnapbis -d 0 -s 5 .RE . .P To do the same as above but save the files into the "/captured" directory with a suffix of "mycap.erf": .RS .B dagsnapbis -d 0 -s 5 -f /captured -o mycap.erf .RE . .P 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: .RS .B dagsnapbis -d dag1:2 -s 5 -r 10 .RE . .P 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: .RS .B dagsnapbis -d dag0 -m 100m -t 5g .RE . .SH SEE ALSO .BR dagsnap "(1), " dagbits "(1), " dagconvert "(1), " erf "(5) " . .SH BUGS Report bugs to . . .SH LAST UPDATED $Author: ben $ .br $Revision: 7181 $ .br $Date: 2007-08-02 11:02:31 +1200 (Thu, 02 Aug 2007) $ . .SH COPYRIGHT (c) 2004-2007 Endace Technology, Hamilton, New Zealand. All Rights Reserved. .