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