Add missing comments in syntax description for -z expert
[obnox/wireshark/wip.git] / doc / editcap.pod
index 3948f1ffcbd8eb74824feb3024b6356c46dda059..deea34ea7644db765fc0beacab99dcdd7f4bdadf 100644 (file)
 
 =head1 NAME
 
-Editcap - Edit and/or translate the format of capture files
+editcap - Edit and/or translate the format of capture files
 
-=head1 SYNOPSYS
+=head1 SYNOPSIS
 
 B<editcap>
-S<[ B<-F> file format ]>
-S<[ B<-T> encapsulation type ]>
+S<[ B<-c> E<lt>packets per fileE<gt> ]>
+S<[ B<-C> E<lt>choplenE<gt> ]>
+S<[ B<-E> E<lt>error probabilityE<gt> ]>
+S<[ B<-F> E<lt>file formatE<gt> ]>
+S<[ B<-W> E<lt>file format optionE<gt>]>
+S<[ B<-H> E<lt>input hosts file<gt> ]>
+S<[ B<-A> E<lt>start timeE<gt> ]>
+S<[ B<-B> E<lt>stop timeE<gt> ]>
+S<[ B<-h> ]>
+S<[ B<-i> E<lt>seconds per fileE<gt> ]>
 S<[ B<-r> ]>
