X-Git-Url: http://git.samba.org/samba.git/?p=obnox%2Fwireshark%2Fwip.git;a=blobdiff_plain;f=doc%2Feditcap.pod;h=deea34ea7644db765fc0beacab99dcdd7f4bdadf;hp=138835f8e1c8a85e78a5c55cae0aa559b8db8fce;hb=ee0f54a3e4a94261570763838b4994c320552b50;hpb=b0f0f9b6a73e88ccb5e9f3d663c677f37f93be31 diff --git a/doc/editcap.pod b/doc/editcap.pod index 138835f8e1..deea34ea76 100644 --- a/doc/editcap.pod +++ b/doc/editcap.pod @@ -3,26 +3,37 @@ editcap - Edit and/or translate the format of capture files -=head1 SYNOPSYS +=head1 SYNOPSIS B S<[ B<-c> Epackets per fileE ]> S<[ B<-C> EchoplenE ]> -S<[ B<-d> ]> S<[ B<-E> Eerror probabilityE ]> S<[ B<-F> Efile formatE ]> +S<[ B<-W> Efile format optionE]> +S<[ B<-H> Einput hosts file ]> 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> 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 + =head1 DESCRIPTION B is a program that reads some or all of the captured packets from the @@ -32,13 +43,17 @@ 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. -A list of packet numbers can be specified on the command line; ranges of -packet numbers can be specified as I-I, referring to all packets -from I to I. -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. +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. @@ -51,7 +66,7 @@ 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. +file; B provides a list of the available output formats. =head1 OPTIONS @@ -59,28 +74,71 @@ file, B provides a list of the available output formats. =item -c Epackets per fileE -Sets the maximum number of packets per output file. Each output file will +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 are written to the output file, the next output file is +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 EchoplenE -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. +Sets the chop length to use when writing the packet data. Each packet is +chopped by a few bytes of data. Positive values chop at the packet +beginning while negative values chop at the packet end. -This is useful in the rare case that the conversion between two file -formats leaves some random bytes at the end of each packet. +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 sum of the -current packet are compared to the previous four packets. If a match -is found, the packet is skipped. +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 Edup windowE + +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. + +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 is specified as an integer value between 0 and 1000000 (inclusive). + +NOTE: Specifying large values with large tracefiles can +result in very long processing times for B. + +=item -w Edup time windowE + +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 . + +The is specified as I[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 values with large tracefiles can +result in very long processing times for B. + +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 Eerror probabilityE -Sets the probabilty that bytes in the output file are randomly changed. +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. @@ -94,6 +152,30 @@ B can write the file in several formats, B provides a list of the available output formats. The default is the B format. +=item -W Efile format optionE + +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 as needed. + +The argument is a string that may contain the following letter: + +B write network address resolution information (pcapng only) + +=item -H Einput "hosts" fileE + +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. + =item -A Estart timeE Saves only the packets whose timestamp is on or after start time. @@ -101,13 +183,21 @@ The time is given in the following format YYYY-MM-DD HH:MM:SS =item -B Estop timeE -Saves only the packets whose timestamp is on or before stop time. +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 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. @@ -143,6 +233,39 @@ 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 Estrict time adjustmentE + +Time adjust selected packets to insure strict chronological order. + +The value represents relative seconds +specified as [-]I[I<.fractional seconds>]. + +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. + +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. + +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. + +This feature is useful when the trace file has an occasional +packet with a negative delta time relative to the previous +packet. + =item -T Eencapsulation typeE Sets the packet encapsulation type of the output capture file. @@ -166,6 +289,10 @@ packet, you will need od(1)/text2pcap(1). Causes B to print verbose messages while it's working. +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. + =back =head1 EXAMPLES @@ -188,15 +315,48 @@ To limit a capture file to packets from number 200 to 750 (inclusive) use: To get all packets from number 1-500 (inclusive) use: - editcap -r capture.pcap 500.pcap 1-500 + editcap -r capture.pcap first500.pcap 1-500 or - editcap capture.pcap 500.pcap 501-9999999 + 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 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 filter out packets 10 to 20 and 30 to 40 into a new file use: +To insure all timestamps are in strict chronological order: - editcap capture.pcap selection.pcap 10-20 30-40 + editcap -S 0 capture.pcap adjusted.pcap To introduce 5% random errors in a capture file use: