1 <!-- WSUG Appendix Tools -->
4 <appendix id="AppTools">
5 <title>Related command line tools</title>
7 <section id="AppToolsIntroduction">
8 <title>Introduction</title>
10 Besides the Wireshark GUI application, there are some command line tools
11 which can be helpful for doing some more specialized things. These tools
12 will be described in this chapter.
16 <section id="AppToolstshark">
17 <title><command>tshark</command>: Terminal-based Wireshark</title>
19 <application>TShark</application> is a terminal oriented version
20 of Wireshark designed for capturing and displaying packets when an
21 interactive user interface isn't necessary or available. It supports
22 the same options as <command>wireshark</command>. For more
23 information on <command>tshark</command>, see the manual pages
24 (<command>man tshark</command>).
27 <example id="AppToolstsharkEx">
28 <title>Help information available from tshark</title>
30 TShark 1.6.0 (SVN Rev 37205 from /trunk-1.6)
31 Dump and analyze network traffic.
32 See http://www.wireshark.org for more information.
34 Copyright 1998-2011 Gerald Combs <gerald@wireshark.org> and contributors.
35 This is free software; see the source for copying conditions. There is NO
36 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
38 Usage: tshark [options] ...
41 -i <interface> name or idx of interface (def: first non-loopback)
42 -f <capture filter> packet filter in libpcap filter syntax
43 -s <snaplen> packet snapshot length (def: 65535)
44 -p don't capture in promiscuous mode
45 -B <buffer size> size of kernel buffer (def: 1MB)
46 -y <link type> link layer type (def: first appropriate)
47 -D print list of interfaces and exit
48 -L print list of link-layer types of iface and exit
50 Capture stop conditions:
51 -c <packet count> stop after n packets (def: infinite)
52 -a <autostop cond.> ... duration:NUM - stop after NUM seconds
53 filesize:NUM - stop this file after NUM KB
54 files:NUM - stop after NUM files
56 -b <ringbuffer opt.> ... duration:NUM - switch to next file after NUM secs
57 filesize:NUM - switch to next file after NUM KB
58 files:NUM - ringbuffer: replace after NUM files
60 -r <infile> set the filename to read from (no pipes or stdin!)
63 -R <read filter> packet filter in Wireshark display filter syntax
64 -n disable all name resolutions (def: all enabled)
65 -N <name resolve flags> enable specific name resolution(s): "mntC"
66 -d <layer_type>==<selector>,<decode_as_protocol> ...
67 "Decode As", see the man page for details
68 Example: tcp.port==8888,http
70 -w <outfile|-> write packets to a pcap-format file named "outfile"
71 (or to the standard output for "-")
72 -C <config profile> start with specified configuration profile
73 -F <output file type> set the output file type, default is libpcap
74 an empty "-F" option will list the file types
75 -V add output of packet tree (Packet Details)
76 -O <protocols> Only show packet details of these protocols, comma
78 -S display packets even when writing to a file
79 -x add output of hex and ASCII dump (Packet Bytes)
80 -T pdml|ps|psml|text|fields
81 format of text output (def: text)
82 -e <field> field to print if -Tfields selected (e.g. tcp.port);
83 this option can be repeated to print multiple fields
84 -E<fieldsoption>=<value> set options for output when -Tfields selected:
85 header=y|n switch headers on and off
86 separator=/t|/s|<char> select tab, space, printable character as separator
87 occurrence=f|l|a print first, last or all occurrences of each field
88 aggregator=,|/s|<char> select comma, space, printable character as
90 quote=d|s|n select double, single, no quotes for values
91 -t ad|a|r|d|dd|e output format of time stamps (def: r: rel. to first)
92 -u s|hms output format of seconds (def: s: seconds)
93 -l flush standard output after each packet
94 -q be more quiet on stdout (e.g. when using statistics)
95 -X <key>:<value> eXtension options, see the man page for details
96 -z <statistics> various statistics, see the man page for details
99 -h display this help and exit
100 -v display version info and exit
101 -o <name>:<value> ... override preference setting
102 -K <keytab> keytab file to use for kerberos decryption
103 -G [report] dump one of several available reports and exit
104 default report="fields"
105 use "-G ?" for more help
111 <section id="AppToolstcpdump">
112 <title><command>tcpdump</command>: Capturing with tcpdump for viewing
113 with Wireshark</title>
115 There are occasions when you want to capture packets using
116 <command>tcpdump</command> rather than <command>wireshark</command>,
117 especially when you want to do a remote capture and do not want the
118 network load associated with running Wireshark remotely (not to
119 mention all the X traffic polluting your capture).
122 However, the default <command>tcpdump</command> parameters result in a
123 capture file where each packet is truncated, because most versions of
124 <command>tcpdump</command>, will, by default, only capture the first
125 68 or 96 bytes of each packet.
128 To ensure that you capture complete packets, use the following command:
130 tcpdump -i <interface> -s 65535 -w <some-file>
132 You will have to specify the correct <command>interface</command> and
133 the name of a <command>file</command> to save into. In addition,
134 you will have to terminate the capture with ^C when you believe you
135 have captured enough packets.
137 <note><title>Note!</title>
139 tcpdump is not part of the Wireshark distribution. You can get it from:
140 <ulink url="&TcpdumpWebsite;">&TcpdumpWebsite;</ulink> for various
146 <section id="AppToolsdumpcap">
147 <title><command>dumpcap</command>: Capturing with dumpcap for viewing
148 with Wireshark</title>
150 <application>Dumpcap</application> is a network traffic dump tool.
151 It captures packet data from a live network and writes the
153 Dumpcap's native capture file format is libpcap format, which is also
154 the format used by Wireshark, tcpdump and various other tools.
157 Without any options set it will use the pcap library to capture traffic
158 from the first available network interface and write the received raw
159 packet data, along with the packets' time stamps into a libpcap file.
162 Packet capturing is performed with the pcap library.
163 The capture filter syntax follows the rules of the pcap library.
166 <example id="AppToolsdumpcapEx">
167 <title>Help information available from dumpcap</title>
169 Dumpcap 1.6.0 (SVN Rev 37205 from /trunk-1.6)
170 Capture network packets and dump them into a libpcap file.
171 See http://www.wireshark.org for more information.
173 Usage: dumpcap [options] ...
176 -i <interface> name or idx of interface (def: first non-loopback)
177 -f <capture filter> packet filter in libpcap filter syntax
178 -s <snaplen> packet snapshot length (def: 65535)
179 -p don't capture in promiscuous mode
180 -B <buffer size> size of kernel buffer (def: 1MB)
181 -y <link type> link layer type (def: first appropriate)
182 -D print list of interfaces and exit
183 -L print list of link-layer types of iface and exit
184 -d print generated BPF code for capture filter
185 -S print statistics for each interface once every second
186 -M for -D, -L, and -S, produce machine-readable output
190 -r don't ignore own RPCAP traffic in capture
191 -u use UDP for RPCAP data transfer
192 -A <user>:<password> use RPCAP password authentication
193 -m <sampling type> use packet sampling
194 count:NUM - capture one packet of every NUM
195 timer:NUM - capture no more than 1 packet in NUM ms
197 -c <packet count> stop after n packets (def: infinite)
198 -a <autostop cond.> ... duration:NUM - stop after NUM seconds
199 filesize:NUM - stop this file after NUM KB
200 files:NUM - stop after NUM files
202 -w <filename> name of file to save (def: tempfile)
203 -g enable group read access on the output file(s)
204 -b <ringbuffer opt.> ... duration:NUM - switch to next file after NUM secs
205 filesize:NUM - switch to next file after NUM KB
206 files:NUM - ringbuffer: replace after NUM files
207 -n use pcapng format instead of pcap
209 -q don't report packet capture counts
210 -v print version information and exit
211 -h display this help and exit
213 Example: dumpcap -i eth0 -a duration:60 -w output.pcap
214 "Capture network packets from interface eth0 until 60s passed into output.pcap"
216 Use Ctrl-C to stop capturing at any time.
222 <section id="AppToolscapinfos">
223 <title><command>capinfos</command>: Print information about capture files
226 Included with Wireshark is a small utility called
227 <command>capinfos</command>, which is a command-line utility to
228 print information about binary capture files.
231 <example id="AppToolscapinfosEx">
232 <title>Help information available from capinfos</title>
234 Capinfos 1.6.0 (SVN Rev 37205 from /trunk-1.6)
235 Prints various information (infos) about capture files.
236 See http://www.wireshark.org for more information.
238 Usage: capinfos [options] <infile> ...
241 -t display the capture file type
242 -E display the capture file encapsulation
243 -H display the SHA1, RMD160, and MD5 hashes of the file
246 -c display the number of packets
247 -s display the size of the file (in bytes)
248 -d display the total length of all packets (in bytes)
249 -l display the packet size limit (snapshot length)
252 -u display the capture duration (in seconds)
253 -a display the capture start time
254 -e display the capture end time
255 -o display the capture file chronological status (True/False)
256 -S display start and end times as seconds
259 -y display average data rate (in bytes/sec)
260 -i display average data rate (in bits/sec)
261 -z display average packet size (in bytes)
262 -x display average packet rate (in packets/sec)
265 -L generate long report (default)
266 -T generate table report
268 Table report options:
269 -R generate header record (default)
270 -r do not generate header record
272 -B separate infos with TAB character (default)
273 -m separate infos with comma (,) character
274 -b separate infos with SPACE character
276 -N do not quote infos (default)
277 -q quote infos with single quotes (')
278 -Q quote infos with double quotes (")
281 -h display this help and exit
282 -C cancel processing if file open fails (default is to continue)
283 -A generate all infos (default)
285 Options are processed from left to right order with later options superceeding
286 or adding to earlier options.
288 If no options are given the default is to display all infos in long report
295 <section id="AppToolsrawshark" >
296 <title><command>rawshark</command>: Dump and analyze network traffic.
299 Rawshark reads a stream of packets from a file or pipe, and prints
300 a line describing its output, followed by a set of matching fields
301 for each packet on stdout.
303 <example id="AppToolsrawsharkEx">
304 <title>Help information available from rawshark</title>
306 Rawshark 1.6.0 (SVN Rev 37205 from /trunk-1.6)
307 Dump and analyze network traffic.
308 See http://www.wireshark.org for more information.
310 Copyright 1998-2011 Gerald Combs <gerald@wireshark.org> and contributors.
311 This is free software; see the source for copying conditions. There is NO
312 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
314 Usage: rawshark [options] ...
317 -r <infile> set the pipe or file name to read from
320 -d <encap:dlt>|<proto:protoname>
321 packet encapsulation or protocol
322 -F <field> field to display
323 -n disable all name resolution (def: all enabled)
324 -N <name resolve flags> enable specific name resolution(s): "mntC"
325 -p use the system's packet header format (which may have 64-bit timestamps)
326 -R <read filter> packet filter in Wireshark display filter syntax
327 -s skip PCAP header on input
329 -l flush output after each packet
330 -S format string for fields (%D - name, %S - stringval, %N numval)
331 -t ad|a|r|d|dd|e output format of time stamps (def: r: rel. to first)
334 -h display this help and exit
335 -o <name>:<value> ... override preference setting
336 -v display version info and exit
341 <section id="AppToolseditcap">
342 <title><command>editcap</command>: Edit capture files</title>
344 Included with Wireshark is a small utility called
345 <command>editcap</command>, which is a command-line utility for
346 working with capture files. Its main function is to remove
347 packets from capture files, but it can also be used to convert
348 capture files from one format to another, as well as to print
349 information about capture files.
353 <example id="AppToolseditcapEx">
354 <title>Help information available from editcap</title>
357 Editcap 1.6.0 (SVN Rev 37205 from /trunk-1.6)
358 Edit and/or translate the format of capture files.
359 See http://www.wireshark.org for more information.
361 Usage: editcap [options] ... <infile> <outfile> [ <packet#>[-<packet#>] ... ]
363 <infile> and <outfile> must both be present.
364 A single packet or a range of packets can be selected.
367 -r keep the selected packets; default is to delete them.
368 -A <start time> only output packets whose timestamp is after (or equal
369 to) the given time (format as YYYY-MM-DD hh:mm:ss).
370 -B <stop time> only output packets whose timestamp is before the
371 given time (format as YYYY-MM-DD hh:mm:ss).
373 Duplicate packet removal:
374 -d remove packet if duplicate (window == 5).
375 -D <dup window> remove packet if duplicate; configurable <dup window>
376 Valid <dup window> values are 0 to 1000000.
377 NOTE: A <dup window> of 0 with -v (verbose option) is
378 useful to print MD5 hashes.
379 -w <dup time window> remove packet if duplicate packet is found EQUAL TO OR
380 LESS THAN <dup time window> prior to current packet.
381 A <dup time window> is specified in relative seconds
384 NOTE: The use of the 'Duplicate packet removal' options with
385 other editcap options except -v may not always work as expected.
386 Specifically the -r, -t or -S options will very likely NOT have the
387 desired effect if combined with the -d, -D or -w.
390 -s <snaplen> truncate each packet to max. <snaplen> bytes of data.
391 -C <choplen> chop each packet by <choplen> bytes. Positive values
392 chop at the packet beginning, negative values at the
394 -t <time adjustment> adjust the timestamp of each packet;
395 <time adjustment> is in relative seconds (e.g. -0.5).
396 -S <strict adjustment> adjust timestamp of packets if necessary to insure
397 strict chronological increasing order. The <strict
398 adjustment> is specified in relative seconds with
399 values of 0 or 0.000001 being the most reasonable.
400 A negative adjustment value will modify timestamps so
401 that each packet's delta time is the absolute value
402 of the adjustment specified. A value of -0 will set
403 all packets to the timestamp of the first packet.
404 -E <error probability> set the probability (between 0.0 and 1.0 incl.)
405 that a particular packet byte will be randomly changed.
408 -c <packets per file> split the packet output to different files
409 based on uniform packet counts
410 with a maximum of <packets per file> each.
411 -i <seconds per file> split the packet output to different files
412 based on uniform time intervals
413 with a maximum of <seconds per file> each.
414 -F <capture type> set the output file type; default is libpcap.
415 an empty "-F" option will list the file types.
416 -T <encap type> set the output file encapsulation type;
417 default is the same as the input file.
418 an empty "-T" option will list the encapsulation types.
421 -h display this help and exit.
423 If -v is used with any of the 'Duplicate Packet
424 Removal' options (-d, -D or -w) then Packet lengths
425 and MD5 hashes are printed to standard-out.
429 <example id="AppToolseditcapEx1">
430 <title>Capture file types available from editcap</title>
434 editcap: option requires an argument -- F
435 editcap: The available capture file types for the "-F" flag are:
436 5views - Accellent 5Views capture
437 btsnoop - Symbian OS btsnoop
438 commview - TamoSoft CommView
439 dct2000 - Catapult DCT2000 trace (.out format)
440 eyesdn - EyeSDN USB S0/E1 ISDN trace format
441 k12text - K12 text file
442 lanalyzer - Novell LANalyzer
443 libpcap - Wireshark/tcpdump/... - libpcap
444 modlibpcap - Modified tcpdump - libpcap
445 netmon1 - Microsoft NetMon 1.x
446 netmon2 - Microsoft NetMon 2.x
447 nettl - HP-UX nettl trace
448 ngsniffer - NA Sniffer (DOS)
449 ngwsniffer_1_1 - NA Sniffer (Windows) 1.1
450 ngwsniffer_2_0 - NA Sniffer (Windows) 2.00x
451 niobserverv - Network Instruments Observer
452 nokialibpcap - Nokia tcpdump - libpcap
453 nseclibpcap - Wireshark - nanosecond libpcap
454 nstrace10 - NetScaler Trace (Version 1.0)
455 nstrace20 - NetScaler Trace (Version 2.0)
456 pcapng - Wireshark - pcapng
457 rf5 - Tektronix K12xx 32-bit .rf5 format
458 rh6_1libpcap - RedHat 6.1 tcpdump - libpcap
460 suse6_3libpcap - SuSE 6.3 tcpdump - libpcap
461 visual - Visual Networks traffic capture
465 <example id="AppToolseditcapEx2">
466 <title>Encapsulation types available from editcap</title>
469 <!-- This kludge is needed since example doesn't break across PDF pages -->
474 editcap: option requires an argument -- T
475 editcap: The available encapsulation types for the "-T" flag are:
476 ap1394 - Apple IP-over-IEEE 1394
478 arcnet_linux - Linux ARCNET
479 ascend - Lucent/Ascend access equipment
481 atm-pdus-untruncated - ATM PDUs - untruncated
482 atm-rfc1483 - RFC 1483 ATM
483 bacnet-ms-tp - BACnet MS/TP
484 ber - ASN.1 Basic Encoding Rules
485 bluetooth-h4 - Bluetooth H4
486 bluetooth-h4-linux - Bluetooth H4 with linux header
487 bluetooth-hci - Bluetooth without transport layer
488 can20b - Controller Area Network 2.0B
490 chdlc-with-direction - Cisco HDLC with Directional Info
491 cosine - CoSine L2 debug log
492 dct2000 - Catapult DCT2000
493 docsis - Data Over Cable Service Interface Specification
494 dpnss_link - Digital Private Signalling System No 1 Link Layer
495 dvbci - DVB-CI (Common Interface)
496 enc - OpenBSD enc(4) encapsulating interface
497 erf - Endace Record File
499 ether-nettl - Ethernet with nettl headers
500 fc2 - Fibre Channel FC-2
501 fc2sof - Fibre Channel FC-2 With Frame Delimiter
503 fddi-nettl - FDDI with nettl headers
504 fddi-swapped - FDDI with bit-swapped MAC addresses
507 frelay-with-direction - Frame Relay with Directional Info
508 gcom-serial - GCOM Serial
509 gcom-tie1 - GCOM TIE1
511 gsm_um - GSM Um Interface
514 ieee-802-11 - IEEE 802.11 Wireless LAN
515 ieee-802-11-avs - IEEE 802.11 plus AVS WLAN header
516 ieee-802-11-netmon - IEEE 802.11 plus Network Monitor radio header
517 ieee-802-11-radio - IEEE 802.11 Wireless LAN with radio information
518 ieee-802-11-radiotap - IEEE 802.11 plus radiotap WLAN header
519 ieee-802-16-mac-cps - IEEE 802.16 MAC Common Part Sublayer
520 ios - Cisco IOS internal
521 ip-over-fc - RFC 2625 IP-over-Fibre Channel
523 ipmb - Intelligent Platform Management Bus
524 ipnet - Solaris IPNET
528 juniper-atm1 - Juniper ATM1
529 juniper-atm2 - Juniper ATM2
530 juniper-chdlc - Juniper C-HDLC
531 juniper-ether - Juniper Ethernet
532 juniper-frelay - Juniper Frame-Relay
533 juniper-ggsn - Juniper GGSN
534 juniper-mlfr - Juniper MLFR
535 juniper-mlppp - Juniper MLPPP
536 juniper-ppp - Juniper PPP
537 juniper-pppoe - Juniper PPPoE
538 juniper-vp - Juniper Voice PIC
539 k12 - K12 protocol analyzer
543 layer1-event - EyeSDN Layer 1 event
544 lin - Local Interconnect Network
545 linux-atm-clip - Linux ATM CLIP
546 linux-sll - Linux cooked-mode capture
548 most - Media Oriented Systems Transport
551 mtp2-with-phdr - MTP2 with pseudoheader
554 nstrace10 - NetScaler Encapsulation 1.0 of Ethernet
555 nstrace20 - NetScaler Encapsulation 2.0 of Ethernet
557 packetlogger - PacketLogger
558 pflog - OpenBSD PF Firewall logs
559 pflog-old - OpenBSD PF Firewall logs, pre-3.4
560 ppi - Per-Packet Information header
562 ppp-with-direction - PPP with Directional Info
563 prism - IEEE 802.11 plus Prism II monitor mode header
564 raw-icmp-nettl - Raw ICMP with nettl headers
565 raw-icmpv6-nettl - Raw ICMPv6 with nettl headers
566 raw-telnet-nettl - Raw telnet with nettl headers
568 rawip-nettl - Raw IP with nettl headers
571 redback - Redback SmartEdge
574 sita-wan - SITA WAN packets
576 socketcan - SocketCAN
577 symantec - Symantec Enterprise Firewall
578 tnef - Transport-Neutral Encapsulation Format
580 tr-nettl - Token Ring with nettl headers
581 tzsp - Tazmen sniffer protocol
583 unknown-nettl - Unknown link-layer type with nettl headers
584 usb - Raw USB packets
585 usb-linux - USB packets with Linux header
586 usb-linux-mmap - USB packets with Linux header and padding
603 whdlc - Wellfleet HDLC
604 wpan - IEEE 802.15.4 Wireless PAN
605 wpan-nofcs - IEEE 802.15.4 Wireless PAN with FCS not present
606 wpan-nonask-phy - IEEE 802.15.4 Wireless PAN non-ASK PHY
607 x25-nettl - X25 with nettl headers
608 x2e-serial - X2E serial line capture
609 x2e-xoraya - X2E Xoraya
616 <section id="AppToolsmergecap">
617 <title><command>mergecap</command>:
618 Merging multiple capture files into one
621 Mergecap is a program that combines multiple saved capture files
622 into a single output file specified by the -w argument. Mergecap
623 knows how to read libpcap capture files, including those of tcpdump.
624 In addition, Mergecap can read capture files from snoop (including
625 Shomiti) and atmsnoop, LanAlyzer, Sniffer (compressed or
626 uncompressed), Microsoft Network Monitor, AIX's iptrace, NetXray,
627 Sniffer Pro, RADCOM's WAN/LAN analyzer, Lucent/Ascend router debug
628 output, HP-UX's nettl, and the dump output from Toshiba's ISDN
629 routers. There is no need to tell Mergecap what type of file you are
630 reading; it will determine the file type by itself. Mergecap is also
631 capable of reading any of these file formats if they are compressed
632 using gzip. Mergecap recognizes this directly from the file; the '.gz'
633 extension is not required for this purpose.
636 By default, it writes the capture file in libpcap format, and writes
637 all of the packets in the input capture files to the output file.
638 The -F flag can be used to specify the format in which to write the
639 capture file; it can write the file in libpcap format (standard
640 libpcap format, a modified format used by some patched versions of
641 libpcap, the format used by Red Hat Linux 6.1, or the format used
642 by SuSE Linux 6.3), snoop format, uncompressed Sniffer format,
643 Microsoft Network Monitor 1.x format, and the format used by
644 Windows-based versions of the Sniffer software.
647 Packets from the input files are merged in chronological order based
648 on each frame's timestamp, unless the -a flag is specified. Mergecap
649 assumes that frames within a single capture file are already stored
650 in chronological order. When the -a flag is specified, packets are
651 copied directly from each input file to the output file, independent
652 of each frame's timestamp.
655 If the -s flag is used to specify a snapshot length, frames in the
656 input file with more captured data than the specified snapshot length
657 will have only the amount of data specified by the snapshot length
658 written to the output file. This may be useful if the program that
659 is to read the output file cannot handle packets larger than a
660 certain size (for example, the versions of snoop in Solaris 2.5.1 and
661 Solaris 2.6 appear to reject Ethernet frames larger than the standard
662 Ethernet MTU, making them incapable of handling gigabit Ethernet
663 captures if jumbo frames were used).
667 If the -T flag is used to specify an encapsulation type, the
668 encapsulation type of the output capture file will be forced to
669 the specified type, rather than being the type appropriate to the
670 encapsulation type of the input capture file. Note that this merely
671 forces the encapsulation type of the output file to be the specified
672 type; the packet headers of the packets will not be translated from the
673 encapsulation type of the input capture file to the specified
674 encapsulation type (for example, it will not translate an Ethernet
675 capture to an FDDI capture if an Ethernet capture is read
676 and '-T fddi' is specified).
678 <example id="AppToolsmergecapEx">
679 <title>Help information available from mergecap</title>
681 Mergecap 1.6.0 (SVN Rev 37205 from /trunk-1.6)
682 Merge two or more capture files into one.
683 See http://www.wireshark.org for more information.
685 Usage: mergecap [options] -w <outfile>|- <infile> ...
688 -a concatenate rather than merge files.
689 default is to merge based on frame timestamps.
690 -s <snaplen> truncate packets to <snaplen> bytes of data.
691 -w <outfile>|- set the output filename to <outfile> or '-' for stdout.
692 -F <capture type> set the output file type; default is libpcap.
693 an empty "-F" option will list the file types.
694 -T <encap type> set the output file encapsulation type;
695 default is the same as the first input file.
696 an empty "-T" option will list the encapsulation types.
699 -h display this help and exit.
704 A simple example merging <filename>dhcp-capture.libpcap</filename>
705 and <filename>imap-1.libpcap</filename> into
706 <filename>outfile.libpcap</filename> is shown below.
708 <example id="AppToolsmergecapExSimple">
709 <title>Simple example of using mergecap</title>
710 <programlisting>$ mergecap -w outfile.libpcap dhcp-capture.libpcap imap-1.libpcap
715 <section id="AppToolstext2pcap" >
716 <title><command>text2pcap</command>: Converting ASCII hexdumps to network
720 There may be some occasions when you wish to convert a hex dump of some
721 network traffic into a libpcap file.</para>
723 <command>Text2pcap</command> is a program that reads in an ASCII hex
724 dump and writes the data described into a libpcap-style capture file.
725 text2pcap can read hexdumps with multiple packets in them, and build a
726 capture file of multiple packets. text2pcap is also capable of
727 generating dummy Ethernet, IP and UDP headers, in order to build fully
728 processable packet dumps from hexdumps of application-level data only.
731 Text2pcap understands a hexdump of the form generated by od -A x -t x1. In
732 other words, each byte is individually displayed and surrounded with a
733 space. Each line begins with an offset describing the position in the
734 file. The offset is a hex number (can also be octal - see -o), of
735 more than two hex digits. Here is a sample dump that text2pcap can
739 000000 00 e0 1e a7 05 6f 00 10 ........
740 000008 5a a0 b9 12 08 00 46 00 ........
741 000010 03 68 00 00 00 00 0a 2e ........
742 000018 ee 33 0f 19 08 7f 0f 19 ........
743 000020 03 80 94 04 00 00 10 01 ........
744 000028 16 a2 0a 00 03 50 00 0c ........
745 000030 01 01 0f 19 03 80 11 01 ........
748 There is no limit on the width or number of bytes per line. Also the
749 text dump at the end of the line is ignored. Bytes/hex numbers can be
750 uppercase or lowercase. Any text before the offset is ignored,
751 including email forwarding characters '>'. Any lines of text
752 between the bytestring lines is ignored. The offsets are used to
753 track the bytes, so offsets must be correct. Any line which has only
754 bytes without a leading offset is ignored. An offset is recognized
755 as being a hex number longer than two characters. Any text after the
756 bytes is ignored (e.g. the character dump). Any hex numbers in this
757 text are also ignored. An offset of zero is indicative of starting a
758 new packet, so a single text file with a series of hexdumps can be
759 converted into a packet capture with multiple packets. Multiple
760 packets are read in with timestamps differing by one second each.
761 In general, short of these restrictions, text2pcap is pretty liberal
762 about reading in hexdumps and has been tested with a variety of mangled
763 outputs (including being forwarded through email multiple times,
764 with limited line wrap etc.)
767 There are a couple of other special features to note. Any line where
768 the first non-whitespace character is '#' will be ignored as a
769 comment. Any line beginning with #TEXT2PCAP is a directive and options
770 can be inserted after this command to be processed by text2pcap.
771 Currently there are no directives implemented; in the future, these
772 may be used to give more fine grained control on the dump and the
773 way it should be processed e.g. timestamps, encapsulation type etc.
776 Text2pcap also allows the user to read in dumps of application-level
777 data, by inserting dummy L2, L3 and L4 headers before each packet.
778 Possibilities include inserting headers such as Ethernet, Ethernet + IP,
779 Ethernet + IP + UDP, or Ethernet + Ip + TCP before each packet.
780 This allows Wireshark or any other full-packet decoder to handle these dumps.
782 <example id="AppToolstext2pcapEx">
783 <title>Help information available for text2pcap</title>
785 Text2pcap 1.6.0 (SVN Rev 37205 from /trunk-1.6)
786 Generate a capture file from an ASCII hexdump of packets.
787 See http://www.wireshark.org for more information.
789 Usage: text2pcap [options] <infile> <outfile>
791 where <infile> specifies input filename (use - for standard input)
792 <outfile> specifies output filename (use - for standard output)
795 -o hex|oct|dec parse offsets as (h)ex, (o)ctal or (d)ecimal;
797 -t <timefmt> treat the text before the packet as a date/time code;
798 the specified argument is a format string of the sort
799 supported by strptime.
800 Example: The time "10:15:14.5476" has the format code
802 NOTE: The subsecond component delimiter, '.', must be
803 given, but no pattern is required; the remaining
804 number is assumed to be fractions of a second.
805 NOTE: Date/time fields from the current date/time are
806 used as the default for unspecified fields.
809 -l <typenum> link-layer type number; default is 1 (Ethernet).
810 See the file net/bpf.h for list of numbers.
811 Use this option if your dump is a complete hex dump
812 of an encapsulated packet and you wish to specify
813 the exact type of encapsulation.
814 Example: -l 7 for ARCNet packets.
815 -m <max-packet> max packet length in output; default is 64000
817 Prepend dummy header:
818 -e <l3pid> prepend dummy Ethernet II header with specified L3PID
820 Example: -e 0x806 to specify an ARP packet.
821 -i <proto> prepend dummy IP header with specified IP protocol
823 Automatically prepends Ethernet header as well.
825 -u <srcp>,<destp> prepend dummy UDP header with specified
826 dest and source ports (in DECIMAL).
827 Automatically prepends Ethernet & IP headers as well.
828 Example: -u 1000,69 to make the packets look like
830 -T <srcp>,<destp> prepend dummy TCP header with specified
831 dest and source ports (in DECIMAL).
832 Automatically prepends Ethernet & IP headers as well.
834 -s <srcp>,<dstp>,<tag> prepend dummy SCTP header with specified
835 dest/source ports and verification tag (in DECIMAL).
836 Automatically prepends Ethernet & IP headers as well.
838 -S <srcp>,<dstp>,<ppi> prepend dummy SCTP header with specified
839 dest/source ports and verification tag 0.
840 Automatically prepends a dummy SCTP DATA
841 chunk header with payload protocol identifier ppi.
845 -h display this help and exit.
846 -d show detailed debug of parser states.
847 -q generate no output at all (automatically turns off -d).
852 <section id="AppToolsidl2wrs" >
853 <title><command>idl2wrs</command>:
854 Creating dissectors from CORBA IDL files
857 In an ideal world idl2wrs would be mentioned in the users guide
858 in passing and documented in the developers guide. As the
860 has not yet been completed it will be documented here.
863 <title>What is it?</title>
865 As you have probably guessed from the name,
866 <command>idl2wrs</command> takes a
867 user specified IDL file and attempts to build a dissector that
868 can decode the IDL traffic over GIOP. The resulting file is
869 "C" code, that should compile okay as a Wireshark dissector.
872 <command>idl2wrs</command> basically parses the data struct given to
873 it by the omniidl compiler, and using the GIOP API available in
874 packet-giop.[ch], generates get_CDR_xxx calls to decode the
875 CORBA traffic on the wire.
877 <para>It consists of 4 main files.</para>
879 <varlistentry><term><filename>README.idl2wrs</filename></term>
881 <para>This document</para>
884 <varlistentry><term><filename>wireshark_be.py</filename></term>
886 <para>The main compiler backend</para>
889 <varlistentry><term><filename>wireshark_gen.py</filename></term>
891 <para>A helper class, that generates the C code.</para>
894 <varlistentry><term><filename>idl2wrs</filename></term>
896 <para> A simple shell script wrapper that the end user should
897 use to generate the dissector from the IDL file(s).</para>
903 <title>Why do this?</title>
905 It is important to understand what CORBA traffic looks
906 like over GIOP/IIOP, and to help build a tool that can assist
907 in troubleshooting CORBA interworking. This was especially the
908 case after seeing a lot of discussions about how particular
909 IDL types are represented inside an octet stream.
912 I have also had comments/feedback that this tool would be good for say
913 a CORBA class when teaching students what CORBA traffic looks like
917 It is also COOL to work on a great Open Source project such as
918 the case with "Wireshark" (
919 <ulink url="&WiresharkWebSite;">&WiresharkWebSite;</ulink>
923 <section><title>How to use idl2wrs</title>
925 To use the idl2wrs to generate Wireshark dissectors, you
929 <title>Prerequisites to using idl2wrs</title>
932 Python must be installed. See
933 <ulink url="http://python.org/"/>
938 omniidl from the omniORB package must be available. See
939 <ulink url="http://omniorb.sourceforge.net/"/>
944 Of course you need Wireshark installed to compile the
945 code and tweak it if required. idl2wrs is part of the
946 standard Wireshark distribution
951 To use idl2wrs to generate an Wireshark dissector from an idl file
952 use the following procedure:
956 Procedure for converting a CORBA idl file into a Wireshark
961 To write the C code to stdout.
962 <programlisting>idl2wrs <your_file.idl></programlisting>
963 e.g.: <programlisting>idl2wrs echo.idl</programlisting>
968 To write to a file, just redirect the output.
969 <programlisting>idl2wrs echo.idl > packet-test-idl.c</programlisting>
970 You may wish to comment out the register_giop_user_module() code
971 and that will leave you with heuristic dissection.
976 If you don't want to use the shell script wrapper, then try
977 steps 3 or 4 instead.</para>
978 <orderedlist continuation="continues">
980 <para>To write the C code to stdout.
981 <programlisting>Usage: omniidl -p ./ -b wireshark_be <your file.idl></programlisting>
983 <programlisting>omniidl -p ./ -b wireshark_be echo.idl</programlisting>
988 To write to a file, just redirect the output.
989 <programlisting>omniidl -p ./ -b wireshark_be echo.idl > packet-test-idl.c</programlisting>
990 You may wish to comment out the register_giop_user_module() code
991 and that will leave you with heuristic dissection.
996 Copy the resulting C code to subdirectory epan/dissectors/ inside your
997 Wireshark source directory.
998 <programlisting>cp packet-test-idl.c /dir/where/wireshark/lives/epan/dissectors/</programlisting>
999 The new dissector has to be added to Makefile.common in the same
1000 directory. Look for the declaration CLEAN_DISSECTOR_SRC and add
1001 the new dissector there. For example,
1003 CLEAN_DISSECTOR_SRC = \
1004 packet-2dparityfec.c \
1005 packet-3com-njack.c \
1010 CLEAN_DISSECTOR_SRC = \
1012 packet-2dparityfec.c \
1013 packet-3com-njack.c \
1018 For the next steps, go up to the top of your Wireshark source directory.
1023 <programlisting>./configure (or ./autogen.sh)</programlisting>
1027 <para> Compile the code
1028 <programlisting>make</programlisting>
1032 <para>Good Luck !!</para>
1036 <section><title>TODO</title>
1040 Exception code not generated (yet), but can be added manually.
1045 Enums not converted to symbolic values (yet), but can be added
1050 <para>Add command line options etc</para>
1053 <para>More I am sure :-)</para>
1057 <section><title>Limitations</title>
1059 See the TODO list inside <filename>packet-giop.c</filename>
1062 <section><title>Notes</title>
1066 The "-p ./" option passed to omniidl indicates that the
1067 wireshark_be.py and wireshark_gen.py are residing in the
1068 current directory. This may need
1069 tweaking if you place these files somewhere else.
1074 If it complains about being unable to find some modules
1076 you may want to check if PYTHONPATH is set correctly.
1077 On my Linux box, it is PYTHONPATH=/usr/lib/python2.4/
1084 <!-- End of WSUG Appendix Tools -->