docbook/eug_src/EUG_app_tools.xml

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