Protocol Dissection in XML Format
=================================
-$Id: README.xml-output,v 1.2 2003/12/09 05:56:30 gram Exp $
+$Id$
Copyright (c) 2003 by Gilbert Ramirez <gram@alumni.rice.edu>
-Tethereal has the ability to print its protocol dissection in an
-XML format, by using the "-Tpdml" options. Similar functionality
-could be put into the "Print" dialog of Ethereal, but that work has
-not been done yet.
+Wireshark has the ability to export its protocol dissection in an
+XML format, tshark has similar functionality by using the "-Tpdml"
+option.
-The XML that tethereal produces follows the Packet Details Markup
+The XML that wireshark produces follows the Packet Details Markup
Language (PDML) specified by the group at the Politecnico Di Torino
working on Analyzer. The specification can be found at:
A related XML format, the Packet Summary Markup Language (PSML), is
also defined by the Analyzer group to provide packet summary information.
The PSML format is not documented in a publicly-available HTML document,
-but its format is simple. Some day it may be added to tethereal so
-that "-Tpsml" would produce PSML.
+but its format is simple. Wireshark can export this format too. Some day it
+may be added to tshark so that "-Tpsml" would produce PSML.
One wonders if the "-T" option should read "-Txml" instead of "-Tpdml"
-(and in the future, "-Tpsml"), but if tethereal was required to produce
+(and in the future, "-Tpsml"), but if tshark was required to produce
another XML-based format of its protocol dissection, then "-Txml" would
be ambiguous.
PDML
====
-The PDML that tethereal produces is known not to be loadable into Analyzer.
-It causes Analyzer to crash. As such, the PDML that tethereal produces
-is be labled with a version number of "0", which means that the PDML does
-not fully follow the PDML spec. Furthemore, a creator attribute in the
-"<pdml>" tag gives the version number of [t]ethereal that produced the PDML.
-In that way, as the PDML produced by tethereal matures, but still does not
+The PDML that wireshark produces is known not to be loadable into Analyzer.
+It causes Analyzer to crash. As such, the PDML that wireshark produces
+is be labeled with a version number of "0", which means that the PDML does
+not fully follow the PDML spec. Furthermore, a creator attribute in the
+"<pdml>" tag gives the version number of wireshark/tshark that produced the PDML.
+In that way, as the PDML produced by wireshark matures, but still does not
meet the PDML spec, scripts can make intelligent decisions about how to
best parse the PDML, based on the "creator" attribute.
A protocol might contain one or more fields, denoted by the "<field>" tag.
A pseudo-protocol named "geninfo" is produced, as is required by the PDML
-spec, and
printed as the first protocol after the opening "<packet>" tag.
-Its information comes from ethereal's "frame" protocol, which servers
+spec, and
exported as the first protocol after the opening "<packet>" tag.
+Its information comes from wireshark's "frame" protocol, which serves
the similar purpose of storing packet meta-data. Both "geninfo" and
"frame" protocols are provided in the PDML output.
The "<pdml>" tag
================
Example:
- <pdml version="0" creator="ethereal/0.9.17">
+ <pdml version="0" creator="wireshark/0.9.17">
-The creator is "ethereal" (i.e., the "ethereal" engine. It will always say
-"ethereal", not "tethereal") version 0.9.17.
+The creator is "wireshark" (i.e., the "wireshark" engine. It will always say
+"wireshark", not "tshark") version 0.9.17.
The "<proto>" tag
but it can be modified by dissectors to include more data
(tcp can do this)
pos - the starting offset within the packet data where this
- protocol starts
+ protocol starts
size - the number of octets in the packet data that this protocol
- covers.
+ covers.
The "<field>" tag
=================
name - the display filter name for the field
showname - the label used to describe this field in the protocol
tree. This is usually the descriptive name of the protocol,
- followed by some represention of the value.
+ followed by some representation of the value.
pos - the starting offset within the packet data where this
- field starts
+ field starts
size - the number of octets in the packet data that this field
- covers.
+ covers.
value - the actual packet data, in hex, that this field covers
show - the representation of the packet data ('value') as it would
appear in a display filter.
Many dissectors label the undissected payload of a protocol as belonging
to a "data" protocol, and the "data" protocol usually resided inside
that last protocol dissected. In the PDML, The "data" protocol becomes
-a "data" field, placed exactly where the "data" protocol is in tethereal's
-protocol tree. So, if tethereal would normally show:
+a "data" field, placed exactly where the "data" protocol is in wireshark's
+protocol tree. So, if wireshark would normally show:
+-- Frame
|
-tools/EtherealXML.py
+tools/WiresharkXML.py
====================
-This is a python module which provides some infrastructor for
+This is a python module which provides some infrastructure for
Python developers who wish to parse PDML. It is designed to read
a PDML file and call a user's callback function every time a packet
is constructed from the protocols and fields for a single packet.
which accepts one argument, and call the parse_fh function:
------------------------------------------------------------
-import EtherealXML
+import WiresharkXML
def my_callback(packet):
# do something
fh = open(xml_filename)
-EtherealXML.parse_fh(fh, my_callback)
+WiresharkXML.parse_fh(fh, my_callback)
-# Now that the script has the packet data, do someting.
+# Now that the script has the packet data, do something.
------------------------------------------------------------
The object that is passed to the callback function is an
-EtherealXML.Packet object, which corresponds to a single packet.
-EtherealXML Provides 3 classes, each of which corresponds to a PDML tag:
+WiresharkXML.Packet object, which corresponds to a single packet.
+WiresharkXML Provides 3 classes, each of which corresponds to a PDML tag:
Packet - "<packet>" tag
Protocol - "<proto>" tag
Protocols and fields can contain other fields. Thus, the Protocol and
Field class have a "children" member, which is a simple list of the
Field objects, if any, that are contained. The "children" list can be
-directly accessed by calling users. It will be empty of this Protocol
-or Field contains no Fields.
+directly accessed by code using the object. The "children" list will be
+empty if this Protocol or Field contains no Fields.
-Furthemore, the Packet class is a sub-class of the PacketList class.
+Furthermore, the Packet class is a sub-class of the PacketList class.
The PacketList class provides methods to look for protocols and fields.
The term "item" is used when the item being looked for can be
a protocol or a field:
General Notes
=============
Generally, parsing XML is slow. If you're writing a script to parse
-the PDML output of tethereal, pass a read filter with "-R" to tethereal to
-try to reduce as much as possible the number of packets coming out of tethereal.
+the PDML output of tshark, pass a read filter with "-R" to tshark to
+try to reduce as much as possible the number of packets coming out of tshark.
The less your script has to process, the faster it will be.
-'tools/msnchat' is a sample Python program that uses EtherealXML to parse PDML.
-Given one or more capture files, it runs tethereal on each of them, providing
-a read filter to reduce tethereal's output. It finds MSN Chat conversations
-in the capture file and produces nice HTML showing the conversations. It has
-only been tested with capture files containing non-simultaneous chat sessions,
-but was written to more-or-less handle any number of simultanous chat
-sessions.
+'tools/msnchat' is a sample Python program that uses WiresharkXML to parse
+PDML. Given one or more capture files, it runs tshark on each of them,
+providing a read filter to reduce tshark's output. It finds MSN Chat
+conversations in the capture file and produces nice HTML showing the
+conversations. It has only been tested with capture files containing
+non-simultaneous chat sessions, but was written to more-or-less handle any
+number of simultaneous chat sessions.
git.samba.org / obnox / wireshark / wip.git / blobdiff