diff options
Diffstat (limited to 'doc/wsug_src/wsug_tools.adoc')
| -rw-r--r-- | doc/wsug_src/wsug_tools.adoc | 301 |
1 files changed, 301 insertions, 0 deletions
diff --git a/doc/wsug_src/wsug_tools.adoc b/doc/wsug_src/wsug_tools.adoc new file mode 100644 index 00000000..3a83d05f --- /dev/null +++ b/doc/wsug_src/wsug_tools.adoc @@ -0,0 +1,301 @@ +// WSUG Appendix Tools + +[#AppTools] + +[appendix] +== Related command line tools + +[#AppToolsIntroduction] + +=== Introduction + +Wireshark comes with an array of +command line tools which can be helpful for packet analysis. Some of +these tools are described in this chapter. You can find more +information about all of Wireshark’s command line tools on +link:{wireshark-man-page-url}[the web site]. + +[#AppToolstshark] + +=== __tshark__: Terminal-based Wireshark + +TShark is a terminal oriented version of Wireshark designed for capturing and +displaying packets when an interactive user interface isn’t necessary or +available. It supports the same options as `wireshark`. For more information on +`tshark` consult your local manual page (`man tshark`) or +link:{wireshark-man-page-url}tshark.html[the online version]. + +[#AppToolstsharkEx] +.Help information available from `tshark` +---- +include::tshark-h.txt[] +---- + +[#AppToolstcpdump] + +=== __tcpdump__: Capturing with “tcpdump” for viewing with Wireshark + +It’s often more useful to capture packets using `tcpdump` rather than +`wireshark`. For example, you might want to do a remote capture and either don’t +have GUI access or don’t have Wireshark installed on the remote machine. + +Older versions of `tcpdump` truncate packets to 68 or 96 bytes. If this is the case, +use `-s` to capture full-sized packets: + +---- +$ tcpdump -i <interface> -s 65535 -w <file> +---- + +You will have to specify the correct _interface_ and the name of a _file_ to +save into. In addition, you will have to terminate the capture with ^C when you +believe you have captured enough packets. + +`tcpdump` is not part of the Wireshark distribution. You can get it from +{tcpdump-main-url} or as a standard package in most Linux distributions. +For more information on `tcpdump` consult your local manual page (`man +tcpdump`) or link:{tcpdump-man-page-url}[the online version]. + +[#AppToolsdumpcap] + +=== __dumpcap__: Capturing with “dumpcap” for viewing with Wireshark + +Dumpcap is a network traffic dump tool. It captures packet data from a live +network and writes the packets to a file. Dumpcap’s native capture file format +is pcapng, which is also the format used by Wireshark. + +By default, Dumpcap uses the pcap library to capture traffic +from the first available network interface and writes the received raw +packet data, along with the packets’ time stamps into a pcapng file. The +capture filter syntax follows the rules of the pcap library. For more +information on `dumpcap` consult your local manual page (`man dumpcap`) +or link:{wireshark-man-page-url}dumpcap.html[the online version]. + +[#AppToolsdumpcapEx] +.Help information available from `dumpcap` +---- +include::dumpcap-h.txt[] +---- + +[#AppToolscapinfos] + +=== __capinfos__: Print information about capture files + +`capinfos` can print information about capture files including the file +type, number of packets, date and time information, and file hashes. +Information can be printed in human and machine readable formats. For +more information on `capinfos` consult your local manual page (`man +capinfos`) or link:{wireshark-man-page-url}capinfos.html[the online +version]. + +[#AppToolscapinfosEx] +.Help information available from `capinfos` +---- +include::capinfos-h.txt[] +---- + +[#AppToolsrawshark] + +=== __rawshark__: Dump and analyze network traffic. + +Rawshark reads a stream of packets from a file or pipe, and prints a +line describing its output, followed by a set of matching fields for +each packet on stdout. For more information on `rawshark` consult your +local manual page (`man rawshark`) or +link:{wireshark-man-page-url}rawshark.html[the online version]. + +[#AppToolsrawsharkEx] +.Help information available from `rawshark` +---- +include::rawshark-h.txt[] +---- + +[#AppToolseditcap] + +=== __editcap__: Edit capture files + +`editcap` is a general-purpose utility for modifying capture files. Its +main function is to remove packets from capture files, but it can also +be used to convert capture files from one format to another, as well as +to print information about capture files. For more information on +`editcap` consult your local manual page (`man editcap`) or +link:{wireshark-man-page-url}editcap.html[the online version]. + +[#AppToolseditcapEx] +.Help information available from editcap +---- +include::editcap-h.txt[] +---- + +[#AppToolseditcapEx1] +.Capture file types available from `editcap -F` +---- +include::editcap-F.txt[] +---- + +[#AppToolseditcapEx2] +.Encapsulation types available from `editcap -T` + +---- +include::editcap-T.txt[] +---- + +[#AppToolsmergecap] + +=== __mergecap__: Merging multiple capture files into one + +Mergecap is a program that combines multiple saved capture files into a single +output file specified by the `-w` argument. Mergecap can read libpcap +capture files, including those of tcpdump. In addition, Mergecap can read +capture files from snoop (including Shomiti) and atmsnoop, LanAlyzer, Sniffer +(compressed or uncompressed), Microsoft Network Monitor, AIX’s iptrace, NetXray, +Sniffer Pro, RADCOM’s WAN/LAN analyzer, Lucent/Ascend router debug output, +HP-UX’s nettl, and the dump output from Toshiba’s ISDN routers. There is no need +to tell Mergecap what type of file you are reading; it will determine the file +type by itself. Mergecap is also capable of reading any of these file formats if +they are compressed using `gzip`. Mergecap recognizes this directly from the +file; the “.gz” extension is not required for this purpose. + +By default, Mergecap writes all of the packets in the input capture files to a +pcapng file. The `-F` flag can be used +to specify the capture file's output format ; it can write the file +in libpcap format (standard libpcap format, a modified format used by some +patched versions of libpcap, the format used by Red Hat Linux 6.1, or the format +used by SuSE Linux 6.3), snoop format, uncompressed Sniffer format, Microsoft +Network Monitor 1.x format, and the format used by Windows-based versions of the +Sniffer software. + +Packets from the input files are merged in chronological order based on each +frame’s timestamp, unless the `-a` flag is specified. Mergecap assumes that +frames within a single capture file are already stored in chronological order. +When the `-a` flag is specified, packets are copied directly from each input +file to the output file, independent of each frame’s timestamp. + +If the `-s` flag is used to specify a snapshot length, frames in the input file +with more captured data than the specified snapshot length will have only the +amount of data specified by the snapshot length written to the output file. This +may be useful if the program that is to read the output file cannot handle +packets larger than a certain size (for example, the versions of snoop in +Solaris 2.5.1 and Solaris 2.6 appear to reject Ethernet frames larger than the +standard Ethernet MTU, making them incapable of handling gigabit Ethernet +captures if jumbo frames were used). + +If the `-T` flag is used to specify an encapsulation type, the encapsulation +type of the output capture file will be forced to the specified type, rather +than being the type appropriate to the encapsulation type of the input capture +file. Note that this merely forces the encapsulation type of the output file to +be the specified type; the packet headers of the packets will not be translated +from the encapsulation type of the input capture file to the specified +encapsulation type (for example, it will not translate an Ethernet capture to an +FDDI capture if an Ethernet capture is read and `-T fddi` is specified). + +For more information on `mergecap` consult your local manual page (`man +mergecap`) or link:{wireshark-man-page-url}mergecap.html[the online +version]. + +[#AppToolsmergecapEx] +.Help information available from `mergecap` +---- +include::mergecap-h.txt[] +---- + +A simple example merging `dhcp-capture.pcapng` and `imap-1.pcapng` into +`outfile.pcapng` is shown below. + +[#AppToolsmergecapExSimple] +.Simple example of using mergecap +---- +$ mergecap -w outfile.pcapng dhcp-capture.pcapng imap-1.pcapng +---- + +[#AppToolstext2pcap] + +=== __text2pcap__: Converting ASCII hexdumps to network captures + +There may be some occasions when you wish to convert a hex dump of some network +traffic into a capture file. + +`text2pcap` is a program that reads in an ASCII hex dump and writes the data +described into any capture file format supported by libwiretap. `text2pcap` can +read hexdumps with multiple packets in them, and build a capture file of +multiple packets. +`text2pcap` is also capable of generating dummy Ethernet, IP, UDP, TCP or SCTP +headers, in order to build fully processable packet dumps from hexdumps of +application-level data only. + +`text2pcap` understands a hexdump of the form generated by `od -A x -t x1`. In +other words, each byte is individually displayed and surrounded with a space. +Each line begins with an offset describing the position in the packet, each new +packet starts with an offset of 0 and there is a space separating the offset +from the following bytes. The offset +is a hex number (can also be octal - see `-o`), of more than two hex digits. Here +is a sample dump that `text2pcap` can recognize: + +---- +000000 00 e0 1e a7 05 6f 00 10 ........ +000008 5a a0 b9 12 08 00 46 00 ........ +000010 03 68 00 00 00 00 0a 2e ........ +000018 ee 33 0f 19 08 7f 0f 19 ........ +000020 03 80 94 04 00 00 10 01 ........ +000028 16 a2 0a 00 03 50 00 0c ........ +000030 01 01 0f 19 03 80 11 01 ........ +---- + +There is no limit on the width or number of bytes per line. Also the text dump +at the end of the line is ignored. Bytes/hex numbers can be uppercase or +lowercase. Any text before the offset is ignored, including email forwarding +characters “>”. Any lines of text between the bytestring lines is ignored. +The offsets are used to track the bytes, so offsets must be correct. Any line +which has only bytes without a leading offset is ignored. An offset is +recognized as being a hex number longer than two characters. Any text after the +bytes is ignored (e.g., the character dump). Any hex numbers in this text are +also ignored. An offset of zero is indicative of starting a new packet, so a +single text file with a series of hexdumps can be converted into a packet +capture with multiple packets. Packets may be preceded by a timestamp. These +are interpreted according to the format given on the command line. If not, the +first packet is timestamped with the current time the conversion takes place. +Multiple packets are written with timestamps differing by one microsecond each. +In general, short of these restrictions, `text2pcap` +is pretty liberal about reading in hexdumps and has been tested with a variety +of mangled outputs (including being forwarded through email multiple times, with +limited line wrap etc.) + +There are a couple of other special features to note. Any line where the first +non-whitespace character is “#” will be ignored as a comment. Any line beginning +with #TEXT2PCAP is a directive and options can be inserted after this command to +be processed by `text2pcap`. Currently there are no directives implemented; in the +future, these may be used to give more fine-grained control on the dump and the +way it should be processed e.g., timestamps, encapsulation type etc. + +`text2pcap` also allows the user to read in dumps of application-level data, by +inserting dummy L2, L3 and L4 headers before each packet. Possibilities include +inserting headers such as Ethernet, Ethernet + IP, Ethernet + IP + UDP, or TCP, +or SCTP before each packet. This allows Wireshark or any other full-packet +decoder to handle these dumps. + +For more information on `text2pcap` consult your local manual page (`man +text2pcap`) or link:{wireshark-man-page-url}text2pcap.html[the online +version]. + +[#AppToolstext2pcapEx] +.Help information available from text2pcap + +---- +include::text2pcap-h.txt[] +---- + +[#AppToolsreordercap] + +=== __reordercap__: Reorder a capture file + +`reordercap` lets you reorder a capture file according to the packets +timestamp. For more information on `reordercap` consult your local +manual page (`man reordercap`) or +link:{wireshark-man-page-url}reordercap.html[the online version]. + +[#AppToolsreordercapEx] +.Help information available from reordercap +---- +include::reordercap-h.txt[] +---- + +// End of WSUG Appendix Tools |