diff options
Diffstat (limited to 'docbook/ug-src/EUG_app_tools.xml')
| -rw-r--r-- | docbook/ug-src/EUG_app_tools.xml | 914 |
1 files changed, 914 insertions, 0 deletions
diff --git a/docbook/ug-src/EUG_app_tools.xml b/docbook/ug-src/EUG_app_tools.xml new file mode 100644 index 0000000000..eff1a5e393 --- /dev/null +++ b/docbook/ug-src/EUG_app_tools.xml @@ -0,0 +1,914 @@ +<!-- EUG Appendix Tools -->
+<appendix id="AppTools">
+ <title>Related command line tools</title>
+
+ <section id="AppToolsIntroduction">
+ <title>Introduction</title>
+ <para>
+ Beside the Ethereal GUI application, there are some command line tools,
+ which can be helpful for some more specialized things to do. These tools
+ will be described in this chapter.
+ </para>
+ </section>
+
+ <section id="AppToolstcpdump">
+ <title>tcpdump: Capturing with tcpdump for viewing with Ethereal</title>
+ <para>
+ There are occasions when you want to capture packets using
+ <command>tcpdump</command> rather than <command>ethereal</command>,
+ especially when you want to do a remote capture and do not want the
+ network load associated with running Ethereal remotely (not to
+ mention all the X traffic polluting your capture).
+ </para>
+ <para>
+ However, the default <command>tcpdump</command> parameters result in a
+ capture file where each packet is truncated, because
+ <command>tcpdump</command>, by default, does only capture the first 68
+ bytes of each packet.
+ </para>
+ <para>
+ To ensure that you capture complete packets, use the following command:
+ <programlisting>
+tcpdump -i <interface> -s 1500 -w <some-file>
+ </programlisting>
+ You will have to specify the correct <command>interface</command> and
+ the name of a <command>file</command> to save into. In addition,
+ you will have to terminate the capture with ^C when you believe you
+ have captured enough packets.
+ </para>
+ <note><title>Note!</title>
+ <para>
+ tcpdump is not part of the Ethereal distribution. You can get it from:
+ <ulink url="http://www.tcpdump.org">http://www.tcpdump.org</ulink> for various
+ platforms.
+ </para>
+ </note>
+ </section>
+
+ <section id="AppToolstethereal">
+ <title>tethereal: Terminal-based Ethereal</title>
+ <para>
+ <application>Tethereal</application> is a terminal oriented version
+ of ethereal designed for capturing and displaying packets when you
+ do not have a graphical environment available. It is command line
+ oriented only and will not show an SAA like user interface. It supports
+ the same option set that <command>ethereal</command> does. For more
+ information on <command>tethereal</command>, see the manual pages
+ (<command>man tethereal</command>).
+ </para>
+ </section>
+
+ <section id="AppToolseditcap">
+ <title>editcap: Edit capture files</title>
+ <para>
+ Included with Ethereal is a small utility called
+ <command>editcap</command>, which is a command-line utility for
+ working with capture files. Its main function is to remove
+ packets from capture file, but it can also be used to convert
+ capture files from one format to another, as well as print
+ information about capture files.
+ </para>
+ <para>
+
+ <example id="AppToolseditcapEx">
+ <title>Help information available from editcap</title>
+ <programlisting>
+$ editcap.exe -h
+Usage: editcap [-r] [-h] [-v] [-T <encap type>] [-F <capture type>]
+ [-s <snaplen>] [-t <time adjustment>]
+ <infile> <outfile> [ <record#>[-<record#>] ... ]
+ where -r specifies that the records specified should be kept, not deleted,
+ default is to delete
+ -v specifies verbose operation, default is silent
+ -h produces this help listing.
+ -T <encap type> specifies the encapsulation type to use:
+ ether - Ethernet
+ tr - Token Ring
+ slip - SLIP
+ ppp - PPP
+ fddi - FDDI
+ fddi-swapped - FDDI with bit-swapped MAC addresses
+ rawip - Raw IP
+ arcnet - ARCNET
+ arcnet_linux - Linux ARCNET
+ atm-rfc1483 - RFC 1483 ATM
+ linux-atm-clip - Linux ATM CLIP
+ lapb - LAPB
+ atm-pdus - ATM PDUs
+ atm-pdus-untruncated - ATM PDUs - untruncated
+ null - NULL
+ ascend - Lucent/Ascend access equipment
+ isdn - ISDN
+ ip-over-fc - RFC 2625 IP-over-Fibre Channel
+ ppp-with-direction - PPP with Directional Info
+ ieee-802-11 - IEEE 802.11 Wireless LAN
+ prism - IEEE 802.11 plus Prism II monitor mode header
+ ieee-802-11-radio - IEEE 802.11 Wireless LAN with radio information
+ ieee-802-11-bsd - IEEE 802.11 plus BSD WLAN header
+ ieee-802-11-avs - IEEE 802.11 plus AVS WLAN header
+ linux-sll - Linux cooked-mode capture
+ frelay - Frame Relay
+ frelay-with-direction - Frame Relay with Directional Info
+ chdlc - Cisco HDLC
+ ios - Cisco IOS internal
+ ltalk - Localtalk
+ pflog-old - OpenBSD PF Firewall logs, pre-3.4
+ hhdlc - HiPath HDLC
+ docsis - Data Over Cable Service Interface Specification
+ cosine - CoSine L2 debug log
+ whdlc - Wellfleet HDLC
+ sdlc - SDLC
+ tzsp - Tazmen sniffer protocol
+ enc - OpenBSD enc(4) encapsulating interface
+ pflog - OpenBSD PF Firewall logs
+ chdlc-with-direction - Cisco HDLC with Directional Info
+ bluetooth-h4 - Bluetooth H4
+ mtp2 - SS7 MTP2
+ mtp3 - SS7 MTP3
+ irda - IrDA
+ user0 - USER 0
+ user1 - USER 1
+ user2 - USER 2
+ user3 - USER 3
+ user4 - USER 4
+ user5 - USER 5
+ user6 - USER 6
+ user7 - USER 7
+ user8 - USER 8
+ user9 - USER 9
+ user10 - USER 10
+ user11 - USER 11
+ user12 - USER 12
+ user13 - USER 13
+ user14 - USER 14
+ user15 - USER 15
+ symantec - Symantec Enterprise Firewall
+ ap1394 - Apple IP-over-IEEE 1394
+ bacnet-ms-tp - BACnet MS/TP
+ default is the same as the input file
+ -F <capture type> specifies the capture file type to write:
+ libpcap - libpcap (tcpdump, Ethereal, etc.)
+ rh6_1libpcap - RedHat Linux 6.1 libpcap (tcpdump)
+ suse6_3libpcap - SuSE Linux 6.3 libpcap (tcpdump)
+ modlibpcap - modified libpcap (tcpdump)
+ nokialibpcap - Nokia libpcap (tcpdump)
+ lanalyzer - Novell LANalyzer
+ ngsniffer - Network Associates Sniffer (DOS-based)
+ snoop - Sun snoop
+ netmon1 - Microsoft Network Monitor 1.x
+ netmon2 - Microsoft Network Monitor 2.x
+ ngwsniffer_1_1 - Network Associates Sniffer (Windows-based) 1.1
+ ngwsniffer_2_0 - Network Associates Sniffer (Windows-based) 2.00x
+ visual - Visual Networks traffic capture
+ 5views - Accellent 5Views capture
+ niobserverv9 - Network Instruments Observer version 9
+ default is libpcap
+ -s <snaplen> specifies that packets should be truncated to
+ <snaplen> bytes of data
+ -t <time adjustment> specifies the time adjustment
+ to be applied to selected packets
+
+ A range of records can be specified as well
+ </programlisting>
+ </example>
+
+ Where each option has the following meaning:
+ <variablelist>
+ <varlistentry><term><command>-r</command></term>
+ <listitem>
+ <para>
+ This option specifies that the frames listed should be kept,
+ not deleted. The default is to delete the listed frames.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-h</command></term>
+ <listitem><para>This option provides help.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><command>-v</command></term>
+ <listitem>
+ <para>
+ This option specifies verbose operation. The default is
+ silent operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-T {encap type}</command></term>
+ <listitem>
+ <para>
+ This option specifies the frame encapsulation type to use.
+ </para>
+ <para>
+ It is mainly for converting funny captures to something
+ that Ethereal can deal with.
+ </para>
+ <para>
+ The default frame
+ encapsulation type is the same as the input encapsulation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><command>-F {capture type}</command></term>
+ <listitem>
+ <para>
+ This option specifies the capture file format to write
+ the output file in.
+ </para>
+ <para>
+ The default is libpcap format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-s {snaplen}</command></term>
+ <listitem>
+ <para>
+ Specifies that packets should be truncated to {snaplen} bytes of data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-t {time adjustment}</command></term>
+ <listitem>
+ <para>
+ Specifies the time adjustment to be applied to selected packets.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>{infile}</command></term>
+ <listitem>
+ <para>
+ This parameter specifies the input file to use. It must be
+ present.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>{outfile}</command></term>
+ <listitem>
+ <para>
+ This parameter specifies the output file to use. It must
+ be present.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>[record#[-][record# ...]]</command></term>
+ <listitem>
+ <para>
+ This optional parameter specifies the records to include
+ or exclude (depending on the <command>-r</command> option.
+ You can specify individual records or a range of records.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </section>
+
+ <section id="AppToolsmergecap">
+ <title>mergecap:
+ Merging multiple capture files into one with
+ <command>mergecap</command>
+ </title>
+ <para>
+ Mergecap is a program that combines multiple saved capture files
+ into a single output file specified by the -w argument. Mergecap
+ knows how to read libpcap capture files, including those of tcpdump.
+ In addition, Mergecap can read capture files from snoop (including
+ Shomiti) and atmsnoop, LanAlyzer, Sniffer (compressed or
+ uncompressed), Microsoft Network Monitor, AIX's iptrace, NetXray,
+ Sniffer Pro, RADCOM's WAN/LAN analyzer, Lucent/Ascend router debug
+ output, HP-UX's nettl, and the dump output from Toshiba's ISDN
+ routers. There is no need to tell Mergecap what type of file you are
+ reading; it will determine the file type by itself. Mergecap is also
+ capable of reading any of these file formats if they are compressed
+ using gzip. Mergecap recognizes this directly from the file; the '.gz'
+ extension is not required for this purpose.
+ </para>
+ <para>
+ By default, it writes the capture file in libpcap format, and writes
+ all of the packets in both input capture files to the output file.
+ The -F flag can be used to specify the format in which to write the
+ capture file; it can write the file in libpcap format (standard
+ libpcap format, a modified format used by some patched versions of
+ libpcap, the format used by Red Hat Linux 6.1, or the format used
+ by SuSE Linux 6.3), snoop format, uncompressed Sniffer format,
+ Microsoft Network Monitor 1.x format, and the format used by
+ Windows-based versions of the Sniffer software.
+ </para>
+ <para>
+ Packets from the input files are merged in chronological order based
+ on each frame's timestamp, unless the -a flag is specified. Mergecap
+ assumes that frames within a single capture file are already stored
+ in chronological order. When the -a flag is specified, packets are
+ copied directly from each input file to the output file, independent
+ of each frame's timestamp.
+ </para>
+ <para>
+ If the -s flag is used to specify a snapshot length, frames in the
+ input file with more captured data than the specified snapshot length
+ will have only the amount of data specified by the snapshot length
+ written to the output file. This may be useful if the program that
+ is to read the output file cannot handle packets larger than a
+ certain size (for example, the versions of snoop in Solaris 2.5.1 and
+ Solaris 2.6 appear to reject Ethernet frames larger than the standard
+ Ethernet MTU, making them incapable of handling gigabit Ethernet
+ captures if jumbo frames were used).
+ </para>
+
+ <para>
+ If the -T flag is used to specify an encapsulation type, the
+ encapsulation type of the output capture file will be forced to
+ the specified type, rather than being the type appropriate to the
+ encapsulation type of the input capture file. Note that this merely
+ forces the encapsulation type of the output file to be the specified
+ type; the packet headers of the packets will not be translated from the
+ encapsulation type of the input capture file to the specified
+ encapsulation type (for example, it will not translate an Ethernet
+ capture to an FDDI capture if an Ethernet capture is read
+ and '-T fddi' is specified).
+ </para>
+ <example id="AppToolsmergecapEx">
+ <title>Help information available from mergecap</title>
+ <programlisting>
+$ mergecap.exe -h
+mergecap version 0.10.5
+Usage: mergecap [-hva] [-s <snaplen>] [-T <encap type>]
+ [-F <capture type>] -w <outfile> <infile> [...]
+
+ where -h produces this help listing.
+ -v verbose operation, default is silent
+ -a files should be concatenated, not merged
+ Default merges based on frame timestamps
+ -s <snaplen>: truncate packets to <snaplen> bytes of data
+ -w <outfile>: sets output filename to <outfile>
+ -T <encap type> encapsulation type to use:
+ ether - Ethernet
+ tr - Token Ring
+ slip - SLIP
+ ppp - PPP
+ fddi - FDDI
+ fddi-swapped - FDDI with bit-swapped MAC addresses
+ rawip - Raw IP
+ arcnet - ARCNET
+ arcnet_linux - Linux ARCNET
+ atm-rfc1483 - RFC 1483 ATM
+ linux-atm-clip - Linux ATM CLIP
+ lapb - LAPB
+ atm-pdus - ATM PDUs
+ atm-pdus-untruncated - ATM PDUs - untruncated
+ null - NULL
+ ascend - Lucent/Ascend access equipment
+ isdn - ISDN
+ ip-over-fc - RFC 2625 IP-over-Fibre Channel
+ ppp-with-direction - PPP with Directional Info
+ ieee-802-11 - IEEE 802.11 Wireless LAN
+ prism - IEEE 802.11 plus Prism II monitor mode header
+ ieee-802-11-radio - IEEE 802.11 Wireless LAN with radio information
+ ieee-802-11-bsd - IEEE 802.11 plus BSD WLAN header
+ ieee-802-11-avs - IEEE 802.11 plus AVS WLAN header
+ linux-sll - Linux cooked-mode capture
+ frelay - Frame Relay
+ frelay-with-direction - Frame Relay with Directional Info
+ chdlc - Cisco HDLC
+ ios - Cisco IOS internal
+ ltalk - Localtalk
+ pflog-old - OpenBSD PF Firewall logs, pre-3.4
+ hhdlc - HiPath HDLC
+ docsis - Data Over Cable Service Interface Specification
+ cosine - CoSine L2 debug log
+ whdlc - Wellfleet HDLC
+ sdlc - SDLC
+ tzsp - Tazmen sniffer protocol
+ enc - OpenBSD enc(4) encapsulating interface
+ pflog - OpenBSD PF Firewall logs
+ chdlc-with-direction - Cisco HDLC with Directional Info
+ bluetooth-h4 - Bluetooth H4
+ mtp2 - SS7 MTP2
+ mtp3 - SS7 MTP3
+ irda - IrDA
+ user0 - USER 0
+ user1 - USER 1
+ user2 - USER 2
+ user3 - USER 3
+ user4 - USER 4
+ user5 - USER 5
+ user6 - USER 6
+ user7 - USER 7
+ user8 - USER 8
+ user9 - USER 9
+ user10 - USER 10
+ user11 - USER 11
+ user12 - USER 12
+ user13 - USER 13
+ user14 - USER 14
+ user15 - USER 15
+ symantec - Symantec Enterprise Firewall
+ ap1394 - Apple IP-over-IEEE 1394
+ bacnet-ms-tp - BACnet MS/TP
+ default is the same as the first input file
+ -F <capture type> capture file type to write:
+ libpcap - libpcap (tcpdump, Ethereal, etc.)
+ rh6_1libpcap - RedHat Linux 6.1 libpcap (tcpdump)
+ suse6_3libpcap - SuSE Linux 6.3 libpcap (tcpdump)
+ modlibpcap - modified libpcap (tcpdump)
+ nokialibpcap - Nokia libpcap (tcpdump)
+ lanalyzer - Novell LANalyzer
+ ngsniffer - Network Associates Sniffer (DOS-based)
+ snoop - Sun snoop
+ netmon1 - Microsoft Network Monitor 1.x
+ netmon2 - Microsoft Network Monitor 2.x
+ ngwsniffer_1_1 - Network Associates Sniffer (Windows-based) 1.1
+ ngwsniffer_2_0 - Network Associates Sniffer (Windows-based) 2.00x
+ visual - Visual Networks traffic capture
+ 5views - Accellent 5Views capture
+ niobserverv9 - Network Instruments Observer version 9
+ default is libpcap
+ </programlisting>
+ </example>
+ <variablelist>
+ <varlistentry><term><command>-h</command></term>
+ <listitem>
+ <para>Prints the version and options and exits.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-v</command></term>
+ <listitem>
+ <para>
+ Causes <command>mergecap</command> to print a number of messages
+ while it's working.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-a</command></term>
+ <listitem>
+ <para>
+ Causes the frame timestamps to be ignored, writing all packets
+ from the first input file followed by all packets from the second
+ input file. By default, when <command>-a</command> is not
+ specified, the contents
+ of the input files are merged in chronological order based on
+ each frame's timestamp. Note: when merging, mergecap assumes
+ that packets within a capture file are already in chronological
+ order.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-s</command></term>
+ <listitem>
+ <para>Sets the snapshot length to use when writing the data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-w</command></term>
+ <listitem>
+ <para>Sets the output filename.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-T</command></term>
+ <listitem>
+ <para>
+ Sets the packet encapsulation type of the output capture file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-F</command></term>
+ <listitem>
+ <para>Sets the file format of the output capture file.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ A simple example merging <filename>dhcp-capture.libpcap</filename>
+ and <filename>imap-1.libpcap</filename> into
+ <filename>outfile.libpcap</filename> is shown below.
+ </para>
+ <example id="AppToolsmergecapExSimple">
+ <title>Simple example of using mergecap</title>
+ <programlisting>$ mergecap -w outfile.libpcap dhcp-capture.libpcap imap-1.libpcap
+ </programlisting>
+ </example>
+ </section>
+
+ <section id="AppToolstext2pcap" >
+ <title>text2pcap: Converting ASCII hexdumps to network captures with
+ <command>text2pcap</command>
+ </title>
+ <para>
+ There may be some occasions when you wish to convert a hex dump of some
+ network traffic into a libpcap file.</para>
+ <para>
+ <command>Text2pcap</command> is a program that reads in an ASCII hex
+ dump and writes the data described into a libpcap-style capture file.
+ text2pcap can read hexdumps withmultiple packets in them, and build a
+ capture file of multiple packets. text2pcap is also capable of
+ generating dummy Ethernet, IP and UDP headers, in order to build fully
+ processable packet dumps from hexdumps of application-level data only.
+ </para>
+ <para>
+ Text2pcap understands a hexdump of the form generated by od -t x1. In
+ other words, each byte is individually displayed and surrounded with a
+ space. Each line begins with an offset describing the position in the
+ file. The offset is a hex number (can also be octal - see -o), of
+ more than two hex digits. Here is a sample dump that text2pcap can
+ recognize:
+ </para>
+ <programlisting>
+000000 00 e0 1e a7 05 6f 00 10 ........
+000008 5a a0 b9 12 08 00 46 00 ........
+000010 03 68 00 00 00 00 0a 2e ........
+000018 ee 33 0f 19 08 7f 0f 19 ........
+000020 03 80 94 04 00 00 10 01 ........
+000028 16 a2 0a 00 03 50 00 0c ........
+000030 01 01 0f 19 03 80 11 01 ........
+ </programlisting>
+ <para>
+ There is no limit on the width or number of bytes per line. Also the
+ text dump at the end of the line is ignored. Bytes/hex numbers can be
+ uppercase or lowercase. Any text before the offset is ignored,
+ including email forwarding characters '>'. Any lines of text
+ between the bytestring lines is ignored. The offsets are used to
+ track the bytes, so offsets must be correct. Any line which has only
+ bytes without a leading offset is ignored. An offset is recognized
+ as being a hex number longer than two characters. Any text after the
+ bytes is ignored (e.g. the character dump). Any hex numbers in this
+ text are also ignored. An offset of zero is indicative of starting a
+ new packet, so a single text file with a series of hexdumps can be
+ converted into a packet capture with multiple packets. Multiple
+ packets are read in with timestamps differing by one second each.
+ In general, short of these restrictions, text2pcap is pretty liberal
+ about reading in hexdumps and has been tested with a variety of mangled
+ outputs (including being forwarded through email multiple times,
+ with limited line wrap etc.)
+ </para>
+ <para>
+ There are a couple of other special features to note. Any line where
+ the first non-whitespace character is '#' will be ignored as a
+ comment. Any line beginning with #TEXT2PCAP is a directive and options
+ can be inserted after this command to be processed by text2pcap.
+ Currently there are no directives implemented; in the future, these
+ may be used to give more fine grained control on the dump and the
+ way it should be processed e.g. timestamps, encapsulation type etc.
+ </para>
+ <para>
+ Text2pcap also allows the user to read in dumps of application-level
+ data, by inserting dummy L2, L3 and L4 headers before each packet.
+ The user can elect to insert Ethernet headers, Ethernet and IP, or
+ Ethernet, IP and UDP headers before each packet. This allows Ethereal
+ or any other full-packet decoder to handle these dumps.
+ </para>
+ <example id="AppToolstext2pcapEx">
+ <title>Help information available for text2pcap</title>
+ <programlisting>
+$ text2pcap.exe -h
+
+Usage: text2pcap.exe [-h] [-d] [-q] [-o h|o] [-l typenum] [-e l3pid] [-i proto]
+ [-m max-packet] [-u srcp,destp] [-T srcp,destp] [-s srcp,destp,tag]
+ [-S srcp,destp,tag] [-t timefmt] <input-filename> <output-filename>
+
+where <input-filename> specifies input filename (use - for standard input)
+ <output-filename> specifies output filename (use - for standard output)
+
+[options] are one or more of the following
+
+ -h : Display this help message
+ -d : Generate detailed debug of parser states
+ -o hex|oct : Parse offsets as (h)ex or (o)ctal. Default is hex
+ -l typenum : Specify link-layer type number. Default is 1 (Ethernet).
+ See net/bpf.h for list of numbers.
+ -q : Generate no output at all (automatically turns off -d)
+ -e l3pid : Prepend dummy Ethernet II header with specified L3PID (in
+ HEX)
+ Example: -e 0x800
+ -i proto : Prepend dummy IP header with specified IP protocol (in
+ DECIMAL).
+ Automatically prepends Ethernet header as well.
+ Example: -i 46
+ -m max-packet : Max packet length in output, default is 64000
+ -u srcp,destp : Prepend dummy UDP header with specified dest and source ports
+ (in DECIMAL).
+ Automatically prepends Ethernet and IP headers as well
+ Example: -u 30,40
+ -T srcp,destp : Prepend dummy TCP header with specified dest and source ports
+ (in DECIMAL).
+ Automatically prepends Ethernet and IP headers as well
+ Example: -T 50,60
+ -s srcp,dstp,tag: Prepend dummy SCTP header with specified dest/source ports
+ and verification tag (in DECIMAL).
+ Automatically prepends Ethernet and IP headers as well
+ Example: -s 30,40,34
+ -S srcp,dstp,ppi: Prepend dummy SCTP header with specified dest/source ports
+ and verification tag 0. It also prepends a dummy SCTP DATA
+ chunk header with payload protocol identifier ppi.
+ Example: -S 30,40,34
+ -t timefmt : Treats the text before the packet as a date/time code; the
+ specified argument is a format string of the sort supported
+ by strptime.
+ Example: The time "10:15:14.5476" has the format code
+ "%H:%M:%S."
+ NOTE: The subsecond component delimiter must be specified
+ (.) but no pattern is required; the remaining number
+ is assumed to be fractions of a second.
+ </programlisting>
+ </example>
+ <variablelist>
+ <varlistentry><term><command>-w <filename></command></term>
+ <listitem>
+ <para>
+ Write the capture file generated by <command>text2pcap</command>
+ to <filename>. The default is to write to standard
+ output.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-h</command></term>
+ <listitem>
+ <para>Display the help message</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-d</command></term>
+ <listitem>
+ <para>
+ Displays debugging information during the process. Can be
+ used multiple times to generate more debugging information.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-q</command></term>
+ <listitem>
+ <para>Be completely quiet during the process.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-o hex|oct</command></term>
+ <listitem>
+ <para> Specify the radix for the offsets (hex or octal). Defaults to
+ hex. This corresponds to the <command>-A</command> option for od.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-l</command></term>
+ <listitem>
+ <para>
+ Specify the link-layer type of this packet. Default is
+ Ethernet(1). See net/bpf.h for the complete list of possible
+ encapsulations. Note that this option should be used if your
+ dump is a complete hex dump of an encapsulated packet and you
+ wish to specify the exact type of encapsulation. Example: -l 7
+ for ARCNet packets.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-e l3pid</command></term>
+ <listitem>
+ <para>
+ Include a dummy Ethernet header before each packet. Specify the
+ L3PID for the Ethernet header in hex. Use this option if your
+ dump has Layer 3 header and payload (e.g. IP header), but no
+ Layer 2 encapsulation. Example: -e 0x806 to specify an ARP
+ packet.
+ </para>
+ <para>
+ For IP packets, instead of generating a fake Ethernet header you
+ can also use -l 12 to indicate a raw IP packet to Ethereal. Note
+ that -l 12 does not work for any non-IP Layer 3 packet (e.g.
+ ARP), whereas generating a dummy Ethernet header with -e works
+ for any sort of L3 packet.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><command>-u srcport destport</command></term>
+ <listitem>
+ <para>
+ Include dummy UDP headers before each packet. Specify the
+ source and destination UDP ports for the packet in decimal.
+ Use this option if your dump is the UDP payload of a packet but
+ does not include any UDP, IP or Ethernet headers. Note that this
+ automatically includes appropriate Ethernet and IP headers with
+ each packet. Example: -u 1000 69 to make the packets look like
+ TFTP/UDP packets.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="AppToolsidl2eth" >
+ <title>idl2eth:
+ Creating dissectors from Corba IDL files with
+ <command>idl2eth</command>
+ </title>
+ <para>
+ In an ideal world idl2eth would be mentioned in the users guide
+ in passing and documented in the developers guide. As the
+ developers guide
+ has not yet been completed it will be documented here.
+ </para>
+ <section>
+ <title>What is it?</title>
+ <para>
+ As you have probably guessed from the name,
+ <command>idl2eth</command> takes a
+ user specified IDL file and attempts to build a dissector that
+ can decode the IDL traffic over GIOP. The resulting file is
+ "C" code, that should compile okay as an ethereal dissector.
+ </para>
+ <para>
+ <command>idl2eth</command>basically parses the data struct given to
+ it by the omniidl compiler, and using the GIOP API available in
+ packet-giop.[ch], generates get_CDR_xxx calls to decode the
+ CORBA traffic on the wire.
+ </para>
+ <para>It consists of 4 main files.</para>
+ <variablelist>
+ <varlistentry><term><filename>README.idl2eth</filename></term>
+ <listitem>
+ <para>This document</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><filename>ethereal_be.py</filename></term>
+ <listitem>
+ <para>The main compiler backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><filename>ethereal_gen.py</filename></term>
+ <listitem>
+ <para>A helper class, that generates the C code.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><filename>idl2eth</filename></term>
+ <listitem>
+ <para> A simple shell script wrapper that the end user should
+ use to generate the dissector from the IDL file(s).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section>
+ <title>Why do this?</title>
+ <para>
+ It is important to understand how CORBA traffic looks
+ like over GIOP/IIOP, and to help build a tool that can assist
+ in troubleshooting CORBA interworking. This was especially the
+ case after seeing a lot of discussions about how particular
+ IDL types are represented inside an octet stream.
+ </para>
+ <para>
+ I have also had comments/feedback that this tool would be good for say
+ a CORBA class when teaching students how CORBA traffic looks like
+ "on the wire".
+ </para>
+ <para>
+ It is also COOL to work on a great Open Source project such as
+ the case with "Ethereal" (
+ <ulink url="http://www.ethereal.com">http://www.ethereal.com</ulink>
+ )
+ </para>
+ </section>
+ <section><title>How to use idl2eth</title>
+ <para>
+ To use the idl2eth to generate ethereal dissectors, you
+ need the following:
+ </para>
+ <orderedlist>
+ <title>Prerequisites to using idl2eth</title>
+ <listitem>
+ <para>
+ Python must be installed. See
+ <ulink url="http://python.org/">http://python.org/</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ omniidl from the the omniORB package must be available.
+ <ulink url="http://www.uk.research.att.com/omniORB/omniORB.html">
+ http://www.uk.research.att.com/omniORB/omniORB.html
+ </ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Of course you need ethereal installed to compile the
+ code an tweak it if required. idl2eth is part of the
+ standard Ethereal distribution
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ To use idl2eth to generate an ethereal dissector from an idl file
+ use the following proceedure:
+ </para>
+ <orderedlist>
+ <title>
+ Proceedure for converting a Corba idl file into an ethereal
+ dissector
+ </title>
+ <listitem>
+ <para>
+ To write the C code to stdout.
+ <programlisting>idl2eth <your file.idl></programlisting>
+ eg: <programlisting>idl2eth echo.idl</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ To write to a file, just redirect the output.
+ <programlisting>idl2eth echo.idl > packet-test-idl.c</programlisting>
+ You may wish to comment out the register_giop_user_module() code
+ and that will leave you with heuristic dissection.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ If you dont want to use the shell script wrapper, then try
+ steps 3 or 4 instead.</para>
+ <orderedlist continuation="continues">
+ <listitem>
+ <para>To write the C code to stdout.
+ <programlisting>Usage: omniidl -p ./ -b ethereal_be <your file.idl></programlisting>
+ eg:
+ <programlisting>omniidl -p ./ -b ethereal_be echo.idl</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ To write to a file, just redirect the output.
+ <programlisting>omniidl -p ./ -b ethereal_be echo.idl > packet-test-idl.c</programlisting>
+ You may wish to comment out the register_giop_user_module() code
+ and that will leave you with heuristic dissection.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Copy the resulting C code to your ethereal src directory,
+ edit the 2 make files to include the packet-test-idl.c
+ <programlisting>
+cp packet-test-idl.c /dir/where/ethereal/lives/
+edit Makefile.am
+edit Makefile.nmake
+ </programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Run configure
+ <programlisting>./configure (or ./autogen.sh)</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para> Compile the code
+ <programlisting>make</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Good Luck !!</para>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section><title>TODO</title>
+ <orderedlist>
+ <listitem>
+ <para>
+ Exception code not generated (yet), but can be added manually.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Enums not converted to symbolic values (yet), but can be added
+ manually.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Add command line options etc</para>
+ </listitem>
+ <listitem>
+ <para>More I am sure :-)</para>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section><title>Limitations</title>
+ <para>
+ See the TODO list inside <filename>packet-giop.c</filename>
+ </para>
+ </section>
+ <section><title>Notes</title>
+ <orderedlist>
+ <listitem>
+ <para>
+ The "-p ./" option passed to omniidl indicates that the
+ ethereal_be.py and ethereal_gen.py are residing in the
+ current directory. This may need
+ tweaking if you place these files somewhere else.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If it complains about being unable to find some modules
+ (eg tempfile.py),
+ you may want to check if PYTHONPATH is set correctly.
+ On my Linux box, it is PYTHONPATH=/usr/lib/python1.5/
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+ </section>
+</appendix>
+<!-- End of EUG Appendix Tools -->
+
+
|