874 lines
35 KiB
XML
874 lines
35 KiB
XML
<!-- WSUG Appendix Tools -->
|
|
<!-- $Id$ -->
|
|
|
|
<appendix id="AppTools">
|
|
<title>Related command line tools</title>
|
|
|
|
<section id="AppToolsIntroduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
Besides the Wireshark GUI application, there are some command line tools
|
|
which can be helpful for doing some more specialized things. These tools
|
|
will be described in this chapter.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="AppToolstshark">
|
|
<title><command>tshark</command>: Terminal-based Wireshark</title>
|
|
<para>
|
|
<application>TShark</application> is a terminal oriented version
|
|
of Wireshark designed for capturing and displaying packets when an
|
|
interactive user interface isn't necessary or available. It supports
|
|
the same options as <command>wireshark</command>. For more
|
|
information on <command>tshark</command>, see the manual pages
|
|
(<command>man tshark</command>).
|
|
</para>
|
|
</section>
|
|
|
|
<section id="AppToolstcpdump">
|
|
<title><command>tcpdump</command>: Capturing with tcpdump for viewing
|
|
with Wireshark</title>
|
|
<para>
|
|
There are occasions when you want to capture packets using
|
|
<command>tcpdump</command> rather than <command>wireshark</command>,
|
|
especially when you want to do a remote capture and do not want the
|
|
network load associated with running Wireshark 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 most versions of
|
|
<command>tcpdump</command>, will, by default, only capture the first
|
|
68 or 96 bytes of each packet.
|
|
</para>
|
|
<para>
|
|
To ensure that you capture complete packets, use the following command:
|
|
<programlisting>
|
|
tcpdump -i <interface> -s 65535 -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 Wireshark distribution. You can get it from:
|
|
<ulink url="&TcpdumpWebsite;">&TcpdumpWebsite;</ulink> for various
|
|
platforms.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="AppToolsdumpcap">
|
|
<title><command>dumpcap</command>: Capturing with dumpcap for viewing
|
|
with Wireshark</title>
|
|
<para>
|
|
<application>Dumpcap</application> is a network traffic dump tool.
|
|
It captures packet data from a live network and writes the
|
|
packets to a file.
|
|
Dumpcap's native capture file format is libpcap format, which is also
|
|
the format used by Wireshark, tcpdump and various other tools.
|
|
</para>
|
|
<para>
|
|
Without any options set it will use the pcap library to capture traffic
|
|
from the first available network interface and write the received raw
|
|
packet data, along with the packets' time stamps into a libpcap file.
|
|
</para>
|
|
<para>
|
|
Packet capturing is performed with the pcap library.
|
|
The capture filter syntax follows the rules of the pcap library.
|
|
</para>
|
|
<para>
|
|
<example id="AppToolsdumpcapEx">
|
|
<title>Help information available from dumpcap</title>
|
|
<programlisting>
|
|
dumpcap -h
|
|
Dumpcap 1.1.4
|
|
Capture network packets and dump them into a libpcap file.
|
|
See http://www.wireshark.org for more information.
|
|
|
|
Usage: dumpcap [options] ...
|
|
|
|
Capture interface:
|
|
-i <interface> name or idx of interface (def: first non-loopback)
|
|
-f <capture filter> packet filter in libpcap filter syntax
|
|
-s <snaplen> packet snapshot length (def: 65535)
|
|
-p don't capture in promiscuous mode
|
|
-B <buffer size> size of kernel buffer (def: 1MB)
|
|
-y <link type> link layer type (def: first appropriate)
|
|
-D print list of interfaces and exit
|
|
-L print list of link-layer types of iface and exit
|
|
-S print statistics for each interface once every second
|
|
-M for -D, -L, and -S produce machine-readable output
|
|
|
|
Stop conditions:
|
|
-c <packet count> stop after n packets (def: infinite)
|
|
-a <autostop cond.> ... duration:NUM - stop after NUM seconds
|
|
filesize:NUM - stop this file after NUM KB
|
|
files:NUM - stop after NUM files
|
|
Output (files):
|
|
-w <filename> name of file to save (def: tempfile)
|
|
-b <ringbuffer opt.> ... duration:NUM - switch to next file after NUM secs
|
|
filesize:NUM - switch to next file after NUM KB
|
|
files:NUM - ringbuffer: replace after NUM files
|
|
-n use pcapng format instead of pcap
|
|
Miscellaneous:
|
|
-v print version information and exit
|
|
-h display this help and exit
|
|
|
|
Example: dumpcap -i eth0 -a duration:60 -w output.pcap
|
|
"Capture network packets from interface eth0 until 60s passed into output.pcap"
|
|
|
|
Use Ctrl-C to stop capturing at any time.
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="AppToolscapinfos">
|
|
<title><command>capinfos</command>: Print information about capture files
|
|
</title>
|
|
<para>
|
|
Included with Wireshark is a small utility called
|
|
<command>capinfos</command>, which is a command-line utility to
|
|
print information about binary capture files.
|
|
</para>
|
|
<para>
|
|
<example id="AppToolscapinfosEx">
|
|
<title>Help information available from capinfos</title>
|
|
<programlisting>
|
|
$ capinfos -h
|
|
Capinfos 1.1.4
|
|
Prints information about capture files.
|
|
See http://www.wireshark.org for more information.
|
|
|
|
Usage: capinfos [options] <infile> ...
|
|
|
|
General:
|
|
-t display the capture file type
|
|
-E display the capture file encapsulation
|
|
|
|
Size:
|
|
-c display the number of packets
|
|
-s display the size of the file (in bytes)
|
|
-d display the total length of all packets (in bytes)
|
|
|
|
Time:
|
|
-u display the capture duration (in seconds)
|
|
-a display the capture start time
|
|
-e display the capture end time
|
|
|
|
Statistic:
|
|
-y display average data rate (in bytes/sec)
|
|
-i display average data rate (in bits/sec)
|
|
-z display average packet size (in bytes)
|
|
-x display average packet rate (in packets/sec)
|
|
|
|
Miscellaneous:
|
|
-h display this help and exit
|
|
|
|
If no options are given the default is to display all infos
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="AppToolseditcap">
|
|
<title><command>editcap</command>: Edit capture files</title>
|
|
<para>
|
|
Included with Wireshark 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 files, but it can also be used to convert
|
|
capture files from one format to another, as well as to print
|
|
information about capture files.
|
|
</para>
|
|
<para>
|
|
|
|
<example id="AppToolseditcapEx">
|
|
<title>Help information available from editcap</title>
|
|
<programlisting>
|
|
$ editcap -h
|
|
Editcap 1.1.4
|
|
Edit and/or translate the format of capture files.
|
|
See http://www.wireshark.org for more information.
|
|
|
|
Usage: editcap [options] ... <infile> <outfile> [ <packet#>[-<packet#>] ... ]
|
|
|
|
<infile> and <outfile> must both be present.
|
|
A single packet or a range of packets can be selected.
|
|
|
|
Packet selection:
|
|
-r keep the selected packets; default is to delete them.
|
|
-A <start time> don't output packets whose timestamp is before the
|
|
given time (format as YYYY-MM-DD hh:mm:ss).
|
|
-B <stop time> don't output packets whose timestamp is after the
|
|
given time (format as YYYY-MM-DD hh:mm:ss).
|
|
|
|
Duplicate packet removal:
|
|
-d remove packet if duplicate (window == 5).
|
|
-D <dup window> remove packet if duplicate; configurable <dup window>
|
|
Valid <dup window> values are 0 to 1000000.
|
|
NOTE: A <dup window> of 0 with -v (verbose option) is
|
|
useful to print MD5 hashes.
|
|
-w <dup time window> remove packet if duplicate packet is found EQUAL TO OR
|
|
LESS THAN <dup time window> prior to current packet.
|
|
A <dup time window> is specified in relative seconds
|
|
(e.g. 0.000001).
|
|
|
|
NOTE: The use of the 'Duplicate packet removal' options with
|
|
other editcap options except -v may not always work as expected.
|
|
Specifically the -r and -t options will very likely NOT have the
|
|
desired effect if combined with the -d, -D or -w.
|
|
|
|
Packet manipulation:
|
|
-s <snaplen> truncate each packet to max. <snaplen> bytes of data.
|
|
-C <choplen> chop each packet at the end by <choplen> bytes.
|
|
-t <time adjustment> adjust the timestamp of each packet;
|
|
<time adjustment> is in relative seconds (e.g. -0.5).
|
|
-E <error probability> set the probability (between 0.0 and 1.0 incl.)
|
|
that a particular packet byte will be randomly changed.
|
|
|
|
Output File(s):
|
|
-c <packets per file> split the packet output to different files
|
|
based on uniform packet counts
|
|
with a maximum of <packets per file> each.
|
|
-i <seconds per file> split the packet output to different files
|
|
based on uniform time intervals
|
|
with a maximum of <seconds per file> each.
|
|
-F <capture type> set the output file type; default is libpcap.
|
|
an empty "-F" option will list the file types.
|
|
-T <encap type> set the output file encapsulation type;
|
|
default is the same as the input file.
|
|
an empty "-T" option will list the encapsulation types.
|
|
|
|
Miscellaneous:
|
|
-h display this help and exit.
|
|
-v verbose output.
|
|
If -v is used with any of the 'Duplicate Packet
|
|
Removal' options (-d, -D or -w) then Packet lengths
|
|
and MD5 hashes are printed to standard-out.
|
|
|
|
$ editcap -F
|
|
editcap: option requires an argument -- F
|
|
editcap: The available capture file types for "F":
|
|
libpcap - Wireshark/tcpdump/... - libpcap
|
|
nseclibpcap - Wireshark - nanosecond libpcap
|
|
modlibpcap - Modified tcpdump - libpcap
|
|
nokialibpcap - Nokia tcpdump - libpcap
|
|
rh6_1libpcap - RedHat 6.1 tcpdump - libpcap
|
|
suse6_3libpcap - SuSE 6.3 tcpdump - libpcap
|
|
5views - Accellent 5Views capture
|
|
dct2000 - Catapult DCT2000 trace (.out format)
|
|
nettl - HP-UX nettl trace
|
|
netmon1 - Microsoft NetMon 1.x
|
|
netmon2 - Microsoft NetMon 2.x
|
|
ngsniffer - NA Sniffer (DOS)
|
|
ngwsniffer_1_1 - NA Sniffer (Windows) 1.1
|
|
ngwsniffer_2_0 - NA Sniffer (Windows) 2.00x
|
|
niobserverv9 - Network Instruments Observer (V9)
|
|
lanalyzer - Novell LANalyzer
|
|
snoop - Sun snoop
|
|
rf5 - Tektronix K12xx 32-bit .rf5 format
|
|
visual - Visual Networks traffic capture
|
|
k12text - K12 text file
|
|
commview - TamoSoft CommView
|
|
pcapng - Wireshark - pcapng (experimental)
|
|
|
|
$ editcap -T
|
|
editcap: option requires an argument -- T
|
|
editcap: The available encapsulation types for "T":
|
|
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-radiotap - IEEE 802.11 plus radiotap 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
|
|
raw-icmp-nettl - Raw ICMP with nettl headers
|
|
raw-icmpv6-nettl - Raw ICMPv6 with nettl headers
|
|
gprs-llc - GPRS LLC
|
|
juniper-atm1 - Juniper ATM1
|
|
juniper-atm2 - Juniper ATM2
|
|
redback - Redback SmartEdge
|
|
rawip-nettl - Raw IP with nettl headers
|
|
ether-nettl - Ethernet with nettl headers
|
|
tr-nettl - Token Ring with nettl headers
|
|
fddi-nettl - FDDI with nettl headers
|
|
unknown-nettl - Unknown link-layer type with nettl headers
|
|
mtp2-with-phdr - MTP2 with pseudoheader
|
|
juniper-pppoe - Juniper PPPoE
|
|
gcom-tie1 - GCOM TIE1
|
|
gcom-serial - GCOM Serial
|
|
x25-nettl - X25 with nettl headers
|
|
k12 - K12 protocol analyzer
|
|
juniper-mlppp - Juniper MLPPP
|
|
juniper-mlfr - Juniper MLFR
|
|
juniper-ether - Juniper Ethernet
|
|
juniper-ppp - Juniper PPP
|
|
juniper-frelay - Juniper Frame-Relay
|
|
juniper-chdlc - Juniper C-HDLC
|
|
juniper-ggsn - Juniper GGSN
|
|
lapd - LAPD
|
|
dct2000 - Catapult DCT2000
|
|
ber - ASN.1 Basic Encoding Rules
|
|
juniper-vp - Juniper Voice PIC
|
|
usb - Raw USB packets
|
|
ieee-802-16-mac-cps - IEEE 802.16 MAC Common Part Sublayer
|
|
raw-telnet-nettl - Raw telnet with nettl headers
|
|
usb-linux - USB packets with Linux header
|
|
mpeg - MPEG
|
|
ppi - Per-Packet Information header
|
|
erf - Endace Record File
|
|
bluetooth-h4 - Bluetooth H4 with linux header
|
|
sita-wan - SITA WAN packets
|
|
sccp - SS7 SCCP
|
|
bluetooth-hci - Bluetooth without transport layer
|
|
ipmb - Intelligent Platform Management Bus
|
|
wpan - IEEE 802.15.4 Wireless PAN
|
|
x2e-xoraya - X2E Xoraya
|
|
flexray - FlexRay
|
|
lin - Local Interconnect Network
|
|
most - Media Oriented Systems Transport
|
|
can20b - Controller Area Network 2.0B
|
|
layer1-event - EyeSDN Layer 1 event
|
|
x2e-serial - X2E serial line capture
|
|
i2c - I2C
|
|
wpan-nonask-phy - IEEE 802.15.4 Wireless PAN non-ASK PHY
|
|
tnef - Transport-Neutral Encapsulation Format
|
|
usb-linux-mmap - USB packets with Linux header and padding
|
|
gsm_um - GSM Um Interface
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="AppToolsmergecap">
|
|
<title><command>mergecap</command>:
|
|
Merging multiple capture files into one
|
|
</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 the 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 -h
|
|
Mergecap 1.1.4
|
|
Merge two or more capture files into one.
|
|
See http://www.wireshark.org for more information.
|
|
|
|
Usage: mergecap [options] -w <outfile>|- <infile> ...
|
|
|
|
Output:
|
|
-a concatenate rather than merge files.
|
|
default is to merge based on frame timestamps.
|
|
-s <snaplen> truncate packets to <snaplen> bytes of data.
|
|
-w <outfile>|- set the output filename to <outfile> or '-' for stdout.
|
|
-F <capture type> set the output file type; default is libpcap.
|
|
an empty "-F" option will list the file types.
|
|
-T <encap type> set the output file encapsulation type;
|
|
default is the same as the first input file.
|
|
an empty "-T" option will list the encapsulation types.
|
|
|
|
Miscellaneous:
|
|
-h display this help and exit.
|
|
-v verbose output.
|
|
</programlisting>
|
|
</example>
|
|
<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><command>text2pcap</command>: Converting ASCII hexdumps to network
|
|
captures
|
|
</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 with multiple 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 -A x -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.
|
|
Possiblities include inserting headers such as Ethernet, Ethernet + IP,
|
|
Ethernet + IP + UDP, or Ethernet + Ip + TCP before each packet.
|
|
This allows Wireshark or any other full-packet decoder to handle these dumps.
|
|
</para>
|
|
<example id="AppToolstext2pcapEx">
|
|
<title>Help information available for text2pcap</title>
|
|
<programlisting>
|
|
$ text2pcap -h
|
|
Text2pcap 1.1.4
|
|
Generate a capture file from an ASCII hexdump of packets.
|
|
See http://www.wireshark.org for more information.
|
|
|
|
Usage: text2pcap [options] <infile> <outfile>
|
|
|
|
where <infile> specifies input filename (use - for standard input)
|
|
<outfile> specifies output filename (use - for standard output)
|
|
|
|
Input:
|
|
-o hex|oct|dec parse offsets as (h)ex, (o)ctal or (d)ecimal; default is hex.
|
|
-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 given
|
|
(.) but no pattern is required; the remaining number
|
|
is assumed to be fractions of a second.
|
|
NOTE: Date/time fields from the current date/time are
|
|
used as the default for unspecified fields.
|
|
|
|
Output:
|
|
-l <typenum> link-layer type number; default is 1 (Ethernet).
|
|
See the file net/bpf.h for list of numbers.
|
|
Use this option 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.
|
|
-m <max-packet> max packet length in output; default is 64000
|
|
|
|
Prepend dummy header:
|
|
-e <l3pid> prepend dummy Ethernet II header with specified L3PID
|
|
(in HEX).
|
|
Example: -e 0x806 to specify an ARP packet.
|
|
-i <proto> prepend dummy IP header with specified IP protocol
|
|
(in DECIMAL).
|
|
Automatically prepends Ethernet header as well.
|
|
Example: -i 46
|
|
-u <srcp>,<destp> prepend dummy UDP header with specified
|
|
dest and source ports (in DECIMAL).
|
|
Automatically prepends Ethernet & IP headers as well.
|
|
Example: -u 1000 69 to make the packets look like TFTP/UDP packets.
|
|
-T <srcp>,<destp> prepend dummy TCP header with specified
|
|
dest and source ports (in DECIMAL).
|
|
Automatically prepends Ethernet & 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 & 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.
|
|
Automatically prepends a dummy SCTP DATA
|
|
chunk header with payload protocol identifier ppi.
|
|
Example: -S 30,40,34
|
|
|
|
Miscellaneous:
|
|
-h display this help and exit.
|
|
-d detailed debug of parser states.
|
|
-q generate no output at all (automatically turns off -d).
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="AppToolsidl2wrs" >
|
|
<title><command>idl2wrs</command>:
|
|
Creating dissectors from CORBA IDL files
|
|
</title>
|
|
<para>
|
|
In an ideal world idl2wrs 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>idl2wrs</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 a Wireshark dissector.
|
|
</para>
|
|
<para>
|
|
<command>idl2wrs</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.idl2wrs</filename></term>
|
|
<listitem>
|
|
<para>This document</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><filename>wireshark_be.py</filename></term>
|
|
<listitem>
|
|
<para>The main compiler backend</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><filename>wireshark_gen.py</filename></term>
|
|
<listitem>
|
|
<para>A helper class, that generates the C code.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><filename>idl2wrs</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 what 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 what 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 "Wireshark" (
|
|
<ulink url="&WiresharkWebSite;">&WiresharkWebSite;</ulink>
|
|
)
|
|
</para>
|
|
</section>
|
|
<section><title>How to use idl2wrs</title>
|
|
<para>
|
|
To use the idl2wrs to generate Wireshark dissectors, you
|
|
need the following:
|
|
</para>
|
|
<orderedlist>
|
|
<title>Prerequisites to using idl2wrs</title>
|
|
<listitem>
|
|
<para>
|
|
Python must be installed. See
|
|
<ulink url="http://python.org/"/>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
omniidl from the the omniORB package must be available. See
|
|
<ulink url="http://omniorb.sourceforge.net/"/>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Of course you need Wireshark installed to compile the
|
|
code and tweak it if required. idl2wrs is part of the
|
|
standard Wireshark distribution
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>
|
|
To use idl2wrs to generate an Wireshark dissector from an idl file
|
|
use the following procedure:
|
|
</para>
|
|
<orderedlist>
|
|
<title>
|
|
Procedure for converting a CORBA idl file into a Wireshark
|
|
dissector
|
|
</title>
|
|
<listitem>
|
|
<para>
|
|
To write the C code to stdout.
|
|
<programlisting>idl2wrs <your file.idl></programlisting>
|
|
e.g.: <programlisting>idl2wrs echo.idl</programlisting>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
To write to a file, just redirect the output.
|
|
<programlisting>idl2wrs 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 don't 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 wireshark_be <your file.idl></programlisting>
|
|
e.g.:
|
|
<programlisting>omniidl -p ./ -b wireshark_be echo.idl</programlisting>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
To write to a file, just redirect the output.
|
|
<programlisting>omniidl -p ./ -b wireshark_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 subdirectory epan/dissectors/ inside your
|
|
Wireshark source directory.
|
|
<programlisting>cp packet-test-idl.c /dir/where/wireshark/lives/epan/dissectors/</programlisting>
|
|
The new dissector has to be added to Makefile.common in the same
|
|
directory. Look for the declaration CLEAN_DISSECTOR_SRC and add
|
|
the new dissector there. For example,
|
|
<programlisting>
|
|
CLEAN_DISSECTOR_SRC = \
|
|
packet-2dparityfec.c \
|
|
packet-3com-njack.c \
|
|
...
|
|
</programlisting>
|
|
becomes
|
|
<programlisting>
|
|
CLEAN_DISSECTOR_SRC = \
|
|
packet-test-idl.c \
|
|
packet-2dparityfec.c \
|
|
packet-3com-njack.c \
|
|
...
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
For the next steps, go up to the top of your Wireshark source directory.
|
|
</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
|
|
wireshark_be.py and wireshark_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
|
|
(e.g. tempfile.py),
|
|
you may want to check if PYTHONPATH is set correctly.
|
|
On my Linux box, it is PYTHONPATH=/usr/lib/python2.4/
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
</section>
|
|
</appendix>
|
|
<!-- End of WSUG Appendix Tools -->
|
|
|
|
|