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>ethereal</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="http://www.tcpdump.org">http://www.tcpdump.org</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 ethereal 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>ethereal</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 -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 an ethereal 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>ethereal_be.py</filename></term>
 782           <listitem>
 783             <para>The main compiler backend</para>
 784           </listitem>
 785         </varlistentry>
 786         <varlistentry><term><filename>ethereal_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="http://www.ethereal.com">http://www.ethereal.com</ulink>
 817         )
 818       </para>
 819     </section>
 820     <section><title>How to use idl2wrs</title>
 821       <para>
 822         To use the idl2wrs to generate ethereal 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 ethereal 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 ethereal 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 an ethereal
 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 ethereal_be &lt;your file.idl&gt;</programlisting>
 879             eg:
 880             <programlisting>omniidl  -p ./ -b ethereal_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 ethereal_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 ethereal src directory,
 894             edit the 2 make files to include the packet-test-idl.c
 895             <programlisting>
 896 cp packet-test-idl.c /dir/where/ethereal/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             ethereal_be.py and ethereal_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