doc/editcap.pod

   1
   2 =head1 NAME
   3
   4 editcap - Edit and/or translate the format of capture files
   5
   6 =head1 SYNOPSYS
   7
   8 B<editcap>
   9 S<[ B<-c> E<lt>packets per fileE<gt> ]>
  10 S<[ B<-C> E<lt>choplenE<gt> ]>
  11 S<[ B<-d> ]>
  12 S<[ B<-E> E<lt>error probabilityE<gt> ]>
  13 S<[ B<-F> E<lt>file formatE<gt> ]>
  14 S<[ B<-A> E<lt>start timeE<gt> ]>
  15 S<[ B<-B> E<lt>stop timeE<gt> ]>
  16 S<[ B<-h> ]>
  17 S<[ B<-r> ]>
  18 S<[ B<-s> E<lt>snaplenE<gt> ]>
  19 S<[ B<-t> E<lt>time adjustmentE<gt> ]>
  20 S<[ B<-T> E<lt>encapsulation typeE<gt> ]>
  21 S<[ B<-v> ]>
  22 I<infile>
  23 I<outfile>
  24 S<[ I<packet#>[-I<packet#>] ... ]>
  25
  26 =head1 DESCRIPTION
  27
  28 B<Editcap> is a program that reads some or all of the captured packets from the
  29 I<infile>, optionally converts them in various ways and writes the
  30 resulting packets to the capture I<outfile> (or outfiles).
  31
  32 By default, it reads all packets from the I<infile> and writes them to the
  33 I<outfile> in libpcap file format.
  34
  35 A list of packet numbers can be specified on the command line; ranges of
  36 packet numbers can be specified as I<start>-I<end>, referring to all packets
  37 from I<start> to I<end>.
  38 The selected packets with those numbers will I<not> be written to the
  39 capture file.
  40 If the B<-r> flag is specified, the whole packet selection is reversed;
  41 in that case I<only> the selected packets will be written to the capture file.
  42
  43 B<Editcap> is able to detect, read and write the same capture files that
  44 are supported by B<Wireshark>.
  45 The input file doesn't need a specific filename extension; the file
  46 format and an optional gzip compression will be automatically detected.
  47 Near the beginning of the DESCRIPTION section of wireshark(1) or
  48 L<http://www.wireshark.org/docs/man-pages/wireshark.html>
  49 is a detailed description of the way B<Wireshark> handles this, which is
  50 the same way B<Editcap> handles this.
  51
  52 B<Editcap> can write the file in several output formats. The B<-F>
  53 flag can be used to specify the format in which to write the capture
  54 file, B<editcap -F> provides a list of the available output formats.
  55
  56 =head1 OPTIONS
  57
  58 =over 4
  59
  60 =item -c  E<lt>packets per fileE<gt>
  61
  62 Sets the maximum number of packets per output file. Each output file will
  63 be created with a suffix -nnnnn, starting with 00000. If the specified
  64 number of packets are written to the output file, the next output file is
  65 opened. The default is to use a single output file.
  66
  67 =item -C  E<lt>choplenE<gt>
  68
  69 Sets the chop length to use when writing the packet data.
  70 Each packet is chopped at the packet end by a few <choplen> bytes of data.
  71
  72 This is useful in the rare case that the conversion between two file
  73 formats leaves some random bytes at the end of each packet.
  74
  75 =item -d
  76
  77 Attempts to remove duplicate packets.  The length and MD5 sum of the
  78 current packet are compared to the previous four packets.  If a match
  79 is found, the packet is skipped.
  80
  81 =item -E  E<lt>error probabilityE<gt>
  82
  83 Sets the probabilty that bytes in the output file are randomly changed.
  84 B<Editcap> uses that probability (between 0.0 and 1.0 inclusive)
  85 to apply errors to each data byte in the file.  For instance, a
  86 probability of 0.02 means that each byte has a 2% chance of having an error.
  87
  88 This option is meant to be used for fuzz-testing protocol dissectors.
  89
  90 =item -F  E<lt>file formatE<gt>
  91
  92 Sets the file format of the output capture file.
  93 B<Editcap> can write the file in several formats, B<editcap -F>
  94 provides a list of the available output formats. The default
  95 is the B<libpcap> format.
  96
  97 =item -A  E<lt>start timeE<gt>
  98
  99 Saves only the packets whose timestamp is on or after start time.
 100 The time is given in the following format YYYY-MM-DD HH:MM:SS
 101
 102 =item -B  E<lt>stop timeE<gt>
 103
 104 Saves only the packets whose timestamp is on or before stop time.
 105 The time is given in the following format YYYY-MM-DD HH:MM:SS
 106
 107 =item -h
 108
 109 Prints the version and options and exits.
 110
 111 =item -r
 112
 113 Reverse the packet selection.
 114 Causes the packets whose packet numbers are specified on the command
 115 line to be written to the output capture file, instead of discarding them.
 116
 117 =item -s  E<lt>snaplenE<gt>
 118
 119 Sets the snapshot length to use when writing the data.
 120 If the B<-s> flag is used to specify a snapshot length, packets in the
 121 input file with more captured data than the specified snapshot length
 122 will have only the amount of data specified by the snapshot length
 123 written to the output file.
 124
 125 This may be useful if the program that is
 126 to read the output file cannot handle packets larger than a certain size
 127 (for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
 128 appear to reject Ethernet packets larger than the standard Ethernet MTU,
 129 making them incapable of handling gigabit Ethernet captures if jumbo
 130 packets were used).
 131
 132 =item -t  E<lt>time adjustmentE<gt>
 133
 134 Sets the time adjustment to use on selected packets.
 135 If the B<-t> flag is used to specify a time adjustment, the specified
 136 adjustment will be applied to all selected packets in the capture file.
 137 The adjustment is specified as [-]I<seconds>[I<.fractional seconds>].
 138 For example, B<-t> 3600 advances the timestamp on selected packets by one
 139 hour while B<-t> -0.5 reduces the timestamp on selected packets by
 140 one-half second.
 141
 142 This feature is useful when synchronizing dumps
 143 collected on different machines where the time difference between the
 144 two machines is known or can be estimated.
 145
 146 =item -T  E<lt>encapsulation typeE<gt>
 147
 148 Sets the packet encapsulation type of the output capture file.
 149 If the B<-T> flag is used to specify an encapsulation type, the
 150 encapsulation type of the output capture file will be forced to the
 151 specified type.
 152 B<editcap -T> provides a list of the available types. The default
 153 type is the one appropriate to the encapsulation type of the input
 154 capture file.
 155
 156 Note: this merely
 157 forces the encapsulation type of the output file to be the specified
 158 type; the packet headers of the packets will not be translated from the
 159 encapsulation type of the input capture file to the specified
 160 encapsulation type (for example, it will not translate an Ethernet
 161 capture to an FDDI capture if an Ethernet capture is read and 'B<-T
 162 fddi>' is specified). If you need to remove/add headers from/to a
 163 packet, you will need od(1)/text2pcap(1).
 164
 165 =item -v
 166
 167 Causes B<editcap> to print verbose messages while it's working.
 168
 169 =back
 170
 171 =head1 EXAMPLES
 172
 173 To see more detailed description of the options use:
 174
 175     editcap -h
 176
 177 To shrink the capture file by truncating the packets at 64 bytes and writing it as Sun snoop file use:
 178
 179     editcap -s 64 -F snoop capture.pcap shortcapture.snoop
 180
 181 To delete packet 1000 from the capture file use:
 182
 183     editcap capture.pcap sans1000.pcap 1000
 184
 185 To limit a capture file to packets from number 200 to 750 (inclusive) use:
 186
 187     editcap -r capture.pcap small.pcap 200-750
 188
 189 To get all packets from number 1-500 (inclusive) use:
 190
 191     editcap -r capture.pcap 500.pcap 1-500
 192
 193 or
 194
 195     editcap capture.pcap 500.pcap 501-9999999
 196
 197 To filter out packets 10 to 20 and 30 to 40 into a new file use:
 198
 199     editcap capture.pcap selection.pcap 10-20 30-40
 200
 201 To introduce 5% random errors in a capture file use:
 202
 203 =over 4
 204
 205   editcap -E 0.05 capture.pcap capture_error.pcap
 206
 207 =back
 208
 209 =head1 SEE ALSO
 210
 211 tcpdump(8), pcap(3), wireshark(1), tshark(1), mergecap(1), dumpcap(1),
 212 capinfos(1), text2pcap(1), od(1)
 213
 214 =head1 NOTES
 215
 216 B<Editcap> is part of the B<Wireshark> distribution.  The latest version
 217 of B<Wireshark> can be found at L<http://www.wireshark.org>.
 218
 219 HTML versions of the Wireshark project man pages are available at:
 220 L<http://www.wireshark.org/docs/man-pages>.
 221
 222 =head1 AUTHORS
 223
 224   Original Author
 225   -------- ------
 226   Richard Sharpe           <sharpe[AT]ns.aus.com>
 227
 228
 229   Contributors
 230   ------------
 231   Guy Harris               <guy[AT]alum.mit.edu>
 232   Ulf Lamping              <ulf.lamping[AT]web.de>