+S<[ B<-s> E<lt>snaplenE<gt> ]>
+S<[ B<-t> E<lt>time adjustmentE<gt> ]>
+S<[ B<-S> E<lt>strict time adjustmentE<gt> ]>
+S<[ B<-T> E<lt>encapsulation typeE<gt> ]>
+S<[ B<-v> ]>
+I<infile>
+I<outfile>
+S<[ I<packet#>[-I<packet#>] ... ]>
+
+B<editcap>
+S< B<-d> > |
+S< B<-D> E<lt>dup windowE<gt> > |
+S< B<-w> E<lt>dup time windowE<gt> >
 S<[ B<-v> ]>
-S<[ B<-h> ]>
 I<infile>
 I<outfile>
-S<[ I<record#> ... ]>
 
 =head1 DESCRIPTION
 
-B<Editcap> is a program that reads a saved capture file and writes some
-or all of the packets in that capture file to another capture file.
-B<Editcap> knows how to read B<libpcap>
-capture files, including those of B<tcpdump>.  In addition, B<Editcap> can
-read capture files from B<snoop> (including B<Shomiti>) and B<atmsnoop>,
-B<LanAlyzer>, uncompressed B<Sniffer>, Microsoft B<Network Monitor>,
-AIX's B<iptrace>, B<NetXray>, B<Sniffer Pro>, B<RADCOM>'s WAN/LAN
-analyzer, B<Lucent/Ascend> router debug output, HP-UX's B<nettl>, and
-the dump output from B<Toshiba's> ISDN routers.  There is no need to
-tell B<Editcap> what type of file you are reading; it will determine the
-file type by itself.  B<Editcap> is also capable of reading any of these
-file formats if they are compressed using gzip.  B<Editcap> recognizes
-this directly from the file; the '.gz' extension is not required for
-this purpose.
-
-By default, it writes the capture file in B<libpcap> format, and writes
-all of the packets in the capture file to the output file.  The B<-F>
-flag can be used to specify the format in which to write the capture
-file; it can write the file in B<libpcap> format (standard B<libpcap>
-format, a modified format used by some patched versions of B<libpcap>,
-or the format used by Red Hat Linux 6.1), B<snoop> format, uncompressed
-B<Sniffer> format, Microsoft B<Network Monitor> 1.x format, and the
-format used by Windows-based versions of the B<Sniffer> software.
-
-A list of packet numbers can be specified on the command line; the
-packets with those numbers will I<not> be written to the capture file,
-unless the B<-r> flag is specified, in which case I<only> those packets
+B<Editcap> is a program that reads some or all of the captured packets from the 
+I<infile>, optionally converts them in various ways and writes the 
+resulting packets to the capture I<outfile> (or outfiles). 
+
+By default, it reads all packets from the I<infile> and writes them to the 
+I<outfile> in libpcap file format.
+
+An optional list of packet numbers can be specified on the command tail; 
+individual packet numbers separated by whitespace and/or ranges of packet
+numbers can be specified as I<start>-I<end>, referring to all packets from
+I<start> to I<end>.  By default the selected packets with those numbers will
+I<not> be written to the capture file.  If the B<-r> flag is specified, the
+whole packet selection is reversed; in that case I<only> the selected packets
 will be written to the capture file.
 
-If the B<-T> flag, the encapsulation type of the output capture file
-will be forced to the specified type, rather than being the type
-appropriate to the encapsulation type of the input capture file.
+B<Editcap> can also be used to remove duplicate packets.  Several different
+options (B<-d>, B<-D> and B<-w>) are used to control the packet window
+or relative time window to be used for duplicate comparison.
+
+B<Editcap> is able to detect, read and write the same capture files that 
+are supported by B<Wireshark>.
+The input file doesn't need a specific filename extension; the file 
+format and an optional gzip compression will be automatically detected.
+Near the beginning of the DESCRIPTION section of wireshark(1) or
+L<http://www.wireshark.org/docs/man-pages/wireshark.html>
+is a detailed description of the way B<Wireshark> handles this, which is
+the same way B<Editcap> handles this.
+
+B<Editcap> can write the file in several output formats. The B<-F>
+flag can be used to specify the format in which to write the capture
+file; B<editcap -F> provides a list of the available output formats.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -F
+=item -c  E<lt>packets per fileE<gt>
+
+Splits the packet output to different files based on uniform packet counts
+with a maximum of <packets per file> each. Each output file will 
+be created with a suffix -nnnnn, starting with 00000. If the specified 
+number of packets is written to the output file, the next output file is 
+opened. The default is to use a single output file.
+
+=item -C  E<lt>choplenE<gt>
+
+Sets the chop length to use when writing the packet data. Each packet is
+chopped by a few <choplen> bytes of data. Positive values chop at the packet
+beginning while negative values chop at the packet end.
+
+This is useful for chopping headers for decapsulation of an entire capture or
+in the rare case that the conversion between two file formats leaves some random
+bytes at the end of each packet.
+
+=item -d
+
+Attempts to remove duplicate packets.  The length and MD5 hash of the 
+current packet are compared to the previous four (4) packets.  If a 
+match is found, the current packet is skipped.  This option is equivalent
+to using the option B<-D 5>.
+
+=item -D  E<lt>dup windowE<gt>
+
+Attempts to remove duplicate packets.  The length and MD5 hash of the
+current packet are compared to the previous <dup window> - 1 packets.
+If a match is found, the current packet is skipped.
+
+The use of the option B<-D 0> combined with the B<-v> option is useful
+in that each packet's Packet number, Len and MD5 Hash will be printed
+to standard out.  This verbose output (specifically the MD5 hash strings)
+can be useful in scripts to identify duplicate packets across trace
+files.
+
+The <dup window> is specified as an integer value between 0 and 1000000 (inclusive).
+
+NOTE: Specifying large <dup window> values with large tracefiles can
+result in very long processing times for B<editcap>.
+
+=item -w  E<lt>dup time windowE<gt>
+
+Attempts to remove duplicate packets.  The current packet's arrival time
+is compared with up to 1000000 previous packets.  If the packet's relative
+arrival time is I<less than or equal to> the <dup time window> of a previous packet
+and the packet length and MD5 hash of the current packet are the same then
+the packet to skipped.  The duplicate comparison test stops when
+the current packet's relative arrival time is greater than <dup time window>.
+
+The <dup time window> is specified as I<seconds>[I<.fractional seconds>].
+
+The [.fractional seconds] component can be specified to nine (9) decimal
+places (billionths of a second) but most typical trace files have resolution
+to six (6) decimal places (millionths of a second).
+
+NOTE: Specifying large <dup time window> values with large tracefiles can
+result in very long processing times for B<editcap>.
+
+NOTE: The B<-w> option assumes that the packets are in chronological order.  
+If the packets are NOT in chronological order then the B<-w> duplication 
+removal option may not identify some duplicates.
+
+=item -E  E<lt>error probabilityE<gt>
+
+Sets the probability that bytes in the output file are randomly changed.
+B<Editcap> uses that probability (between 0.0 and 1.0 inclusive) 
+to apply errors to each data byte in the file.  For instance, a 
+probability of 0.02 means that each byte has a 2% chance of having an error.
+
+This option is meant to be used for fuzz-testing protocol dissectors.
+
+=item -F  E<lt>file formatE<gt>
 
 Sets the file format of the output capture file.
+B<Editcap> can write the file in several formats, B<editcap -F> 
+provides a list of the available output formats. The default
+is the B<libpcap> format.
 
-=item -T
+=item -W  E<lt>file format optionE<gt>
 
-Sets the packet encapsulation type of the output capture file.
+Save extra information in the file if the format supports it. For
+example,
+
+  -F pcapng -W n
+
+will save host name resolution records along with captured packets.
+
+Future versions of Wireshark may automatically change the capture format to
+B<pcapng> as needed.
+
+The argument is a string that may contain the following letter:
+
+B<n> write network address resolution information (pcapng only)
+
+=item -H  E<lt>input "hosts" fileE<gt>
+
+Read a list of address to host name mappings and include the result in
+the output file. Implies B<-W n>.
+
+The input file format is described at
+L<http://en.wikipedia.org/wiki/Hosts_%28file%29>.
+
+=item -A  E<lt>start timeE<gt>
+
+Saves only the packets whose timestamp is on or after start time.
+The time is given in the following format YYYY-MM-DD HH:MM:SS
+
+=item -B  E<lt>stop timeE<gt>
+
+Saves only the packets whose timestamp is before stop time.
+The time is given in the following format YYYY-MM-DD HH:MM:SS
+
+=item -h
+
+Prints the version and options and exits.
+
+=item -i  E<lt>seconds per fileE<gt>
+
+Splits the packet output to different files based on uniform time intervals
+using a maximum interval of <seconds per file> each. Each output file will 
+be created with a suffix -nnnnn, starting with 00000. If packets for the specified 
+time interval are written to the output file, the next output file is 
+opened. The default is to use a single output file.
 
 =item -r
 
+Reverse the packet selection.
 Causes the packets whose packet numbers are specified on the command
-line to be written to the output capture file, and no other packets to
-be written to the output capture file.
+line to be written to the output capture file, instead of discarding them.
+
+=item -s  E<lt>snaplenE<gt>
+
+Sets the snapshot length to use when writing the data.
+If the B<-s> flag is used to specify a snapshot length, packets in the
+input file with more captured data than the specified snapshot length
+will have only the amount of data specified by the snapshot length
+written to the output file.  
+
+This may be useful if the program that is
+to read the output file cannot handle packets larger than a certain size
+(for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
+appear to reject Ethernet packets larger than the standard Ethernet MTU,
+making them incapable of handling gigabit Ethernet captures if jumbo
+packets were used).
+
+=item -t  E<lt>time adjustmentE<gt>
+
+Sets the time adjustment to use on selected packets.
+If the B<-t> flag is used to specify a time adjustment, the specified
+adjustment will be applied to all selected packets in the capture file.
+The adjustment is specified as [-]I<seconds>[I<.fractional seconds>].
+For example, B<-t> 3600 advances the timestamp on selected packets by one
+hour while B<-t> -0.5 reduces the timestamp on selected packets by
+one-half second.  
+
+This feature is useful when synchronizing dumps
+collected on different machines where the time difference between the
+two machines is known or can be estimated.
+
+=item -S  E<lt>strict time adjustmentE<gt>
+
+Time adjust selected packets to insure strict chronological order. 
+
+The <strict time adjustment> value represents relative seconds
+specified as [-]I<seconds>[I<.fractional seconds>].
+
+As the capture file is processed each packet's absolute time is 
+I<possibly> adjusted to be equal to or greater than the previous 
+packet's absolute timestamp depending on the <strict time 
+adjustment> value.  
+
+If <strict time adjustment> value is 0 or greater (e.g. 0.000001) 
+then B<only> packets with a timestamp less than the previous packet 
+will adjusted.  The adjusted timestamp value will be set to be 
+equal to the timestamp value of the previous packet plus the value 
+of the <strict time adjustment> value.  A <strict time adjustment> 
+value of 0 will adjust the minimum number of timestamp values 
+necessary to insure that the resulting capture file is in 
+strict chronological order.
+
+If <strict time adjustment> value is specified as a 
+negative value, then the timestamp values of B<all> 
+packets will be adjusted to be equal to the timestamp value 
+of the previous packet plus the absolute value of the 
+<lt>strict time adjustment<gt> value. A <strict time
+adjustment> value of -0 will result in all packets
+having the timestamp value of the first packet.
+
+This feature is useful when the trace file has an occasional
+packet with a negative delta time relative to the previous 
+packet.
+
+=item -T  E<lt>encapsulation typeE<gt>
+
+Sets the packet encapsulation type of the output capture file.
+If the B<-T> flag is used to specify an encapsulation type, the
+encapsulation type of the output capture file will be forced to the
+specified type. 
+B<editcap -T> provides a list of the available types. The default
+type is the one appropriate to the encapsulation type of the input 
+capture file.
+
+Note: this merely
+forces the encapsulation type of the output file to be the specified
+type; the packet headers of the packets will not be translated from the
+encapsulation type of the input capture file to the specified
+encapsulation type (for example, it will not translate an Ethernet
+capture to an FDDI capture if an Ethernet capture is read and 'B<-T
+fddi>' is specified). If you need to remove/add headers from/to a
+packet, you will need od(1)/text2pcap(1).
 
 =item -v
 
-Causes B<editcap> to print a number of messages while it's working.
+Causes B<editcap> to print verbose messages while it's working.
 
-=item -h
+Use of B<-v> with the de-duplication switches of B<-d>, B<-D> or B<-w>
+will cause all MD5 hashes to be printed whether the packet is skipped
+or not.
 
-Prints the version and options and exits.
+=back
+
+=head1 EXAMPLES
+
+To see more detailed description of the options use:
+
+    editcap -h
+
+To shrink the capture file by truncating the packets at 64 bytes and writing it as Sun snoop file use:
+
+    editcap -s 64 -F snoop capture.pcap shortcapture.snoop
+
+To delete packet 1000 from the capture file use:
+
+    editcap capture.pcap sans1000.pcap 1000
+
+To limit a capture file to packets from number 200 to 750 (inclusive) use:
+
+    editcap -r capture.pcap small.pcap 200-750
+
+To get all packets from number 1-500 (inclusive) use:
+
+    editcap -r capture.pcap first500.pcap 1-500
+
+or
+
+    editcap capture.pcap first500.pcap 501-9999999
+
+To exclude packets 1, 5, 10 to 20 and 30 to 40 from the new file use:
+
+    editcap capture.pcap exclude.pcap 1 5 10-20 30-40
+
+To select just packets 1, 5, 10 to 20 and 30 to 40 for the new file use:
+
+    editcap -r capture.pcap select.pcap 1 5 10-20 30-40
+
+To remove duplicate packets seen within the prior four frames use:
+
+    editcap -d capture.pcap dedup.pcap
+
+To remove duplicate packets seen within the prior 100 frames use:
+
+    editcap -D 101 capture.pcap dedup.pcap
+
+To remove duplicate packets seen I<equal to or less than> 1/10th of a second:
+
+    editcap -w 0.1 capture.pcap dedup.pcap
+
+To display the MD5 hash for all of the packets (and NOT generate any
+real output file):
+
+    editcap -v -D 0 capture.pcap /dev/null
+
+or on Windows systems
+
+    editcap -v -D 0 capture.pcap NUL
+
+To advance the timestamps of each packet forward by 3.0827 seconds:
+
+    editcap -t 3.0827 capture.pcap adjusted.pcap
+
+To insure all timestamps are in strict chronological order:
+
+    editcap -S 0 capture.pcap adjusted.pcap
+
+To introduce 5% random errors in a capture file use:
+
+=over 4
+
+  editcap -E 0.05 capture.pcap capture_error.pcap
+
+=back
 
 =head1 SEE ALSO
 
-L<tcpdump(8)>, L<pcap(3)>, L<ethereal(1)>
+tcpdump(8), pcap(3), wireshark(1), tshark(1), mergecap(1), dumpcap(1),
+capinfos(1), text2pcap(1), od(1)
 
 =head1 NOTES
 
-B<Editcap> is part of the B<Ethereal> distribution.  The latest version
-of B<Ethereal> can be found at B<http://ethereal.zing.org>.
+B<Editcap> is part of the B<Wireshark> distribution.  The latest version
+of B<Wireshark> can be found at L<http://www.wireshark.org>.
+
+HTML versions of the Wireshark project man pages are available at:
+L<http://www.wireshark.org/docs/man-pages>.
 
 =head1 AUTHORS
 
   Original Author
   -------- ------
-  Richard Sharpe           <sharpe@ns.aus.com>
+  Richard Sharpe           <sharpe[AT]ns.aus.com>
 
 
   Contributors
   ------------
-  Guy Harris               <guy@alum.mit.edu>
+  Guy Harris               <guy[AT]alum.mit.edu>
+  Ulf Lamping              <ulf.lamping[AT]web.de>