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 pcap or pcapng 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