build a list of the input file formats instead of a floating text,
[obnox/wireshark/wip.git] / doc / mergecap.pod
1
2 =head1 NAME
3
4 mergecap - Merges two capture files into one
5
6 =head1 SYNOPSYS
7
8 B<mergecap>
9 S<[ B<-hva> ]>
10 S<[ B<-s> I<snaplen> ]>
11 S<[ B<-F> I<file format> ]>
12 S<[ B<-T> I<encapsulation type> ]>
13 S<B<-w> I<outfile>|->
14 I<infile>
15 I<...>
16
17 =head1 DESCRIPTION
18
19 B<Mergecap> is a program that combines multiple saved capture files into
20 a single output file specified by the B<-w> argument.  B<Mergecap> knows
21 how to read B<libpcap> capture files, including those of B<tcpdump>,
22 B<Ethereal>, and other tools that write captures in that format.  
23
24 B<Mergecap> can read / import the following file formats:
25
26 =over 4
27
28 =item *
29 libpcap/WinPcap, tcpdump and various other tools using tcpdump's capture format
30
31 =item *
32 B<snoop> and B<atmsnoop>
33
34 =item *
35 Shomiti/Finisar B<Surveyor> captures
36
37 =item *
38 Novell B<LANalyzer> captures
39
40 =item *
41 Microsoft B<Network Monitor> captures
42
43 =item *
44 AIX's B<iptrace> captures
45
46 =item *
47 Cinco Networks B<NetXRay> captures
48
49 =item *
50 Network Associates Windows-based B<Sniffer> captures
51
52 =item *
53 Network General/Network Associates DOS-based B<Sniffer> (compressed or uncompressed) captures
54
55 =item *
56 AG Group/WildPackets B<EtherPeek>/B<TokenPeek>/B<AiroPeek>/B<EtherHelp>/B<PacketGrabber> captures
57
58 =item *
59 B<RADCOM>'s WAN/LAN analyzer captures
60
61 =item *
62 Network Instruments B<Observer> version 9 captures
63
64 =item *
65 B<Lucent/Ascend> router debug output
66
67 =item *
68 files from HP-UX's B<nettl>
69
70 =item *
71 B<Toshiba's> ISDN routers dump output
72
73 =item *
74 the output from B<i4btrace> from the ISDN4BSD project
75
76 =item *
77 traces from the B<EyeSDN> USB S0.
78
79 =item *
80 the output in B<IPLog> format from the Cisco Secure Intrusion Detection System
81
82 =item *
83 B<pppd logs> (pppdump format)
84
85 =item *
86 the output from VMS's B<TCPIPtrace>/B<TCPtrace>/B<UCX$TRACE> utilities
87
88 =item *
89 the text output from the B<DBS Etherwatch> VMS utility
90
91 =item *
92 Visual Networks' B<Visual UpTime> traffic capture
93
94 =item *
95 the output from B<CoSine> L2 debug
96
97 =item *
98 the output from Accellent's B<5Views> LAN agents
99
100 =item *
101 Endace Measurement Systems' ERF format captures 
102
103 =item *
104 Linux Bluez Bluetooth stack B<hcidump -w> traces
105
106 =back
107
108 There is no need to tell B<Mergecap> what type of
109 file you are reading; it will determine the file type by itself. 
110 B<Mergecap> is also capable of reading any of these file formats if they
111 are compressed using gzip.  B<Mergecap> recognizes this directly from
112 the file; the '.gz' extension is not required for this purpose.
113
114 By default, it writes the capture file in B<libpcap> format, and writes
115 all of the packets in both input capture files to the output file.  The
116 B<-F> flag can be used to specify the format in which to write the
117 capture file; it can write the file in B<libpcap> format (standard
118 B<libpcap> format, a modified format used by some patched versions of
119 B<libpcap>, the format used by Red Hat Linux 6.1, or the format used by
120 SuSE Linux 6.3), B<snoop> format, uncompressed B<Sniffer> format,
121 Microsoft B<Network Monitor> 1.x format, the format used by
122 Windows-based versions of the B<Sniffer> software, and the format used
123 by Visual Networks' software.
124
125 Packets from the input files are merged in chronological order based on
126 each frame's timestamp, unless the B<-a> flag is specified.  B<Mergecap>
127 assumes that frames within a single capture file are already stored in
128 chronological order.  When the B<-a> flag is specified, packets are
129 copied directly from each input file to the output file, independent of
130 each frame's timestamp.
131
132 If the B<-s> flag is used to specify a snapshot length, frames in the
133 input file with more captured data than the specified snapshot length
134 will have only the amount of data specified by the snapshot length
135 written to the output file.  This may be useful if the program that is
136 to read the output file cannot handle packets larger than a certain size
137 (for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
138 appear to reject Ethernet frames larger than the standard Ethernet MTU,
139 making them incapable of handling gigabit Ethernet captures if jumbo
140 frames were used).
141
142 The output file frame encapsulation type is set to the type of the input
143 files, if all input files have the same type.  If not all of the input
144 files have the same frame encapsulation type, the output file type is
145 set to WTAP_ENCAP_PER_PACKET.  Note that some capture file formats, most
146 notably B<libpcap>, do not currently support WTAP_ENCAP_PER_PACKET.
147 This combination will cause the output file creation to fail.
148
149 If the B<-T> flag is used to specify a frame encapsulation type, the
150 encapsulation type of the output capture file will be forced to the
151 specified type, rather than being the type appropriate to the
152 encapsulation type of the input capture files.  Note that this merely
153 forces the encapsulation type of the output file to be the specified
154 type; the packet headers of the packets will not be translated from the
155 encapsulation type of the input capture file to the specified
156 encapsulation type (for example, it will not translate an Ethernet
157 capture to an FDDI capture if an Ethernet capture is read and 'B<-T
158 fddi>' is specified).
159
160 =head1 OPTIONS
161
162 =over 4
163
164 =item -w
165
166 Sets the output filename. If the name is 'B<->', stdout will be used.
167
168 =item -F
169
170 Sets the file format of the output capture file.
171
172 =item -T
173
174 Sets the packet encapsulation type of the output capture file.
175
176 =item -a
177
178 Causes the frame timestamps to be ignored, writing all packets from the
179 first input file followed by all packets from the second input file.  By
180 default, when B<-a> is not specified, the contents of the input files
181 are merged in chronological order based on each frame's timestamp.
182 Note: when merging, B<mergecap> assumes that packets within a capture
183 file are already in chronological order.
184
185 =item -v
186
187 Causes B<mergecap> to print a number of messages while it's working.
188
189 =item -s
190
191 Sets the snapshot length to use when writing the data.
192
193 =item -h
194
195 Prints the version and options and exits.
196
197 =back
198
199 =head1 SEE ALSO
200
201 I<tcpdump(8)>, I<pcap(3)>, I<ethereal(1)>, I<editcap(1)>
202
203 =head1 NOTES
204
205 B<Mergecap> is based heavily upon B<editcap> by Richard Sharpe
206 <sharpe[AT]ns.aus.com> and Guy Harris <guy[AT]alum.mit.edu>.
207
208 B<Mergecap> is part of the B<Ethereal> distribution.  The latest version
209 of B<Ethereal> can be found at B<http://www.ethereal.com>.
210
211 =head1 AUTHORS
212
213   Original Author
214   -------- ------
215   Scott Renfro             <scott[AT]renfro.org>
216
217
218   Contributors
219   ------------
220   Bill Guyton              <guyton[AT]bguyton.com>