doc/wsug_src/wsug_tools.adoc

   1 // WSUG Appendix Tools
   2
   3 [#AppTools]
   4
   5 [appendix]
   6 == Related command line tools
   7
   8 [#AppToolsIntroduction]
   9
  10 === Introduction
  11
  12 Wireshark comes with an array of
  13 command line tools which can be helpful for packet analysis. Some of
  14 these tools are 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 <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 By default, Dumpcap uses the pcap library to capture traffic
  67 from the first available network interface and writes 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 can 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, Mergecap writes all of the packets in the input capture files to a
 159 pcapng file. The `-F` flag can be used
 160 to specify the capture file's output format ; 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 capture file.
 216
 217 `text2pcap` is a program that reads in an ASCII hex dump and writes the data
 218 described into any capture file format supported by libwiretap. `text2pcap` can
 219 read hexdumps with multiple packets in them, and build a capture file of
 220 multiple packets.
 221 `text2pcap` is also capable of generating dummy Ethernet, IP, UDP, TCP or SCTP
 222 headers, in order to build fully processable packet dumps from hexdumps of
 223 application-level data only.
 224
 225 `text2pcap` understands a hexdump of the form generated by `od -A x -t x1`. In
 226 other words, each byte is individually displayed and surrounded with a space.
 227 Each line begins with an offset describing the position in the packet, each new
 228 packet starts with an offset of 0 and there is a space separating the offset
 229 from the following bytes. The offset
 230 is a hex number (can also be octal - see `-o`), of more than two hex digits. Here
 231 is a sample dump that `text2pcap` can recognize:
 232
 233 ----
 234 000000 00 e0 1e a7 05 6f 00 10 ........
 235 000008 5a a0 b9 12 08 00 46 00 ........
 236 000010 03 68 00 00 00 00 0a 2e ........
 237 000018 ee 33 0f 19 08 7f 0f 19 ........
 238 000020 03 80 94 04 00 00 10 01 ........
 239 000028 16 a2 0a 00 03 50 00 0c ........
 240 000030 01 01 0f 19 03 80 11 01 ........
 241 ----
 242
 243 There is no limit on the width or number of bytes per line. Also the text dump
 244 at the end of the line is ignored. Bytes/hex numbers can be uppercase or
 245 lowercase. Any text before the offset is ignored, including email forwarding
 246 characters “>”. Any lines of text between the bytestring lines is ignored.
 247 The offsets are used to track the bytes, so offsets must be correct. Any line
 248 which has only bytes without a leading offset is ignored. An offset is
 249 recognized as being a hex number longer than two characters. Any text after the
 250 bytes is ignored (e.g., the character dump). Any hex numbers in this text are
 251 also ignored. An offset of zero is indicative of starting a new packet, so a
 252 single text file with a series of hexdumps can be converted into a packet
 253 capture with multiple packets. Packets may be preceded by a timestamp. These
 254 are interpreted according to the format given on the command line. If not, the
 255 first packet is timestamped with the current time the conversion takes place.
 256 Multiple packets are written with timestamps differing by one microsecond each.
 257 In general, short of these restrictions, `text2pcap`
 258 is pretty liberal about reading in hexdumps and has been tested with a variety
 259 of mangled outputs (including being forwarded through email multiple times, with
 260 limited line wrap etc.)
 261
 262 There are a couple of other special features to note. Any line where the first
 263 non-whitespace character is “#” will be ignored as a comment. Any line beginning
 264 with #TEXT2PCAP is a directive and options can be inserted after this command to
 265 be processed by `text2pcap`. Currently there are no directives implemented; in the
 266 future, these may be used to give more fine-grained control on the dump and the
 267 way it should be processed e.g., timestamps, encapsulation type etc.
 268
 269 `text2pcap` also allows the user to read in dumps of application-level data, by
 270 inserting dummy L2, L3 and L4 headers before each packet. Possibilities include
 271 inserting headers such as Ethernet, Ethernet + IP, Ethernet + IP + UDP, or TCP,
 272 or SCTP before each packet. This allows Wireshark or any other full-packet
 273 decoder to handle these dumps.
 274
 275 For more information on `text2pcap` consult your local manual page (`man
 276 text2pcap`) or link:{wireshark-man-page-url}text2pcap.html[the online
 277 version].
 278
 279 [#AppToolstext2pcapEx]
 280 .Help information available from text2pcap
 281
 282 ----
 283 include::text2pcap-h.txt[]
 284 ----
 285
 286 [#AppToolsreordercap]
 287
 288 === __reordercap__: Reorder a capture file
 289
 290 `reordercap` lets you reorder a capture file according to the packets
 291 timestamp. For more information on `reordercap` consult your local
 292 manual page (`man reordercap`) or
 293 link:{wireshark-man-page-url}reordercap.html[the online version].
 294
 295 [#AppToolsreordercapEx]
 296 .Help information available from reordercap
 297 ----
 298 include::reordercap-h.txt[]
 299 ----
 300
 301 // End of WSUG Appendix Tools