doc/mergecap.pod

   1
   2 =head1 NAME
   3
   4 mergecap - Merges two or more capture files into one
   5
   6 =head1 SYNOPSIS
   7
   8 B<mergecap>
   9 S<[ B<-a> ]>
  10 S<[ B<-F> E<lt>I<file format>E<gt> ]>
  11 S<[ B<-h> ]>
  12 S<[ B<-I> E<lt>I<IDB merge mode>E<gt> ]>
  13 S<[ B<-s> E<lt>I<snaplen>E<gt> ]>
  14 S<[ B<-v> ]>
  15 S<[ B<-V> ]>
  16 S<B<-w> E<lt>I<outfile>E<gt>|->
  17 E<lt>I<infile>E<gt> [E<lt>I<infile>E<gt> I<...>]
  18
  19 =head1 DESCRIPTION
  20
  21 B<Mergecap> is a program that combines multiple saved capture files into
  22 a single output file specified by the B<-w> argument.  B<Mergecap> knows
  23 how to read B<pcap> capture files, including those of B<tcpdump>,
  24 B<Wireshark>, and other tools that write captures in that format.
  25
  26 By default, B<Mergecap> writes the capture file in B<pcap> format, and writes
  27 all of the packets from the input capture files to the output file.
  28
  29 B<Mergecap> is able to detect, read and write the same capture files that
  30 are supported by B<Wireshark>.
  31 The input files don't need a specific filename extension; the file
  32 format and an optional gzip compression will be automatically detected.
  33 Near the beginning of the DESCRIPTION section of wireshark(1) or
  34 L<https://www.wireshark.org/docs/man-pages/wireshark.html>
  35 is a detailed description of the way B<Wireshark> handles this, which is
  36 the same way B<Mergecap> handles this.
  37
  38 B<Mergecap> can write the file in several output formats.
  39 The B<-F> flag can be used to specify the format in which to write the
  40 capture file, B<mergecap -F> provides a list of the available output
  41 formats.
  42
  43 Packets from the input files are merged in chronological order based on
  44 each frame's timestamp, unless the B<-a> flag is specified.  B<Mergecap>
  45 assumes that frames within a single capture file are already stored in
  46 chronological order.  When the B<-a> flag is specified, packets are
  47 copied directly from each input file to the output file, independent of
  48 each frame's timestamp.
  49
  50 The output file frame encapsulation type is set to the type of the input
  51 files if all input files have the same type.  If not all of the input
  52 files have the same frame encapsulation type, the output file type is
  53 set to WTAP_ENCAP_PER_PACKET.  Note that some capture file formats, most
  54 notably B<pcap>, do not currently support WTAP_ENCAP_PER_PACKET.
  55 This combination will cause the output file creation to fail.
  56
  57 =head1 OPTIONS
  58
  59 =over 4
  60
  61 =item -a
  62
  63 Causes the frame timestamps to be ignored, writing all packets from the
  64 first input file followed by all packets from the second input file.  By
  65 default, when B<-a> is not specified, the contents of the input files
  66 are merged in chronological order based on each frame's timestamp.
  67
  68 Note: when merging, B<mergecap> assumes that packets within a capture
  69 file are already in chronological order.
  70
  71 =item -F  E<lt>file formatE<gt>
  72
  73 Sets the file format of the output capture file. B<Mergecap> can write
  74 the file in several formats; B<mergecap -F> provides a list of the
  75 available output formats. The default is to use the file format of the
  76 first input file.
  77
  78 =item -h
  79
  80 Prints the version and options and exits.
  81
  82 =item -I  E<lt>IDB merge modeE<gt>
  83
  84 Sets the Interface Description Block (IDB) merge mode to use during merging.
  85 B<mergecap -I> provides a list of the available IDB merge modes.
  86
  87 Every input file has one or more IDBs, which describe the interface(s) the
  88 capture was performed on originally. This includes encapsulation type,
  89 interface name, etc. When mergecap merges multiple input files, it has to
  90 merge these IDBs somehow for the new merged output file. This flag controls
  91 how that is accomplished. The currently available modes are:
  92
  93  * 'B<none>': no merging of IDBs is performed, and instead all IDBs are
  94               copied to the merged output file.
  95  * 'B<all>':  IDBs are merged only if all input files have the same number
  96               of IDBs, and each IDB matches their respective entry in the
  97               other files. This is the default mode.
  98  * 'B<any>':  Any and all duplicate IDBs are merged into one IDB, regardless
  99               of what file they are in.
 100
 101 Note that an IDB is only considered a matching duplicate if it has the same
 102 encapsulation type, name, speed, time precision, comments, description, etc.
 103
 104 =item -s  E<lt>snaplenE<gt>
 105
 106 Sets the snapshot length to use when writing the data.
 107 If the B<-s> flag is used to specify a snapshot length, frames in the
 108 input file with more captured data than the specified snapshot length
 109 will have only the amount of data specified by the snapshot length
 110 written to the output file.  This may be useful if the program that is
 111 to read the output file cannot handle packets larger than a certain size
 112 (for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
 113 appear to reject Ethernet frames larger than the standard Ethernet MTU,
 114 making them incapable of handling gigabit Ethernet captures if jumbo
 115 frames were used).
 116
 117 =item -v
 118
 119 Causes B<mergecap> to print a number of messages while it's working.
 120
 121 =item -V
 122
 123 Print the version and exit.
 124
 125 =item -w  E<lt>outfileE<gt>|-
 126
 127 Sets the output filename. If the name is 'B<->', stdout will be used.
 128 This setting is mandatory.
 129
 130 =back
 131
 132 =head1 EXAMPLES
 133
 134 To merge two capture files together, 100 seconds apart use:
 135
 136     capinfos -aeS a.pcap b.pcap
 137
 138 (Let's suppose a.pcap starts at 1009932757 and b.pcap ends
 139 at 873660281. 1009932757 - 873660281 - 100 = 136272376
 140 seconds.)
 141
 142     editcap -t 136272376 b.pcap b-shifted.pcap
 143     mergecap -w compare.pcap a.pcap b-shifted.pcap
 144
 145 =head1 SEE ALSO
 146
 147 pcap(3), wireshark(1), tshark(1), dumpcap(1), editcap(1), text2pcap(1),
 148 pcap-filter(7) or tcpdump(8)
 149
 150 =head1 NOTES
 151
 152 B<Mergecap> is based heavily upon B<editcap> by Richard Sharpe
 153 <sharpe[AT]ns.aus.com> and Guy Harris <guy[AT]alum.mit.edu>.
 154
 155 B<Mergecap> is part of the B<Wireshark> distribution.  The latest version
 156 of B<Wireshark> can be found at L<https://www.wireshark.org>.
 157
 158 HTML versions of the Wireshark project man pages are available at:
 159 L<https://www.wireshark.org/docs/man-pages>.
 160
 161 =head1 AUTHORS
 162
 163   Original Author
 164   -------- ------
 165   Scott Renfro             <scott[AT]renfro.org>
 166
 167
 168   Contributors
 169   ------------
 170   Bill Guyton              <guyton[AT]bguyton.com>