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