bf529293c8d71b40d2ebd0250aaff7ac21eeca1a
[metze/wireshark/wip.git] / docbook / wsug_src / WSUG_app_tools.asciidoc
1 // WSUG Appendix Tools
2
3 [[AppTools]]
4
5 [appendix]
6 == Related command line tools
7
8 [[AppToolsIntroduction]]
9
10 === Introduction
11
12 Along with the main application, Wireshark comes with an array of
13 command line tools which can be helpful for specialized tasks. Some of
14 these tools will be described in this chapter. You can find more
15 information about all of Wireshark’s command line tools on
16 link:{wireshark-man-page-url}[the web site].
17
18 [[AppToolstshark]]
19
20 === __tshark__: Terminal-based Wireshark
21
22 TShark is a terminal oriented version of Wireshark designed for capturing and
23 displaying packets when an interactive user interface isn’t necessary or
24 available. It supports the same options as `wireshark`. For more information on
25 `tshark` consult your local manual page (`man tshark`) or
26 link:{wireshark-man-page-url}tshark.html[the online version].
27
28 [[AppToolstsharkEx]]
29 .Help information available from `tshark`
30 ----
31 include::tshark-h.txt[]
32 ----
33
34 [[AppToolstcpdump]]
35
36 === __tcpdump__: Capturing with “tcpdump” for viewing with Wireshark
37
38 It’s often more useful to capture packets using `tcpdump` rather than
39 `wireshark`. For example, you might want to do a remote capture and either don’t
40 have GUI access or don’t have Wireshark installed on the remote machine.
41
42 Older versions of `tcpdump` truncate packets to 68 or 96 bytes. If this is the case,
43 use `-s` to capture full-sized packets:
44
45 ----
46 $ tcpdump -i <interface> -s 65535 -w <some-file>
47 ----
48
49 You will have to specify the correct _interface_ and the name of a _file_ to
50 save into. In addition, you will have to terminate the capture with ^C when you
51 believe you have captured enough packets.
52
53 `tcpdump` is not part of the Wireshark distribution. You can get it from
54 {tcpdump-main-url} or as a standard package in most Linux distributions.
55 For more information on `tcpdump` consult your local manual page (`man
56 tcpdump`) or link:{tcpdump-man-page-url}[the online version].
57
58 [[AppToolsdumpcap]]
59
60 === __dumpcap__: Capturing with “dumpcap” for viewing with Wireshark
61
62 Dumpcap is a network traffic dump tool. It captures packet data from a live
63 network and writes the packets to a file. Dumpcap’s native capture file format
64 is pcapng, which is also the format used by Wireshark.
65
66 Without any options set it will use the pcap library to capture traffic
67 from the first available network interface and write the received raw
68 packet data, along with the packets’ time stamps into a pcapng file. The
69 capture filter syntax follows the rules of the pcap library. For more
70 information on `dumpcap` consult your local manual page (`man dumpcap`)
71 or link:{wireshark-man-page-url}dumpcap.html[the online version].
72
73 [[AppToolsdumpcapEx]]
74 .Help information available from `dumpcap`
75 ----
76 include::dumpcap-h.txt[]
77 ----
78
79 [[AppToolscapinfos]]
80
81 === __capinfos__: Print information about capture files
82
83 `capinfos` can print information about capture files including the file
84 type, number of packets, date and time information, and file hashes.
85 Information can be printed in human and machine readable formats. For
86 more information on `capinfos` consult your local manual page (`man
87 capinfos`) or link:{wireshark-man-page-url}capinfos.html[the online
88 version].
89
90 [[AppToolscapinfosEx]]
91 .Help information available from `capinfos`
92 ----
93 include::capinfos-h.txt[]
94 ----
95
96 [[AppToolsrawshark]]
97
98 === __rawshark__: Dump and analyze network traffic.
99
100 Rawshark reads a stream of packets from a file or pipe, and prints a
101 line describing its output, followed by a set of matching fields for
102 each packet on stdout. For more information on `rawshark` consult your
103 local manual page (`man rawshark`) or
104 link:{wireshark-man-page-url}rawshark.html[the online version].
105
106 [[AppToolsrawsharkEx]]
107 .Help information available from `rawshark`
108 ----
109 include::rawshark-h.txt[]
110 ----
111
112 [[AppToolseditcap]]
113
114 === __editcap__: Edit capture files
115
116 `editcap` is a general-purpose utility for modifying capture files. Its
117 main function is to remove packets from capture files, but it can also
118 be used to convert capture files from one format to another, as well as
119 to print information about capture files. For more information on
120 `editcap` consult your local manual page (`man editcap`) or
121 link:{wireshark-man-page-url}editcap.html[the online version].
122
123 [[AppToolseditcapEx]]
124 .Help information available from editcap
125 ----
126 include::editcap-h.txt[]
127 ----
128
129 [[AppToolseditcapEx1]]
130 .Capture file types available from `editcap -F`
131 ----
132 include::editcap-F.txt[]
133 ----
134
135 [[AppToolseditcapEx2]]
136 .Encapsulation types available from `editcap -T`
137
138 ----
139 include::editcap-T.txt[]
140 ----
141
142 [[AppToolsmergecap]]
143
144 === __mergecap__: Merging multiple capture files into one
145
146 Mergecap is a program that combines multiple saved capture files into a single
147 output file specified by the `-w` argument. Mergecap knows how to read libpcap
148 capture files, including those of tcpdump. In addition, Mergecap can read
149 capture files from snoop (including Shomiti) and atmsnoop, LanAlyzer, Sniffer
150 (compressed or uncompressed), Microsoft Network Monitor, AIX’s iptrace, NetXray,
151 Sniffer Pro, RADCOM’s WAN/LAN analyzer, Lucent/Ascend router debug output,
152 HP-UX’s nettl, and the dump output from Toshiba’s ISDN routers. There is no need
153 to tell Mergecap what type of file you are reading; it will determine the file
154 type by itself. Mergecap is also capable of reading any of these file formats if
155 they are compressed using `gzip`. Mergecap recognizes this directly from the
156 file; the “.gz” extension is not required for this purpose.
157
158 By default, it writes the capture file in pcapng format, and writes all of the
159 packets in the input capture files to the output file. The `-F` flag can be used
160 to specify the format in which to write the capture file; it can write the file
161 in libpcap format (standard libpcap format, a modified format used by some
162 patched versions of libpcap, the format used by Red Hat Linux 6.1, or the format
163 used by SuSE Linux 6.3), snoop format, uncompressed Sniffer format, Microsoft
164 Network Monitor 1.x format, and the format used by Windows-based versions of the
165 Sniffer software.
166
167 Packets from the input files are merged in chronological order based on each
168 frame’s timestamp, unless the `-a` flag is specified. Mergecap assumes that
169 frames within a single capture file are already stored in chronological order.
170 When the `-a` flag is specified, packets are copied directly from each input
171 file to the output file, independent of each frame’s timestamp.
172
173 If the `-s` flag is used to specify a snapshot length, frames in the input file
174 with more captured data than the specified snapshot length will have only the
175 amount of data specified by the snapshot length written to the output file. This
176 may be useful if the program that is to read the output file cannot handle
177 packets larger than a certain size (for example, the versions of snoop in
178 Solaris 2.5.1 and Solaris 2.6 appear to reject Ethernet frames larger than the
179 standard Ethernet MTU, making them incapable of handling gigabit Ethernet
180 captures if jumbo frames were used).
181
182 If the `-T` flag is used to specify an encapsulation type, the encapsulation
183 type of the output capture file will be forced to the specified type, rather
184 than being the type appropriate to the encapsulation type of the input capture
185 file. Note that this merely forces the encapsulation type of the output file to
186 be the specified type; the packet headers of the packets will not be translated
187 from the encapsulation type of the input capture file to the specified
188 encapsulation type (for example, it will not translate an Ethernet capture to an
189 FDDI capture if an Ethernet capture is read and `-T fddi` is specified).
190
191 For more information on `mergecap` consult your local manual page (`man
192 mergecap`) or link:{wireshark-man-page-url}mergecap.html[the online
193 version].
194
195 [[AppToolsmergecapEx]]
196 .Help information available from `mergecap`
197 ----
198 include::mergecap-h.txt[]
199 ----
200
201 A simple example merging `dhcp-capture.pcapng` and `imap-1.pcapng` into
202 `outfile.pcapng` is shown below.
203
204 [[AppToolsmergecapExSimple]]
205 .Simple example of using mergecap
206 ----
207 $ mergecap -w outfile.pcapng dhcp-capture.pcapng imap-1.pcapng
208 ----
209
210 [[AppToolstext2pcap]]
211
212 === __text2pcap__: Converting ASCII hexdumps to network captures
213
214 There may be some occasions when you wish to convert a hex dump of some network
215 traffic into a libpcap file.
216
217 `text2pcap` is a program that reads in an ASCII hex dump and writes the data
218 described into a libpcap-style capture file. text2pcap can read hexdumps with
219 multiple packets in them, and build a capture file of multiple packets.
220 `text2pcap` is also capable of generating dummy Ethernet, IP, UDP, TCP or SCTP
221 headers, in order to build fully processable packet dumps from hexdumps of
222 application-level data only.
223
224 `text2pcap` understands a hexdump of the form generated by `od -A x -t x1`. In
225 other words, each byte is individually displayed and surrounded with a space.
226 Each line begins with an offset describing the position in the packet, each new
227 packet starts with an offset of 0 and there is a space separating the offset
228 from the following bytes. The offset
229 is a hex number (can also be octal - see `-o`), of more than two hex digits. Here
230 is a sample dump that `text2pcap` can recognize:
231
232 ----
233 000000 00 e0 1e a7 05 6f 00 10 ........
234 000008 5a a0 b9 12 08 00 46 00 ........
235 000010 03 68 00 00 00 00 0a 2e ........
236 000018 ee 33 0f 19 08 7f 0f 19 ........
237 000020 03 80 94 04 00 00 10 01 ........
238 000028 16 a2 0a 00 03 50 00 0c ........
239 000030 01 01 0f 19 03 80 11 01 ........
240 ----
241
242 There is no limit on the width or number of bytes per line. Also the text dump
243 at the end of the line is ignored. Bytes/hex numbers can be uppercase or
244 lowercase. Any text before the offset is ignored, including email forwarding
245 characters “>”. Any lines of text between the bytestring lines is ignored.
246 The offsets are used to track the bytes, so offsets must be correct. Any line
247 which has only bytes without a leading offset is ignored. An offset is
248 recognized as being a hex number longer than two characters. Any text after the
249 bytes is ignored (e.g. the character dump). Any hex numbers in this text are
250 also ignored. An offset of zero is indicative of starting a new packet, so a
251 single text file with a series of hexdumps can be converted into a packet
252 capture with multiple packets. Packets may be preceded by a timestamp. These
253 are interpreted according to the format given on the command line. If not, the
254 first packet is timestamped with the current time the conversion takes place.
255 Multiple packets are written with timestamps differing by one microsecond each.
256 In general, short of these restrictions, text2pcap
257 is pretty liberal about reading in hexdumps and has been tested with a variety
258 of mangled outputs (including being forwarded through email multiple times, with
259 limited line wrap etc.)
260
261 There are a couple of other special features to note. Any line where the first
262 non-whitespace character is “#” will be ignored as a comment. Any line beginning
263 with #TEXT2PCAP is a directive and options can be inserted after this command to
264 be processed by `text2pcap`. Currently there are no directives implemented; in the
265 future, these may be used to give more fine grained control on the dump and the
266 way it should be processed e.g. timestamps, encapsulation type etc.
267
268 `text2pcap` also allows the user to read in dumps of application-level data, by
269 inserting dummy L2, L3 and L4 headers before each packet. Possibilities include
270 inserting headers such as Ethernet, Ethernet + IP, Ethernet + IP + UDP, or TCP,
271 or SCTP before each packet. This allows Wireshark or any other full-packet
272 decoder to handle these dumps.
273
274 For more information on `text2pcap` consult your local manual page (`man
275 text2pcap`) or link:{wireshark-man-page-url}text2pcap.html[the online
276 version].
277
278 [[AppToolstext2pcapEx]]
279 .Help information available from text2pcap
280
281 ----
282 include::text2pcap-h.txt[]
283 ----
284
285 [[AppToolsreordercap]]
286
287 === __reordercap__: Reorder a capture file
288
289 `reordercap` lets you reorder a capture file according to the packets
290 timestamp. For more information on `reordercap` consult your local
291 manual page (`man reordercap`) or
292 link:{wireshark-man-page-url}reordercap.html[the online version].
293
294 [[AppToolsreordercapEx]]
295 .Help information available from reordercap
296 ----
297 include::reordercap-h.txt[]
298 ----
299
300 // End of WSUG Appendix Tools