X-Git-Url: http://git.samba.org/samba.git/?p=obnox%2Fwireshark%2Fwip.git;a=blobdiff_plain;f=doc%2Feditcap.pod;h=7101ea7d005613d3fe1d0286d55479ec05d81c91;hp=e0a25e92e38aca04d24f1e690b84eb2f7fe6486c;hb=06cb0e53ac14d88063811f325e67bd0d692db30a;hpb=9efaafed79686c732075e375c86e293b07940e35 diff --git a/doc/editcap.pod b/doc/editcap.pod index e0a25e92e3..7101ea7d00 100644 --- a/doc/editcap.pod +++ b/doc/editcap.pod @@ -3,267 +3,332 @@ editcap - Edit and/or translate the format of capture files -=head1 SYNOPSYS +=head1 SYNOPSIS B -S<[ B<-E> error probability]> -S<[ B<-F> file format ]> +S<[ B<-c> Epackets per fileE ]> +S<[ B<-C> EchoplenE ]> +S<[ B<-E> Eerror probabilityE ]> +S<[ B<-F> Efile formatE ]> +S<[ B<-A> Estart timeE ]> +S<[ B<-B> Estop timeE ]> S<[ B<-h> ]> +S<[ B<-i> Eseconds per fileE ]> S<[ B<-r> ]> -S<[ B<-s> snaplen ]> -S<[ B<-t> time adjustment ]> -S<[ B<-T> encapsulation type ]> +S<[ B<-s> EsnaplenE ]> +S<[ B<-t> Etime adjustmentE ]> +S<[ B<-S> Estrict time adjustmentE ]> +S<[ B<-T> Eencapsulation typeE ]> +S<[ B<-v> ]> +I +I +S<[ I[-I] ... ]> + +B +S< B<-d> > | +S< B<-D> Edup windowE > | +S< B<-w> Edup time windowE > S<[ B<-v> ]> I I -S<[ I[-I] ... ]> =head1 DESCRIPTION -B 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 knows how to read B capture files, including those -of B, B, and other tools that write captures in that -format. +B is a program that reads some or all of the captured packets from the +I, optionally converts them in various ways and writes the +resulting packets to the capture I (or outfiles). + +By default, it reads all packets from the I and writes them to the +I 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-I, referring to all packets from +I to I. By default the selected packets with those numbers will +I be written to the capture file. If the B<-r> flag is specified, the +whole packet selection is reversed; in that case I the selected packets +will be written to the capture file. + +B 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 is able to detect, read and write the same capture files that +are supported by B. +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 +is a detailed description of the way B handles this, which is +the same way B handles this. + +B 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 provides a list of the available output formats. -B can read / import the following file formats: +=head1 OPTIONS =over 4 -=item * -libpcap/WinPcap, tcpdump and various other tools using tcpdump's capture format +=item -c Epackets per fileE -=item * -B and B +Splits the packet output to different files based on uniform packet counts +with a maximum of 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 * -Shomiti/Finisar B captures +=item -C EchoplenE -=item * -Novell B captures +Sets the chop length to use when writing the packet data. +Each packet is chopped at the packet end by a few bytes of data. -=item * -Microsoft B captures +This is useful in the rare case that the conversion between two file +formats leaves some random bytes at the end of each packet. -=item * -AIX's B captures +=item -d -=item * -Cinco Networks B captures +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 * -Network Associates Windows-based B captures +=item -D Edup windowE -=item * -Network General/Network Associates DOS-based B (compressed or uncompressed) captures +Attempts to remove duplicate packets. The length and MD5 hash of the +current packet are compared to the previous - 1 packets. +If a match is found, the current packet is skipped. -=item * -AG Group/WildPackets B/B/B/B/B captures +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. -=item * -B's WAN/LAN analyzer captures +The is specified as an integer value between 0 and 1000000 (inclusive). -=item * -Network Instruments B version 9 captures +NOTE: Specifying large values with large tracefiles can +result in very long processing times for B. -=item * -B router debug output +=item -w Edup time windowE -=item * -files from HP-UX's B +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 the 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 . -=item * -B ISDN routers dump output +The is specified as I[I<.fractional seconds>]. -=item * -the output from B from the ISDN4BSD project +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). -=item * -traces from the B USB S0. +NOTE: Specifying large values with large tracefiles can +result in very long processing times for B. -=item * -the output in B format from the Cisco Secure Intrusion Detection System +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 * -B (pppdump format) +=item -E Eerror probabilityE -=item * -the output from VMS's B/B/B utilities +Sets the probability that bytes in the output file are randomly changed. +B 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. -=item * -the text output from the B VMS utility +This option is meant to be used for fuzz-testing protocol dissectors. -=item * -Visual Networks' B traffic capture +=item -F Efile formatE -=item * -the output from B L2 debug +Sets the file format of the output capture file. +B can write the file in several formats, B +provides a list of the available output formats. The default +is the B format. -=item * -the output from Accellent's B<5Views> LAN agents +=item -A Estart timeE -=item * -Endace Measurement Systems' ERF format captures +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 * -Linux Bluez Bluetooth stack B traces +=item -B Estop timeE -=back +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 -There is no need to tell B what type of -file you are reading; it will determine the file type by itself. -B is also capable of reading any of these file formats if they -are compressed using gzip. B recognizes this directly from the -file; the '.gz' extension is not required for this purpose. +Prints the version and options and exits. -By default, it writes the capture file in B 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 format (standard B -format, a modified format used by some patched versions of B, -the format used by Red Hat Linux 6.1, or the format used by SuSE Linux -6.3), B format, uncompressed B format, Microsoft -B 1.x format, the format used by Windows-based versions -of the B software, and the format used by Visual Networks' -software. - -A list of packet numbers can be specified on the command line; the -packets with those numbers will I be written to the capture file, -unless the B<-r> flag is specified, in which case I those packets -will be written to the capture file. Ranges of packet numbers can be -specified as I-I, referring to all packets from I to -I (removing them all if B<-r> isn't specified, including them all -if B<-r> is specified). - -If the B<-s> flag is used to specify a snapshot length, frames in the +=item -i Eseconds per fileE + +Splits the packet output to different files based on uniform time intervals +using a maximum interval of 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, instead of discarding them. + +=item -s EsnaplenE + +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 +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 frames larger than the standard Ethernet MTU, +appear to reject Ethernet packets larger than the standard Ethernet MTU, making them incapable of handling gigabit Ethernet captures if jumbo -frames were used). +packets were used). + +=item -t Etime adjustmentE +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 frames in the capture file. +adjustment will be applied to all selected packets in the capture file. The adjustment is specified as [-]I[I<.fractional seconds>]. -For example, B<-t> 3600 advances the timestamp on selected frames by one -hour while B<-t> -0.5 reduces the timestamp on selected frames by -one-half second. This feature is useful when synchronizing dumps +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. -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, rather than being the type appropriate to the -encapsulation type of the input capture file. Note that 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). +=item -S Estrict time adjustmentE -If the B<-E> flag is used to specify a probability (between 0.0 and -1.0 inclusive), Editcap uses that probability 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. +Time adjust selected packets to insure strict chronological order. -=head1 OPTIONS +The value represents relative seconds +specified as [-]I[I<.fractional seconds>]. -=over 4 +As the capture file is processed each packet's absolute time is +I adjusted to be equal to or greater than the previous +packet's absolute timestamp depending on the value. -=item -E +If value is 0 or greater (e.g. 0.000001) +then B 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 value. A +value of 0 will adjust the minimum number of timestamp values +necessary to insure that the resulting capture file is in +strict chronological order. -Sets the probabilty that bytes in the output file are randomly changed. +If value is specified as a +negative value, then the timestamp values of B +packets will be adjusted to be equal to the timestamp value +of the previous packet plus the absolute value of the +strict time adjustment value. A value of -0 will result in all packets +having the timestamp value of the first packet. -=item -F - -Sets the file format of the output capture file. +This feature is useful when the trace file has an occasional +packet with a negative delta time relative to the previous +packet. -=item -T +=item -T Eencapsulation typeE 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 provides a list of the available types. The default +type is the one appropriate to the encapsulation type of the input +capture file. -=item -r - -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. +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 to print a number of messages while it's working. +Causes B to print verbose messages while it's working. -=item -s +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. -Sets the snapshot length to use when writing the data. +=back -=item -t +=head1 EXAMPLES -Sets the time adjustment to use on selected frames. +To see more detailed description of the options use: -=item -h + editcap -h -Prints the version and options and exits. +To shrink the capture file by truncating the packets at 64 bytes and writing it as Sun snoop file use: -=back + editcap -s 64 -F snoop capture.pcap shortcapture.snoop -=head1 EXAMPLES +To delete packet 1000 from the capture file use: -To see more detailed description of the options use: + editcap capture.pcap sans1000.pcap 1000 -=over 4 +To limit a capture file to packets from number 200 to 750 (inclusive) use: - editcap -h + editcap -r capture.pcap small.pcap 200-750 -=back +To get all packets from number 1-500 (inclusive) use: -To shrink the capture file by truncating the packets at 64 bytes and writing it as Sun snoop file use: + editcap -r capture.pcap first500.pcap 1-500 -=over 4 +or - editcap -s 64 -F snoop capture.pcap shortcapture.snoop + editcap capture.pcap first500.pcap 501-9999999 -=back +To exclude packets 1, 5, 10 to 20 and 30 to 40 from the new file use: -To delete packet 1000 from the capture file use: + editcap capture.pcap exclude.pcap 1 5 10-20 30-40 -=over 4 +To select just packets 1, 5, 10 to 20 and 30 to 40 for the new file use: - editcap capture.pcap sans1000.pcap 1000 + editcap -r capture.pcap select.pcap 1 5 10-20 30-40 -=back +To remove duplicate packets seen within the prior four frames use: -To limit a capture file to packets from number 200 to 750 (inclusive) use: + editcap -d capture.pcap dedup.pcap -=over 4 +To remove duplicate packets seen within the prior 100 frames use: - editcap -r capture.pcap small.pcap 200-750 + editcap -D 101 capture.pcap dedup.pcap -=back +To remove duplicate packets seen I 1/10th of a second: -To get all packets from number 1-500 (inclusive) use: + editcap -w 0.1 capture.pcap dedup.pcap -=over 4 +To display the MD5 hash for all of the packets (and NOT generate any +real output file): - editcap -r capture.pcap 500.pcap 1-500 + editcap -v -D 0 capture.pcap /dev/null -or +or on Windows systems - editcap capture.pcap 500.pcap 501-9999999 + editcap -v -D 0 capture.pcap NUL -=back +To advance the timestamps of each packet forward by 3.0827 seconds: -To filter out packets 10 to 20 and 30 to 40 into a new file use: + editcap -t 3.0827 capture.pcap adjusted.pcap -=over 4 - - editcap capture.pcap selection.pcap 10-20 30-40 +To insure all timestamps are in strict chronological order: -=back + editcap -S 0 capture.pcap adjusted.pcap To introduce 5% random errors in a capture file use: @@ -275,12 +340,16 @@ To introduce 5% random errors in a capture file use: =head1 SEE ALSO -I, I, I, I +tcpdump(8), pcap(3), wireshark(1), tshark(1), mergecap(1), dumpcap(1), +capinfos(1), text2pcap(1), od(1) =head1 NOTES -B is part of the B distribution. The latest version -of B can be found at B. +B is part of the B distribution. The latest version +of B can be found at L. + +HTML versions of the Wireshark project man pages are available at: +L. =head1 AUTHORS @@ -292,3 +361,4 @@ of B can be found at B. Contributors ------------ Guy Harris + Ulf Lamping