doc/man_pages/mergecap.adoc

   1 include::../attributes.adoc[]
   2 = mergecap(1)
   3 :doctype: manpage
   4 :stylesheet: ws.css
   5 :linkcss:
   6 :copycss: {css_dir}/{stylesheet}
   7
   8 == NAME
   9
  10 mergecap - Merges two or more capture files into one
  11
  12 == SYNOPSIS
  13
  14 [manarg]
  15 *mergecap*
  16 [ *-a* ]
  17 [ *-F* <__file format__> ]
  18 [ *-I* <__IDB merge mode__> ]
  19 [ *-s* <__snaplen__> ]
  20 [ *-V* ]
  21 *-w* <__outfile__>|-
  22 <__infile__> [<__infile__> __...__]
  23
  24 [manarg]
  25 *mergecap*
  26 *-h|--help*
  27
  28 [manarg]
  29 *mergecap*
  30 *-v|--version*
  31
  32 == DESCRIPTION
  33
  34 *Mergecap* is a program that combines multiple saved capture files into
  35 a single output file specified by the *-w* argument.  *Mergecap* knows
  36 how to read *pcap* and *pcapng* capture files, including those of
  37 *tcpdump*, *Wireshark* and other tools that write captures in those
  38 formats.
  39
  40 By default, *Mergecap* writes the capture file in *pcapng* format, and
  41 writes all of the packets from the input capture files to the output file.
  42
  43 *Mergecap* is able to detect, read and write the same capture files that
  44 are supported by *Wireshark*.
  45 The input files don't need a specific filename extension; the file
  46 format and an optional gzip, zstd or lz4 compression will be automatically detected.
  47 Near the beginning of the DESCRIPTION section of xref:wireshark.html[wireshark](1) or
  48 https://www.wireshark.org/docs/man-pages/wireshark.html
  49 is a detailed description of the way *Wireshark* handles this, which is
  50 the same way *Mergecap* handles this.
  51
  52 *Mergecap* can write the file in several output formats.
  53 The *-F* flag can be used to specify the format in which to write the
  54 capture file, *mergecap -F* provides a list of the available output
  55 formats.
  56
  57 Packets from the input files are merged in chronological order based on
  58 each frame's timestamp, unless the *-a* flag is specified.  *Mergecap*
  59 assumes that frames within a single capture file are already stored in
  60 chronological order.  When the *-a* flag is specified, packets are
  61 copied directly from each input file to the output file, independent of
  62 each frame's timestamp.
  63
  64 The output file frame encapsulation type is set to the type of the input
  65 files if all input files have the same type.  If not all of the input
  66 files have the same frame encapsulation type, the output file type is
  67 set to WTAP_ENCAP_PER_PACKET.  Note that some capture file formats, most
  68 notably *pcap*, do not currently support WTAP_ENCAP_PER_PACKET.
  69 This combination will cause the output file creation to fail.
  70
  71 == OPTIONS
  72
  73 -a::
  74 +
  75 --
  76 Causes the frame timestamps to be ignored, writing all packets from the
  77 first input file followed by all packets from the second input file.  By
  78 default, when *-a* is not specified, the contents of the input files
  79 are merged in chronological order based on each frame's timestamp.
  80
  81 Note: when merging, *mergecap* assumes that packets within a capture
  82 file are already in chronological order.
  83 --
  84
  85 -F  <file format>::
  86 +
  87 --
  88 Sets the file format of the output capture file. *Mergecap* can write
  89 the file in several formats; *mergecap -F* provides a list of the
  90 available output formats.  By default this is the *pcapng* format.
  91 --
  92
  93 -h|--help::
  94 Print the version number and options and exit.
  95
  96 -I  <IDB merge mode>::
  97 +
  98 --
  99 Sets the Interface Description Block (IDB) merge mode to use during merging.
 100 *mergecap -I* provides a list of the available IDB merge modes.
 101
 102 Every input file has one or more IDBs, which describe the interface(s) the
 103 capture was performed on originally. This includes encapsulation type,
 104 interface name, etc. When mergecap merges multiple input files, it has to
 105 merge these IDBs somehow for the new merged output file. This flag controls
 106 how that is accomplished. The currently available modes are:
 107
 108 *none*: No merging of IDBs is performed, and instead all IDBs are
 109 copied to the merged output file.
 110
 111 *all*: IDBs are merged only if all input files have the same number
 112 of IDBs, and each IDB matches their respective entry in the
 113 other files. (Only the IDBs that occur at the beginning of the files,
 114 before any packet blocks, are compared. IDBs that occur later in the
 115 files are merged with duplicates iff the initial IDBs were merged.)
 116 This is the default mode.
 117
 118 *any*: Any and all duplicate IDBs are merged into one IDB, regardless
 119 of what file they are in.
 120
 121 Note that an IDB is only considered a matching duplicate if it has the same
 122 encapsulation type, name, speed, time precision, comments, description, etc.
 123 --
 124
 125 -s  <snaplen>::
 126 +
 127 --
 128 Sets the snapshot length to use when writing the data.
 129 If the *-s* flag is used to specify a snapshot length, frames in the
 130 input file with more captured data than the specified snapshot length
 131 will have only the amount of data specified by the snapshot length
 132 written to the output file.  This may be useful if the program that is
 133 to read the output file cannot handle packets larger than a certain size
 134 (for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
 135 appear to reject Ethernet frames larger than the standard Ethernet MTU,
 136 making them incapable of handling gigabit Ethernet captures if jumbo
 137 frames were used).
 138 --
 139
 140 -v|--version::
 141 Print the full version information and exit.
 142
 143 -V::
 144 Causes *mergecap* to print a number of messages while it's working.
 145
 146 -w  <outfile>|-::
 147 Sets the output filename. If the name is '*-*', stdout will be used.
 148 If the *--compress* option is not given, then the filename extension is
 149 used to deduce the desired compression method, if any; e.g., if the name has
 150 the extension '.gz', then the output file is compressed to a gzip archive.
 151 This setting is mandatory.
 152
 153 --compress <type>::
 154 +
 155 --
 156 Compress the output file using the type compression format.
 157 *--compress* with no argument provides a list of the compression formats supported
 158 for writing. The type given takes precedence over the extension of __outfile__.
 159 --
 160
 161 include::diagnostic-options.adoc[]
 162
 163 == EXAMPLES
 164
 165 To merge two capture files together into a third capture file, in which
 166 the last packet of one file arrives 100 seconds before the first packet
 167 of another file, use the following sequence of commands.
 168
 169 First, use:
 170
 171     capinfos -aeS a.pcap b.pcap
 172
 173 to determine the start and end times of the two capture files, as
 174 seconds since January 1, 1970, 00:00:00 UTC.
 175
 176 If a.pcap starts at 1009932757 and b.pcap ends at 873660281, then the
 177 time adjustment to b.pcap that would make it end 100 seconds before
 178 a.pcap begins would be 1009932757 - 873660281 - 100 = 136272376 seconds.
 179
 180 Thus, the next step would be to use:
 181
 182     editcap -t 136272376 b.pcap b-shifted.pcap
 183
 184 to generate a version of b.pcap with its time stamps shifted 136272376
 185 ahead.
 186
 187 Then the final step would be to use :
 188
 189     mergecap -w compare.pcap a.pcap b-shifted.pcap
 190
 191 to merge a.pcap and the shifted b.pcap into compare.pcap.
 192
 193 == SEE ALSO
 194
 195 xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:editcap.html[editcap](1), xref:text2pcap.html[text2pcap](1),
 196 xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8)
 197
 198 == NOTES
 199
 200 *Mergecap* is based heavily upon *editcap* by Richard Sharpe
 201 <sharpe[AT]ns.aus.com> and Guy Harris <guy[AT]alum.mit.edu>.
 202
 203 This is the manual page for *Mergecap* {wireshark-version}.
 204 *Mergecap* is part of the *Wireshark* distribution.
 205 The latest version of *Wireshark* can be found at https://www.wireshark.org.
 206
 207 HTML versions of the Wireshark project man pages are available at
 208 https://www.wireshark.org/docs/man-pages.
 209
 210 == AUTHORS
 211
 212 .Original Author
 213 [%hardbreaks]
 214 Scott Renfro <scott[AT]renfro.org>
 215
 216 .Contributors
 217 [%hardbreaks]
 218 Bill Guyton <guyton[AT]bguyton.com>