Further cleanup of Wireshark User Guide
[obnox/wireshark/wip.git] / docbook / wsug_src / WSUG_app_tools.xml
1 <!-- WSUG Appendix Tools -->
2
3 <!-- $Id$ -->
4
5 <appendix id="AppTools">
6   <title>Related command line tools</title>
7   
8   <section id="AppToolsIntroduction">
9     <title>Introduction</title>
10     <para>
11         Beside the Wireshark GUI application, there are some command line tools, 
12         which can be helpful for doing some more specialized things. These tools 
13         will be described in this chapter.
14         </para>
15   </section>
16   
17   <section id="AppToolstcpdump">
18     <title><command>tcpdump</command>: Capturing with tcpdump for viewing 
19         with Wireshark</title>
20     <para>
21       There are occasions when you want to capture packets using 
22       <command>tcpdump</command> rather than <command>wireshark</command>, 
23       especially when you want to do a remote capture and do not want the 
24       network load associated with running Wireshark remotely (not to 
25       mention all the X traffic polluting your capture).
26     </para>
27     <para>
28       However, the default <command>tcpdump</command> parameters result in a 
29       capture file where each packet is truncated, because 
30       <command>tcpdump</command>, by default, does only capture the first 68 
31           bytes of each packet.
32     </para>
33     <para>
34       To ensure that you capture complete packets, use the following command:
35       <programlisting>
36 tcpdump -i &lt;interface> -s 1500 -w &lt;some-file>
37       </programlisting>
38       You will have to specify the correct <command>interface</command> and 
39       the name of a <command>file</command> to save into. In addition, 
40       you will have to terminate the capture with ^C when you believe you 
41       have captured enough packets.
42     </para>
43         <note><title>Note!</title>
44         <para>
45         tcpdump is not part of the Wireshark distribution. You can get it from:
46         <ulink url="&TcpdumpWebsite;">&TcpdumpWebsite;</ulink> for various 
47         platforms.
48         </para>
49         </note>
50   </section>
51   
52   <section id="AppToolstshark">
53     <title><command>TShark</command>: Terminal-based Wireshark</title>
54     <para>
55       <application>TShark</application> is a terminal oriented version 
56       of Wireshark designed for capturing and displaying packets when an 
57           interactive user interface isn't necessary or available. It supports 
58           the same options as <command>wireshark</command>. For more 
59       information on <command>tshark</command>, see the manual pages 
60       (<command>man tshark</command>).
61     </para>
62   </section>
63
64   <section id="AppToolscapinfos">
65     <title><command>capinfos</command>: Print information about capture files
66         </title>
67     <para>
68       Included with Wireshark is a small utility called 
69       <command>capinfos</command>, which is a command-line utility to
70           print information about binary capture files.
71     </para>
72     <para>
73     <example id="AppToolscapinfosEx">
74       <title>Help information available from capinfos</title>
75       <programlisting>  
76 $ capinfos -h
77 Usage: capinfos [-t] [-c] [-s] [-d] [-u] [-a] [-e] [-y]
78                 [-i] [-z] [-h] &lt;capfile&gt;
79   where -t display the capture type of &lt;capfile&gt;
80         -c count the number of packets
81         -s display the size of the file
82         -d display the total length of all packets in the file
83            (in bytes)
84         -u display the capture duration (in seconds)
85         -a display the capture start time
86         -e display the capture end time
87         -y display average data rate (in bytes)
88         -i display average data rate (in bits)
89         -z display average packet size (in bytes)
90         -h produces this help listing.
91
92             If no data flags are given, default is to display all statistics    
93       </programlisting>
94         </example>
95     </para>
96   </section>
97
98   <section id="AppToolseditcap">
99     <title><command>editcap</command>: Edit capture files</title>
100     <para>
101       Included with Wireshark is a small utility called 
102       <command>editcap</command>, which is a command-line utility for 
103       working with capture files.  Its main function is to remove 
104       packets from capture files, but it can also be used to convert 
105       capture files from one format to another, as well as print 
106       information about capture files.
107     </para>
108     <para>
109         
110     <example id="AppToolseditcapEx">
111       <title>Help information available from editcap</title>
112       <programlisting>  
113 $ editcap.exe -h
114 Usage: editcap [-r] [-h] [-v] [-T &lt;encap type>] [-E &lt;probability>]
115                [-F &lt;capture type>]> [-s &lt;snaplen>] [-t &lt;time adjustment>]
116                &lt;infile> &lt;outfile> [ &lt;record#>[-&lt;record#>] ... ]
117   where
118         -E &lt;probability> specifies the probability (between 0 and 1)
119             that a particular byte will will have an error.
120         -F &lt;capture type> specifies the capture file type to write:
121             libpcap - libpcap (tcpdump, Wireshark, etc.)
122             rh6_1libpcap - RedHat Linux 6.1 libpcap (tcpdump)
123             suse6_3libpcap - SuSE Linux 6.3 libpcap (tcpdump)
124             modlibpcap - modified libpcap (tcpdump)
125             nokialibpcap - Nokia libpcap (tcpdump)
126             lanalyzer - Novell LANalyzer
127             ngsniffer - Network Associates Sniffer (DOS-based)
128             snoop - Sun snoop
129             netmon1 - Microsoft Network Monitor 1.x
130             netmon2 - Microsoft Network Monitor 2.x
131             ngwsniffer_1_1 - Network Associates Sniffer (Windows-based) 1.1
132             ngwsniffer_2_0 - Network Associates Sniffer (Windows-based) 2.00x
133             nettl - HP-UX nettl trace
134             visual - Visual Networks traffic capture
135             5views - Accellent 5Views capture
136             niobserverv9 - Network Instruments Observer version 9
137             default is libpcap
138         -h produces this help listing.
139         -r specifies that the records specified should be kept, not deleted,
140                            default is to delete
141         -s &lt;snaplen> specifies that packets should be truncated to
142            &lt;snaplen> bytes of data
143         -t &lt;time adjustment> specifies the time adjustment
144            to be applied to selected packets
145         -T &lt;encap type> specifies the encapsulation type to use:
146             ether - Ethernet
147             tr - Token Ring
148             slip - SLIP
149             ppp - PPP
150             fddi - FDDI
151             fddi-swapped - FDDI with bit-swapped MAC addresses
152             rawip - Raw IP
153             arcnet - ARCNET
154             arcnet_linux - Linux ARCNET
155             atm-rfc1483 - RFC 1483 ATM
156             linux-atm-clip - Linux ATM CLIP
157             lapb - LAPB
158             atm-pdus - ATM PDUs
159             atm-pdus-untruncated - ATM PDUs - untruncated
160             null - NULL
161             ascend - Lucent/Ascend access equipment
162             isdn - ISDN
163             ip-over-fc - RFC 2625 IP-over-Fibre Channel
164             ppp-with-direction - PPP with Directional Info
165             ieee-802-11 - IEEE 802.11 Wireless LAN
166             prism - IEEE 802.11 plus Prism II monitor mode header
167             ieee-802-11-radio - IEEE 802.11 Wireless LAN with radio information
168             ieee-802-11-radiotap - IEEE 802.11 plus radiotap WLAN header
169             ieee-802-11-avs - IEEE 802.11 plus AVS WLAN header
170             linux-sll - Linux cooked-mode capture
171             frelay - Frame Relay
172             frelay-with-direction - Frame Relay with Directional Info
173             chdlc - Cisco HDLC
174             ios - Cisco IOS internal
175             ltalk - Localtalk
176             pflog-old - OpenBSD PF Firewall logs, pre-3.4
177             hhdlc - HiPath HDLC
178             docsis - Data Over Cable Service Interface Specification
179             cosine - CoSine L2 debug log
180             whdlc - Wellfleet HDLC
181             sdlc - SDLC
182             tzsp - Tazmen sniffer protocol
183             enc - OpenBSD enc(4) encapsulating interface
184             pflog - OpenBSD PF Firewall logs
185             chdlc-with-direction - Cisco HDLC with Directional Info
186             bluetooth-h4 - Bluetooth H4
187             mtp2 - SS7 MTP2
188             mtp3 - SS7 MTP3
189             irda - IrDA
190             user0 - USER 0
191             user1 - USER 1
192             user2 - USER 2
193             user3 - USER 3
194             user4 - USER 4
195             user5 - USER 5
196             user6 - USER 6
197             user7 - USER 7
198             user8 - USER 8
199             user9 - USER 9
200             user10 - USER 10
201             user11 - USER 11
202             user12 - USER 12
203             user13 - USER 13
204             user14 - USER 14
205             user15 - USER 15
206             symantec - Symantec Enterprise Firewall
207             ap1394 - Apple IP-over-IEEE 1394
208             bacnet-ms-tp - BACnet MS/TP
209             raw-icmp-nettl - Raw ICMP with nettl headers
210             raw-icmpv6-nettl - Raw ICMPv6 with nettl headers
211             gprs-llc - GPRS LLC
212             juniper-atm1 - Juniper ATM1
213             juniper-atm2 - Juniper ATM2
214             redback - Redback SmartEdge
215             rawip-nettl - Raw IP with nettl headers
216             ether-nettl - Ethernet with nettl headers
217             tr-nettl - Token Ring with nettl headers
218             fddi-nettl - FDDI with nettl headers
219             unknown-nettl - Unknown link-layer type with nettl headers
220             mtp2-with-phdr - MTP2 with pseudoheader
221             juniper-pppoe - Juniper PPPoE
222             gcom-tie1 - GCOM TIE1
223             gcom-serial - GCOM Serial
224             x25-nettl - X25 with nettl headers
225             default is the same as the input file
226         -v specifies verbose operation, default is silent
227
228             A range of records can be specified as well
229       </programlisting> 
230     </example>
231         
232       Where each option has the following meaning:
233       <variablelist>
234         <varlistentry><term><command>-r</command></term>
235           <listitem>
236             <para>
237               This option specifies that the frames listed should be kept, 
238               not deleted. The default is to delete the listed frames.
239             </para>
240           </listitem>
241         </varlistentry>
242         <varlistentry><term><command>-h</command></term>
243           <listitem><para>This option provides help.</para></listitem>
244         </varlistentry>
245         <varlistentry><term><command>-v</command></term>
246           <listitem>
247             <para>
248               This option specifies verbose operation.  The default is 
249               silent operation.
250             </para>
251           </listitem>
252         </varlistentry>
253         <varlistentry><term><command>-T {encap type}</command></term>
254           <listitem>
255             <para>
256               This option specifies the frame encapsulation type to use. 
257             </para>
258             <para>
259               It is mainly for converting funny captures to something 
260               that Wireshark can deal with.
261             </para>
262             <para>
263                   The default frame 
264               encapsulation type is the same as the input encapsulation. 
265             </para>
266           </listitem>
267         </varlistentry>
268
269         <varlistentry><term><command>-F {capture type}</command></term>
270           <listitem>
271             <para>
272               This option specifies the capture file format to write 
273               the output file in.
274             </para>
275             <para>
276               The default is libpcap format.
277             </para>
278           </listitem>
279         </varlistentry>
280         <varlistentry><term><command>-s {snaplen}</command></term>
281           <listitem>
282             <para>
283         Specifies that packets should be truncated to {snaplen} bytes of data.
284                 </para>
285           </listitem>
286         </varlistentry>
287         <varlistentry><term><command>-t {time adjustment}</command></term>
288           <listitem>
289             <para>
290         Specifies the time adjustment to be applied to selected packets.
291                 </para>
292           </listitem>
293         </varlistentry>
294         <varlistentry><term><command>{infile}</command></term>
295           <listitem>
296             <para>
297               This parameter specifies the input file to use. It must be 
298               present.
299             </para>
300           </listitem>
301         </varlistentry>
302         <varlistentry><term><command>{outfile}</command></term>
303           <listitem>
304             <para>
305               This parameter specifies the output file to use. It must 
306               be present.
307             </para>
308           </listitem>
309         </varlistentry>
310         <varlistentry>
311           <term><command>[record#[-][record# ...]]</command></term>
312           <listitem>
313             <para>
314               This optional parameter specifies the records to include 
315               or exclude (depending on the <command>-r</command> option. 
316               You can specify individual records or a range of records.
317             </para>
318           </listitem>
319         </varlistentry>
320       </variablelist>
321     </para>
322   </section>
323   
324   <section id="AppToolsmergecap">
325     <title><command>mergecap</command>: 
326       Merging multiple capture files into one
327     </title>
328     <para>
329       Mergecap is a program that combines multiple saved capture files 
330       into a single output file specified by the -w argument.  Mergecap 
331       knows how to read libpcap capture files, including those of tcpdump.  
332       In addition, Mergecap can read capture files from snoop (including 
333       Shomiti) and atmsnoop, LanAlyzer, Sniffer (compressed or 
334       uncompressed), Microsoft Network Monitor, AIX's iptrace, NetXray, 
335       Sniffer Pro, RADCOM's WAN/LAN analyzer, Lucent/Ascend router debug 
336       output, HP-UX's nettl, and the dump output from Toshiba's ISDN 
337       routers.  There is no need to tell Mergecap what type of file you are 
338       reading; it will determine the file type by itself.  Mergecap is also 
339       capable of reading any of these file formats if they are compressed 
340       using gzip.  Mergecap recognizes this directly from the file; the '.gz' 
341       extension is not required for this purpose.
342     </para>
343     <para>       
344       By default, it writes the capture file in libpcap format, and writes 
345       all of the packets in both input capture files to the output file.  
346       The -F flag can be used to specify the format in which to write the 
347       capture file; it can write the file in libpcap format (standard 
348       libpcap format, a modified format used by some patched versions of 
349       libpcap, the format used by Red Hat Linux 6.1, or the format used 
350       by SuSE Linux 6.3), snoop format, uncompressed Sniffer format, 
351       Microsoft Network Monitor 1.x format, and the format used by 
352       Windows-based versions of the Sniffer software.
353     </para>
354     <para>
355       Packets from the input files are merged in chronological order based
356       on each frame's timestamp, unless the -a flag is specified.  Mergecap
357       assumes that frames within a single capture file are already stored
358       in chronological order.  When the -a flag is specified, packets are
359       copied directly from each input file to the output file, independent
360       of each frame's timestamp.
361     </para>
362     <para>
363       If the -s flag is used to specify a snapshot length, frames in the
364       input file with more captured data than the specified snapshot length
365       will have only the amount of data specified by the snapshot length
366       written to the output file.  This may be useful if the program that
367       is to read the output file cannot handle packets larger than a 
368       certain size (for example, the versions of snoop in Solaris 2.5.1 and
369       Solaris 2.6 appear to reject Ethernet frames larger than the standard
370       Ethernet MTU, making them incapable of handling gigabit Ethernet 
371       captures if jumbo frames were used).
372     </para>
373
374     <para>
375       If the -T flag is used to specify an encapsulation type, the 
376       encapsulation type of the output capture file will be forced to 
377       the specified type, rather than being the type appropriate to the 
378       encapsulation type of the input capture file.  Note that this merely 
379       forces the encapsulation type of the output file to be the specified 
380       type; the packet headers of the packets will not be translated from the
381       encapsulation type of the input capture file to the specified 
382       encapsulation type (for example, it will not translate an Ethernet 
383       capture to an FDDI capture if an Ethernet capture is read 
384       and '-T fddi' is specified).
385     </para>
386     <example id="AppToolsmergecapEx">
387       <title>Help information available from mergecap</title>
388       <programlisting>
389 $ mergecap.exe -h
390 mergecap version 0.10.5
391 Usage: mergecap [-hva] [-s &lt;snaplen&gt;] [-T &lt;encap type&gt;]
392           [-F &lt;capture type&gt;] -w &lt;outfile&gt; &lt;infile&gt; [...]
393
394   where -h produces this help listing.
395         -v verbose operation, default is silent
396         -a files should be concatenated, not merged
397              Default merges based on frame timestamps
398         -s &lt;snaplen&gt;: truncate packets to &lt;snaplen&gt; bytes of data
399         -w &lt;outfile&gt;: sets output filename to &lt;outfile&gt;
400         -T &lt;encap type&gt; encapsulation type to use:
401              ether - Ethernet
402              tr - Token Ring
403              slip - SLIP
404              ppp - PPP
405              fddi - FDDI
406              fddi-swapped - FDDI with bit-swapped MAC addresses
407              rawip - Raw IP
408              arcnet - ARCNET
409              arcnet_linux - Linux ARCNET
410              atm-rfc1483 - RFC 1483 ATM
411              linux-atm-clip - Linux ATM CLIP
412              lapb - LAPB
413              atm-pdus - ATM PDUs
414              atm-pdus-untruncated - ATM PDUs - untruncated
415              null - NULL
416              ascend - Lucent/Ascend access equipment
417              isdn - ISDN
418              ip-over-fc - RFC 2625 IP-over-Fibre Channel
419              ppp-with-direction - PPP with Directional Info
420              ieee-802-11 - IEEE 802.11 Wireless LAN
421              prism - IEEE 802.11 plus Prism II monitor mode header
422              ieee-802-11-radio - IEEE 802.11 Wireless LAN with radio information
423              ieee-802-11-bsd - IEEE 802.11 plus BSD WLAN header
424              ieee-802-11-avs - IEEE 802.11 plus AVS WLAN header
425              linux-sll - Linux cooked-mode capture
426              frelay - Frame Relay
427              frelay-with-direction - Frame Relay with Directional Info
428              chdlc - Cisco HDLC
429              ios - Cisco IOS internal
430              ltalk - Localtalk
431              pflog-old - OpenBSD PF Firewall logs, pre-3.4
432              hhdlc - HiPath HDLC
433              docsis - Data Over Cable Service Interface Specification
434              cosine - CoSine L2 debug log
435              whdlc - Wellfleet HDLC
436              sdlc - SDLC
437              tzsp - Tazmen sniffer protocol
438              enc - OpenBSD enc(4) encapsulating interface
439              pflog - OpenBSD PF Firewall logs
440              chdlc-with-direction - Cisco HDLC with Directional Info
441              bluetooth-h4 - Bluetooth H4
442              mtp2 - SS7 MTP2
443              mtp3 - SS7 MTP3
444              irda - IrDA
445              user0 - USER 0
446              user1 - USER 1
447              user2 - USER 2
448              user3 - USER 3
449              user4 - USER 4
450              user5 - USER 5
451              user6 - USER 6
452              user7 - USER 7
453              user8 - USER 8
454              user9 - USER 9
455              user10 - USER 10
456              user11 - USER 11
457              user12 - USER 12
458              user13 - USER 13
459              user14 - USER 14
460              user15 - USER 15
461              symantec - Symantec Enterprise Firewall
462              ap1394 - Apple IP-over-IEEE 1394
463              bacnet-ms-tp - BACnet MS/TP
464              default is the same as the first input file
465         -F &lt;capture type&gt; capture file type to write:
466              libpcap - libpcap (tcpdump, Wireshark, etc.)
467              rh6_1libpcap - RedHat Linux 6.1 libpcap (tcpdump)
468              suse6_3libpcap - SuSE Linux 6.3 libpcap (tcpdump)
469              modlibpcap - modified libpcap (tcpdump)
470              nokialibpcap - Nokia libpcap (tcpdump)
471              lanalyzer - Novell LANalyzer
472              ngsniffer - Network Associates Sniffer (DOS-based)
473              snoop - Sun snoop
474              netmon1 - Microsoft Network Monitor 1.x
475              netmon2 - Microsoft Network Monitor 2.x
476              ngwsniffer_1_1 - Network Associates Sniffer (Windows-based) 1.1
477              ngwsniffer_2_0 - Network Associates Sniffer (Windows-based) 2.00x
478              visual - Visual Networks traffic capture
479              5views - Accellent 5Views capture
480              niobserverv9 - Network Instruments Observer version 9
481              default is libpcap
482       </programlisting>
483     </example>
484     <variablelist>
485       <varlistentry><term><command>-h</command></term>
486         <listitem>
487           <para>Prints the version and options and exits.</para>
488         </listitem>
489       </varlistentry>
490       <varlistentry><term><command>-v</command></term>
491         <listitem>
492           <para> 
493             Causes <command>mergecap</command> to print a number of messages 
494             while it's working.
495           </para>
496         </listitem>
497       </varlistentry>
498       <varlistentry><term><command>-a</command></term>
499         <listitem>
500           <para>
501             Causes the frame timestamps to be ignored, writing all packets
502             from the first input file followed by all packets from the second
503             input file.  By default, when <command>-a</command> is not 
504             specified, the contents
505             of the input files are merged in chronological order based on
506             each frame's timestamp.  Note: when merging, mergecap assumes
507             that packets within a capture file are already in chronological
508             order.
509           </para>
510         </listitem>
511       </varlistentry>
512       <varlistentry><term><command>-s</command></term>
513         <listitem>
514           <para>Sets the snapshot length to use when writing the data.</para>
515         </listitem>
516       </varlistentry>
517       <varlistentry><term><command>-w</command></term>
518         <listitem>
519           <para>Sets the output filename.</para>
520         </listitem>
521       </varlistentry>
522       <varlistentry><term><command>-T</command></term>
523         <listitem>
524           <para>
525             Sets the packet encapsulation type of the output capture file.
526           </para>
527         </listitem>
528       </varlistentry>
529       <varlistentry><term><command>-F</command></term>
530         <listitem>
531           <para>Sets the file format of the output capture file.</para>
532         </listitem>
533       </varlistentry>
534     </variablelist>
535     <para>
536       A simple example merging <filename>dhcp-capture.libpcap</filename> 
537       and <filename>imap-1.libpcap</filename> into 
538       <filename>outfile.libpcap</filename> is shown below.
539     </para>
540     <example id="AppToolsmergecapExSimple">
541       <title>Simple example of using mergecap</title>
542       <programlisting>$ mergecap -w outfile.libpcap dhcp-capture.libpcap imap-1.libpcap 
543       </programlisting>
544     </example> 
545   </section>
546   
547   <section id="AppToolstext2pcap" >
548     <title><command>text2pcap</command>: Converting ASCII hexdumps to network 
549         captures
550     </title>
551     <para>
552       There may be some occasions when you wish to convert a hex dump of some
553       network traffic into a libpcap file.</para>
554     <para>
555       <command>Text2pcap</command> is a program that reads in an ASCII hex 
556       dump and writes the data described into a libpcap-style capture file. 
557       text2pcap can read hexdumps with multiple packets in them, and build a 
558       capture file of multiple packets. text2pcap is also capable of 
559       generating dummy Ethernet, IP and UDP headers, in order to build fully 
560       processable packet dumps from hexdumps of application-level data only.
561     </para>
562     <para>
563       Text2pcap understands a hexdump of the form generated by od -A x -t x1. In 
564       other words, each byte is individually displayed and surrounded with a 
565       space. Each line begins with an offset describing the position in the 
566       file. The offset is a hex number (can also be octal - see -o), of 
567       more than two hex digits. Here is a sample dump that text2pcap can 
568       recognize:
569     </para>
570     <programlisting>
571 000000 00 e0 1e a7 05 6f 00 10 ........
572 000008 5a a0 b9 12 08 00 46 00 ........
573 000010 03 68 00 00 00 00 0a 2e ........
574 000018 ee 33 0f 19 08 7f 0f 19 ........
575 000020 03 80 94 04 00 00 10 01 ........
576 000028 16 a2 0a 00 03 50 00 0c ........
577 000030 01 01 0f 19 03 80 11 01 ........
578     </programlisting>
579     <para>
580       There is no limit on the width or number of bytes per line. Also the 
581       text dump at the end of the line is ignored. Bytes/hex numbers can be 
582       uppercase or lowercase. Any text before the offset is ignored, 
583       including email forwarding characters '&gt;'. Any lines of text 
584       between the bytestring lines is ignored. The offsets are used to 
585       track the bytes, so offsets must be correct. Any line which has only 
586       bytes without a leading offset is ignored. An offset is recognized 
587       as being a hex number longer than two characters. Any text after the 
588       bytes is ignored (e.g. the character dump). Any hex numbers in this 
589       text are also ignored. An offset of zero is indicative of starting a 
590       new packet, so a single text file with a series of hexdumps can be 
591       converted into a packet capture with multiple packets. Multiple 
592       packets are read in with timestamps differing by one second each. 
593       In general, short of these restrictions, text2pcap is pretty liberal 
594       about reading in hexdumps and has been tested with a variety of mangled 
595       outputs (including being forwarded through email multiple times, 
596       with limited line wrap etc.)
597     </para>
598     <para> 
599       There are a couple of other special features to note. Any line where 
600       the first non-whitespace character is '#' will be ignored as a 
601       comment. Any line beginning with #TEXT2PCAP is a directive and options 
602       can be inserted after this command to be processed by text2pcap. 
603       Currently there are no directives implemented; in the future, these 
604       may be used to give more fine grained control on the dump and the 
605       way it should be processed e.g. timestamps, encapsulation type etc.
606     </para>
607     <para>
608       Text2pcap also allows the user to read in dumps of application-level
609       data, by inserting dummy L2, L3 and L4 headers before each packet.
610       The user can elect to insert Ethernet headers, Ethernet and IP, or
611       Ethernet, IP and UDP headers before each packet. This allows Wireshark
612       or any other full-packet decoder to handle these dumps.
613     </para>
614     <example id="AppToolstext2pcapEx">
615       <title>Help information available for text2pcap</title>
616       <programlisting>
617 $ text2pcap.exe -h
618
619 Usage: text2pcap.exe [-h] [-d] [-q] [-o h|o] [-l typenum] [-e l3pid] [-i proto]
620           [-m max-packet] [-u srcp,destp] [-T srcp,destp] [-s srcp,destp,tag]
621           [-S srcp,destp,tag] [-t timefmt] &lt;input-filename&gt; &lt;output-filename&gt;
622
623 where &lt;input-filename&gt; specifies input filename (use - for standard input)
624       &lt;output-filename&gt; specifies output filename (use - for standard output)
625
626 [options] are one or more of the following
627
628  -h              : Display this help message
629  -d              : Generate detailed debug of parser states
630  -o hex|oct      : Parse offsets as (h)ex or (o)ctal. Default is hex
631  -l typenum      : Specify link-layer type number. Default is 1 (Ethernet).
632                    See net/bpf.h for list of numbers.
633  -q              : Generate no output at all (automatically turns off -d)
634  -e l3pid        : Prepend dummy Ethernet II header with specified L3PID (in
635                    HEX)
636                    Example: -e 0x800
637  -i proto        : Prepend dummy IP header with specified IP protocol (in
638                    DECIMAL).
639                    Automatically prepends Ethernet header as well.
640                    Example: -i 46
641  -m max-packet   : Max packet length in output, default is 64000
642  -u srcp,destp   : Prepend dummy UDP header with specified dest and source ports
643                    (in DECIMAL).
644                    Automatically prepends Ethernet and IP headers as well
645                    Example: -u 30,40
646  -T srcp,destp   : Prepend dummy TCP header with specified dest and source ports
647                    (in DECIMAL).
648                    Automatically prepends Ethernet and IP headers as well
649                    Example: -T 50,60
650  -s srcp,dstp,tag: Prepend dummy SCTP header with specified dest/source ports
651                    and verification tag (in DECIMAL).
652                    Automatically prepends Ethernet and IP headers as well
653                    Example: -s 30,40,34
654  -S srcp,dstp,ppi: Prepend dummy SCTP header with specified dest/source ports
655                    and verification tag 0. It also prepends a dummy SCTP DATA
656                    chunk header with payload protocol identifier ppi.
657                    Example: -S 30,40,34
658  -t timefmt      : Treats the text before the packet as a date/time code; the
659                    specified argument is a format string of the sort supported
660                    by strptime.
661                    Example: The time "10:15:14.5476" has the format code
662                    "%H:%M:%S."
663                    NOTE:    The subsecond component delimiter must be specified
664                             (.) but no pattern is required; the remaining number
665                             is assumed to be fractions of a second.
666       </programlisting>
667     </example>
668     <variablelist>
669       <varlistentry><term><command>-w &lt;filename&gt;</command></term>
670         <listitem>
671           <para>
672             Write the capture file generated by <command>text2pcap</command> 
673             to &lt;filename&gt;.  The default is to write to standard 
674             output.
675           </para>
676         </listitem>
677       </varlistentry>
678       <varlistentry><term><command>-h</command></term>
679         <listitem>
680           <para>Display the help message</para>
681         </listitem>
682       </varlistentry>
683       <varlistentry><term><command>-d</command></term>
684         <listitem>
685           <para>
686             Displays debugging information during the process. Can be 
687             used multiple times to generate more debugging information.
688           </para>
689         </listitem>
690       </varlistentry>
691       <varlistentry><term><command>-q</command></term>
692         <listitem>
693           <para>Be completely quiet during the process.</para>
694         </listitem>
695       </varlistentry>
696       <varlistentry><term><command>-o hex|oct</command></term>
697         <listitem>
698           <para> Specify the radix for the offsets (hex or octal). Defaults to
699             hex. This corresponds to the <command>-A</command> option for od.
700           </para>
701         </listitem>
702       </varlistentry>
703       <varlistentry><term><command>-l</command></term>
704         <listitem>
705           <para> 
706             Specify the link-layer type of this packet. Default is 
707             Ethernet(1). See net/bpf.h for the complete list of possible 
708             encapsulations. Note that this option should be used if your 
709             dump is a complete hex dump of an encapsulated packet and you 
710             wish to specify the exact type of encapsulation. Example: -l 7 
711             for ARCNet packets.
712           </para>
713         </listitem>
714       </varlistentry>
715       <varlistentry><term><command>-e l3pid</command></term>
716         <listitem>
717           <para> 
718             Include a dummy Ethernet header before each packet. Specify the
719             L3PID for the Ethernet header in hex. Use this option if your
720             dump has Layer 3 header and payload (e.g. IP header), but no
721             Layer 2 encapsulation. Example: -e 0x806 to specify an ARP
722             packet.
723           </para>
724           <para>
725             For IP packets, instead of generating a fake Ethernet header you
726             can also use -l 12 to indicate a raw IP packet to Wireshark. Note
727             that -l 12 does not work for any non-IP Layer 3 packet (e.g.
728             ARP), whereas generating a dummy Ethernet header with -e works
729             for any sort of L3 packet.
730           </para>
731         </listitem>
732       </varlistentry>
733       <varlistentry><term><command>-u srcport destport</command></term>
734         <listitem>
735           <para>
736             Include dummy UDP headers before each packet. Specify the 
737             source and destination UDP ports for the packet in decimal. 
738             Use this option if your dump is the UDP payload of a packet but 
739             does not include any UDP, IP or Ethernet headers. Note that this 
740             automatically includes appropriate Ethernet and IP headers with 
741             each packet. Example: -u 1000 69 to make the packets look like 
742             TFTP/UDP packets.
743           </para>
744         </listitem>
745       </varlistentry>
746     </variablelist>
747   </section>
748   
749   <section id="AppToolsidl2wrs" >
750     <title><command>idl2wrs</command>: 
751       Creating dissectors from CORBA IDL files
752     </title>
753     <para>
754       In an ideal world idl2wrs would be mentioned in the users guide 
755       in passing and documented in the developers guide.  As the 
756       developers guide 
757       has not yet been completed it will be documented here.
758     </para>
759     <section>
760       <title>What is it?</title>
761       <para>
762         As you have probably guessed from the name, 
763         <command>idl2wrs</command> takes a
764         user specified IDL file and attempts to build a dissector that
765         can decode the IDL traffic over GIOP. The resulting file is
766         "C" code, that should compile okay as a Wireshark dissector.
767       </para>
768       <para>
769         <command>idl2wrs</command> basically parses the data struct given to 
770         it by the omniidl compiler, and using the GIOP API available in 
771         packet-giop.[ch], generates  get_CDR_xxx calls to decode the 
772         CORBA traffic on the wire.
773       </para>
774       <para>It consists of 4 main files.</para>
775       <variablelist>
776         <varlistentry><term><filename>README.idl2wrs</filename></term>
777           <listitem>
778             <para>This document</para>
779           </listitem>
780         </varlistentry>
781         <varlistentry><term><filename>wireshark_be.py</filename></term>
782           <listitem>
783             <para>The main compiler backend</para>
784           </listitem>
785         </varlistentry>
786         <varlistentry><term><filename>wireshark_gen.py</filename></term>
787           <listitem>
788             <para>A helper class, that generates the C code.</para>
789           </listitem>
790         </varlistentry>
791         <varlistentry><term><filename>idl2wrs</filename></term>
792           <listitem>
793             <para> A simple shell script wrapper that the end user should
794               use to generate the dissector from the IDL file(s).</para>
795           </listitem>
796         </varlistentry>
797       </variablelist>
798     </section>
799     <section>
800       <title>Why do this?</title>
801       <para>
802         It is important to understand what CORBA traffic looks
803         like over GIOP/IIOP, and to help build a tool that can assist
804         in troubleshooting CORBA interworking. This was especially the
805         case after seeing a lot of discussions about how particular
806         IDL types are represented inside an octet stream.
807       </para>
808       <para>
809         I have also had comments/feedback that this tool would be good for say
810         a CORBA class when teaching students what CORBA traffic looks like
811         "on the wire".
812       </para>
813       <para>
814         It is also COOL to work on a great Open Source project such as
815         the case with "Wireshark" (
816         <ulink url="&WiresharkWebSite;">&WiresharkWebSite;</ulink>
817         )
818       </para>
819     </section>
820     <section><title>How to use idl2wrs</title>
821       <para>
822         To use the idl2wrs to generate Wireshark dissectors, you
823         need the following:
824       </para>
825       <orderedlist>
826         <title>Prerequisites to using idl2wrs</title>
827         <listitem>
828           <para>
829             Python must be installed.  See 
830             <ulink url="http://python.org/"/>
831           </para>
832         </listitem>
833         <listitem>
834           <para> 
835             omniidl from the the omniORB package must be available. See
836             <ulink url="http://omniorb.sourceforge.net/"/>
837           </para>
838         </listitem>
839         <listitem>
840           <para>
841             Of course you need Wireshark installed to compile the
842             code and tweak it if required. idl2wrs is part of the 
843             standard Wireshark distribution
844           </para>
845         </listitem>
846       </orderedlist>
847       <para>
848         To use idl2wrs to generate an Wireshark dissector from an idl file 
849         use the following procedure:
850       </para>
851       <orderedlist>
852         <title>
853           Procedure for converting a CORBA idl file into a Wireshark 
854           dissector
855         </title>
856         <listitem>
857           <para>
858             To write the C code to stdout.
859             <programlisting>idl2wrs  &lt;your file.idl&gt;</programlisting>
860             eg: <programlisting>idl2wrs echo.idl</programlisting>
861           </para>
862         </listitem>
863         <listitem>
864           <para>
865             To write to a file, just redirect the output.
866             <programlisting>idl2wrs echo.idl > packet-test-idl.c</programlisting>
867             You may wish to comment out the register_giop_user_module() code 
868             and that will leave you with heuristic dissection.
869           </para>
870         </listitem>
871       </orderedlist>
872       <para>
873         If you don't want to use the shell script wrapper, then try
874         steps 3 or 4 instead.</para>
875       <orderedlist continuation="continues">
876         <listitem>
877           <para>To write the C code to stdout.
878             <programlisting>Usage: omniidl  -p ./ -b wireshark_be &lt;your file.idl&gt;</programlisting>
879             eg:
880             <programlisting>omniidl  -p ./ -b wireshark_be echo.idl</programlisting>
881           </para>
882         </listitem>
883         <listitem>
884           <para>
885             To write to a file, just redirect the output.
886             <programlisting>omniidl  -p ./ -b wireshark_be echo.idl > packet-test-idl.c</programlisting>
887             You may wish to comment out the register_giop_user_module() code
888             and that will leave you with heuristic dissection.
889           </para>
890         </listitem>
891         <listitem>
892           <para>
893             Copy the resulting C code to your Wireshark src directory, 
894             edit the two make files to include the packet-test-idl.c
895             <programlisting>
896 cp packet-test-idl.c /dir/where/wireshark/lives/
897 edit Makefile.am
898 edit Makefile.nmake
899             </programlisting>
900           </para>
901         </listitem>
902         <listitem>
903           <para>Run configure
904             <programlisting>./configure (or ./autogen.sh)</programlisting>
905           </para>
906         </listitem>
907         <listitem>
908           <para> Compile the code
909             <programlisting>make</programlisting>
910           </para>
911         </listitem>
912         <listitem>
913           <para>Good Luck !!</para>
914         </listitem>
915       </orderedlist>
916     </section>
917     <section><title>TODO</title>
918       <orderedlist>
919         <listitem>
920           <para>
921             Exception code not generated  (yet), but can be added manually.
922           </para>
923         </listitem>
924         <listitem>
925           <para> 
926             Enums not converted to symbolic values (yet), but can be added 
927             manually.
928           </para>
929         </listitem>
930         <listitem>
931           <para>Add command line options etc</para>
932         </listitem>
933         <listitem>
934           <para>More I am sure :-)</para>
935         </listitem>
936       </orderedlist>
937     </section>
938     <section><title>Limitations</title>
939       <para>
940         See the TODO list inside <filename>packet-giop.c</filename>
941       </para>
942     </section>
943     <section><title>Notes</title>
944       <orderedlist>
945         <listitem>
946           <para>
947             The "-p ./" option passed to omniidl indicates that the 
948             wireshark_be.py and wireshark_gen.py are residing in the 
949             current directory. This may need
950             tweaking if you place these files somewhere else.
951           </para>
952         </listitem>
953         <listitem>
954           <para>
955             If it complains about being unable to find some modules 
956             (eg tempfile.py), 
957             you may want to check if PYTHONPATH is set correctly.
958             On my Linux box, it is  PYTHONPATH=/usr/lib/python1.5/ 
959           </para>
960         </listitem>
961       </orderedlist>
962     </section>
963   </section>
964 </appendix>
965 <!-- End of WSUG Appendix Tools -->
966
967